307 lines
8.2 KiB
Markdown
307 lines
8.2 KiB
Markdown
# PunimTag CLI - Minimal Photo Face Tagger
|
|
|
|
A simple command-line tool for automatic face recognition and photo tagging. No web interface, no complex dependencies - just the essentials.
|
|
|
|
## 🚀 Quick Start
|
|
|
|
```bash
|
|
# 1. Setup (one time only)
|
|
git clone <your-repo>
|
|
cd PunimTag
|
|
python3 -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
python3 setup.py
|
|
|
|
# 2. Scan photos
|
|
python3 photo_tagger.py scan /path/to/your/photos
|
|
|
|
# 3. Process faces
|
|
python3 photo_tagger.py process
|
|
|
|
# 4. Identify faces with visual display
|
|
python3 photo_tagger.py identify --show-faces
|
|
|
|
# 5. Auto-match faces across photos
|
|
python3 photo_tagger.py auto-match --show-faces
|
|
|
|
# 6. View statistics
|
|
python3 photo_tagger.py stats
|
|
```
|
|
|
|
## 📦 Installation
|
|
|
|
### Automatic Setup (Recommended)
|
|
```bash
|
|
# Clone and setup
|
|
git clone <your-repo>
|
|
cd PunimTag
|
|
|
|
# Create virtual environment (IMPORTANT!)
|
|
python3 -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
|
|
# Run setup script
|
|
python3 setup.py
|
|
```
|
|
|
|
**⚠️ IMPORTANT**: Always activate the virtual environment before running any commands:
|
|
```bash
|
|
source venv/bin/activate # Run this every time you open a new terminal
|
|
```
|
|
|
|
### Manual Setup (Alternative)
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
python3 photo_tagger.py stats # Creates database
|
|
```
|
|
|
|
## 🎯 Commands
|
|
|
|
### Scan for Photos
|
|
```bash
|
|
# Scan a folder
|
|
python3 photo_tagger.py scan /path/to/photos
|
|
|
|
# Scan recursively (recommended)
|
|
python3 photo_tagger.py scan /path/to/photos --recursive
|
|
```
|
|
|
|
### Process Photos for Faces
|
|
```bash
|
|
# Process 50 photos (default)
|
|
python3 photo_tagger.py process
|
|
|
|
# Process 20 photos with CNN model (more accurate)
|
|
python3 photo_tagger.py process --limit 20 --model cnn
|
|
|
|
# Process with HOG model (faster)
|
|
python3 photo_tagger.py process --limit 100 --model hog
|
|
```
|
|
|
|
### Identify Faces (Enhanced!)
|
|
```bash
|
|
# Identify with individual face display (RECOMMENDED)
|
|
python3 photo_tagger.py identify --show-faces --batch 10
|
|
|
|
# Traditional mode (coordinates only)
|
|
python3 photo_tagger.py identify --batch 10
|
|
|
|
# Auto-match faces across photos (NEW!)
|
|
python3 photo_tagger.py auto-match --show-faces
|
|
|
|
# Auto-identify high-confidence matches
|
|
python3 photo_tagger.py auto-match --auto --show-faces
|
|
```
|
|
|
|
**Enhanced identification features:**
|
|
- 🖼️ **Individual face crops** - See exactly which face you're identifying
|
|
- 🔍 **Side-by-side comparisons** - Visual matching across photos
|
|
- 📊 **Confidence scoring** - Know how similar faces are
|
|
- 🎯 **Smart cross-photo matching** - Find same people in different photos
|
|
- 🧹 **Auto cleanup** - No temporary files left behind
|
|
|
|
**Interactive commands:**
|
|
- Type person's name to identify
|
|
- `s` = skip this face
|
|
- `q` = quit
|
|
- `list` = show known people
|
|
|
|
### Add Tags
|
|
```bash
|
|
# Tag photos matching pattern
|
|
python3 photo_tagger.py tag --pattern "vacation"
|
|
|
|
# Tag any photos
|
|
python3 photo_tagger.py tag
|
|
```
|
|
|
|
### Search
|
|
```bash
|
|
# Find photos with a person
|
|
python3 photo_tagger.py search "John"
|
|
|
|
# Find photos with partial name match
|
|
python3 photo_tagger.py search "Joh"
|
|
```
|
|
|
|
### Statistics
|
|
```bash
|
|
# View database statistics
|
|
python3 photo_tagger.py stats
|
|
```
|
|
|
|
## 📊 Enhanced Example Workflow
|
|
|
|
```bash
|
|
# ALWAYS activate virtual environment first!
|
|
source venv/bin/activate
|
|
|
|
# 1. Scan your photo collection
|
|
python3 photo_tagger.py scan ~/Pictures --recursive
|
|
|
|
# 2. Process photos for faces (start with small batch)
|
|
python3 photo_tagger.py process --limit 20
|
|
|
|
# 3. Check what we found
|
|
python3 photo_tagger.py stats
|
|
|
|
# 4. Identify faces with visual display (ENHANCED!)
|
|
python3 photo_tagger.py identify --show-faces --batch 10
|
|
|
|
# 5. Auto-match faces across photos (NEW!)
|
|
python3 photo_tagger.py auto-match --show-faces
|
|
|
|
# 6. Search for photos of someone
|
|
python3 photo_tagger.py search "Alice"
|
|
|
|
# 7. Add some tags
|
|
python3 photo_tagger.py tag --pattern "birthday"
|
|
```
|
|
|
|
## 🗃️ Database
|
|
|
|
The tool uses SQLite database (`photos.db` by default) with these tables:
|
|
- **photos** - Photo file paths and processing status
|
|
- **people** - Known people names
|
|
- **faces** - Face encodings and locations
|
|
- **tags** - Custom tags for photos
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### Face Detection Models
|
|
- **hog** - Faster, good for CPU-only systems
|
|
- **cnn** - More accurate, requires more processing power
|
|
|
|
### Database Location
|
|
```bash
|
|
# Use custom database file
|
|
python3 photo_tagger.py scan /photos --db /path/to/my.db
|
|
```
|
|
|
|
## 🔧 System Requirements
|
|
|
|
### Required System Packages (Ubuntu/Debian)
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install -y cmake build-essential libopenblas-dev liblapack-dev libx11-dev libgtk-3-dev python3-dev python3-venv
|
|
```
|
|
|
|
### Python Dependencies
|
|
- `face-recognition` - Face detection and recognition
|
|
- `dlib` - Machine learning library
|
|
- `pillow` - Image processing
|
|
- `numpy` - Numerical operations
|
|
- `click` - Command line interface
|
|
- `setuptools` - Package management
|
|
|
|
## 📁 File Structure
|
|
|
|
```
|
|
PunimTag/
|
|
├── photo_tagger.py # Main CLI tool
|
|
├── setup.py # Setup script
|
|
├── run.sh # Convenience script (auto-activates venv)
|
|
├── requirements.txt # Python dependencies
|
|
├── README.md # This file
|
|
├── venv/ # Virtual environment (created by setup)
|
|
├── photos.db # Database (created automatically)
|
|
├── data/ # Additional data files
|
|
└── logs/ # Log files
|
|
```
|
|
|
|
## 🚨 Troubleshooting
|
|
|
|
### "externally-managed-environment" Error
|
|
**Solution**: Always use a virtual environment!
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
python3 setup.py
|
|
```
|
|
|
|
### Virtual Environment Not Active
|
|
**Problem**: Commands fail or use wrong Python
|
|
**Solution**: Always activate the virtual environment:
|
|
```bash
|
|
source venv/bin/activate
|
|
# You should see (venv) in your prompt
|
|
```
|
|
|
|
### dlib Installation Issues
|
|
```bash
|
|
# Ubuntu/Debian - install system dependencies first
|
|
sudo apt-get install build-essential cmake libopenblas-dev
|
|
|
|
# Then retry setup
|
|
source venv/bin/activate
|
|
python3 setup.py
|
|
```
|
|
|
|
### "Please install face_recognition_models" Warning
|
|
This warning is harmless - the application still works correctly. It's a known issue with Python 3.13.
|
|
|
|
### Memory Issues
|
|
- Use `--model hog` for faster processing
|
|
- Process in smaller batches with `--limit 10`
|
|
- Close other applications to free memory
|
|
|
|
### No Faces Found
|
|
- Check image quality and lighting
|
|
- Ensure faces are clearly visible
|
|
- Try `--model cnn` for better detection
|
|
|
|
## 🎯 What This Tool Does
|
|
|
|
✅ **Simple**: Single Python file, minimal dependencies
|
|
✅ **Fast**: Efficient face detection and recognition
|
|
✅ **Private**: Everything runs locally, no cloud services
|
|
✅ **Flexible**: Batch processing, interactive identification
|
|
✅ **Lightweight**: No web interface overhead
|
|
|
|
## 📈 Performance Tips
|
|
|
|
- **Always use virtual environment** to avoid conflicts
|
|
- Start with small batches (`--limit 20`) to test
|
|
- Use `hog` model for speed, `cnn` for accuracy
|
|
- Process photos in smaller folders first
|
|
- Identify faces in batches to avoid fatigue
|
|
|
|
## 🤝 Contributing
|
|
|
|
This is now a minimal, focused tool. Key principles:
|
|
- Keep it simple and fast
|
|
- CLI-only interface
|
|
- Minimal dependencies
|
|
- Clear, readable code
|
|
- **Always use python3** commands
|
|
|
|
---
|
|
|
|
**Total project size**: ~300 lines of Python code
|
|
**Dependencies**: 6 essential packages
|
|
**Setup time**: ~5 minutes
|
|
**Perfect for**: Batch processing personal photo collections
|
|
|
|
## 🔄 Common Commands Cheat Sheet
|
|
|
|
```bash
|
|
# Setup (one time)
|
|
python3 -m venv venv && source venv/bin/activate && python3 setup.py
|
|
|
|
# Daily usage - Option 1: Use run script (automatic venv activation)
|
|
./run.sh scan ~/Pictures --recursive
|
|
./run.sh process --limit 50
|
|
./run.sh identify --show-faces --batch 10
|
|
./run.sh auto-match --show-faces
|
|
./run.sh stats
|
|
|
|
# Daily usage - Option 2: Manual venv activation (ENHANCED)
|
|
source venv/bin/activate
|
|
python3 photo_tagger.py scan ~/Pictures --recursive
|
|
python3 photo_tagger.py process --limit 50
|
|
python3 photo_tagger.py identify --show-faces --batch 10
|
|
python3 photo_tagger.py auto-match --show-faces
|
|
python3 photo_tagger.py stats
|
|
``` |