# Helper: Types

**Purpose**: Shared data structures used across all components. Defined as Python dataclasses (or Cython structs where performance matters).

**Used by**: All 6 components

## Structs

### FrameContext
```
frame_id: uint64
timestamp: float (epoch seconds)
image: numpy array (H,W,3)
scan_level: int (1 or 2)
quality_score: float
pan: float
tilt: float
zoom: float
```

### Detection
```
centerX: float (0-1)
centerY: float (0-1)
width: float (0-1)
height: float (0-1)
classNum: int
label: str
confidence: float (0-1)
mask: numpy array (H,W) or None
```

### SemanticDetection (extends Detection for logging)
```
# All Detection fields plus:
tier: int (1, 2, or 3)
freshness: str or None
tier2_result: str or None
tier2_confidence: float or None
tier3_used: bool
tier3_text: str or None
thumbnail_path: str or None
```

### POI
```
poi_id: uint64
frame_id: uint64
trigger_class: str
scenario_name: str
investigation_type: str  # from scenario
confidence: float
bbox: tuple (cx, cy, w, h)
priority: float
status: str (queued / investigating / done / timeout)
created_at: float (epoch)
```

### GimbalState
```
pan: float
tilt: float
zoom: float
target_pan: float
target_tilt: float
target_zoom: float
last_heartbeat: float
```

### CapabilityFlags
```
vlm_available: bool
gimbal_available: bool
semantic_available: bool
```

### SpatialAnalysisResult
```
pattern_type: str  # "mask_trace" or "cluster_trace"
waypoints: list[Waypoint]
trajectory: list[tuple(x, y)]
overall_direction: tuple(dx, dy)
skeleton: numpy array (H,W) or None  # only for mask_trace
cluster_bbox: tuple(cx, cy, w, h) or None  # only for cluster_trace
```

### Waypoint
```
x: int
y: int
dx: float
dy: float
label: str
confidence: float
freshness_tag: str or None  # mask_trace only
roi_thumbnail: numpy array
```

### VLMResponse
```
text: str
confidence: float
latency_ms: float
```

### SearchScenario
```
name: str
enabled: bool
trigger_classes: list[str]
trigger_min_confidence: float
investigation_type: str  # "path_follow", "area_sweep", "zoom_classify", "cluster_follow"
follow_class: str or None  # only for path_follow
target_classes: list[str]
use_vlm: bool
priority_boost: float
min_cluster_size: int or None  # only for cluster_follow
cluster_radius_px: int or None  # only for cluster_follow
```
