---
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.