Skip to content

Latest commit

 

History

History
114 lines (89 loc) · 5.36 KB

README.md

File metadata and controls

114 lines (89 loc) · 5.36 KB

data/

Your workspace, plus the small bundled dataset the demo notebooks run on.

data/
├── images/<individual>/            Raw labelled photographs — directory name IS the identity
├── images-segmented/<individual>/  Segmentation output (scripts/P1)
├── images-pattern/<individual>/    Pattern extraction output (scripts/P1) — what ReMatch matches on
├── new/<batch>/                    A batch of photographs to identify
├── new/<batch>-pattern/            Their pattern crops
├── precomputed/                    Match tables for the bundled sets (below)
└── raw-demo/                       Raw photographs demo-0 walks through, stage by stage

Nothing here is tracked by git except the bundled demo set — the lizard_* directories. Add your own images under any other name and they stay out of version control.

The bundled demo set

Gallery 12 individuals × 4 photographs = 48, in images-pattern/lizard_*/
Query batch 20 photographs in new/lizard_demo-pattern/
— of individuals in the gallery 13
— of individuals never seen 7, across 4 animals

That last row is the point: it lets the demo show open-set behaviour, where the pipeline must reject a query rather than force it onto the nearest known animal. lizard_demo_ground_truth.json records the true identity of every query image and whether it is in the gallery — used only to score the result at the end.

Run it with demo-1-training.ipynb followed by demo-2-query.ipynb.

The bundled zebra set

Gallery 8 individuals × 4 photographs = 32, in images/zebra_*/
Query batch 11 photographs in new/zebra_demo/
— of individuals in the gallery 5
— of individuals never seen 6, across 3 animals

Unlike the lizards these are raw field photographs, not crops: background, vegetation and all. demo-3-new-species.ipynb segments them with Grounded-SAM and matches on the segmented animal directly, with no pattern-extraction step — the route the paper uses for zebras, seals and whale sharks. zebra_demo_ground_truth.json records the true identities, used only to score the result. The segmentation output (images-segmented/, new/zebra_demo-segmented/) is regenerated by the notebook and not tracked.

Source and licence

From the Great Zebra and Giraffe Count and ID dataset (GZGC), released by Wild Me under the Community Data License Agreement – Permissive 1.0, which permits redistribution. Full dataset: lila.science/datasets/great-zebra-giraffe-id.

Parham J, Crall J, Stewart C, Berger-Wolf T, Rubenstein DI. Animal population censusing at scale with citizen science and photographic identification. AAAI Spring Symposium — Technical Report, 2017.

These are pattern crops, not raw photographs

The bundled images are the output of scripts/P1 — the lizard is segmented with YOLO, then its ventral scale mosaic is isolated with SAM and structured edge detection. That is the stage the demos skip, because it needs the original field photographs. The crops are what ReMatch actually matches on, so the demos begin from them.

To run the segmentation stage yourself, download the full dataset (below) into data/images/<individual>/ and run python scripts/P1-image_preparation.py.

Source and licence

The images come from BalearicLizard: 4 619 photographs of 1 009 individual Balearic wall lizards (Podarcis lilfordi), collected over fifteen years of capture–recapture monitoring on Illot d'en Curt, Mallorca, and identified by expert observers from their ventral scale patterns.

Alcaraz, R., Albalat-Oliver, B., Villa, A. et al. A long-term photographic dataset for individual identification of the Balearic wall lizard. Scientific Data (2026). doi:10.1038/s41597-026-07411-z

Download the full dataset: kaggle.com/datasets/roberalcaraz/baleariclizard

The 68 crops here are a subset, downscaled to 900 px high. Identity labels (lizard_C116, lizard_C373, …) are the dataset's own annotations with a lizard_ prefix, which is what keeps them distinguishable from your own data in .gitignore.

Precomputed match tables

Matching is the slow step of every demo — a quarter of an hour or more per notebook on a CPU. precomputed/ holds the match tables for the two bundled sets, which the notebooks load by default (RUN_MATCHING = False):

File Loaded by
lizard_demo_matches.parquet demo-1 — every pair of the lizard gallery
lizard_demo_query_matches.parquet demo-2 — every lizard query against the gallery
zebra_demo_matches.parquet demo-3 — every pair of the zebra gallery
zebra_demo_query_matches.parquet demo-3 — every zebra query against the gallery

They are produced by scripts/make_demo_matches.py with the same calls the notebooks make, and a notebook uses one only if it covers exactly the images it is about to match. Change the images, or point a notebook at your own, and it matches from scratch. Re-run that script whenever the bundled images, the wireframe configuration or the matcher change.