| --- |
| license: mit |
| tags: |
| - image-feature-extraction |
| - LiteRT |
| - wildlife |
| - animal-re-identification |
| - face-recognition |
| - arcface |
| - megadescriptor |
| - gorilla |
| - open-set |
| pipeline_tag: image-feature-extraction |
| --- |
| |
| # GorillaIdentifier |
|
|
| Individual facial recognition for mountain gorillas (*Gorilla beringei beringei*, Virunga), from field photographs to an offline Android deployment. |
|
|
| - Source code (ML pipeline): https://github.com/tit-exe/GorillaIdentifier |
| - Source code (Android app): https://github.com/tit-exe/GorillaIdentifier_AndroidApp |
| |
| ## Overview |
| |
| This project trains a face detector and an individual identification model from labeled field |
| photographs, then exports the result as a lightweight gallery JSON for an Android app that runs |
| entirely offline. The gallery holds up to 25 exemplar embeddings per individual. Adding a new |
| individual takes a handful of photos on the phone and requires no retraining. |
| |
| ## Inference pipeline |
| |
| ``` |
| Field photo -> YOLO gorilla face detection |
| -> 224x224 crop |
| -> MegaDescriptor-T-224 (Swin Transformer Tiny, 768-dim embedding) |
| -> max cosine similarity over the exemplars of each individual |
| -> Known individual (score >= 0.4689 and margin >= 0.08) or Unknown |
| ``` |
| |
| ## Android app assets |
| |
| This repository hosts the assets required to run the offline Android app. The app identifies files |
| by role, so the recognition backbone must be downloaded here (it exceeds the GitHub 100 MB limit), |
| while the detector and the gallery are also bundled in the app repository: |
| |
| - `megadesc_T_arcface_backbone.tflite` : the MegaDescriptor-T embedding backbone (107 MB). Download |
| it and place it in `app/src/main/assets/` before building the app. |
| - `yolo_v2_detector.tflite` : the gorilla face detector (the filename is the one the Android app |
| expects; it is the gorilla detector, not an orangutan model). |
| - `gallery.json` : the identity database, 66 individuals. |
|
|
| ## Models |
|
|
| | File | Role | Size | Description | |
| |------|------|------|-------------| |
| | `yolo_gorilla.pt` | pipeline | 18 MB | Gorilla face detector (YOLOv8), used for crop extraction and training | |
| | `gorilla_v1_best.pt` | pipeline | 105 MB | Trained V1 identifier checkpoint (MegaDescriptor-T + Sub-center ArcFace) | |
| | `megadesc_T_arcface_backbone.tflite` | app | 107 MB | Identifier backbone exported to TFLite for the Android app | |
| | `yolo_v2_detector.tflite` | app | 6 MB | Gorilla face detector exported to TFLite for the Android app | |
| | `gallery.json` | app | 30 MB | Identity gallery, 66 individuals, up to 25 exemplars each, 768-dim | |
|
|
| The generic MegaDescriptor-T-224 backbone used as the training starting point is not stored here. |
| `timm` downloads it automatically from `BVRA/MegaDescriptor-T-224` the first time training runs. |
|
|
| ## Performance |
|
|
| Version 1, 66 individuals, Virunga 2025. Metrics are measured on the held-out validation set after |
| training. |
|
|
| | Metric | Value | |
| |---|---| |
| | Recognized individuals | 66 | |
| | Top-1 accuracy | 93.0% | |
| | Top-3 accuracy | 96.1% | |
| | Mean F1 | 0.981 | |
| | Composite score | 0.808 | |
| | Rejection threshold | 0.4689 | |
| | Separability gap | 0.4351 | |
| | Backbone | MegaDescriptor-T-224 (Swin Transformer Tiny, 27.5M parameters) | |
| | Training time | about 66 minutes on an RTX 3050 4 GB | |
|
|
| The rejection threshold is the cosine-similarity cutoff below which a face is reported as unknown, |
| calibrated by maximizing F1 on the validation set. The separability gap is the average similarity |
| gap between an individual's own exemplars and its closest rival; a higher gap means less confusion. |
|
|
| ## Dataset |
|
|
| | Source | Individuals | Crops | Role | |
| |--------|-------------|-------|------| |
| | Field photographs (Virunga) | 66 known (+ 3 held out) | 2,809 | Training and validation | |
| | Internet / background images | unlabeled | 428 | Background class (pseudo-unknowns) | |
|
|
| Two individuals with too few crops were excluded from training, and three were held out as |
| pseudo-unknowns to calibrate the rejection threshold. Photographs are not included in this repository. |
|
|
| ## Download |
|
|
| ```python |
| from huggingface_hub import hf_hub_download |
| |
| path = hf_hub_download( |
| repo_id="tit0000/GorillaIdentifier", |
| filename="gorilla_v1_best.pt", |
| ) |
| ``` |
|
|
| Or, for the pipeline detector, via the helper script in the code repository: |
|
|
| ```bash |
| python models/download_models.py |
| ``` |
|
|
| ## Security note |
|
|
| These `.pt` files are standard PyTorch and Ultralytics checkpoints. The pickle imports flagged by |
| Hugging Face come from trusted libraries (torch, ultralytics, collections) and contain no malicious |
| code. |
|
|
| ## References |
|
|
| - Čermák et al. (2024). WildlifeDatasets. WACV 2024. |
| - Deng et al. (2019). ArcFace. CVPR 2019. |
| - Deng et al. (2020). Sub-center ArcFace. ECCV 2020. |
| - Liu et al. (2021). Swin Transformer. ICCV 2021. |
| - Khosla et al. (2020). Supervised Contrastive Learning. NeurIPS 2020. |
|
|
