From 842f588f19a0bd85cc753a42d996e8ee09877391 Mon Sep 17 00:00:00 2001 From: tanyar09 Date: Tue, 11 Nov 2025 15:31:36 -0500 Subject: [PATCH] docs: Add comprehensive user guide for PunimTag web application This commit introduces a new user guide in the documentation, providing detailed instructions on using the PunimTag web application. The guide includes sections on getting started, navigation overview, page-by-page usage, workflow examples, and tips for best practices. This addition aims to enhance user experience by offering clear guidance on application features and functionalities. --- docs/USER_GUIDE.md | 511 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 511 insertions(+) create mode 100644 docs/USER_GUIDE.md diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 0000000..87e1004 --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,511 @@ +# PunimTag Web - User Guide + +**Complete guide to using the PunimTag web application** + +--- + +## Table of Contents + +1. [Getting Started](#getting-started) +2. [Navigation Overview](#navigation-overview) +3. [Page-by-Page Guide](#page-by-page-guide) + - [Login Page](#login-page) + - [Dashboard](#dashboard) + - [Scan Page](#scan-page) + - [Process Page](#process-page) + - [Identify Page](#identify-page) + - [Auto-Match Page](#auto-match-page) + - [Search Page](#search-page) + - [Modify Page](#modify-page) + - [Tags Page](#tags-page) + - [Faces Maintenance Page](#faces-maintenance-page) + - [Settings Page](#settings-page) +4. [Workflow Examples](#workflow-examples) +5. [Tips & Best Practices](#tips--best-practices) +6. [Troubleshooting](#troubleshooting) + +--- + +## Getting Started + +### First Time Setup + +1. **Start the Application** + - Ensure Redis is running + - Start the backend API server + - Start the frontend development server + - Open your browser to `http://localhost:3000` + +2. **Login** + - Default credentials: + - Username: `admin` + - Password: `admin` + - ⚠️ **Important**: Change these credentials in production! + +3. **Initial Workflow** + - **Scan** → Import your photos + - **Process** → Detect faces in photos + - **Identify** → Name the people in your photos + - **Auto-Match** → Automatically match similar faces to previously identified people + - **Search** → Find photos by people, dates, or tags + - **Tags** → Tag photos and manage tags + +--- + +## Navigation Overview + +The application uses a **left sidebar navigation** with the following pages: + +- 🏠 **Dashboard** - Overview and statistics +- 📁 **Scan** - Import photos from folders or upload files +- ⚙️ **Process** - Detect and process faces in photos +- 👤 **Identify** - Manually identify people in faces +- 🤖 **Auto-Match** - Automatically match similar faces to previously identified faces +- 🔍 **Search** - Search and filter photos +- ✏️ **Modify** - Edit person information +- 🏷️ **Tags** - Tag photos and manage photo tags +- 🔧 **Faces Maintenance** - Manage face data +- ⚙️ **Settings** - Application settings + +--- + +## Page-by-Page Guide + +### Login Page + +**Purpose**: Authenticate and access the application + +**Features**: +- Username and password login +- JWT-based authentication +- Automatic redirect to dashboard after login + +**How to Use**: +1. Enter your username (default: `admin`) +2. Enter your password (default: `admin`) +3. Click "Login" button +4. You'll be redirected to the Dashboard + +**Notes**: +- Session persists until logout +- Default credentials are for development only +- Change credentials in production for security + +--- + +### Dashboard + +**Purpose**: Overview of your photo collection and statistics + +**Features**: +- Collection statistics +- Quick access to main features +- Recent activity summary + +**How to Use**: +- View statistics about your photo collection +- Navigate to other pages using the sidebar +- Monitor overall system status + +**Current Status**: Basic implementation - more features coming in future updates + +--- + +### Scan Page + +**Purpose**: Import photos into your collection from folders or upload files + +**Features**: +- **Folder Selection**: Browse and select folders containing photos +- **File Upload**: Drag-and-drop or click to upload individual files +- **Recursive Scanning**: Option to scan subfolders recursively +- **Duplicate Detection**: Automatically detects and skips duplicate photos +- **Real-time Progress**: Live progress tracking during import +- **EXIF Extraction**: Automatically extracts date taken and metadata + +**How to Use**: + +**Folder Scan** +1. Click "Browse Folder" button +2. Select a folder containing photos +3. Toggle "Recursive" if you want to include subfolders +4. Click "Start Scan" button +5. Monitor progress in the progress bar +6. View results (photos added, existing photos skipped) + +**What Happens**: +- Photos are copied to `data/uploads` directory +- EXIF metadata is extracted (date taken, orientation, etc.) +- Duplicate detection by checksum +- Photos are added to database +- Faces are NOT detected yet (use Process page for that) + +**Tips**: +- Large folders may take time - be patient! + +--- + +### Process Page + +**Purpose**: Detect faces in imported photos and generate face encodings + +**Features**: +- **face detection method used - `retinaface` - Best accuracy, medium speed + +- **Face recognition model used - `ArcFace` - Best accuracy, medium speed +- **Batch Size**: Configure how many photos to process at once +- **Real-time Progress**: Live progress tracking +- **Job Cancellation**: Stop processing if needed + +**How to Use**: +1. Optionally set **Batch Size** (leave empty for default) +2. Click "Start Processing" button +3. Monitor progress: + - Progress bar shows overall completion + - Photo count shows photos processed + - Face count shows faces detected and stored +4. Wait for completion or click "Stop Processing" to cancel + +**What Happens**: +- DeepFace analyzes each unprocessed photo +- Faces are detected and located +- 512-dimensional face encodings are generated +- Face metadata is stored (confidence, quality, location) +- Photos are marked as processed + +**Tips**: +- You can cancel and resume later + +--- + +### Identify Page + +**Purpose**: Manually identify people in detected faces + +**Features**: +- **Face Navigation**: Browse through unidentified faces +- **Person Creation**: Create new person records +- **Similar Faces Panel**: View similar faces for comparison +- **Confidence Display**: See match confidence percentages +- **Date Filtering**: Filter faces by date taken or processed +- **Unique Faces Filter**: Hide duplicate faces of same person +- **Face Information**: View face metadata (confidence, quality, detector/model) + +**How to Use**: + +**Basic Identification**: +1. Navigate to Identify page +2. View the current face on the left panel +3. Select existing person from the drop down list or create new person below +4. Enter person information: + - First Name (required) + - Last Name (required) + - Middle Name (optional) + - Maiden Name (optional) + - Date of Birth (required) +5. Click "Identify" button to identify the face + +**Using Similar Faces**: +1. Toggle "Compare" checkbox to show similar faces +2. View similar faces in the right panel +3. See confidence percentages (color-coded) +4. Select similar faces to bulk identify with the current left face +5. Click "Identify" button to bulk identify left and all selected on the right faces to that person. + +**Navigation**: +- Use "Next" button to move to next unidentified face +- Use "Back" button to go to previous face +- Use filters to narrow down faces to identify + +**Unique Faces Filter**: +- Check "Unique faces only" to hide duplicates +- Shows only one representative face per person +- Similar faces panel remains unfiltered + +**Confidence Colors**: +- 🟢 **80%+** = Very High (Almost Certain) +- 🟡 **70%+** = High (Likely Match) +- 🟠 **60%+** = Medium (Possible Match) +- 🔴 **50%+** = Low (Questionable) +- ⚫ **<50%** = Very Low (Unlikely) + +**Tips**: +- Use similar faces to identify groups of photos +- Date filtering helps focus on specific time periods +- Unique faces filter reduces clutter +- Confidence scores help prioritize identification + +--- + +### Auto-Match Page + +**Purpose**: Automatically match unidentified faces to identified people + +**Features**: +- **Person-Centric View**: Shows identified person on left, matches on right +- **Checkbox Selection**: Select which faces to identify +- **Confidence Display**: Color-coded match confidence +- **Batch Identification**: Identify multiple faces at once +- **Navigation**: Move between different people + +**How to Use**: + +**Manual Match Workflow**: +1. Navigate to Auto-Match page +2. Faces load automatically on page load +3. View identified person on the left panel +4. View matching unidentified faces on the right panel +5. Check boxes next to faces you want to identify +6. Click "Save changes for [Person Name]" button +7. Use "Next" and "Back" buttons to navigate between people + +***Automatic Match Workflow**: +1. Navigate to Auto-Match page +2. Click Run Auto-Match button +3. All unidentified faces will be matched to identified faces based on the following clitiria: +simillarity higher than 70% +picture quality higher than 50% +profile faces are excluded for better accuracy + +**Understanding Matches**: +- Left panel shows an identified person with their reference face +- Right panel shows unidentified faces that match this person +- Confidence percentages show match quality +- Only faces above threshold are shown + +**Selecting Faces**: +- Check boxes to select faces to identify +- Uncheck boxes to deselect +- Previously identified faces are pre-checked +- Selections persist when navigating between people + +**Saving Changes**: +- Click "Save changes" button in left panel +- Only checked faces are identified +- Changes are saved immediately +- You can go back and uncheck faces to unidentify them + +**Navigation**: +- "Next" button moves to next person (disabled on last person) +- "Back" button moves to previous person (disabled on first person) +- Navigation preserves checkbox selections + +**Tips**: +- Review matches carefully before saving +- Use confidence scores to guide decisions +- You can correct mistakes by going back and unchecking +- High confidence matches (>70%) are usually accurate + +--- + +### Search Page + +**Purpose**: Search and filter photos by various criteria + +**Features**: +- **People Filter**: Filter by identified people +- **Date Filter**: Filter by date taken or date added +- **Tag Filter**: Filter by photo tags +- **Folder Filter**: Filter by source folder +- **Photo Grid**: Virtualized grid of matching photos +- **Pagination**: Navigate through search results + +**How to Use**: + +**Basic Search**: +1. Navigate to Search page +2. Use filter dropdowns to set criteria: + - **People**: Select one or more people + - **Date Taken**: Set date range + - **Date Added**: Set date range + - **Tags**: Select one or more tags + - **Folder**: Select source folder +3. Click "Search" or filters apply automatically +4. View matching photos in the grid +5. Click on photos to view details + +**Filters**: +- Multiple filters can be combined +- All filters work together (AND logic) +- Clear individual filters or reset all + +**Photo Grid**: +- Virtualized for performance with large result sets +- Scroll to load more photos +- Click photos for details or actions + +**Tips**: +- Combine filters for precise searches +- Use date ranges to find photos from specific periods +- Tag filtering helps find themed photos +- People filter is most useful after identification + +--- + +### Modify Page + +**Purpose**: Edit person information and manage person records + +**Features**: +- **Person Selection**: Choose person to edit +- **Information Editing**: Update names and date of birth +- **Face Management**: View and manage person's faces +- **Person Deletion**: Remove person records (with confirmation) + +**How to Use**: + +**Editing Person Information**: +1. Navigate to Modify page +2. Select person from dropdown +3. Edit information fields: + - First Name + - Last Name + - Middle Name + - Maiden Name + - Date of Birth +4. Click "Save Changes" button + +**Managing Faces**: +- View all faces associated with person +- See face thumbnails +- Remove faces from person if needed (unmatch) + +**Tips**: +- Use this to correct mistakes in identification +- Update names if you learn more information +- Be careful with deletion - it's permanent + +--- + +### Tags Page + +**Purpose**: Manage photo tags and tag-photo relationships + +**Features**: +- **Tag List**: View all existing tags +- **Tag Creation**: Create new tags +- **Tag Editing**: Edit tag names +- **Tag Deletion**: Remove tags +- **Photo-Tag Linkage**: Assign tags to photos + +**How to Use**: + +**Creating Tags**: +1. Navigate to Tags page +2. Click "Manage Tags" button +3. Enter new tag name +4. Click "Add tag" button + +**Managing Tags**: +- Click "Manage Tags" button +- View all tags in a list +- Edit tag names by clicking edit button +- Delete tags by selecting it's check box and clicking "Delete selected tags" button +- ⚠️ **Warning**: Deleting a tag removes it from all photos + +**Assigning Tags to Photos**: +- Select photos from Tags page(or from Search page) +- Use tag assignment interface +- Tags can be assigned to multiple photos at once by selecting multiple photos and clicking "Tag Selected Photos" button +- Tags can be assigned to all photos in a specific folder at once by clicking the linkage icon next to the folder name +- Tags can be assigned to a single photo by clicking the linkage icon on the right of each photo + +**Tips**: +- Use descriptive tag names +- Create tags for events, locations, themes +- Tags help organize and find photos later +Note: Tags are case insensitive!********* +--- + +### Faces Maintenance Page + +**Purpose**: Remove unwanted faces - mainly due to low quality face detections + +**Features**: +- **Face List**: View all faces in database +- **Face Filtering**: Filter quality +- **Face Deletion**: Remove unwanted faces +- **Bulk Operations**: Perform actions on multiple faces + +**How to Use**: + +**Viewing Faces**: +1. Navigate to Faces Maintenance page +2. View list of all faces +3. See face thumbnails and metadata +4. Filter faces by quality (delete faces with low quality) + +**Deleting Faces**: +- Select faces to delete +- Click "Delete Selected" button +- Confirm deletion +- ⚠️ **Warning**: Deletion is permanent + +**Bulk Operations**: +- Select multiple faces +- Perform bulk actions (delete, unidentify, etc.) +- Useful for cleaning up database + +**Tips**: +- Remove low-quality face detections +- Regular maintenance keeps database clean + +--- + +### Settings Page + +**Purpose**: Configure application settings and preferences +--- + +## Workflow Examples + +### Complete Workflow: Import and Identify Photos + +1. **Scan Photos** + - Go to Scan page + - Browse folder or upload files + - Wait for import to complete + +2. **Process Faces** + - Go to Process page + - Select detector and model (or use defaults) + - Click "Start Processing" + - Wait for face detection to complete + +3. **Identify People** + - Go to Identify page + - Browse through faces + - Create person records and identify faces + - Use similar faces to help identification + +4. **Auto-Match Remaining** + - Go to Auto-Match page + - Review automatic matches + - Select faces to identify + - Save changes + +5. **Search and Organize** + - Go to Search page + - Filter by people, dates, or tags + - Find specific photos + - Assign tags for organization + +### Quick Workflow: Just Process New Photos + +1. **Scan** → Import new photos +2. **Process** → Detect faces +3. **Identify** → Manually identify any remaining faces +4. **Auto-Match** → Automatically match to existing people +5. **Tag Photos** → Tag photos for easy future search + + +--- + +**Last Updated**: October 2025 +**Version**: 1.0 +**Application**: PunimTag Web + +--- + +*For technical details and development information, see the main README.md* +