face-search 0.2.0

AI-powered face search for photo libraries

🔍 face-search

Find photos of anyone in your library — in seconds.

AI-powered face search that actually works. No cloud. No subscriptions. Just results.

Installation • Quick Start • GUI Guide • CLI Reference • Python API

---

🎬 The Problem

You have 50,000+ photos. Your mom asks: "Can you find all photos of grandma from the last 10 years?"

Without face-search: Hours of manual scrolling 😫
With face-search: 30 seconds ⚡

pip install face-search
face-search build ~/Photos
face-search search --ref ./grandma_photo.jpg
# Done. ✅

---

🏗️ How It Works

┌─────────────────────────────────────────────────────────────────────────────┐
│                           face-search Architecture                          │
└─────────────────────────────────────────────────────────────────────────────┘

  📁 Your Photos              🔍 Reference Photo            🎯 Results
  ─────────────              ──────────────────            ──────────
       │                            │                           ▲
       ▼                            ▼                           │
┌─────────────┐              ┌─────────────┐                    │
│   BUILD     │              │   SEARCH    │                    │
│   Phase     │              │   Phase     │                    │
└──────┬──────┘              └──────┬──────┘                    │
       │                            │                           │
       ▼                            ▼                           │
┌─────────────┐              ┌─────────────┐              ┌─────┴─────┐
│    Face     │              │    Face     │              │   FAISS   │
│  Detection  │              │  Detection  │              │  Nearest  │
│  (OpenCV)   │              │  (OpenCV)   │              │ Neighbor  │
└──────┬──────┘              └──────┬──────┘              │  Search   │
       │                            │                     └─────┬─────┘
       ▼                            ▼                           ▲
┌─────────────┐              ┌─────────────┐                    │
│  FaceNet512 │              │  FaceNet512 │                    │
│  Embedding  │              │  Embedding  │                    │
│  (512-dim)  │              │  (512-dim)  │                    │
└──────┬──────┘              └──────┬──────┘                    │
       │                            │                           │
       ▼                            └───────────────────────────┘
┌─────────────┐
│   FAISS     │
│   Index     │◄─── Persisted to disk (face_index.faiss)
│  (L2 dist)  │
└─────────────┘

🧠 The Tech Stack

Component	Technology	Why
Face Detection	OpenCV / RetinaFace	Fast + accurate bounding boxes
Face Embeddings	FaceNet512	512-dim vectors, 98.4% accuracy
Vector Search	FAISS	Handles 1M+ vectors, sub-second search
Multi-Ref Fusion	Average Distance	Multiple photos = stricter matching
GUI	Gradio	Beautiful web UI, zero config

🔬 Multi-Reference Magic

When you provide multiple reference photos, face-search doesn't just look for matches to ANY of them — it requires matches to ALL of them:

Single Reference Photo:
┌─────────┐
│  Photo  │──────► Search ──────► Results (may include false positives)
└─────────┘

Multiple Reference Photos (RECOMMENDED):
┌─────────┐
│ Photo 1 │───┐
└─────────┘   │
┌─────────┐   │    ┌─────────────┐
│ Photo 2 │───┼───►│   Average   │──────► Results (much more accurate!)
└─────────┘   │    │  Distance   │
┌─────────┐   │    └─────────────┘
│ Photo 3 │───┘         │
└─────────┘             │
                        ▼
              Must match ALL refs
              to score well

Why this works:

• Person A might look like Person B from one angle
• But Person A WON'T look like Person B from ALL angles
• Multiple angles = unique "face signature"

---

✨ Why face-search?

The Killer Use Case:

"Find every photo of grandma from 50,000 photos in 30 seconds"

🆚 face-search vs. The Alternatives

