# 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.