diff --git a/README.md b/README.md index fd9bf2b..119c81f 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,12 @@ A fast, simple, and modern web application for organizing and tagging photos usi - **🎨 Flexible Models**: Select ArcFace, Facenet, Facenet512, or VGG-Face recognition models - **πŸ‘€ Person Identification**: Identify and tag people across your photo collection - **πŸ€– Smart Auto-Matching**: Intelligent face matching with quality scoring and cosine similarity +- **πŸ“Š Confidence Calibration**: Empirical-based confidence scores for realistic match probabilities - **πŸ” Advanced Search**: Search by people, dates, tags, and folders - **🏷️ Tag Management**: Organize photos with hierarchical tags - **⚑ Batch Processing**: Process thousands of photos efficiently +- **🎯 Unique Faces Filter**: Hide duplicate faces to focus on unique individuals +- **πŸ”„ Real-time Updates**: Live progress tracking and job status updates - **πŸ”’ Privacy-First**: All data stored locally, no cloud dependencies --- @@ -156,23 +159,9 @@ Then open your browser to **http://localhost:3000** ## πŸ“– Documentation - **[Architecture](docs/ARCHITECTURE.md)**: System design and technical details -- **[Web Migration Plan](docs/WEBSITE_MIGRATION_PLAN.md)**: Detailed migration roadmap -- **[Phase 1 Status](docs/PHASE1_FOUNDATION_STATUS.md)**: Phase 1 implementation status -- **[Phase 1 Checklist](docs/PHASE1_CHECKLIST.md)**: Complete Phase 1 checklist -**Phase 2 Features:** -- Photo import via folder scan or file upload -- Background processing with progress tracking -- Real-time job status updates (SSE) -- Duplicate detection by checksum -- EXIF metadata extraction -- DeepFace face detection and recognition pipeline -- Configurable detectors (RetinaFace, MTCNN, OpenCV, SSD) -- Configurable models (ArcFace, Facenet, Facenet512, VGG-Face) -- Process tab UI for face processing -- Job cancellation support ---- +* ## πŸ—οΈ Project Structure @@ -204,7 +193,7 @@ punimtag/ ## πŸ“Š Current Status -### Phase 1: Foundations βœ… **COMPLETE** +### Foundations **Backend:** - βœ… FastAPI application with CORS middleware @@ -230,7 +219,7 @@ punimtag/ - βœ… Indices configured for performance - βœ… SQLite database at `data/punimtag.db` (auto-created if missing) -### Phase 2: Image Ingestion & Processing βœ… **COMPLETE** +### Image Ingestion & Processing **Backend:** - βœ… Photo import service with checksum computation @@ -272,13 +261,45 @@ punimtag/ - βœ… Graceful shutdown handling - βœ… **String-based function paths for reliable serialization** -### Next: Phase 3 - Identify Workflow & Auto-Match +### Identify Workflow & Auto-Match -- Identify workflow UI -- Auto-match engine with similarity thresholds -- Unidentified faces management -- Person creation and linking -- Batch identification support +**Backend:** +- βœ… Identify face endpoints with person creation +- βœ… Auto-match engine with similarity thresholds +- βœ… Unidentified faces management and filtering +- βœ… Person creation and linking +- βœ… Batch identification support +- βœ… Similar faces search with cosine similarity +- βœ… Confidence calibration system (empirical-based) +- βœ… Face unmatch/removal functionality +- βœ… Batch similarity calculations + +**Frontend:** +- βœ… Identify page UI with face navigation +- βœ… Person creation and editing +- βœ… Similar faces panel with confidence display +- βœ… Auto-Match page with person-centric view +- βœ… Checkbox selection for batch identification +- βœ… Confidence percentages with color coding +- βœ… Unique faces filter (hide duplicates) +- βœ… Date filtering for faces +- βœ… Real-time face matching and display + +### PSearch & Tags + +**Backend:** +- βœ… Search endpoints with filters (people, dates, tags, folders) +- βœ… Tag management endpoints (create, update, delete) +- βœ… Photo-tag linkage system +- βœ… Advanced filtering and querying +- βœ… Photo grid endpoints with pagination + +**Frontend:** +- βœ… Search page with advanced filters +- βœ… Tag management UI +- βœ… Photo grid with virtualized rendering +- βœ… Filter by people, dates, tags, and folders +- βœ… Search results display --- @@ -316,60 +337,14 @@ PHOTO_STORAGE_DIR=data/uploads --- -## πŸ§ͺ Testing - -```bash -# Backend tests (to be implemented) -cd /home/ladmin/Code/punimtag -source venv/bin/activate -export PYTHONPATH=/home/ladmin/Code/punimtag -pytest tests/ - -# Frontend tests (to be implemented) -cd frontend -npm test -``` --- -## πŸ—ΊοΈ Roadmap - -### βœ… Phase 1: Foundations (Complete) -- FastAPI backend scaffold -- React frontend scaffold -- Authentication system -- Database setup -- Basic API endpoints - -### βœ… Phase 2: Image Ingestion & Processing (Complete) -- βœ… Photo import (folder scan and file upload) -- βœ… Background job processing with RQ -- βœ… Real-time progress tracking via SSE -- βœ… Scan tab UI implementation -- βœ… Duplicate detection and metadata extraction -- βœ… DeepFace face detection and processing pipeline -- βœ… Process tab UI with configuration controls -- βœ… Configurable detectors and models -- βœ… Face processing with progress tracking -- βœ… Job cancellation support - -### πŸ”„ Phase 3: Identify Workflow & Auto-Match (In Progress) -- Identify workflow UI -- Auto-match engine with similarity thresholds -- Unidentified faces management -- Person creation and linking - -### πŸ“‹ Phase 4: Search & Tags -- Search endpoints with filters -- Tag management UI -- Virtualized photo grid -- Advanced filtering - -### 🎨 Phase 5: Polish & Release +### πŸ”„ Phase 5: Polish & Release (In Progress) - Performance optimization - Accessibility improvements - Production deployment -- Documentation +- Documentation updates --- @@ -436,10 +411,11 @@ npm test - Single-user mode only (multi-user support planned) - SQLite for development (PostgreSQL recommended for production) - No password hashing yet (plain text comparison - fix before production) -- GPU acceleration not yet implemented +- GPU acceleration not yet implemented (CPU-only for now) - Large databases (>50K photos) may require optimization -- DeepFace model downloads on first use (can take 5-10 minutes) -- Face processing is CPU-intensive (GPU support planned for future) +- DeepFace model downloads on first use (can take 5-10 minutes, ~100MB) +- Face processing is CPU-intensive (~2-3x slower than face_recognition, but more accurate) +- First run is slower due to model downloads (subsequent runs are faster) --- @@ -455,6 +431,8 @@ PunimTag Development Team --- + + ## πŸ™ Acknowledgments - **DeepFace** library by Sefik Ilkin Serengil - Modern face recognition framework @@ -468,12 +446,10 @@ PunimTag Development Team For questions or issues: 1. Check documentation in `docs/` -2. See [Phase 1 Checklist](docs/PHASE1_CHECKLIST.md) for implementation status -3. Review [Migration Plan](docs/WEBSITE_MIGRATION_PLAN.md) for roadmap + --- **Made with ❀️ for photo enthusiasts** -*For the desktop version, see [README_DESKTOP.md](README_DESKTOP.md)*