Reid Extractor

app.infrastructure.tracking.reid_extractor

View source code

Deterministic, part-based appearance embeddings for object tracking.

See Also

• DeepSortStrategy — uses appearance features for association
• BotSortStrategy — uses appearance features for conservative re-identification

Layer: Infrastructure. Context: Implements concrete processing and I/O behind application-facing contracts.

ReIDExtractorProtocol

Bases: Protocol

Interface for extracting one optional appearance vector per box.

Note

Implementations may use a hand-crafted descriptor or a learned backbone; callers rely only on input-order preservation and unit-normalized vectors.

Layer: Infrastructure. Context: Implements concrete processing or I/O behind application-facing contracts.

extract_for_boxes(frame: RGBFrame | None, boxes: Sequence[BBoxViewModel]) -> list[np.ndarray | None]

Extract embeddings aligned with boxes, using None for invalid crops.

PARAMETER	DESCRIPTION
frame	RGB image for the current video frame, or None when unavailable. TYPE: RGBFrame | None
boxes	Bounding boxes in frame pixel coordinates. TYPE: Sequence[BBoxViewModel]

RETURNS	DESCRIPTION
list[ndarray | None]	A list with one normalized float32 vector or None per input box.

RAISES	DESCRIPTION
ValueError	If an implementation receives malformed frame data.

Note

Result positions must correspond exactly to the input box positions.

Example

vectors = extractor.extract_for_boxes(frame, boxes)

PartBasedAppearanceEmbedder

Build compact, illumination-tolerant color and texture descriptors.

ATTRIBUTE	DESCRIPTION
embedding_dim	Requested output size; supported values are 128, 256, and 512.

Note

Each crop is resized to a canonical 64-by-128 grid. HSV and CIE-LAB histograms encode chromatic appearance while Sobel orientation histograms preserve local texture and edge structure. The 128 mode prioritizes speed, 256 adds a center-weighted core, and 512 uses a six-region spatial pyramid.

Example

embedder = PartBasedAppearanceEmbedder(embedding_dim=256)

Layer: Infrastructure. Context: Implements concrete processing or I/O behind application-facing contracts.

embedding_dim = embedding_dim instance-attribute

__init__(embedding_dim: int = 256) -> None

PARAMETER	DESCRIPTION
embedding_dim	Output dimension, either 128, 256, or 512. TYPE: int DEFAULT: 256

RAISES	DESCRIPTION
ValueError	If the requested dimension is unsupported.

Note: No learned weights or network downloads are required.

Example

embedder = PartBasedAppearanceEmbedder(embedding_dim=128)

extract_for_boxes(frame: RGBFrame | None, boxes: Sequence[BBoxViewModel]) -> list[np.ndarray | None]

Extract an appearance descriptor for every usable box crop.

PARAMETER	DESCRIPTION
frame	RGB image for the current frame, or None. TYPE: RGBFrame | None
boxes	Boxes to crop in their original input order. TYPE: Sequence[BBoxViewModel]

RETURNS	DESCRIPTION
list[ndarray | None]	Unit-normalized float32 vectors, or None for invalid crops.

RAISES	DESCRIPTION
ValueError	If the input frame does not have an RGB array shape.

Note

Coordinates are clamped before cropping, and crops smaller than two pixels in either dimension are rejected.

Example

vectors = embedder.extract_for_boxes(frame, detections)

cosine_similarity(vec_a: np.ndarray, vec_b: np.ndarray) -> float

Return cosine similarity for two equal-length vectors.

PARAMETER	DESCRIPTION
vec_a	First feature vector. TYPE: ndarray
vec_b	Second feature vector. TYPE: ndarray

RETURNS	DESCRIPTION
float	Cosine similarity clamped to the range [-1, 1].

RAISES	DESCRIPTION
ValueError	If the vectors have different shapes.

Note

For nonzero inputs, similarity is

\[ \operatorname{sim}(\mathbf{a},\mathbf{b}) = \operatorname{clip}\!\left( \frac{\mathbf{a}^{\mathsf T}\mathbf{b}} {\lVert\mathbf{a}\rVert_2\lVert\mathbf{b}\rVert_2},-1,1\right). \]

If either input norm is at most \(10^{-8}\), the implementation returns zero instead of dividing by zero.

Example

similarity = cosine_similarity(first, second)

cosine_distance(vec_a: np.ndarray, vec_b: np.ndarray) -> float

Return cosine distance, defined as one minus cosine similarity.

PARAMETER	DESCRIPTION
vec_a	First feature vector. TYPE: ndarray
vec_b	Second feature vector. TYPE: ndarray

RETURNS	DESCRIPTION
float	A distance in [0, 2].

RAISES	DESCRIPTION
ValueError	If the vectors have different shapes.

Note

The implementation uses \(d_{\cos}(\mathbf{a},\mathbf{b}) = 1-\operatorname{sim}(\mathbf{a},\mathbf{b})\). For unit-normalized nonzero vectors, this reduces to \(1-\mathbf{a}^{\mathsf T}\mathbf{b}\). If either input norm is at most \(10^{-8}\), the similarity fallback is zero and the distance is one.

Example

distance = cosine_distance(first, second)

update_ema_embedding(prototype: np.ndarray | None, new_vec: np.ndarray, momentum: float = 0.9) -> np.ndarray

Blend a new unit feature into a normalized exponential-moving prototype.

PARAMETER	DESCRIPTION
prototype	Prior normalized appearance vector, if any. TYPE: ndarray | None
new_vec	Newly observed appearance vector. TYPE: ndarray
momentum	Weight assigned to the existing prototype in [0, 1). TYPE: float DEFAULT: 0.9

RETURNS	DESCRIPTION
ndarray	A normalized float32 vector.

RAISES	DESCRIPTION
ValueError	If momentum or vector shapes are invalid.

Note

For prior prototype \(\mathbf{p}\), observation \(\mathbf{x}\), and momentum \(m\), the blend and normalized update are

\[ \mathbf{b} = \begin{cases} \mathbf{x}, & \mathbf{p}\text{ is absent},\\ m\mathbf{p} + (1-m)\mathbf{x}, & \text{otherwise}, \end{cases} \qquad \mathbf{p}_{\mathrm{new}} = \frac{\mathbf{b}}{\max(\lVert\mathbf{b}\rVert_2,10^{-8})}. \]

Inputs are converted to float32; an existing prototype is expected to already be normalized. The denominator's epsilon floor prevents division by zero.

Example

prototype = update_ema_embedding(previous, observation, momentum=0.9)