Feature	face-search	Google Photos	Apple Photos	Amazon Photos
Cost	Free forever	Free (15GB) / $3+/mo	Free (5GB) / $1+/mo	Free (5GB) / $2+/mo
Privacy	100% local	Trains AI on your photos	Cloud sync	Cloud sync
Works Offline	✅ Always	❌ Needs internet	⚠️ Limited	❌ Needs internet
Own Your Data	✅ Full control	❌ Locked in	⚠️ Export pain	❌ Locked in
Custom Threshold	✅ Tunable	❌ Fixed	❌ Fixed	❌ Fixed
CLI Automation	✅ Full scripting	❌ None	❌ None	❌ None
Multi-Reference	✅ Average fusion	❌ Single face	❌ Single face	❌ Single face

🌟 What Makes It Special

🚀 Zero Setup pip install face-search # That's it. No Docker, no databases, # no API keys, no cloud accounts.	⚡ Blazing Fast Index: 1,000 photos/minute Search: <100ms for 100k faces Storage: ~2KB per face
🔒 100% Private Everything runs locally. Your photos never leave your machine. No internet required after install.	🎯 Accurate FaceNet512: 98.4% accuracy Multiple detectors available Tunable thresholds

🧠 Smart Features

Feature	What It Does	Why It Matters
Multi-Reference Fusion	Uses 3+ photos to create a "face signature"	Dramatically reduces false positives
Labels System	Save faces with names, search by name forever	"Find all photos of Dad" — one click
Co-occurrence Intelligence	Tracks who appears together in photos	"Mom + Dad always together" = higher confidence
Incremental Indexing	Add new photos without re-indexing everything	Perfect for growing libraries
CLI + GUI + Python API	Three ways to use it	Works for everyone — tech-savvy or not

---

📦 Installation

# Basic install
pip install face-search

# With GUI support (recommended)
pip install face-search[gui]

System Requirements

• Python: 3.8+
• RAM: 4GB minimum, 8GB recommended
• Disk: ~50MB + index size (2KB per face)
• OS: macOS, Linux, Windows

---

🚀 Quick Start

3 Commands to Find Anyone

# 1️⃣ Put reference photo(s) in a folder
mkdir reference_faces
cp photo_of_person.jpg reference_faces/

# 2️⃣ Build index from your photo library (one-time)
face-search build ~/Photos

# 3️⃣ Search!
face-search search

Output:

🔍 Searching for faces...
Found 47 matches:

  /Photos/2023/vacation/beach_001.jpg (distance: 0.312)
  /Photos/2022/birthday/party_042.jpg (distance: 0.387)
  /Photos/2021/christmas/family_003.jpg (distance: 0.401)
  ...

---

🎨 GUI Guide

The GUI provides a complete visual workflow for face search.

Launch

pip install face-search[gui]
face-search gui

Opens at http://localhost:7860

GUI Workflow

┌─────────────────────────────────────────────────────────────────┐
│                     face-search GUI                              │
├─────────────┬─────────────┬─────────────┬───────────────────────┤
│ 1️⃣ Build    │ 2️⃣ Reference │ 3️⃣ Search   │ 4️⃣ Export             │
│   Index     │   Photos     │   Results   │   Results             │
└─────────────┴─────────────┴─────────────┴───────────────────────┘

Tab 1: Build Index

Configure and build your face index:

Setting	Description	Recommendation
Directory Path	Your photo library	/Users/you/Photos
Detector	Face detection model	opencv (fast) or retinaface (accurate)
Workers	Parallel processing	4-8 for faster indexing
Max Size	Image resize	1280 (balanced) or 0 (best quality)
Incremental	Add to existing	✅ Keep checked to add new photos

Tab 2: Reference Photos

Upload photos of the person you're searching for:

• Drag & drop multiple photos
• Use 2-3 photos from different angles
• Good lighting helps accuracy
• Photos are cached automatically

💡 Multi-Reference Enhancement: When you upload multiple photos, face-search combines them intelligently. A photo must match ALL your references to score well, dramatically reducing false positives. More references = stricter matching!

Tab 3: Search

Find matches in your library:

Setting	Range	Use Case
Threshold 0.3	Very strict	Only near-identical
Threshold 0.5	Balanced	Same person, different photos
Threshold 0.7	Lenient	Different angles/lighting

Features:

