Family Match — Privacy-Preserving Family Resemblance System

🏆 Finalist — Social Development Innovation Hackathon (Team Mulai'm / مُلائم)

A facial-resemblance matching system that, given photos of two parents, finds the children whose faces most resemble the combined parental identity — built on face embeddings rather than raw images, so no personal photos need to be stored.

The project was built for a social-development use case (e.g. supporting family reunification / kinship matching) where privacy is a hard requirement: faces are converted to mathematical vectors immediately, and matching happens entirely in embedding space.

---

How it works

1. Face embeddings — each face is encoded with InsightFace (buffalo_l, ArcFace) into a normalized 512-dimensional vector (family_system.py:FaceProcessor).
2. Family embedding — the mother and father embeddings are blended into a single "family identity" vector using a tunable mixing weight alpha (create_family_embedding). find_best_alpha can optimize alpha against a known child when one is available.
3. Matching — the family vector is compared against a database of children embeddings using cosine similarity, returning the top-K most similar children with a 0–100 resemblance score and a low_confidence flag when a match falls below the similarity threshold.
4. Two strategies, auto-selected — the system implements both a family-vector method (single blended vector) and a weighted method (parent similarities combined separately), and pick_method automatically chooses the stronger one per query.

Privacy by design

• Matching operates on embeddings (vectors), not stored photographs.
• Uploaded images are processed transiently to extract an embedding; this repository intentionally ships no faces, no embedding database, and no personal data (enforced via .gitignore).
• The embedding database is built locally by the operator from their own images.

Tech stack

• Face recognition: InsightFace (buffalo_l / ArcFace), OpenCV
• Matching: NumPy (cosine similarity over normalized embeddings)
• API: Flask + Flask-CORS (app.py — POST /api/upload)
• Storage: NumPy .npy embedding store + SQLite embedding store (sql.py)
• Frontend: HTML templates (templates/)

Project structure

family-system/
├── family_system.py     # Core: FaceProcessor, FamilyMatcher, build_database
├── app.py               # Flask API — POST /api/upload (mother + father → top-K children)
├── sql.py               # Build a SQLite embedding store from the .npy database
├── backend/             # Alternative Flask app factory + blueprint
├── templates/           # index / results / base HTML
└── requirements.txt

Run locally

# 1. Install
pip install -r requirements.txt

# 2. Build the children embedding database from your own images
#    (place images in ./children_db, then:)
python -c "from family_system import build_database; build_database('children_db')"

# 3. Start the API
python app.py
# POST mother_img + father_img (multipart) to http://localhost:5000/api/upload

Notes & roadmap

• Matching currently uses NumPy cosine similarity; swapping in a FAISS index is the natural next step for scaling to large databases.
• A per-region facial-landmark explainability view (which regions drive the match) is a planned explainability layer.

---

Collaborative hackathon project. Core matching engine by @yousef0852; team contributions from @Manar567.