V1 models, app assets and model card

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+gallery.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,3 +1,125 @@
 ---
 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.

gallery.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cbf13ddbcb13036edf2465618fcc4f3903157f18c14627560d167789e0fd55de
+size 30901377

gorilla_v1_best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2b87855224bff7d1fd08a014580847b0b7bd863f1349b14993046e32aa1b73bc
+size 110410112

megadesc_T_arcface_backbone.tflite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:475376e35a2d1931f693a76f583636e93743d57d718dd80127cf1b67257c7496
+size 112476636

yolo_gorilla.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3cedb88b0a6d55a53d11c455d383440c07b2d048cd37a8226f3864517299bb51
+size 18474390

yolo_v2_detector.tflite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:551c92d9c179437610f075cfd92a0e8f3561749d40e89f7637d59e761ec3ffb1
+size 6199005