This project focuses on Re-Identifying Jaguars from various data sources including camera trap videos, images, and jaguar ID guides.
The project is divided into three main components:
- Jaguar Re-Identification: The core pipeline for building training datasets and training re-id models.
- Jaguar Orientation: A module for determining the orientation (Left/Right/Front) of a jaguar, used to filter re-id data.
- Segmentation: A service module providing SAM3 and YOLOE segmentation capabilities.
For a detailed technical overview, see ARCHITECTURE.md.
- Python 3.10+
uv(recommended) orpiporcondafor package management.- FFMPEG is required for video processing. Please install it by following the instructions here.
- If you use conda:
conda install -c conda-forge ffmpeg -y
- If you use conda:
- DVC is used for data versioning. Please install it by following the instructions here.
# Install dependencies
uv pip install -r requirements.txt
pip install -e .
# Install generic SAM3 dependencies
pip install -q git+https://github.com/huggingface/transformers.git#egg=transformersWe use DVC to keep large datasets out of Git while tracking them reproducibly.
- Initialize DVC locally (run once already):
dvc init
# TODO configure a remote (S3, GCS, Azure, SSH, etc.) - only once
dvc remote add -d myremote s3://my-bucket/path
git add .dvc .dvcignore
git commit -m "chore: init dvc"-
Authenticate (everyone once)
-
Add a (large) dataset and push to remote (example):
## DVC START ##
dvc add data/large-dataset
### GIT START ###
git add data/large-dataset.dvc .gitignore
git commit -m "chore: track dataset with dvc"
git push
### GIT END ###
dvc push
## DVC END ##Note: How dvc commands always wrap around the git commands! It is essential that these are applied in the correct order to avoid issues with dvc!
- To get data on another machine, run:
dvc pullThe Makefile includes a data target that runs dvc pull for convenience.
src/jaguars/ingestion: Data ingestion and preprocessing.src/jaguars/reidentification: Main reidentification pipeline logic.src/jaguars/orientation: Orientation classification.src/jaguars/segmentation: Object detection/segmentation wrappers.src/jaguars/common: Shared utilities.data/: Data storage (dvc tracked).
- Huggingface Jaguar Dataset
- Camera Trap Data
- JaguarIdentification ReidentificationModels GitHub
- Notebook to perform embeddings-based exploration and segmentation on FiftyOne
- Mehdi Gouasmi (https://github.com/D-i-n-o)
- Philipp Kolbe (https://github.com/philippkolbe)
- Supervisor: Antonio Rueda-Toicen (https://github.com/andandandand)