• 📄 Pagination - Browse all results (50 per page)
• 🖼️ Preview - Click any image to enlarge
• 📊 Distance scores - Lower = better match

Tab 4: Export

Export your results:

Format	Output	Use Case
TXT	One path per line	Import to other tools
JSON	Paths + distances	Programmatic use
Shell	cp commands	Copy files to folder

---

💻 CLI Reference

build - Index Your Photos

# Basic
face-search build /path/to/photos

# Fast mode (smaller images, more workers)
face-search build /path/to/photos --max-size 640 --workers 8

# Best quality (no resize, accurate detector)
face-search build /path/to/photos --max-size 0 --detector retinaface

# Add new photos to existing index
face-search build /path/to/new/photos --incremental

# Skip tiny faces (faster, cleaner results)
face-search build /path/to/photos --min-face-size 40

All Options:

Option	Default	Description
--detector	opencv	opencv, ssd, mtcnn, retinaface
--conf	0.3	Min detection confidence (0-1)
--max-size	1280	Max image dimension (0 = no resize)
--workers	auto	Parallel workers
--incremental	true	Only index new files
--min-face-size	0	Skip faces smaller than N pixels
--index	./face_index.faiss	Index file location

search - Find Faces

# Basic search
face-search search

# Strict matching (fewer false positives)
face-search search --threshold 0.3

# Get more results
face-search search --top 500

# Save to file
face-search search --output-file matches.txt

# Copy matched photos to folder
face-search search --copy --output ./my_matches

All Options:

Option	Default	Description
--ref	./reference_faces	Reference photos directory
--threshold	0.5	Distance threshold (lower = stricter)
--top	100	Max results per reference
--output-file	-	Save paths to text file
--copy	false	Copy matches to output folder
--output	./matches	Output folder for --copy

info - Show Index Stats

face-search info

Output:

📊 Index Statistics
═══════════════════════════════════
  Total Faces:    32,450
  Unique Images:  18,234
  Index Size:     64.2 MB
  
📁 Sources:
  • /Users/you/Photos (28,000 faces)
  • /Volumes/Backup/Old Photos (4,450 faces)

gui - Launch Web Interface

face-search gui                    # Default port 7860
face-search gui --port 8080        # Custom port
face-search gui --share            # Create public link

---

🐍 Python API

Basic Usage

from face_search import FaceFinder

# Initialize
finder = FaceFinder()

# Build index from photos
finder.build("/path/to/photos")

# Load reference faces
finder.load_references("./reference_faces")

# Search
matches = finder.search(threshold=0.5, top_k=100)

# Process results
for match in matches:
    print(f"{match.file_path} (distance: {match.distance:.3f})")

Advanced Configuration

from face_search import FaceFinder
from face_search.detectors import DetectorFactory
from face_search.embedders import EmbedderFactory

# Custom detector
detector = DetectorFactory.create("retinaface")

# Initialize with custom components
finder = FaceFinder(
    detector=detector,
    min_confidence=0.5,
    index_file="./custom_index.faiss"
)

# Build with options
finder.build(
    "/path/to/photos",
    max_size=0,           # No resize
    workers=8,            # Parallel processing
    incremental=True,     # Add to existing
    min_face_size=40      # Skip tiny faces
)

Batch Processing

from face_search import FaceFinder

finder = FaceFinder()
finder.load()  # Load existing index

# Multiple search sessions
for ref_dir in ["./person1", "./person2", "./person3"]:
    finder.load_references(ref_dir)
    matches = finder.search(threshold=0.5)
    
    print(f"\n{ref_dir}: {len(matches)} matches")
    for m in matches[:5]:
        print(f"  {m.file_name} ({m.distance:.3f})")

---

⚡ Performance Guide

Speed vs Accuracy Tradeoffs

                    SPEED ◄─────────────────────────────► ACCURACY
                    
  --max-size 640          --max-size 1280           --max-size 0
  --detector opencv       --detector ssd            --detector retinaface
  --workers 8             --workers 4               --workers 1
  --min-face-size 60      --min-face-size 40        --min-face-size 0
  
  ⚡ ~15 img/sec          ⚖️ ~6 img/sec              🎯 ~2 img/sec

