README.md

---
license: mit
tags:
  - wildlife
  - animal-re-identification
  - face-recognition
  - arcface
  - megadescriptor
  - orangutan
  - open-set
pipeline_tag: image-feature-extraction
---

# OrangIdentifier

**Individual facial recognition for Bornean orangutans** — end-to-end pipeline from raw photographs to offline Android deployment.

Source code (ML Pipeline): [github.com/tit-exe/OrangIdentifier](https://github.com/tit-exe/OrangIdentifier)  
Source code (Android App): [github.com/tit-exe/OrangIdentifier-Android](https://github.com/tit-exe/OrangIdentifier-Android)

## Overview

This pipeline trains a face detector and an individual identification model from labeled photographs, then exports the result as a lightweight gallery JSON for an Android app that runs entirely offline.

The gallery is a JSON file containing one averaged embedding vector per individual. Adding a new individual requires 10–20 photos, takes under a minute, and requires no retraining.

## Android App Assets

This repository also hosts the exported `.tflite` models and the gallery database required to run the **offline Android app**. 

If you are building the Android app, download these three files from the `main` branch and place them in the `app/src/main/assets/` folder of the Android project:
- `gallery.json`: The database containing the identity prototypes.
- `yolo_v2_detector.tflite`: The optimized YOLO face detector model.
- `megadesc_T_arcface_backbone.tflite`: The MegaDescriptor-T embedding backbone (112 MB).

## Inference pipeline

```
Raw photo → YOLO face detection (mAP@50=99.4%)
         → 224×224 crop
         → MegaDescriptor-T-224 (Swin Transformer, 768-dim embedding)
         → Cosine similarity vs gallery
         → Known individual (sim ≥ 0.22) or Unknown (sim < 0.22)
```

## Models

| File | Used in | Size | Description |
|------|---------|------|-------------|
| `yolo_v1_nano_mAP92.pt` | V1 | 6 MB | YOLO nano — mAP@50 = 91.98% |
| `yolo_v2_medium_mAP99.pt` | V1–V4 | 85 MB | YOLO medium — mAP@50 = 99.39% |
| `resnet50_classifier_10classes_acc96.pt` | V1 | 90 MB | Closed-set classifier, acc = 96.3% |
| `resnet50_backbone_2048dim.pt` | V2 | 90 MB | Embedding backbone, 2048-dim |
| `megadesc_T_arcface_final_epoch21_acc99.pt` | V3 | 105 MB | ArcFace, 10 individuals |
| `megadesc_T_arcface_v4_40individuals_acc99.pt` | V4 ★ | 105 MB | ArcFace, 40 individuals |

## Performance

|  | V1 | V2 | V3 | **V4** |
|--|----|----|----|----|
| Backbone | ResNet50 | ResNet50 | MegaDescriptor-T | **MegaDescriptor-T** |
| Supervised individuals | 10 | 10 | 10 | **40** |
| Closed-set accuracy | 96.3% | ~98% | 99.2% | **99.2%** |
| Unknown rejection (1,622 unseen crops) | — | 27.5% | 97.5% | **97.5%** |
| Wild internet rejection | — | 48.5% | 93.2% | **93.0%** |
| Separability gap | — | 0.294 | 0.883 | **0.885** |

## Dataset

| Source | Individuals | Crops | Role |
|--------|-------------|-------|------|
| Captive collection | 10 | 2,127 | Training (known) |
| Field rescue center | 30 | 1,622 | Open-set test only |
| Internet (iNaturalist, GBIF, web) | unlabeled | 5,429 | Background class |

Images are not included.

## Download

```python
from huggingface_hub import hf_hub_download

path = hf_hub_download(
    repo_id="tit0000/OrangIdentifier",
    filename="megadesc_T_arcface_v4_40individuals_acc99.pt"
)
```

Or via the pipeline:
```bash
python models/download_models.py
```

## Security note

These `.pt` files are standard PyTorch/Ultralytics checkpoints. The pickle imports
flagged by HuggingFace are all 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.
- Jocher et al. (2023). Ultralytics YOLOv8.