punimtag/docs/USER_GUIDE.md

PunimTag Web - User Guide

Complete guide to using the PunimTag web application

---

Table of Contents

1. Getting Started
2. Navigation Overview
3. Page-by-Page Guide
   • Login Page
   • Dashboard
   • Scan Page
   • Process Page
   • Identify Page
   • Auto-Match Page
   • Search Page
   • Modify Page
   • Tags Page
   • Faces Maintenance Page
   • Settings Page
4. Workflow Examples
5. Tips & Best Practices
6. 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