# 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**