ilia/punimtag
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Pushing code to migrate git

Browse Source
This commit is contained in:
ilia
2025-08-15 00:57:39 -08:00
parent 53f3e8a44d
commit 455bdac187
50 changed files with 14761 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+104 -116
View File
@@ -1,148 +1,136 @@
# PunimTag
# PunimTag - Intelligent Photo Management System
A minimal face tagging proof-of-concept that automatically groups similar faces in your photo collection using face recognition and clustering.
A Flask-based photo management system with automatic face recognition, tagging, and duplicate detection.
## What it does
PunimTag scans a folder of photos, detects all faces, and automatically groups similar faces together. It:
1. **Walks through your photos folder** - Processes all `.jpg` and `.png` files
2. **Detects faces** - Finds all faces in each image using dlib's face detection
3. **Creates face encodings** - Generates 128-dimensional face embeddings for each detected face
4. **Clusters similar faces** - Uses HDBSCAN clustering to group similar faces together
5. **Stores results in SQLite** - Saves everything to a `faces.db` database for easy querying
## Prerequisites
- Python 3.8+
- CMake (required for dlib installation)
- A `photos/` folder with your images
## Installation
1. Clone this repository:
```bash
git clone <repository-url>
cd PunimTag
```
2. Create and activate a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install CMake if not already installed:
```bash
# Ubuntu/Debian
sudo apt-get install cmake
# macOS
brew install cmake
# Windows
# Download from https://cmake.org/download/
```
4. Install Python dependencies:
## 🚀 Quick Start
```bash
# Install dependencies
pip install -r requirements.txt
# Run the application
python main.py
# Access the web interface
# http://localhost:5000
```
## Usage
## 📁 Project Structure
1. Place your photos in the `photos/` folder (subdirectories are supported)
```
PunimTag/
├── src/ # Main application source code
│ ├── backend/ # Flask backend and API
│ │ ├── app.py # Main Flask application
│ │ ├── db_manager.py # Database operations
│ │ └── visual_identifier.py # Face recognition
│ ├── frontend/ # JavaScript and UI components
│ └── utils/ # Utility functions
│ └── tag_manager.py # Tag management
├── docs/ # Documentation and steering documents
│ ├── product.md # Product vision and goals
│ ├── structure.md # Project organization
│ ├── tech.md # Technical architecture
│ ├── api-standards.md # API design standards
│ ├── testing-standards.md # Testing guidelines
│ └── code-conventions.md # Coding standards
├── tests/ # Test files
│ ├── test_main.py # Main test suite
│ └── conftest.py # Test configuration
├── data/ # Database files and user data
├── config/ # Configuration files
│ ├── settings.py # Application settings
│ └── punimtag_config.json
├── scripts/ # Utility scripts
├── assets/ # Static assets
├── photos/ # User photo storage
└── main.py # Application entry point
```
2. Run the script:
## 🎯 Key Features
- **Automatic Face Recognition**: Identify and tag people in photos
- **Smart Organization**: Group photos by people, events, and locations
- **Duplicate Detection**: Find and manage duplicate photos automatically
- **Intuitive Interface**: Web-based GUI with progressive loading
- **Privacy-First**: Local processing, no cloud dependencies
## 📚 Documentation
### Steering Documents
- **[Product Vision](docs/product.md)**: Product goals, target users, and roadmap
- **[Project Structure](docs/structure.md)**: Architecture and organization principles
- **[Technical Architecture](docs/tech.md)**: Technology stack and implementation details
- **[API Standards](docs/api-standards.md)**: API design and development guidelines
- **[Testing Standards](docs/testing-standards.md)**: Testing strategy and best practices
- **[Code Conventions](docs/code-conventions.md)**: Coding standards and style guides
### Development Guidelines
1. **Follow the steering documents** for consistent development
2. **Use the organized structure** - place code in appropriate directories
3. **Write tests** following the testing standards
4. **Follow API standards** for all endpoints
5. **Adhere to code conventions** for maintainability
## 🧪 Testing
```bash
python punimtag.py
# Run the main test suite
python tests/test_main.py
# Run with pytest (if installed)
pytest tests/
```
3. The script will process all images and create a `faces.db` SQLite database
## 🔧 Configuration
## Database Schema
Configuration is centralized in `config/settings.py`:
The script creates three tables:
- Database paths
- Face recognition settings
- File upload limits
- Thumbnail sizes
### `images` table
## 🚀 Deployment
- `id`: Primary key
- `path`: File path to the image
### `faces` table
- `id`: Primary key
- `image_id`: Foreign key to images table
- `location`: Face bounding box coordinates as string
- `encoding`: 128-dimensional face encoding (stored as BLOB)
- `cluster_id`: Foreign key to clusters table (NULL for unclustered faces)
### `clusters` table
- `id`: Primary key
- `label`: Cluster label (e.g., "Cluster 0", "Cluster 1")
## Querying the Database
You can explore the results using any SQLite client:
### Development
```bash
sqlite3 faces.db
python main.py
```
Example queries:
### Production
```sql
-- Count faces per image
SELECT i.path, COUNT(f.id) as face_count
FROM images i
LEFT JOIN faces f ON i.id = f.image_id
GROUP BY i.path;
-- Find all images containing faces from a specific cluster
SELECT DISTINCT i.path
FROM images i
JOIN faces f ON i.id = f.image_id
WHERE f.cluster_id = 1;
-- Count faces per cluster
SELECT c.label, COUNT(f.id) as face_count
FROM clusters c
JOIN faces f ON c.id = f.cluster_id
GROUP BY c.id;
```bash
# Use a WSGI server like Gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 main:app
```
## How It Works
## 📦 Dependencies
1. **Face Detection**: Uses HOG-based face detection from dlib to find face locations
2. **Face Encoding**: Generates a 128-dimensional vector for each face using a pre-trained neural network
3. **Clustering**: HDBSCAN (Hierarchical Density-Based Spatial Clustering of Applications with Noise) groups similar face encodings together
- Faces with similar encodings are grouped into the same cluster
- Faces that don't match any cluster well are marked as noise (cluster_id = NULL)
- **Flask**: Web framework
- **SQLite**: Database
- **dlib**: Face recognition
- **Pillow**: Image processing
- **NumPy**: Numerical operations
## Limitations
## 🤝 Contributing
- This is a proof-of-concept with minimal error handling
- Face detection may miss faces in poor lighting or at extreme angles
- Clustering quality depends on having multiple photos of the same person
- No GUI - results must be queried from the database
1. Read the steering documents in `docs/`
2. Follow the code conventions
3. Write tests for new features
4. Update documentation as needed
## Next Steps
## 📄 License
This minimal implementation can be extended with:
This project is licensed under the MIT License.
- A web interface for viewing clustered faces
- Better error handling and logging
- Support for more image formats
- Face recognition (matching against known individuals)
- Incremental processing of new photos
- Export functionality for organized photo albums
## 🆘 Support
## License
For issues and questions:
[Your chosen license]
1. Check the steering documents in `docs/`
2. Review existing tests in `tests/`
3. Check the API standards for endpoint usage