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.
This commit is contained in:
parent
049f9de4f8
commit
842f588f19
511
docs/USER_GUIDE.md
Normal file
511
docs/USER_GUIDE.md
Normal file
@ -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*
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user