Hugging Face's logo

tit0000
/
GorillaIdentifier

Image Feature Extraction
LiteRT
LiteRT
wildlife
animal-re-identification
face-recognition
arcface
megadescriptor
gorilla
open-set
Model card Files
xet
 Community
GorillaIdentifier
File size: 4,858 Bytes
424bffe
 
2a1ffd0
 
 
 
 
 
 
 
 
 
 
424bffe
2a1ffd0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
---
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.