tanyar09
d300eb1122
This commit introduces several new files to enhance project organization and developer onboarding. The `.cursorignore` and `.cursorrules` files provide guidelines for Cursor AI, while `CONTRIBUTING.md` outlines contribution procedures. Additionally, `IMPORT_FIX_SUMMARY.md`, `RESTRUCTURE_SUMMARY.md`, and `STATUS.md` summarize recent changes and project status. The `README.md` has been updated to reflect the new project focus and structure, ensuring clarity for contributors and users. These additions aim to improve maintainability and facilitate collaboration within the PunimTag project.
215 lines
4.2 KiB
Markdown
215 lines
4.2 KiB
Markdown
# PunimTag
|
|
|
|
**Photo Management and Facial Recognition System**
|
|
|
|
A powerful desktop application for organizing and tagging photos using advanced facial recognition AI.
|
|
|
|
---
|
|
|
|
## 🎯 Features
|
|
|
|
- **Automated Face Detection**: Detect faces in your photos automatically
|
|
- **Person Identification**: Identify and tag people across your photo collection
|
|
- **Smart Auto-Matching**: Intelligent face matching with quality scoring
|
|
- **Advanced Search**: Search by people, dates, tags, and folders
|
|
- **Tag Management**: Organize photos with hierarchical tags
|
|
- **Batch Processing**: Process thousands of photos efficiently
|
|
- **Privacy-First**: All data stored locally by default
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Python 3.12 or higher
|
|
- pip package manager
|
|
- Virtual environment (recommended)
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd punimtag
|
|
|
|
# Create and activate virtual environment
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Running the Application
|
|
|
|
#### GUI Dashboard (Recommended)
|
|
```bash
|
|
python src/gui/dashboard_gui.py
|
|
```
|
|
|
|
#### CLI Interface
|
|
```bash
|
|
python src/photo_tagger.py --help
|
|
```
|
|
|
|
---
|
|
|
|
## 📖 Documentation
|
|
|
|
- **[Architecture](docs/ARCHITECTURE.md)**: System design and technical details
|
|
- **[Demo Guide](docs/DEMO.md)**: Step-by-step tutorial
|
|
- **[Dashboard Guide](docs/README_UNIFIED_DASHBOARD.md)**: GUI reference
|
|
- **[Contributing](CONTRIBUTING.md)**: How to contribute
|
|
|
|
---
|
|
|
|
## 🏗️ Project Structure
|
|
|
|
```
|
|
punimtag/
|
|
├── src/ # Source code
|
|
│ ├── core/ # Business logic
|
|
│ ├── gui/ # GUI components
|
|
│ └── utils/ # Utilities
|
|
├── tests/ # Test suite
|
|
├── docs/ # Documentation
|
|
├── .notes/ # Project notes
|
|
└── data/ # Application data
|
|
```
|
|
|
|
See [Directory Structure](.notes/directory_structure.md) for details.
|
|
|
|
---
|
|
|
|
## 🎮 Usage
|
|
|
|
### 1. Import Photos
|
|
```bash
|
|
# Add photos from a folder
|
|
python src/photo_tagger.py scan /path/to/photos
|
|
```
|
|
|
|
### 2. Process Faces
|
|
Open the dashboard and click "Process Photos" to detect faces.
|
|
|
|
### 3. Identify People
|
|
Use the "Identify" panel to tag faces with names.
|
|
|
|
### 4. Search
|
|
Use the "Search" panel to find photos by people, dates, or tags.
|
|
|
|
---
|
|
|
|
## 🔧 Configuration
|
|
|
|
Edit `src/core/config.py` to customize:
|
|
- Face detection model (HOG/CNN)
|
|
- Similarity tolerance
|
|
- Batch sizes
|
|
- Quality thresholds
|
|
|
|
---
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
python -m pytest tests/
|
|
|
|
# Run specific test
|
|
python tests/test_deepface_gui.py
|
|
```
|
|
|
|
---
|
|
|
|
## 🗺️ Roadmap
|
|
|
|
### Current (v1.0)
|
|
- ✅ Unified dashboard interface
|
|
- ✅ Face detection and identification
|
|
- ✅ Tag management system
|
|
- ✅ Advanced search
|
|
|
|
### Next (v1.1)
|
|
- 🔄 DeepFace migration (in progress)
|
|
- 🔄 Enhanced accuracy with ArcFace
|
|
- 📋 GPU acceleration
|
|
- 📋 Performance optimization
|
|
|
|
### Future
|
|
- Web interface
|
|
- Cloud storage integration
|
|
- Mobile app
|
|
- Video face detection
|
|
- Face clustering
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
|
|
### Quick Contribution Guide
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests
|
|
5. Submit a pull request
|
|
|
|
---
|
|
|
|
## 📊 Current Status
|
|
|
|
- **Version**: 1.0 (Development)
|
|
- **Face Recognition**: face_recognition library
|
|
- **Database**: SQLite
|
|
- **GUI**: Tkinter
|
|
- **Platform**: Cross-platform (Linux, Windows, macOS)
|
|
|
|
---
|
|
|
|
## 🐛 Known Issues
|
|
|
|
- Large databases (>50K photos) may experience slowdown
|
|
- Face recognition accuracy depends on photo quality
|
|
- No GPU acceleration yet
|
|
|
|
See [Task List](.notes/task_list.md) for all tracked issues.
|
|
|
|
---
|
|
|
|
## 📝 License
|
|
|
|
[Add your license here]
|
|
|
|
---
|
|
|
|
## 👥 Authors
|
|
|
|
PunimTag Development Team
|
|
|
|
---
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- face_recognition library by Adam Geitgey
|
|
- DeepFace library by serengil
|
|
- All contributors and users
|
|
|
|
---
|
|
|
|
## 📧 Contact
|
|
|
|
[Add contact information]
|
|
|
|
---
|
|
|
|
## ⭐ Star History
|
|
|
|
If you find this project useful, please consider giving it a star!
|
|
|
|
---
|
|
|
|
**Made with ❤️ for photo enthusiasts**
|
|
|