149 lines
3.8 KiB
Markdown
149 lines
3.8 KiB
Markdown
# PunimTag
|
|
|
|
A minimal face tagging proof-of-concept that automatically groups similar faces in your photo collection using face recognition and clustering.
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. Place your photos in the `photos/` folder (subdirectories are supported)
|
|
|
|
2. Run the script:
|
|
|
|
```bash
|
|
python punimtag.py
|
|
```
|
|
|
|
3. The script will process all images and create a `faces.db` SQLite database
|
|
|
|
## Database Schema
|
|
|
|
The script creates three tables:
|
|
|
|
### `images` table
|
|
|
|
- `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:
|
|
|
|
```bash
|
|
sqlite3 faces.db
|
|
```
|
|
|
|
Example queries:
|
|
|
|
```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;
|
|
```
|
|
|
|
## How It Works
|
|
|
|
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)
|
|
|
|
## Limitations
|
|
|
|
- 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
|
|
|
|
## Next Steps
|
|
|
|
This minimal implementation can be extended with:
|
|
|
|
- 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
|
|
|
|
## License
|
|
|
|
[Your chosen license]
|