Initial commit

Made-with: Cursor
2026-04-22 11:16:37 +00:00 · 2026-03-26 00:20:30 +02:00
commit 8e2ecf50fd
144 changed files with 19781 additions and 0 deletions
@@ -0,0 +1,120 @@
+# Helper: Config
+
+**Purpose**: Loads and validates YAML configuration file. Provides typed access to all runtime parameters. Supports dev and production configs.
+
+**Used by**: All 6 components
+
+## Interface
+
+| Method | Input | Output | Error Types |
+|--------|-------|--------|-------------|
+| `load(path)` | str | Config | ConfigError (missing file, invalid YAML, validation failure) |
+| `get(key, default)` | str, Any | Any | KeyError |
+
+## Key Config Sections
+
+```yaml
+version: 1
+season: winter
+
+tier1:
+  backbone: yoloe-11s-seg  # or yoloe-26s-seg
+  engine_path: /models/yoloe-11s-seg.engine
+  input_resolution: 1280
+  confidence_threshold: 0.3
+
+tier2:
+  min_branch_length: 20  # pixels, for skeleton pruning
+  base_roi_px: 100
+  darkness_threshold: 80  # 0-255
+  contrast_threshold: 0.3
+  freshness_contrast_threshold: 0.2
+  cluster_radius_px: 300  # default max distance between cluster members
+  min_cluster_size: 2  # default minimum detections to form a cluster
+
+vlm:
+  enabled: true
+  socket_path: /tmp/vlm.sock
+  model: VILA1.5-3B
+  timeout_s: 5
+  prompt_template: "..."
+
+gimbal:
+  mode: real_uart  # or mock_tcp
+  port: /dev/ttyTHS1
+  baud: 115200
+  mock_host: mock-gimbal
+  mock_port: 9090
+  pid_p: 0.5
+  pid_i: 0.01
+  pid_d: 0.1
+
+scan:
+  sweep_angle_range: 45  # degrees, +/- from center
+  sweep_step: 5  # degrees per step
+  poi_queue_max: 10
+  investigation_timeout_s: 10
+  quality_gate_threshold: 50.0  # Laplacian variance
+
+search_scenarios:
+  - name: winter_concealment
+    enabled: true
+    trigger:
+      classes: [footpath_winter, branch_pile, dark_entrance]
+      min_confidence: 0.5
+    investigation:
+      type: path_follow
+      follow_class: footpath_winter
+      target_classes: [concealed_position, branch_pile, dark_entrance, trash]
+      use_vlm: true
+    priority_boost: 1.0
+  - name: building_area_search
+    enabled: true
+    trigger:
+      classes: [building_block, road_with_traces, house_with_vehicle]
+      min_confidence: 0.6
+    investigation:
+      type: area_sweep
+      target_classes: [vehicle, military_vehicle, traces, dark_entrance]
+      use_vlm: false
+    priority_boost: 0.8
+  - name: aa_defense_network
+    enabled: false
+    trigger:
+      classes: [radar_dish, aa_launcher, military_truck]
+      min_confidence: 0.4
+      min_cluster_size: 2
+    investigation:
+      type: cluster_follow
+      target_classes: [radar_dish, aa_launcher, military_truck, command_vehicle]
+      cluster_radius_px: 300
+      use_vlm: true
+    priority_boost: 1.5
+
+output:
+  base_dir: /data/output
+  recording_l1_fps: 2
+  recording_l2_fps: 30
+  log_flush_interval: 10  # entries or 5s
+  storage_warning_pct: 20
+
+health:
+  thermal_vlm_disable_c: 75
+  thermal_semantic_disable_c: 80
+  gimbal_timeout_s: 4
+  vlm_max_failures: 3
+  gimbal_max_failures: 3
+```
+
+## Validation Rules
+
+- version must be 1
+- engine_path must exist on filesystem (warn if not, don't fail — may be building)
+- All thresholds must be positive
+- gimbal.mode must be "real_uart" or "mock_tcp"
+- season must be one of: winter, spring, summer, autumn
+- search_scenarios: at least 1 enabled scenario required
+- Each scenario must have valid investigation.type: "path_follow", "area_sweep", "zoom_classify", or "cluster_follow"
+- path_follow scenarios must specify follow_class
+- cluster_follow scenarios must specify min_cluster_size (>= 2) and cluster_radius_px (> 0)
+- trigger.classes must be non-empty list of strings
@@ -0,0 +1,119 @@
+# 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
+```