mirror of
https://github.com/azaion/detections.git
synced 2026-04-22 22:16:31 +00:00
Oleksandr Bezdieniezhnykh
84 lines
3.0 KiB
Markdown
84 lines
3.0 KiB
Markdown
# 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.
|