Initial commit

Made-with: Cursor
2026-04-22 22:56:36 +00:00 · 2026-03-26 00:20:30 +02:00
commit 8e2ecf50fd
144 changed files with 19781 additions and 0 deletions
@@ -0,0 +1,117 @@
+# Component Diagram — Semantic Detection System
+
+```mermaid
+graph TB
+    subgraph External["External Systems"]
+        YOLO["Existing YOLO Pipeline"]
+        CAM["ViewPro A40 Camera"]
+        GPS["GPS-Denied System"]
+        OP["Operator Display"]
+        NVME["NVMe Storage"]
+    end
+
+    subgraph Helpers["Common Helpers"]
+        CFG["Config\n(YAML loader + validation)"]
+        TYP["Types\n(shared dataclasses)"]
+    end
+
+    subgraph Core["Core Components"]
+        SC["ScanController\n(py_trees BT orchestrator)"]
+        T1["Tier1Detector\n(YOLOE TensorRT FP16)"]
+        T2["Tier2SpatialAnalyzer\n(mask trace + cluster trace)"]
+        VLM["VLMClient\n(NanoLLM IPC)"]
+        GD["GimbalDriver\n(ViewLink + PID)"]
+        OM["OutputManager\n(logging + recording)"]
+    end
+
+    subgraph VLMContainer["Docker Container"]
+        NANO["NanoLLM\n(VILA1.5-3B)"]
+    end
+
+    %% Helper dependencies (all components use both)
+    CFG -.-> T1
+    CFG -.-> T2
+    CFG -.-> VLM
+    CFG -.-> GD
+    CFG -.-> OM
+    CFG -.-> SC
+    TYP -.-> T1
+    TYP -.-> T2
+    TYP -.-> VLM
+    TYP -.-> GD
+    TYP -.-> OM
+    TYP -.-> SC
+
+    %% ScanController orchestrates all
+    SC -->|"detect(frame)"| T1
+    SC -->|"trace_mask / trace_cluster"| T2
+    SC -->|"analyze(roi, prompt)"| VLM
+    SC -->|"set_angles / follow_path / zoom_to_poi"| GD
+    SC -->|"log_detection / record_frame"| OM
+
+    %% VLM to NanoLLM container
+    VLM -->|"Unix socket IPC"| NANO
+
+    %% External integrations
+    YOLO -->|"detections[]"| SC
+    CAM -->|"HDMI/IP frames"| SC
+    GD -->|"UART ViewLink"| CAM
+    OM -->|"YOLO format output"| OP
+    OM -->|"JPEG + JSON-lines"| NVME
+    GPS -.->|"coordinates (optional)"| OM
+
+    %% Styling
+    classDef external fill:#f0f0f0,stroke:#999,color:#333
+    classDef helper fill:#e8f4fd,stroke:#4a90d9,color:#333
+    classDef core fill:#d4edda,stroke:#28a745,color:#333
+    classDef container fill:#fff3cd,stroke:#ffc107,color:#333
+
+    class YOLO,CAM,GPS,OP,NVME external
+    class CFG,TYP helper
+    class SC,T1,T2,VLM,GD,OM core
+    class NANO container
+```
+
+## Component Dependency Graph (implementation order)
+
+```mermaid
+graph LR
+    CFG["Config"] --> T1["Tier1Detector"]
+    CFG --> T2["Tier2SpatialAnalyzer"]
+    CFG --> VLM["VLMClient"]
+    CFG --> GD["GimbalDriver"]
+    CFG --> OM["OutputManager"]
+    TYP["Types"] --> T1
+    TYP --> T2
+    TYP --> VLM
+    TYP --> GD
+    TYP --> OM
+
+    T1 --> SC["ScanController"]
+    T2 --> SC
+    VLM --> SC
+    GD --> SC
+    OM --> SC
+
+    SC --> IT["Integration Tests"]
+```
+
+## Data Flow Summary
+
+```mermaid
+flowchart LR
+    Frame["Camera Frame"] --> T1["Tier1\nYOLOE detect"]
+    T1 -->|"detections[]"| Eval["EvaluatePOI\n(scenario match)"]
+    Eval -->|"POI queued"| L2["L2 Investigation"]
+    L2 -->|"mask"| T2M["Tier2\ntrace_mask"]
+    L2 -->|"cluster dets"| T2C["Tier2\ntrace_cluster"]
+    T2M -->|"waypoints"| Follow["Gimbal\nPID follow"]
+    T2C -->|"waypoints"| Visit["Gimbal\nvisit loop"]
+    Follow -->|"ambiguous"| VLM["VLM\nanalyze"]
+    Visit -->|"ambiguous"| VLM
+    Follow -->|"detection"| Log["OutputManager\nlog + record"]
+    Visit -->|"detection"| Log
+    VLM -->|"tier3 result"| Log
+    Log -->|"operator format"| OP["Operator Display"]
+    Log -->|"JPEG + JSON"| NVME["NVMe Storage"]
+```