{"id":49007752,"url":"https://github.com/hunkontech/local_ai_face_recognizer","last_synced_at":"2026-06-12T10:00:42.911Z","repository":{"id":352103723,"uuid":"1212860198","full_name":"HunKonTech/local_ai_face_recognizer","owner":"HunKonTech","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-06T14:16:45.000Z","size":52807,"stargazers_count":1,"open_issues_count":26,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T14:19:38.452Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HunKonTech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T20:01:53.000Z","updated_at":"2026-06-06T14:16:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"b1da1041-246d-4e6f-ad84-2ccb774e11f9","html_url":"https://github.com/HunKonTech/local_ai_face_recognizer","commit_stats":null,"previous_names":["benkoncsik/local_ai_face_recognizer","hukontech/local_ai_face_recognizer","hunkontech/local_ai_face_recognizer"],"tags_count":92,"template":false,"template_full_name":null,"purl":"pkg:github/HunKonTech/local_ai_face_recognizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HunKonTech%2Flocal_ai_face_recognizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HunKonTech%2Flocal_ai_face_recognizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HunKonTech%2Flocal_ai_face_recognizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HunKonTech%2Flocal_ai_face_recognizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HunKonTech","download_url":"https://codeload.github.com/HunKonTech/local_ai_face_recognizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HunKonTech%2Flocal_ai_face_recognizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34041089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-18T21:12:47.987Z","updated_at":"2026-06-07T23:01:00.478Z","avatar_url":"https://github.com/HunKonTech.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Face-Local\n\n**Offline face grouping and person labeling with Google Coral Edge TPU acceleration.**\n\nScans a folder tree of images, detects faces, groups identical people into clusters, and lets you label, merge, and browse identities — entirely local, no cloud dependency.\n\n---\n\n## What it does\n\n1. **Scan** — recursively indexes images (`.jpg`, `.jpeg`, `.png`, `.webp`), hashes each file, skips unchanged ones on re-runs.\n2. **Detect** — runs face detection using a Google Coral Edge TPU (if available) or CPU fallback (OpenCV DNN SSD or Haar cascade).\n3. **Embed** — generates 192-dim face embeddings with MobileFaceNet TFLite on **CPU** (Coral is not used for this step — no practical Edge TPU ArcFace model is publicly available).\n4. **Cluster** — groups faces by cosine similarity using DBSCAN.\n5. **Label** — PySide6 GUI lets you rename clusters, merge wrong splits, reassign individual faces, and mark same/different pairs.\n6. **Export** — CSV, JSON reports, or copy face images to a folder.\n7. **Record** — a built-in screen recorder (toolbar ● / ⏸ / ■) captures the app\n   window, cursor and microphone for documenting meetings or image\n   walk-throughs, alongside a same-named `.srt` subtitle log of which image and\n   selected person was active at each moment.\n\nEverything is persisted in a local SQLite database. No network calls are made.\n\n### Screen recording\n\nThe recorder shells out to the system **`ffmpeg`** binary (install via\n`brew install ffmpeg` on macOS, or set the path in **Settings → Recording**).\nOutput is written as short, independently playable MP4 **segments** (default\n8 s) so an interrupted recording still leaves a usable file; the segments are\nconcatenated into `recording.mp4` when you stop. The microphone is always\ncaptured. **System/speaker audio** is best-effort and only included when a\nvirtual loopback device is present — macOS needs\n[BlackHole](https://github.com/ExistentialAudio/BlackHole) or Loopback,\nWindows a WASAPI `virtual-audio-capturer`; otherwise it is silently skipped.\n\n---\n\n## Architecture\n\n```\napp/\n├── main.py               Entry point (Qt app init, arg parsing)\n├── config.py             AppConfig dataclass + YAML loader\n├── logging_setup.py      Structured logging + QLogHandler for GUI\n├── db/\n│   ├── models.py         SQLAlchemy ORM: Image, Face, Person, FaceCorrection\n│   └── database.py       Engine init, session_scope context manager\n├── detectors/\n│   ├── base.py           FaceDetector ABC + Detection dataclass\n│   ├── coral_detector.py CoralDetector — real pycoral integration\n│   ├── cpu_detector.py   CpuDetector  — OpenCV DNN SSD + Haar fallback\n│   └── factory.py        probe_coral() + create_detector() factory\n├── embeddings/\n│   ├── base.py           FaceEmbedder ABC\n│   └── tflite_embedder.py TFLiteEmbedder (CPU, MobileFaceNet) + HOG stub\n├── clustering/\n│   └── clusterer.py      cluster_embeddings() — DBSCAN + same-pair constraints\n├── services/\n│   ├── scan_service.py      ScanService — file discovery + hashing\n│   ├── detection_service.py DetectionService — runs detector, saves crops\n│   ├── embedding_service.py EmbeddingService — runs embedder, stores vectors\n│   ├── clustering_service.py ClusteringService — DBSCAN → Person assignment\n│   ├── identity_service.py  IdentityService — rename/merge/reassign ops\n│   ├── object_service.py    ObjectService — tagged objects (cars, boats, …), point occurrences, person links, merge\n│   └── export_service.py    ExportService — CSV/JSON/image export\n├── workers/\n│   └── pipeline_worker.py PipelineWorker — QThread, runs all 4 stages\n└── ui/\n    ├── main_window.py     MainWindow — toolbar, splitter, dock\n    ├── panels/\n    │   ├── sidebar_panel.py  Person list + search\n    │   ├── cluster_panel.py  Face thumbnail grid\n    │   ├── log_panel.py      Coloured activity log\n    │   └── preview_panel.py  Full image preview with bbox overlay\n    └── dialogs/\n        ├── rename_dialog.py  Rename person dialog\n        └── merge_dialog.py   Merge into … dialog\n```\n\n---\n\n## Requirements\n\n- **Python 3.11+**\n- **Linux** (primary target — tested on Ubuntu 22.04 and Raspberry Pi OS Bookworm)\n- **Google Coral USB Accelerator** *(optional)* — for Edge TPU acceleration\n- Display / X11 or Wayland for the GUI\n\nmacOS and Windows are secondary targets. PySide6 and OpenCV work on both, but pycoral only supports Linux officially.\n\n### macOS: first launch (unsigned build)\n\nThe released `.app` may not be notarized, so macOS Gatekeeper can block the first launch.\n\nAfter installing:\n\n**System Settings → Privacy \u0026 Security → Open Anyway**\n\nIf it is still blocked:\n\n```bash\nxattr -dr com.apple.quarantine /Applications/Face-Local.app\n```\n\n---\n\n## Setup\n\n### 1. Clone and create a virtual environment\n\n```bash\ngit clone \u003crepo-url\u003e face-local\ncd face-local\npython3.11 -m venv .venv\nsource .venv/bin/activate\n```\n\n### 2. Install Python dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n\u003e **Note on tflite-runtime:** The package is available for Linux x86-64 and ARM.\n\u003e On macOS or Windows, install TensorFlow instead: `pip install tensorflow`\n\n### 3. Download model files\n\n#### Face detection (CPU) — Caffe SSD res10\n\n```bash\nmkdir -p models\nwget -P models/ \\\n  https://raw.githubusercontent.com/opencv/opencv/master/samples/dnn/face_detector/deploy.prototxt\n\nwget -P models/ \\\n  https://raw.githubusercontent.com/opencv/opencv_3rdparty/dnn_samples_face_detector_20170830/res10_300x300_ssd_iter_140000.caffemodel\n```\n\nWithout these files, the detector falls back to OpenCV's Haar cascade (lower quality but always available).\n\n#### Face detection (CPU) — YuNet (recommended; enables aligned crops)\n\nYuNet returns 5 facial landmarks per face, which the `aligned` embedding crop\nmode needs to warp faces onto the ArcFace template.  When present it is used in\npreference to the Caffe SSD / Haar CPU path.\n\n```bash\nwget -P models/ \\\n  https://github.com/opencv/opencv_zoo/raw/main/models/face_detection_yunet/face_detection_yunet_2023mar.onnx\n```\n\nOverride the location with `detection.yunet_model_path`, or set\n`detection.use_yunet: false` to force the Caffe/Haar path.\n\n\u003e **Changing `embedding.crop_mode`** (`legacy` → `square` → `aligned`) changes\n\u003e the geometry of every crop and therefore every embedding.  Existing\n\u003e embeddings are *not* comparable to new ones, so after switching you must\n\u003e re-run a full **re-detect + re-embed** of the library.\n\n#### Face embedding — MobileFaceNet TFLite (CPU only)\n\nThe embedding model is NOT included in the repository.  You have three options:\n\n**Option A — Community pre-converted model** (easiest):\n```bash\n# Search for \"mobilefacenet tflite\" on GitHub or HuggingFace.\n# A commonly used one is from the sirius-ai/MobileFaceNet_TF project.\n# Place the downloaded .tflite file at:\ncp /path/to/mobilefacenet.tflite models/mobilefacenet.tflite\n```\n\n**Option B — Convert from ONNX yourself**:\n```bash\npip install onnx onnx-tf tensorflow\n# Download mobilefacenet.onnx from InsightFace model zoo\n# (https://github.com/deepinsight/insightface/tree/master/model_zoo)\n# Then convert — see docs/convert_model.md (TODO: write this guide)\n```\n\n**Option C — Use the HOG stub (development only)**:  \nLeave `embedding.model_path` unset in `config.yaml`.  The app will warn you and use a low-quality HOG-based fallback.  Pipeline plumbing works, face recognition quality does not.\n\n#### Face detection (Coral Edge TPU)\n\n```bash\nwget -P models/ \\\n  https://raw.githubusercontent.com/google-coral/test_data/master/ssd_mobilenet_v2_face_quant_postprocess_edgetpu.tflite\n```\n\nThen set in `config.yaml`:\n```yaml\ndetection:\n  coral_model_path: models/ssd_mobilenet_v2_face_quant_postprocess_edgetpu.tflite\n```\n\n### 4. Install pycoral (Coral users only)\n\nFollow the official guide at https://coral.ai/docs/accelerator/get-started/\n\n```bash\necho \"deb https://packages.cloud.google.com/apt coral-edgetpu-stable main\" \\\n  | sudo tee /etc/apt/sources.list.d/coral-edgetpu.list\ncurl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -\nsudo apt update\nsudo apt install libedgetpu1-std   # or libedgetpu1-max for max clock speed\npip install pycoral\n```\n\n### 5. Configure\n\n```bash\ncp config.example.yaml config.yaml\n# Edit config.yaml — set model paths, thresholds, etc.\n```\n\n---\n\n## Running the application\n\n```bash\n# Default (auto-discovers config.yaml in cwd)\npython -m app.main\n\n# Explicit config\npython -m app.main --config /path/to/config.yaml\n\n# Debug logging\npython -m app.main --debug\n\n# Custom database location\npython -m app.main --db /tmp/test.db\n```\n\nOr if installed via pip:\n\n```bash\nface-local --config config.yaml\n```\n\n---\n\n## GUI workflow\n\n1. **Select Folder** — choose the root directory containing your images.\n2. **Scan \u0026 Index** — runs all 4 pipeline stages:\n   - Scanning → hashing → DB insert\n   - Detection → face bbox → crop thumbnails\n   - Embedding → face vectors\n   - Clustering → person groups\n3. **Browse** — click a person in the left sidebar to see their face thumbnails.\n4. **Click a thumbnail** — previews the original image with the face highlighted.\n5. **Rename** — give a person a real name.\n6. **Merge** — combine two clusters that represent the same person.\n7. **Remove Face** — kick a wrong face out of a cluster.\n8. **Reassign Face** — move a face to a different cluster.\n9. **Re-cluster All** — re-run DBSCAN with current manual corrections applied.\n10. **Export** — CSV/JSON report or copy images to a folder.\n\n---\n\n## Coral vs CPU — what's real, what's not\n\n| Stage | Coral | CPU |\n|-------|-------|-----|\n| Face detection | ✅ Real pycoral integration via `CoralDetector` | ✅ OpenCV DNN SSD + Haar fallback |\n| Face embedding | ❌ Not used — no practical public Edge TPU ArcFace model available | ✅ MobileFaceNet TFLite via `TFLiteEmbedder` |\n| Clustering | ❌ Not applicable | ✅ scikit-learn DBSCAN |\n\n**Performance expectations:**\n- Coral: ~50–200 ms per image for detection (USB Accelerator speed)\n- CPU DNN: ~100–500 ms per image depending on hardware\n- Haar cascade: fast but misses ~30–40% of faces\n- MobileFaceNet embedding: ~10–50 ms per face crop on modern x86 CPU\n\n---\n\n## Testing Coral fallback\n\nTo verify the CPU fallback path without Coral hardware:\n\n```bash\n# 1. Don't install pycoral — factory will auto-fallback:\npython -m app.main\n\n# 2. With pycoral installed but no USB Accelerator:\npython -m app.main\n# You will see in the log: \"pycoral available but no Edge TPU devices found\"\n\n# 3. Set coral_model_path but unplug the USB stick:\npython -m app.main\n# You will see: \"Coral init failed: ... — falling back to CPU\"\n\n# 4. Run tests:\npytest tests/test_detectors.py -v\n# TestFactoryFallback verifies the CPU fallback path with monkeypatching\n```\n\n---\n\n## Running tests\n\n```bash\npytest -v\n\n# Specific modules\npytest tests/test_clustering.py -v\npytest tests/test_database.py -v\npytest tests/test_detectors.py -v\npytest tests/test_scan_service.py -v\n```\n\nTests do NOT require a real camera, Coral hardware, or model files.  They use in-memory SQLite databases and synthetic embeddings.\n\n---\n\n## Configuration reference\n\nSee [`config.example.yaml`](config.example.yaml) for all options with inline documentation.\n\nKey thresholds:\n\n| Parameter | Default | Effect |\n|-----------|---------|--------|\n| `detection.confidence_threshold` | `0.5` | Lower → more detections, more false positives |\n| `clustering.epsilon` | `0.4` | Lower → stricter matching, more clusters |\n| `clustering.min_samples` | `2` | Higher → singletons become noise |\n| `scan.thumbnail_size` | `[128, 128]` | Larger → better visual quality, more disk space |\n\n---\n\n## Project status\n\n### Working in MVP\n- Full pipeline: scan → detect → embed → cluster → GUI\n- Coral detection with real pycoral integration\n- CPU detection: OpenCV DNN SSD + Haar cascade fallback\n- TFLite embedding with MobileFaceNet (or HOG stub)\n- DBSCAN clustering with manual correction constraints\n- SQLite persistence with SQLAlchemy ORM\n- PySide6 GUI: sidebar, cluster grid, preview, rename, merge, remove, reassign\n- Export: CSV, JSON, image folder\n- Resumable processing (skips unchanged files)\n- Structured logging with GUI log panel\n\n### Placeholder / known limitations\n- Embedding model file must be downloaded separately (see Setup)\n- CPU model files (Caffe SSD) must be downloaded separately\n- Face alignment available via `embedding.crop_mode: aligned` (5-point ArcFace\n  alignment) when the YuNet detector supplies landmarks; otherwise crops are\n  axis-aligned rectangles with no rotation correction\n- Clustering is global re-run (not incremental)\n- Re-clustering does not preserve cluster↔person mapping when many clusters change\n- `worker_threads` config exists but pipeline is currently serial (QThread runs one thread)\n- No HEIC support (extension point exists in `ScanConfig.image_extensions`)\n- No split-cluster operation in GUI (remove faces one by one as workaround)\n\n---\n\n## License\n\n[KOAI Personal Use License v1.0](LICENSE)\n\n---\n\n# Magyar változat\n\n# Face-Local\n\n**Offline arccsoportosítás és személycímkézés Google Coral Edge TPU gyorsítással.**\n\nBeolvas egy képeket tartalmazó mappastruktúrát, arcokat érzékel, azonos személyeket klaszterekbe rendez, majd lehetővé teszi az identitások címkézését, egyesítését és böngészését teljesen helyben, felhőfüggőség nélkül.\n\n---\n\n## Mit csinál\n\n1. **Beolvasás** — rekurzívan indexeli a képeket (`.jpg`, `.jpeg`, `.png`, `.webp`), minden fájlt hashel, majd újrafuttatáskor kihagyja a változatlanokat.\n2. **Érzékelés** — arcfelismerést futtat Google Coral Edge TPU-val (ha elérhető), vagy CPU-s tartalékmegoldással (OpenCV DNN SSD vagy Haar cascade).\n3. **Beágyazás** — 192 dimenziós arcbeágyazásokat generál MobileFaceNet TFLite segítségével **CPU-n** (ehhez a lépéshez a Coral nincs használatban, mert nyilvánosan nem érhető el gyakorlatban használható Edge TPU ArcFace modell).\n4. **Klaszterezés** — az arcokat koszinusz-hasonlóság alapján DBSCAN-nel csoportosítja.\n5. **Címkézés** — a PySide6 GUI-val átnevezheted a klasztereket, összevonhatod a hibás szétválásokat, újra hozzárendelhetsz egyedi arcokat, és megjelölhetsz azonos/különböző párokat.\n6. **Exportálás** — CSV- és JSON-jelentések készítése, vagy az arcképek mappába másolása.\n\nMinden adat egy helyi SQLite-adatbázisban tárolódik. Nem történik hálózati kommunikáció.\n\n---\n\n## Architektúra\n\n```\napp/\n├── main.py               Belépési pont (Qt app inicializálás, argumentumfeldolgozás)\n├── config.py             AppConfig dataclass + YAML betöltő\n├── logging_setup.py      Strukturált naplózás + QLogHandler a GUI-hoz\n├── db/\n│   ├── models.py         SQLAlchemy ORM: Image, Face, Person, FaceCorrection\n│   └── database.py       Engine inicializálás, session_scope context manager\n├── detectors/\n│   ├── base.py           FaceDetector ABC + Detection dataclass\n│   ├── coral_detector.py CoralDetector — valódi pycoral integráció\n│   ├── cpu_detector.py   CpuDetector — OpenCV DNN SSD + Haar tartalékmegoldás\n│   └── factory.py        probe_coral() + create_detector() gyárfüggvény\n├── embeddings/\n│   ├── base.py           FaceEmbedder ABC\n│   └── tflite_embedder.py TFLiteEmbedder (CPU, MobileFaceNet) + HOG csonk\n├── clustering/\n│   └── clusterer.py      cluster_embeddings() — DBSCAN + same-pair korlátozások\n├── services/\n│   ├── scan_service.py      ScanService — fájlfelderítés + hashelés\n│   ├── detection_service.py DetectionService — detektor futtatása, kivágások mentése\n│   ├── embedding_service.py EmbeddingService — beágyazó futtatása, vektorok tárolása\n│   ├── clustering_service.py ClusteringService — DBSCAN → Person hozzárendelés\n│   ├── identity_service.py  IdentityService — átnevezés/egyesítés/áthelyezés műveletek\n│   └── export_service.py    ExportService — CSV/JSON/kép export\n├── workers/\n│   └── pipeline_worker.py PipelineWorker — QThread, mind a 4 lépcsőt futtatja\n└── ui/\n    ├── main_window.py     MainWindow — eszköztár, splitter, dock\n    ├── panels/\n    │   ├── sidebar_panel.py  Személylista + keresés\n    │   ├── cluster_panel.py  Arcbélyegkép-rács\n    │   ├── log_panel.py      Színezett aktivitási napló\n    │   └── preview_panel.py  Teljes képelőnézet bbox átfedéssel\n    └── dialogs/\n        ├── rename_dialog.py  Személy átnevezése párbeszédablak\n        └── merge_dialog.py   Beolvasztás ide: ... párbeszédablak\n```\n\n---\n\n## Követelmények\n\n- **Python 3.11+**\n- **Linux** (elsődleges célplatform — Ubuntu 22.04-en és Raspberry Pi OS Bookwormön tesztelve)\n- **Google Coral USB Accelerator** *(opcionális)* — Edge TPU gyorsításhoz\n- Kijelző / X11 vagy Wayland a GUI-hoz\n\nA macOS és a Windows másodlagos célplatformok. A PySide6 és az OpenCV mindkettőn működik, de a pycoral hivatalosan csak Linuxot támogat.\n\n### macOS: első indítás (aláíratlan build)\n\nA kiadott `.app` nincs feltétlenül notarizálva, ezért a macOS Gatekeeper az első indításkor blokkolhatja.\n\nTelepítés után:\n\n**System Settings → Privacy \u0026 Security → Open Anyway**\n\nHa továbbra is blokkolja:\n\n```bash\nxattr -dr com.apple.quarantine /Applications/Face-Local.app\n```\n\n---\n\n## Telepítés\n\n### 1. Klónozás és virtuális környezet létrehozása\n\n```bash\ngit clone \u003crepo-url\u003e face-local\ncd face-local\npython3.11 -m venv .venv\nsource .venv/bin/activate\n```\n\n### 2. Python-függőségek telepítése\n\n```bash\npip install -r requirements.txt\n```\n\n\u003e **Megjegyzés a tflite-runtime-ról:** A csomag Linux x86-64 és ARM platformokra érhető el.\n\u003e macOS-en vagy Windowson inkább a TensorFlow telepítése ajánlott: `pip install tensorflow`\n\n### 3. Modellfájlok letöltése\n\n#### Arcérzékelés (CPU) — Caffe SSD res10\n\n```bash\nmkdir -p models\nwget -P models/ \\\n  https://raw.githubusercontent.com/opencv/opencv/master/samples/dnn/face_detector/deploy.prototxt\n\nwget -P models/ \\\n  https://raw.githubusercontent.com/opencv/opencv_3rdparty/dnn_samples_face_detector_20170830/res10_300x300_ssd_iter_140000.caffemodel\n```\n\nE fájlok nélkül a detektor az OpenCV Haar cascade megoldására áll vissza (gyengébb minőség, de mindig elérhető).\n\n#### Arcbeágyazás — MobileFaceNet TFLite (csak CPU)\n\nA beágyazó modell nincs benne a repóban. Három lehetőséged van:\n\n**A lehetőség — Közösségi, előre konvertált modell** (legegyszerűbb):\n```bash\n# Keress rá GitHubon vagy Hugging Face-en erre: \"mobilefacenet tflite\".\n# Egy gyakran használt változat a sirius-ai/MobileFaceNet_TF projektből származik.\n# A letöltött .tflite fájlt ide helyezd:\ncp /path/to/mobilefacenet.tflite models/mobilefacenet.tflite\n```\n\n**B lehetőség — Konvertáld át magad ONNX-ből**:\n```bash\npip install onnx onnx-tf tensorflow\n# Töltsd le a mobilefacenet.onnx fájlt az InsightFace model zoo-ból\n# (https://github.com/deepinsight/insightface/tree/master/model_zoo)\n# Majd konvertáld át — lásd: docs/convert_model.md (TODO: ezt az útmutatót még meg kell írni)\n```\n\n**C lehetőség — Használd a HOG csonkot (csak fejlesztéshez)**:\nHagyd üresen az `embedding.model_path` értékét a `config.yaml` fájlban. Az alkalmazás figyelmeztetést ad, és egy gyenge minőségű, HOG-alapú tartalékmegoldást használ. A pipeline működni fog, az arcfelismerés minősége viszont nem lesz megfelelő.\n\n#### Arcérzékelés (Coral Edge TPU)\n\n```bash\nwget -P models/ \\\n  https://raw.githubusercontent.com/google-coral/test_data/master/ssd_mobilenet_v2_face_quant_postprocess_edgetpu.tflite\n```\n\nEzután ezt állítsd be a `config.yaml` fájlban:\n```yaml\ndetection:\n  coral_model_path: models/ssd_mobilenet_v2_face_quant_postprocess_edgetpu.tflite\n```\n\n### 4. pycoral telepítése (csak Coral felhasználóknak)\n\nKövesd a hivatalos útmutatót: https://coral.ai/docs/accelerator/get-started/\n\n```bash\necho \"deb https://packages.cloud.google.com/apt coral-edgetpu-stable main\" \\\n  | sudo tee /etc/apt/sources.list.d/coral-edgetpu.list\ncurl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -\nsudo apt update\nsudo apt install libedgetpu1-std   # vagy libedgetpu1-max a maximális órajelhez\npip install pycoral\n```\n\n### 5. Konfigurálás\n\n```bash\ncp config.example.yaml config.yaml\n# Szerkeszd a config.yaml fájlt — állítsd be a modellútvonalakat, küszöböket stb.\n```\n\n---\n\n## Az alkalmazás futtatása\n\n```bash\n# Alapértelmezett (automatikusan megkeresi a config.yaml fájlt az aktuális mappában)\npython -m app.main\n\n# Konfigurációs fájl megadása\npython -m app.main --config /path/to/config.yaml\n\n# Hibakeresési naplózás\npython -m app.main --debug\n\n# Egyéni adatbázis-hely\npython -m app.main --db /tmp/test.db\n```\n\nVagy ha `pip`-pel van telepítve:\n\n```bash\nface-local --config config.yaml\n```\n\n---\n\n## GUI munkafolyamat\n\n1. **Mappa kiválasztása** — válaszd ki a képeket tartalmazó gyökérkönyvtárat.\n2. **Beolvasás és indexelés** — lefuttatja a pipeline mind a 4 szakaszát:\n   - Beolvasás → hashelés → DB beszúrás\n   - Érzékelés → arc bbox → bélyegképkivágások\n   - Beágyazás → arcvetktorok\n   - Klaszterezés → személycsoportok\n3. **Böngészés** — kattints egy személyre a bal oldali sávban az arcbélyegképek megtekintéséhez.\n4. **Kattintás a bélyegképre** — megnyitja az eredeti képet kiemelt arccal.\n5. **Átnevezés** — adj egy valós nevet a személyhez.\n6. **Egyesítés** — vonj össze két klasztert, ha ugyanazt a személyt jelölik.\n7. **Arc eltávolítása** — vedd ki a rossz arcot a klaszterből.\n8. **Arc újra hozzárendelése** — helyezd át az arcot egy másik klaszterbe.\n9. **Összes újraklaszterezése** — futtasd újra a DBSCAN-t a jelenlegi kézi korrekciók figyelembevételével.\n10. **Exportálás** — CSV/JSON jelentés vagy képek másolása egy mappába.\n\n---\n\n## Coral vs CPU — mi a valóság, és mi nem\n\n| Szakasz | Coral | CPU |\n|-------|-------|-----|\n| Arcérzékelés | ✅ Valódi pycoral integráció a `CoralDetector` segítségével | ✅ OpenCV DNN SSD + Haar tartalékmegoldás |\n| Arcbeágyazás | ❌ Nincs használatban — nem érhető el gyakorlatban használható nyilvános Edge TPU ArcFace modell | ✅ MobileFaceNet TFLite a `TFLiteEmbedder` segítségével |\n| Klaszterezés | ❌ Nem alkalmazható | ✅ scikit-learn DBSCAN |\n\n**Várható teljesítmény:**\n- Coral: kb. 50–200 ms képenként az érzékeléshez (USB Accelerator sebesség)\n- CPU DNN: kb. 100–500 ms képenként, hardvertől függően\n- Haar cascade: gyors, de az arcok kb. 30–40%-át kihagyhatja\n- MobileFaceNet beágyazás: kb. 10–50 ms arckivágásonként modern x86 CPU-n\n\n---\n\n## Coral fallback tesztelése\n\nÍgy ellenőrizheted a CPU-s tartalék útvonalat Coral hardver nélkül:\n\n```bash\n# 1. Ne telepítsd a pycoral csomagot — a factory automatikusan visszaáll CPU-ra:\npython -m app.main\n\n# 2. Telepített pycoral mellett, de USB Accelerator nélkül:\npython -m app.main\n# A naplóban ezt látod majd: \"pycoral available but no Edge TPU devices found\"\n\n# 3. Állíts be coral_model_path értéket, de húzd ki az USB eszközt:\npython -m app.main\n# Ezt fogod látni: \"Coral init failed: ... — falling back to CPU\"\n\n# 4. Futtasd a teszteket:\npytest tests/test_detectors.py -v\n# A TestFactoryFallback monkeypatch segítségével ellenőrzi a CPU fallback útvonalat\n```\n\n---\n\n## Tesztek futtatása\n\n```bash\npytest -v\n\n# Konkrét modulok\npytest tests/test_clustering.py -v\npytest tests/test_database.py -v\npytest tests/test_detectors.py -v\npytest tests/test_scan_service.py -v\n```\n\nA tesztekhez NEM szükséges valódi kamera, Coral hardver vagy modellfájl. Memóriában futó SQLite-adatbázisokat és szintetikus beágyazásokat használnak.\n\n---\n\n## Konfigurációs referencia\n\nAz összes opcióért és a beágyazott dokumentációért lásd: [`config.example.yaml`](config.example.yaml).\n\nFontos küszöbértékek:\n\n| Paraméter | Alapértelmezett | Hatás |\n|-----------|------------------|-------|\n| `detection.confidence_threshold` | `0.5` | Alacsonyabb érték → több találat, több hamis pozitív |\n| `clustering.epsilon` | `0.4` | Alacsonyabb érték → szigorúbb egyezés, több klaszter |\n| `clustering.min_samples` | `2` | Magasabb érték → az egyedülálló elemek zajnak számítanak |\n| `scan.thumbnail_size` | `[128, 128]` | Nagyobb érték → jobb vizuális minőség, több lemezhasználat |\n\n---\n\n## Projektállapot\n\n### Működő MVP-elemek\n- Teljes pipeline: beolvasás → érzékelés → beágyazás → klaszterezés → GUI\n- Coral-alapú érzékelés valódi pycoral integrációval\n- CPU-s érzékelés: OpenCV DNN SSD + Haar cascade fallback\n- TFLite beágyazás MobileFaceNettel (vagy HOG csonkkal)\n- DBSCAN klaszterezés kézi korrekciós megkötésekkel\n- SQLite perzisztencia SQLAlchemy ORM-mel\n- PySide6 GUI: oldalsáv, klaszterrács, előnézet, átnevezés, egyesítés, eltávolítás, áthelyezés\n- Export: CSV, JSON, képmappa\n- Folytatható feldolgozás (kihagyja a változatlan fájlokat)\n- Strukturált naplózás GUI naplópanellel\n\n### Helykitöltő elemek / ismert korlátok\n- A beágyazó modellfájlt külön kell letölteni (lásd: Telepítés)\n- A CPU-s modellfájlokat (Caffe SSD) külön kell letölteni\n- Nincs arckiegyenesítési lépés (a kivágások tengelyhez igazított téglalapok, nincs forgatáskorrekció)\n- A klaszterezés teljes újrafuttatással történik (nem inkrementális)\n- Az újraklaszterezés nem őrzi meg a klaszter↔személy megfeleltetést, ha sok klaszter változik\n- A `worker_threads` konfiguráció létezik, de a pipeline jelenleg soros (a QThread egy szálon fut)\n- Nincs HEIC támogatás (kiterjesztési pont van a `ScanConfig.image_extensions` mezőben)\n- Nincs klaszter-szétválasztó művelet a GUI-ban (kerülőmegoldásként az arcokat egyesével lehet eltávolítani)\n\n---\n\n## Licenc\n\n[KOAI Personal Use License v1.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunkontech%2Flocal_ai_face_recognizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhunkontech%2Flocal_ai_face_recognizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunkontech%2Flocal_ai_face_recognizer/lists"}