detections/_docs/02_document/modules/annotation.md

Module: annotation

Purpose

Data models for object detections and annotations (grouped detections for a frame/tile with metadata).

Public Interface

Class: Detection

Represents a single bounding box detection in normalized coordinates.

Field	Type	Description
x	double	Center X (normalized 0..1)
y	double	Center Y (normalized 0..1)
w	double	Width (normalized 0..1)
h	double	Height (normalized 0..1)
cls	int	Class ID (maps to constants_inf.annotations_dict)
confidence	double	Detection confidence (0..1)
annotation_name	str	Parent annotation name (set after construction)

Method	Signature	Description
__init__	(double x, y, w, h, int cls, double confidence)	Constructor
__str__	() -> str	Format: "{cls}: {x} {y} {w} {h}, prob: {confidence}%"
__eq__	(other) -> bool	Two detections are equal if all bbox coordinates differ by less than TILE_DUPLICATE_CONFIDENCE_THRESHOLD
overlaps	(Detection det2, float confidence_threshold) -> bool	Returns True if IoU-like overlap ratio (overlap area / min area) exceeds threshold

Class: Annotation

Groups detections for a single frame or image tile.

Field	Type	Description
name	str	Unique annotation name (encodes tile/time info)
original_media_name	str	Source media filename (without extension/spaces)
time	long	Timestamp in milliseconds (video) or 0 (image)
detections	list[Detection]	Detections found in this frame/tile
image	bytes	JPEG-encoded frame image (set after validation)

Method	Signature	Description
__init__	(str name, str original_media_name, long ms, list[Detection] detections)	Sets annotation_name on all detections
__str__	() -> str	Formatted detection summary
serialize	() -> bytes	Msgpack serialization with compact keys (legacy — not called in current codebase)

Internal Logic

• Detection.__eq__ uses constants_inf.TILE_DUPLICATE_CONFIDENCE_THRESHOLD (0.01) to determine if two detections at absolute coordinates are duplicates across adjacent tiles.
• Detection.overlaps computes the overlap as overlap_area / min(area1, area2) — this is not standard IoU but a containment-biased metric.
• Annotation.__init__ sets annotation_name on every child detection.

Dependencies

• External: msgpack
• Internal: constants_inf (TILE_DUPLICATE_CONFIDENCE_THRESHOLD constant)

Consumers

• inference — creates Detection and Annotation instances during postprocessing, uses overlaps for NMS, uses equality for tile dedup
• main — reads Detection fields for DTO conversion

Data Models

• Detection — bounding box + class + confidence
• Annotation — frame/tile container for detections + metadata + image

Configuration

None.

External Integrations

None.

Security

None.

Tests

None found.