diff --git a/README.md b/README.md index 23dbc51..afea056 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate python3 setup.py # Installs system deps + Python packages -# 2. Scan photos +# 2. Scan photos (absolute or relative paths work) python3 photo_tagger.py scan /path/to/your/photos # 3. Process faces @@ -86,13 +86,22 @@ python3 photo_tagger.py stats # Creates database ### Scan for Photos ```bash -# Scan a folder +# Scan a folder (absolute path recommended) python3 photo_tagger.py scan /path/to/photos +# Scan with relative path (auto-converted to absolute) +python3 photo_tagger.py scan demo_photos + # Scan recursively (recommended) python3 photo_tagger.py scan /path/to/photos --recursive ``` +**📁 Path Handling:** +- **Absolute paths**: Use full paths like `/home/user/photos` or `C:\Users\Photos` +- **Relative paths**: Automatically converted to absolute paths (e.g., `demo_photos` → `/current/directory/demo_photos`) +- **Cross-platform**: Works on Windows, Linux, and macOS +- **Web-app ready**: Absolute paths work perfectly in web applications + ### Process Photos for Faces (with Quality Scoring) ```bash # Process 50 photos (default) - now includes face quality scoring @@ -367,8 +376,9 @@ python3 photo_tagger.py search-gui **📋 Filters Area (Collapsible):** - **Folder Location Filter**: Filter results by specific folder path -- **Browse Button**: Visual folder selection dialog +- **Browse Button**: Visual folder selection dialog (selects absolute paths) - **Clear Button**: Reset folder filter +- **Apply Filters Button**: Apply folder filter to current search - **Expand/Collapse**: Click +/- to show/hide filters - **Tooltips**: Hover over +/- for expand/collapse guidance @@ -417,13 +427,32 @@ python3 photo_tagger.py stats python3 photo_tagger.py tag-manager ``` +### Dashboard GUI +```bash +# Open the main dashboard +python3 photo_tagger.py dashboard +``` + +**🎯 Dashboard Features:** +- **📁 Scan Section**: Add photos to database with folder selection +- **Browse Button**: Visual folder selection dialog (selects absolute paths) +- **Recursive Option**: Include photos in subfolders +- **Path Validation**: Automatic path validation and error handling +- **Cross-platform**: Works on Windows, Linux, and macOS + +**📁 Enhanced Folder Selection:** +- **Visual Selection**: Click "Browse" to select folders visually +- **Absolute Paths**: All selected paths are stored as absolute paths +- **Path Normalization**: Relative paths automatically converted to absolute +- **Error Handling**: Clear error messages for invalid paths + ## 📊 Enhanced Example Workflow ```bash # ALWAYS activate virtual environment first! source venv/bin/activate -# 1. Scan your photo collection +# 1. Scan your photo collection (absolute or relative paths work) python3 photo_tagger.py scan ~/Pictures --recursive # 2. Process photos for faces (start with small batch) @@ -486,6 +515,51 @@ The tool uses SQLite database (`data/photos.db` by default) with these tables: python3 photo_tagger.py scan /photos --db /path/to/my.db ``` +## 🌐 Path Handling & Web Application Compatibility + +### Absolute Path System +PunimTag now uses a robust absolute path system that ensures consistency across all platforms and deployment scenarios. + +**📁 Key Features:** +- **Automatic Path Normalization**: All paths are converted to absolute paths +- **Cross-Platform Support**: Works on Windows (`C:\Photos`), Linux (`/home/user/photos`), and macOS +- **Web Application Ready**: Absolute paths work perfectly in web applications +- **Browse Buttons**: Visual folder selection in all GUI components +- **Path Validation**: Automatic validation and error handling + +**🔧 Path Utilities:** +- **`normalize_path()`**: Converts any path to absolute path +- **`validate_path_exists()`**: Checks if path exists and is accessible +- **`get_path_info()`**: Provides detailed path information +- **Cross-platform**: Handles Windows, Linux, and macOS path formats + +**🌐 Web Application Integration:** +```python +# Example: Flask web application integration +from path_utils import normalize_path + +@app.route('/scan_photos', methods=['POST']) +def scan_photos(): + upload_dir = request.form['upload_dir'] + absolute_path = normalize_path(upload_dir) # Always absolute + # Run photo_tagger with absolute path + subprocess.run(f"python3 photo_tagger.py scan {absolute_path}") +``` + +**📋 Path Examples:** +```bash +# CLI - relative path auto-converted +python3 photo_tagger.py scan demo_photos +# Stored as: /home/user/punimtag/demo_photos/photo.jpg + +# CLI - absolute path used as-is +python3 photo_tagger.py scan /home/user/photos +# Stored as: /home/user/photos/photo.jpg + +# GUI - Browse button selects absolute path +# User selects folder → absolute path stored in database +``` + ## 🔧 System Requirements ### Required System Packages (Ubuntu/Debian) @@ -968,7 +1042,7 @@ python3 photo_tagger.py identify --show-faces --batch 10 # Opens GUI python3 photo_tagger.py auto-match --show-faces # Opens GUI python3 photo_tagger.py search-gui # Opens Search GUI python3 photo_tagger.py modifyidentified # Opens GUI to view/modify -python3 photo_tagger.py dashboard # Opens Dashboard (placeholders) +python3 photo_tagger.py dashboard # Opens Dashboard with Browse buttons python3 photo_tagger.py tag-manager # Opens GUI for tag management python3 photo_tagger.py stats ``` \ No newline at end of file