Model API

reid.ReIDModel

Appearance encoder with loading, preprocessing, and checkpoint I/O.

Provides extract_embeddings (for video-frame crops) and extract_embeddings_from_paths (for on-disk crops), plus from_pretrained and save. The default checkpoint is pedestrian-trained; pass source / architecture for other domains.

Constructing it builds the architecture with randomly initialised weights, without downloading anything. Its embeddings carry no identity information until it is trained; to load trained weights, use :meth:from_pretrained.

Parameters:

Name	Type	Description	Default
architecture	str | Module	Registered architecture name (see list_architectures), timm:<name>, or a pre-built nn.Module ((B, 3, H, W) → (B, D) in eval). save needs a name.	required
preprocessing	ReIDPreprocessing | None	Crop and embedding preprocessing. Defaults to the architecture's own preprocessing.	None
device	str | device	Compute device ("auto" picks the best available).	'auto'

device property

Device the backbone runs on.

preprocessing property

Active preprocessing pipeline.

to(device)

Move the encoder to device and return self, for chaining.

from_pretrained(source=None, *, architecture=None, preprocessing=None, device='auto') classmethod

Load a ReIDModel with trained weights from an alias or a Hub, web or local checkpoint.

source may be a curated alias, hf:// repo or file, an http(s):// file or folder URL, a local path or directory with reid_config.json, or None for the default model. A bare .pth / .safetensors file requires architecture.

Parameters:

Name	Type	Description	Default
source	str | None	Model source (alias, Hub URL, file or folder URL, local path, or None).	None
architecture	str | Module | None	Backbone override; required for bare weight files, and must be the architecture the weights were trained with.	None
preprocessing	ReIDPreprocessing | None	Preprocessing override.	None
device	str	Compute device ("auto" picks the best available).	'auto'

Returns:

Type	Description
ReIDModel	Loaded model with the backbone on device.

Raises:

Type	Description
ValueError	If architecture is given without a source (construct ReIDModel(architecture) for a randomly initialised model), if a bare weights file is given without architecture, or the weights cover less of the architecture than required: all of it for a pretrained name or saved model, half for a bare weights file.

save(directory)

Save the model's current weights and its configuration, so from_pretrained(directory) loads it back.

Writes the weights to weights.safetensors and the architecture and preprocessing to reid_config.json.

Parameters:

Name	Type	Description	Default
directory	str	Output directory (created if missing).	required

Raises:

Type	Description
ValueError	If the architecture name is unknown.

evaluate(data, gallery=None, *, protocol=None, batch_size=64, return_distmat=False, verbose=True)

Evaluate this model under an evaluation protocol.

The protocol selects which images are compared and which metrics are reported; this model embeds them. Selection is deterministic, so the same data and protocol score identical inputs for every model.

Parameters:

Name	Type	Description	Default
data	ReIDSplit	Images to evaluate. The protocol splits them into query and gallery images; when gallery is provided, they are the query images.	required
gallery	ReIDSplit | None	Gallery images for the queries in data. When provided, both splits are used as given; re-association builds its own gallery and rejects one.	None
protocol	EvaluationProtocol | None	Evaluation protocol. Defaults to RetrievalProtocol.	None
batch_size	int	Images per embedding batch.	64
return_distmat	bool	Keep the query-by-gallery distance matrix in the result.	False
verbose	bool	Log progress.	True

Returns:

Type	Description
ReIDResult	ReIDResult with protocol metrics as percentages,
ReIDResult	the number of scored queries, and protocol metadata.

Raises:

Type	Description
TypeError	If protocol is not an EvaluationProtocol.
ValueError	If an input is invalid, the model returns non-finite embeddings or embeddings too large to compare, or no query can be scored.

extract_embeddings_from_paths(image_paths, *, batch_size=32, num_workers=0)

Extract embeddings from pre-cropped image paths.

For bbox crops from a video frame, use extract_embeddings. Images are decoded and preprocessed via a DataLoader so num_workers > 0 parallelises disk I/O on platforms that support it. Raw (un-normalised) embeddings are returned; cosine callers normalise at distance time.

Parameters:

Name	Type	Description	Default
image_paths	Sequence[str]	Paths to RGB-ready crop images.	required
batch_size	int	Images per forward pass.	32
num_workers	int	DataLoader worker processes (0 decodes inline).	0

Returns:

Type	Description
ndarray	Float32 array of shape (N, D).

Raises:

Type	Description
ValueError	If batch_size is not a positive integer.

extract_embeddings(detections, frame, *, batch_size=32)

Extract appearance embeddings for each detection.

Crops are sub-batched so crowded frames do not build one oversized forward pass. Shares crop→tensor→forward with extract_embeddings_from_paths. Raw (un-normalised) embeddings are returned; cosine callers normalise at distance time.

Parameters:

Name	Type	Description	Default
detections	Detections	Detections whose xyxy boxes define the crops.	required
frame	ndarray	BGR video frame the detections were produced on.	required
batch_size	int	Crops per forward pass.	32

Returns:

Type	Description
ndarray	Float32 array of shape (N, D), or (0, 0) when empty.

Raises:

Type	Description
ValueError	If batch_size is not a positive integer.

reid.ReIDPreprocessing dataclass

Crop resize and colour/tensor conversion for backbone input.

Preprocessing does not own embedding L2 normalisation: extract_* always returns raw embeddings and cosine similarity is normalised at distance time (see reid.distance_matrix).

describe()

Human-readable one-line summary.

prepare_crop_array(crop, *, from_bgr_frame)

Normalise crop colour to RGB before it is resized.

Video frames from OpenCV / supervision are BGR; when to_rgb is True, they are converted here. On-disk crops loaded via PIL are already RGB and must not be channel-swapped, regardless of to_rgb.

resize_image(image)

Resize a PIL crop to input_size with PIL, as torchvision's Resize does.

stretch ignores aspect ratio. letterbox preserves aspect ratio and pads with pad_value.

build_crop_transform()

Full crop pipeline for an RGB PIL image: resize, then tensor normalisation.

to_dict()

Serialise for reid_config.json.

from_dict(data) classmethod

Reconstruct from a reid_config.json preprocessing dict.

Unknown keys are ignored, so configs written by older versions (e.g. a legacy normalize_embeddings flag) still load cleanly.

reid.Interpolation

Bases: str, Enum

Supported crop interpolation modes.

reid.list_architectures()

Return registered architecture names (timm models use timm:<name>).

reid.list_aliases()

Return curated alias names (sorted keys of ALIASES).