autopilot/_docs/02_document/components/scan_controller/description.md

Component — scan_controller

Layer: Decision + Memory Status: forward-looking design (Rust)

1. Purpose

The system's brain. A deterministic typed state machine — ZoomedOut, ZoomedIn { roi, hold_started_at }, and TargetFollow { target_id, started_at }. Owns the POI queue, timeouts, the ≤5 POIs/min operator-review cap, the confidence-scaled operator-decision window, gimbal command issuance, and the new/moved/existing/removed dispatch into mapobjects_store.

The full behaviour-tree spec — including tick scenarios and the 15 fixed-wing rules — lives in system-flows.md §F4.

2. Inputs

Input	Source	Cadence	Notes
DetectionBatch	detection_client	per frame	Tier 1 primitives.
MovementCandidate	movement_detector	per frame at both zoom-out and zoom-in (suppressed only during TargetFollow)	Each candidate carries source_zoom_band.
Tier2Evidence	semantic_analyzer	per zoom-in hold	Path / endpoint / concealment scoring.
VlmAssessment	vlm_client (optional)	per zoom-in endpoint hold	status: disabled if VLM is off.
Operator commands	operator_bridge	event	confirm / decline / target-follow start / target-follow release. Authenticated, signed, replay-protected upstream of this component.
UAV telemetry	mavlink_layer (via mission_executor)	10 Hz target	Position used for proximity-weighted POI priority and middle-waypoint computation.
Mission state	mission_executor	event	Current waypoint, mission progress; used for sweep-vs-route alignment.
MapObjects sync state	mapobjects_store	event at startup + post-flight	synced / cached_fallback / degraded — surfaces a health flag and (for degraded) suppresses MapObject diff classifications until corrected.

3. Outputs

Output	Consumer	Shape
GimbalCommand (yaw / pitch / zoom)	gimbal_controller	per state-machine tick or per zoom-in plan step
POI to operator	operator_bridge (then telemetry_stream)	enqueue / dequeue events
Middle-waypoint hint	mission_executor	event on operator-confirmed target
MapObjects update	mapobjects_store	new / moved / existing / removed dispatch
Health metric	health aggregator	state, pois_in_queue, pois_per_min, tick_latency_p99, last_state_change_ts, mapobjects_sync_state.

4. Key Responsibilities

• Run the ZoomedOut / ZoomedIn / TargetFollow state machine. Transitions are explicit, typed, and fully enumerated; no ad-hoc booleans.
• Maintain the POI queue ordered by confidence × proximity_to_current_camera × age_factor. Hard-cap output to ≤5 POIs/min surfaced to the operator.
• Apply the confidence-scaled operator decision window (40 % → 30 s, 100 % → 120 s, linear; below 40 % the POI is not surfaced). Timeout = forget; decline = IgnoredItem entry via mapobjects_store.
• Suppress new POIs whose (MGRS, class_group) matches an existing IgnoredItem.
• For each new detection or movement candidate: compute the H3 cell, ask mapobjects_store to classify as new / moved / existing, and only surface non-existing entries.
• Zoom-in candidate handling. When a MovementCandidate arrives with source_zoom_band = zoomed_in, evaluate against the current ROI: if inside, bump current-ROI confidence; if outside the ROI but inside the broader zoomed FOV, enqueue as a candidate-POI; only interrupt the current zoom-in hold if the candidate's priority exceeds the current hold's priority.
• On operator confirmation: hand a middle-waypoint hint to mission_executor, transition to TargetFollow, and command gimbal_controller to keep the target in the centre 25 % of frame.
• On operator decline / timeout / target loss: append (decline only) an IgnoredItem and return to ZoomedOut.
• On mapobjects_store reporting sync_state = degraded, surface health → red and do not classify new detections (avoid corrupting the central observation log on next push); continue to surface POIs to the operator on Tier-1 + movement evidence alone.

5. Internal State

The state machine lives entirely in this component. State variables:

• Current state: ZoomedOut | ZoomedIn { roi, hold_started_at } | TargetFollow { target_id, started_at }.
• POI queue: ordered, with per-entry priority and queue position.
• Per-class operator-decision-window thresholds.
• Last-N tick timestamps for tick-latency observability.
• Frame-rate floor monitor: when sustained FPS < 10, suppress ZoomedOut → ZoomedIn transitions and surface health → yellow.

State is in-process only; restart starts in ZoomedOut with an empty queue.

6. Failure Modes

Failure	Detection	Behaviour
detection_client health red	health input	Continue zoom-out sweep; emit no new POIs from Tier 1; movement candidates still flow.
movement_detector health red	health input	Continue; lose movement-candidate enqueueing.
semantic_analyzer health red	health input	Skip Tier 2; surface POIs with Tier-1-only evidence; flag in operator overlay.
vlm_client returns status: disabled | timeout | ipc_error | schema_invalid	per-call status	Surface POI without VLM evidence (fail-closed).
gimbal_controller not ready	health input	Stay in current state; alert; do not silently drop scan steps.
operator_bridge disconnected	health input	Continue zoom-out (operator UI is unreachable, but the system must not crash); pause POI surfacing; resume on reconnect. F10 lost-link ladder owns the larger response.
mapobjects_store sync degraded	sync_state input	Suppress diff classifications; surface POIs on Tier-1 + movement only; health → red.
Sustained FPS < 10	self-instrumented	Suppress zoom-in transitions; health → yellow.
Tick-latency above budget	self-instrumented	Health → yellow; investigate (likely upstream consumer slowness).

7. Dependencies

In-process (input): detection_client, movement_detector, semantic_analyzer, vlm_client, operator_bridge, mission_executor, mapobjects_store. In-process (output): gimbal_controller, operator_bridge, mission_executor, mapobjects_store.

External: none directly. All external integrations are mediated by other components.

8. Non-Functional Targets

Concern	Target
Tick latency	≤10 ms p99
POI enqueue → operator surface	≤1 s in normal load
POI rate to operator	≤5 POIs/min (hard cap)
Zoom-out → zoom-in transition	≤2 s including physical zoom
Zoom-in hold duration	configurable; default 5 s/POI
Target-follow centre-window	target inside centre 25 % of frame while visible
Frame-rate floor	≥10 fps sustained; below this, suppress zoom-in transitions

9. References

• architecture.md §3, §5 Architectural Principles, §6 NFR, §7.6 Scan controller and POI queue, §7.12 New vs Existing / Moved / Removed Object Detection, §7.13 MapObjects Sync.
• system-flows.md §F4 Scan controller behaviour tree (full BT spec, tick scenarios, 15 fixed-wing rules).
• data_model.md §POI, §IgnoredItem, §MapObject.