Recommended Presets

# 🚀 FAST - Quick scan, good enough quality
face-search build ~/Photos --max-size 640 --workers 8 --min-face-size 50

# ⚖️ BALANCED - Default, works for most cases  
face-search build ~/Photos

# 🎯 ACCURATE - Best quality, slower
face-search build ~/Photos --max-size 0 --detector retinaface

# 📈 LARGE LIBRARY - For 100k+ photos
face-search build ~/Photos --max-size 1024 --workers 8 --incremental

Performance Tips

Tip	Impact	How
Use SSD	2-3x faster	Store photos on SSD, not HDD
Resize images	2x faster	--max-size 640
Skip tiny faces	10-30% faster	--min-face-size 40
Parallel workers	4-8x faster	--workers 8
Incremental builds	Huge for updates	--incremental

---

🎯 Threshold Guide

The threshold controls how strict matching is (lower = stricter):

Distance
   │
0.2├─────────── Nearly identical (same photo, minor edit)
   │
0.3├─────────── Very confident match
   │             └─ Use for: Exact person identification
0.4├───────────
   │
0.5├─────────── Good match (DEFAULT)
   │             └─ Use for: General face search
0.6├───────────
   │
0.7├─────────── Possible match
   │             └─ Use for: Different angles/lighting
0.8├───────────
   │
0.9├─────────── Weak match (may include false positives)
   │
1.0├─────────── Very different faces

---

🔧 Troubleshooting

No faces detected

# Try more accurate detector
face-search build ~/Photos --detector retinaface

# Lower confidence threshold
face-search build ~/Photos --conf 0.2

# Check image quality - blurry/dark photos are harder

Too many false positives

# Lower threshold (stricter)
face-search search --threshold 0.3

# Use more reference photos (2-3 different angles)
cp more_photos/*.jpg ./reference_faces/

Slow indexing

# Resize images
face-search build ~/Photos --max-size 640

# More workers
face-search build ~/Photos --workers 8

# Skip tiny faces
face-search build ~/Photos --min-face-size 50

Missing matches

# Higher threshold (more lenient)
face-search search --threshold 0.7

# More results
face-search search --top 500

# Better reference photos (clear face, good lighting)

---

📊 Benchmarks

Tested on MacBook Pro M1, 16GB RAM:

Photos	Faces	Index Time	Index Size	Search Time
1,000	2,500	2 min	5 MB	<50ms
10,000	25,000	20 min	50 MB	<100ms
50,000	120,000	1.5 hr	240 MB	<200ms
100,000	250,000	3 hr	500 MB	<300ms

---

🏛️ Architecture

face_search/
├── core.py          # FaceFinder main class
├── detectors.py     # Face detection (OpenCV, RetinaFace, etc.)
├── embedders.py     # Face embeddings (FaceNet512)
├── index.py         # FAISS vector index
├── loaders.py       # Image loading
├── cache.py         # Reference caching
├── models.py        # Data models
├── interfaces.py    # Abstract interfaces (SOLID)
├── cli.py           # Click CLI
└── gui.py           # Gradio GUI

Design Principles:

• 🔌 Pluggable - Swap any component (detector, embedder, index)
• 📦 SOLID - Clean interfaces, single responsibility
• 🧪 Testable - Dependency injection throughout
• 🚀 Efficient - Batch processing, multiprocessing, caching

---

📄 License

AGPL-3.0 - Open source with copyleft

✅ Allowed	❌ Required
Commercial use	Disclose source
Modification	Same license
Distribution	State changes
Private use	Network use = distribution

For details: GNU AGPL-3.0

---

🙏 Credits

Built with amazing open source:

• DeepFace - Face recognition framework
• FAISS - Vector similarity search
• Gradio - Web interface
• Click - CLI framework
• OpenCV - Computer vision

---

Made with ❤️ for finding memories

⬆ Back to Top