The Problem
Large‑scale security or sports analytics systems need to identify a person across multiple camera views or over time. Existing generic deep‑learning frameworks lack a ready‑made, battle‑tested pipeline that turns image crops into embeddings, evaluates them against public benchmarks, and exposes a simple API for integration.
What This Does
reid provides a lightweight, pure‑Python library that turns a person crop into a 512‑dimensional appearance vector and evaluates those vectors against standard re‑identification benchmarks.
- Model loading –
src/reid/model.pyexposesReIDModel.from_pretrained, which downloads a checkpoint (e.g.,osnet_x1_0_msmt17_combineall) or builds an architecture from scratch (ReIDModel("osnet_x1_0")). - Embedding extraction –
ReIDModel.extract_embeddingstakes asupervision.Detectionsbatch or a list of image paths (ReIDModel.extract_embeddings_from_paths) and returns a NumPy array. - Evaluation –
ReIDModel.evaluateruns a chosen protocol (src/reid/eval/protocols.py) against a query/gallery pair and returns ametricsdict. The metrics functions live insrc/reid/eval/metrics.py.
The package ships with pre‑built datasets loaders (src/reid/data/benchmarks.py, src/reid/data/splits.py) and helper functions (src/reid/loaders.py) so callers can drop in a directory of person crops and immediately score a model.
How It Is Wired
Entry Point – import reid loads src/reid/__init__.py, which exposes ReIDModel. Model Construction – ReIDModel.from_pretrained calls src/reid/architectures/registry.py to instantiate the chosen backbone (OSNet or FastReID) and then loads weights via torch.hub.load_state_dict. Embedding – ReIDModel.extract_embeddings routes each crop through src/reid/preprocessing.py (cropping, resizing, normalization) and the backbone’s forward pass, producing a 512‑dim vector. Evaluation – The evaluate method passes the embeddings to src/reid/eval/metrics.py which implements mean‑average‑precision, rank‑k, and min‑p computations. The protocol dispatcher in src/reid/eval/protocols.py selects between gallery retrieval or re‑association logic. Side‑effects – No external database or network calls beyond the optional weight download; all processing is in‑memory. The only external I/O is reading image files or videos via supervision utilities.
How To Use It
# Install from PyPI
pip install -U reid
or from source for development:
git clone https://github.com/moses-y/re-ID
cd re-ID
uv sync --all-extras # or pip install -e ".[dev]"
Load a model and run a quick benchmark:
from reid import ReIDModel, load_market1501
model = ReIDModel.from_pretrained("osnet_x1_0_msmt17_combineall")
query, gallery = load_market1501("/data/Market-1501")
result = model.evaluate(query, gallery)
print(result.metrics)
For embeddings from image files:
embs = model.extract_embeddings_from_paths(["crop1.jpg", "crop2.jpg"])
No environment variables are required; the only configuration is the path to the dataset or image folder.
Real‑World Use
A surveillance platform can wrap ReIDModel as a microservice:
- Detector (e.g., RF‑DETR) emits bounding boxes.
- Service calls
extract_embeddingson each frame. - A tracker stores embeddings per person ID and queries the re‑association protocol to confirm identity across frames.
- Periodic evaluation against Market‑1501 ensures the model remains calibrated.
Code Health & Issues
- Low –
pyproject.tomllacks a lockfile → non‑reproducible builds. - Low –
docs/contains extensive Markdown, but no typed stubs outsidepy.typed. - Low – CI workflows exist (
.github/workflows/*.yml) but no publish step for pre‑release tags.
The repository follows a clean, test‑driven structure: 11 test files cover embeddings, metrics, and data loaders. The docs/ folder hosts Jupyter notebooks that act as living examples, easing onboarding.
The Bottom Line
reid is a compact, well‑tested library that turns person crops into embeddings and evaluates them against industry‑standard benchmarks. Its API is straightforward, the code is modular, and the documentation is thorough. The main drawback is the absence of a lockfile, which could cause version drift in larger projects. For teams that need a plug‑and‑play re‑identification component, this package is a solid choice.