gps-denied-onboard/_docs/02_document/system-flows.md

GPS-Denied Onboard System - System Flows

Flow Inventory

#	Flow Name	Trigger	Primary Components	Criticality
F1	Airframe Provisioning & FC Bootstrap	Client setup or airframe maintenance	C-12, C-6, FC, Jetson UI	High
F2	Pre-Flight Mission Setup & Tile Fetch	Operator prepares mission on Jetson UI	Jetson UI, C-1, C-2, Suite Satellite Service	High
F3	In-Flight VO-First Localization	Nav-cam frame arrives	C-4, C-2, C-3, C-5, C-6, C-10, C-11	High
F4	Re-Localization Recovery	Cold start, VO loss, sharp turn, disconnected segment, or sigma_xy > 50 m	C-2, C-3, C-5, C-7	High
F5	In-Flight Tile Generation & Local Write	Eligible satellite-anchored frame	C-1b, C-1, C-10	Medium
F6	Post-Flight Candidate Tile Upload	Aircraft lands and network is available	C-1, Suite Satellite Service	Medium
F7	Cold Start, Spoofing Promotion & Failsafe	Boot, GPS-denial signal, or output gap	C-6, C-7, FC, QGC	High
F8	AI-Camera Object Localization	AI detection system requests object coordinates	C-8, C-5, MAVROS/FC telemetry	Medium

Flow Dependencies

Flow	Depends On	Shares Data With
F1	Physical wiring and FC access	F2 and F3 via signed airframe manifest and FC parameter pins
F2	F1 for manifest and signing; Suite Service connectivity	F3/F4/F5 via tile cache, mission YAML, VPR index
F3	F2 for sufficient local cache; F1 for FC integration	F4 via re-loc triggers; F5 via satellite-anchored pose; F7 via output health
F4	F2 cache and descriptors; F3 trigger context	F3 via recovered anchor fix; F7 via failure state
F5	F3 satellite-anchored pose and tile cache	F6 via candidate tiles; C-10 via tile-generation events
F6	F5 candidate tiles and post-flight network	Future F2 through Suite Service trusted-basemap refresh
F7	F1 signing and FC params; F3 output health	F3 via source mode; QGC via status messages
F8	F3 current pose and FC altitude/attitude	FDR via object-localization audit records

---

Flow F1: Airframe Provisioning & FC Bootstrap

Description

At client setup, the operator or field engineer uses the Jetson UI and Provisioning Tool to make one airframe safe and repeatable for GPS-Denied operation. The output is a signed airframe manifest and a verified FC link.

Preconditions

• Jetson, FC, nav camera, and harness are physically installed.
• FC is reachable over the intended companion link.
• The operator can perform manual physical wiring checks and standard QGC compass/accelerometer calibration.

Sequence Diagram

sequenceDiagram
    participant Operator
    participant JetsonUI as Jetson UI
    participant Provisioner as C-12 Provisioning Tool
    participant FC as ArduPilot FC
    participant Manifest as Airframe Manifest

    Operator->>JetsonUI: Start airframe provisioning
    JetsonUI->>Provisioner: Launch provision-fc.py
    Provisioner->>FC: Detect FC and read firmware/sysid
    FC-->>Provisioner: FC identity and current parameters
    Provisioner->>FC: Pin SERIAL2_BAUD/SERIAL2_PROTOCOL
    Provisioner->>FC: Pin GPS1_TYPE=14 and EK3_SRC1_*
    Provisioner->>FC: Bootstrap MAVLink2 signing key
    Provisioner->>FC: Smoke-test RAW_IMU rate and GPS_INPUT round-trip
    Provisioner->>JetsonUI: Request checkerboard intrinsics calibration
    Operator->>JetsonUI: Complete guided calibration
    Provisioner->>Manifest: Write signed airframe manifest
    JetsonUI-->>Operator: Provisioning complete

Flowchart

flowchart TD
    start([Start provisioning]) --> detectFc[Detect FC]
    detectFc --> fcReachable{FC reachable?}
    fcReachable -->|No| stopRepair[Stop for wiring/link repair]
    fcReachable -->|Yes| pinParams[Pin serial, GPS_INPUT, EK3 params]
    pinParams --> signing[Install MAVLink2 signing key]
    signing --> smoke[RAW_IMU + GPS_INPUT smoke test]
    smoke --> smokeOk{Smoke test passes?}
    smokeOk -->|No| stopDebug[Stop with failed check]
    smokeOk -->|Yes| calibrate[Guided nav-cam intrinsics calibration]
    calibrate --> manifest[Write signed airframe manifest]
    manifest --> done([Airframe ready])

Data Flow

Step	From	To	Data	Format
1	FC	Provisioning Tool	Firmware, sysid, current params	MAVLink
2	Provisioning Tool	FC	Serial/GPS/EKF params, signing key	MAVLink commands
3	Jetson UI	Provisioning Tool	Camera calibration observations	Guided calibration payload
4	Provisioning Tool	Runtime	Airframe manifest	Signed file

Error Scenarios

Error	Where	Detection	Recovery
FC not detected	FC link check	No heartbeat	Stop and repair wiring/link settings.
Signing bootstrap fails	Signing setup	FC rejects command or verification	Stop; do not run flight stack unsigned.
GPS_INPUT round-trip fails	Smoke test	FC does not receive/accept test frame	Stop and debug params/sysids/signing.
Intrinsics calibration incomplete	Jetson UI	Missing calibration artifact	Keep airframe unprovisioned.

Performance Expectations

Metric	Target	Notes
Provisioning duration	Human-paced	Safety and correctness matter more than speed.
Smoke-test result	Deterministic pass/fail	Must run before production flight.

---

Flow F2: Pre-Flight Mission Setup & Tile Fetch

Description

Before takeoff, the operator connects to the Jetson UI, defines the route and sector, requests tiles from the Suite Satellite Service, and writes mission YAML next to the local tile cache. This is the only time the aircraft needs Service connectivity for the upcoming mission.

Preconditions

• Airframe provisioning is complete.
• Jetson has pre-flight internet.
• Suite Satellite Service is reachable and authorized.
• The operator knows the intended operational area and sector classes.

Sequence Diagram

sequenceDiagram
    participant Operator
    participant JetsonUI as Jetson UI
    participant Service as Suite Satellite Service
    participant Cache as C-1 Tile Cache
    participant VPR as C-2 VPR Index

    Operator->>JetsonUI: Draw route, sector, and transit corridor
    JetsonUI->>JetsonUI: Classify sectors and write mission YAML draft
    JetsonUI->>Service: Request z=19 tiles for operational area
    Service-->>JetsonUI: Tile package and metadata
    JetsonUI->>Cache: Store MBTiles and sidecar metadata
    Cache->>VPR: Build/update chunk descriptors and FAISS index
    VPR-->>JetsonUI: Index ready
    JetsonUI-->>Operator: Mission cache ready for flight

Flowchart

flowchart TD
    start([Operator opens Jetson UI]) --> draw[Draw route + sector]
    draw --> classify[Set active-conflict/stable sector classes]
    classify --> fetch[Request tiles from Suite Service]
    fetch --> enoughTiles{Tiles meet coverage, freshness, resolution?}
    enoughTiles -->|No| block[Block flight cache-ready status]
    enoughTiles -->|Yes| store[Store z=19 MBTiles + sidecars]
    store --> index[Build VPR chunks and descriptors]
    index --> yaml[Write mission YAML]
    yaml --> ready([Mission ready])

Data Flow

Step	From	To	Data	Format
1	Operator	Jetson UI	Route, sector polygon, mission ID	UI form
2	Jetson UI	Suite Service	Tile fetch request	HTTPS/API
3	Suite Service	Tile Cache	Tiles and metadata	MBTiles/package contract
4	Tile Cache	VPR Index	Chunks and descriptors	Local files / FAISS index
5	Jetson UI	Runtime	Mission configuration	YAML

Error Scenarios

Error	Where	Detection	Recovery
Service unavailable	Tile fetch	Request fails	Retry pre-flight; do not assume in-flight fetch.
Tile freshness invalid	Cache validation	Capture date violates sector budget	Reject or mark down-confidence per AC-NEW-6.
Cache incomplete	Coverage validation	Operational area gap	Block mission-ready status until resolved.
Descriptor build fails	VPR index	Index missing or corrupt	Rebuild; block flight if unresolved.

Performance Expectations

Metric	Target	Notes
Initial preload size	About 700 MB for 400 km2 at z=19	Throughput-sensitive but pre-flight only.
Runtime dependency	Zero Service calls in flight	All needed data must be local before takeoff.

---

Flow F3: In-Flight VO-First Localization

Description

For each nav-camera frame, the runtime uses the cheap C-4 motion bridge to propagate pose from the last satellite anchor. Satellite retrieval and matching are not run on every frame; they are invoked on anchor cadence, covariance growth, VO-health triggers, sharp turns, cold start, or disconnected-segment recovery.

Preconditions

• Mission YAML and tile cache are loaded.
• Airframe manifest is valid.
• Camera stream and FC telemetry are live.
• TensorRT engines and descriptor indexes are warmed.

Sequence Diagram

sequenceDiagram
    participant Cam as Nav Camera
    participant FC as ArduPilot FC
    participant VO as C-4 Nadir Motion Bridge
    participant VPR as C-2 VPR
    participant Matcher as C-3 Matcher/PnP
    participant Output as C-5/C-11 Output Stage
    participant Mav as C-6 MAVLink Injector
    participant FDR as C-10 FDR

    Cam->>VO: Frame
    FC-->>VO: IMU, attitude, altitude
    VO-->>Output: Relative motion + covariance
    Output->>Output: Check anchor age, sigma_xy, drift budget, VO health
    alt Anchor cadence or re-localization trigger
        Output->>VPR: Request candidate chunks
        VPR-->>Matcher: Top-K chunks
        Cam->>Matcher: Current frame
        Matcher-->>Output: Absolute pose + covariance + inliers
    end
    Output->>Output: Mahalanobis gate and covariance calibration
    Output->>Mav: GPS_INPUT payload
    Mav->>FC: Signed GPS_INPUT
    Output->>FDR: Source label, gates, covariance, decision

Flowchart

flowchart TD
    frame([Frame arrives]) --> vo[Update nadir motion bridge]
    vo --> trigger{Anchor cadence or re-loc trigger?}
    trigger -->|No| extrapolate[Produce vo_extrapolated candidate]
    trigger -->|Yes| retrieve[VPR top-K candidate chunks]
    retrieve --> match[Cross-view match + PnP]
    match --> gate[Mahalanobis gate]
    extrapolate --> gate
    gate --> valid{Valid confidence?}
    valid -->|Yes| emit[Emit signed GPS_INPUT]
    valid -->|No| dead[Mark dead_reckoned/no fix]
    emit --> record[FDR decision record]
    dead --> record
    record --> next([Next frame])

Data Flow

Step	From	To	Data	Format
1	Nav camera	Motion bridge / matcher	Current frame	ROS 2 image
2	FC	Motion bridge / output	IMU, attitude, altitude, GPS health	MAVLink -> ROS 2
3	Tile cache	VPR / matcher	Candidate chunks and descriptors	Local cache/index
4	Matcher / VO	Output stage	Pose hypotheses and covariance	ROS 2 messages
5	Output stage	FC	WGS84 fix and accuracy	MAVLink GPS_INPUT
6	Output stage	FDR	Decisions and gates	FlatBuffers record

Error Scenarios

Error	Where	Detection	Recovery
Frame dropped under load	Camera/runtime	Queue overflow or skip policy	Drop up to allowed budget; keep latest-frame processing.
VO unhealthy	Motion bridge	Low overlap, blur, weak features, inconsistent IMU/attitude, or covariance growth	Trigger F4 re-localization.
Matcher outlier	Output gate	Mahalanobis distance exceeds threshold	Reject, do not down-weight into a false anchor.
GPS_INPUT rejected	FC	Missing acceptance/round-trip evidence	Raise health alert and F7 failsafe path.

Performance Expectations

Metric	Target	Notes
Camera-to-FC output	<400 ms p95	Steady-state path is VO-first; satellite matching is cadence/triggered correction, not every-frame work.
Frame rate	3 fps input; up to about 10% drops allowed under load	Output must not batch.
Memory	<8 GB shared	Includes TensorRT engines and ROS 2 overhead.

---

Flow F4: Re-Localization Recovery

Description

When the system lacks a trustworthy recent anchor, it expands retrieval and matching to recover an absolute pose. This path handles cold start, sharp turns, disconnected segments, sigma_xy growth, and VO failure.

Preconditions

• Tile cache and VPR index cover the current operational area.
• The runtime has an initial or predicted position from FC/VO/dead reckoning.
• LiteSAM and inline matcher engines are installed and warmed according to deployment mode.

Sequence Diagram

sequenceDiagram
    participant Output as C-5 Output Stage
    participant VPR as C-2 VPR
    participant Matcher as C-3 Inline Matcher
    participant LiteSAM as LiteSAM Fallback
    participant FDR as C-10 FDR

    Output->>VPR: Re-loc request with predicted position and sector class
    VPR-->>Output: Top-K chunks based on sector and sigma_xy
    Output->>Matcher: Try SP+LG/GIM-LG over candidates
    alt Inline match succeeds
        Matcher-->>Output: Absolute pose + covariance
    else Inline match fails and fallback allowed
        Output->>LiteSAM: Rare fallback match request
        LiteSAM-->>Output: Absolute pose candidate
    end
    Output->>Output: Gate against VO/dead-reckoned prior
    Output->>FDR: Re-loc attempt and result

Flowchart

flowchart TD
    trigger([Re-loc trigger]) --> chooseK[Choose K by sector and sigma_xy]
    chooseK --> vpr[VPR retrieval]
    vpr --> inline[Run inline matcher over candidates]
    inline --> inlineOk{Good inliers and MRE?}
    inlineOk -->|Yes| pnp[PnP absolute pose]
    inlineOk -->|No| fallbackAllowed{LiteSAM fallback allowed?}
    fallbackAllowed -->|Yes| litesam[Run LiteSAM rare fallback]
    fallbackAllowed -->|No| noFix[No anchor this frame]
    litesam --> pnp
    pnp --> gate[Mahalanobis gate]
    gate --> recovered{Gate passes?}
    recovered -->|Yes| anchor[Emit satellite_anchored fix]
    recovered -->|No| noFix
    noFix --> escalate[Continue VO/dead reckoning and update failure counters]

Data Flow

Step	From	To	Data	Format
1	Output stage	VPR	Predicted position, sector type, sigma_xy	Re-loc request
2	VPR	Matcher	Candidate chunks	Chunk list
3	Matcher/LiteSAM	Output stage	Correspondences, pose, covariance	Pose candidate
4	Output stage	FDR	Attempt metadata	FlatBuffers record

Error Scenarios

Error	Where	Detection	Recovery
No candidate chunk	VPR	Empty result	Expand window to K=50; if still empty, no anchor.
Stale tile match	Matcher/output	Tile freshness metadata invalid	Reject or downgrade; never emit satellite_anchored from stale tile.
LiteSAM too slow	Fallback	Exceeds rare-path budget	Record timeout; continue dead reckoning/failsafe logic.

Performance Expectations

Metric	Target	Notes
Inline re-loc pair latency	<=200 ms per candidate path target	Bench-off decides exact settings.
LiteSAM fallback	<=2 s rare-path budget	Not part of steady-state p95.
Cold-start TTFF	<30 s p95	F7 includes full boot budget.

---

Flow F5: In-Flight Tile Generation & Local Write

Description

When a frame has a high-confidence satellite-anchored pose, the system may orthorectify it into the z=19 basemap projection and write a candidate tile into the local cache with sidecar metadata.

Preconditions

• Current source label is satellite_anchored.
• Parent pose sigma_xy <=5 m for hard write eligibility.
• Terrain class is flat or moderate, not rugged.
• DEM and camera intrinsics are available.

Sequence Diagram

sequenceDiagram
    participant Output as C-5 Output Stage
    participant Ortho as C-1b Ortho Generator
    participant Cache as C-1 Tile Cache
    participant FDR as C-10 FDR

    Output->>Ortho: Eligible frame + pose + covariance
    Ortho->>Ortho: Orthorectify with Orthority + DEM
    Ortho->>Ortho: Score quality and deduplicate
    Ortho->>Cache: Transactional candidate/soft tile write
    Cache-->>Ortho: Write result
    Ortho->>FDR: Tile-generation event and sidecar metadata

Flowchart

flowchart TD
    candidate([Frame candidate]) --> eligible{source=satellite_anchored and sigma<=5m?}
    eligible -->|No| skip[Skip tile generation]
    eligible -->|Yes| terrain{Terrain allowed?}
    terrain -->|No| skip
    terrain -->|Yes| ortho[Orthorectify with DEM + camera model]
    ortho --> quality{Quality and dedup pass?}
    quality -->|No| thumb[Record failure thumbnail <=0.1 Hz]
    quality -->|Yes| write[Write MBTiles transaction + sidecar]
    write --> record[FDR tile-generation event]
    thumb --> record

Data Flow

Step	From	To	Data	Format
1	Output stage	Ortho generator	Frame, pose, covariance, source label	ROS 2/local message
2	Tile cache	Ortho generator	Existing tile metadata	SQLite/sidecar
3	Ortho generator	Tile cache	Candidate/soft tile and metadata	MBTiles transaction
4	Ortho generator	FDR	Quality, write decision, failure thumbnail reference	FlatBuffers record

Error Scenarios

Error	Where	Detection	Recovery
Orthority latency too high	F-T14/runtime metric	>50 ms/frame budget	Switch implementation to OpenCV + bilinear DEM fallback after validation.
Pose covariance too high	Eligibility	sigma_xy >5 m	Skip write; do not poison cache.
Service tile overwrite risk	Dedup/write	Existing trusted tile within freshness budget	Do not overwrite service-source tile.
Cache write failure	SQLite/MBTiles	Transaction fails	Log event; keep localization running.

Performance Expectations

Metric	Target	Notes
Orthorectification latency	<=50 ms/frame budget	Measured on Orin Nano Super.
Misaligned tile probability	>30 m <1%; >100 m <0.1% per flight	AC-NEW-7 Monte Carlo gate.

---

Flow F6: Post-Flight Candidate Tile Upload

Description

After landing, candidate tiles generated during flight are uploaded from the local cache boundary to the Suite Satellite Service candidate pool. The Service owns voting and trusted-basemap promotion.

Preconditions

• Aircraft has landed and post-flight network is available.
• Candidate tiles and sidecars are present.
• Suite Service credentials are available in the approved ground context.

Sequence Diagram

sequenceDiagram
    participant Operator
    participant Uploader as Post-Flight Uploader
    participant Cache as C-1 Tile Cache
    participant Service as Suite Satellite Service
    participant FDR as C-10 FDR

    Operator->>Uploader: Start post-flight sync
    Uploader->>Cache: Enumerate candidate/soft tiles
    Cache-->>Uploader: Tile payloads and sidecars
    Uploader->>Service: Upload candidate pool batch
    Service-->>Uploader: Accepted/rejected result
    Uploader->>FDR: Record upload summary

Flowchart

flowchart TD
    start([Post-flight sync]) --> enumerate[Enumerate candidate tiles]
    enumerate --> any{Any candidates?}
    any -->|No| done([Nothing to upload])
    any -->|Yes| upload[Upload batch to Suite Service candidate pool]
    upload --> accepted{Accepted?}
    accepted -->|Yes| mark[Mark uploaded locally]
    accepted -->|No| retry[Keep pending with failure reason]
    mark --> done
    retry --> done

Data Flow

Step	From	To	Data	Format
1	Tile cache	Uploader	Candidate tiles and sidecars	Local files/SQLite
2	Uploader	Suite Service	Candidate upload batch	Service API contract
3	Suite Service	Uploader	Accepted/rejected records	API response
4	Uploader	FDR/log	Upload summary	FlatBuffers/log record

Error Scenarios

Error	Where	Detection	Recovery
Network unavailable	Upload	Connection failure	Keep candidates pending; retry on next post-flight sync.
Service rejects tile	Service ingest	Rejection response	Record reason; do not mark uploaded.
Contract mismatch	Upload payload	Schema/API error	Block upload and raise integration issue with ../satellite-service/.

Performance Expectations

Metric	Target	Notes
Upload timing	Post-flight, not flight-critical	Can retry without affecting flight safety.
Promotion	Service-owned	This build never marks tiles trusted.

---

Flow F7: Cold Start, Spoofing Promotion & Failsafe

Description

This flow covers safety state changes around boot, GPS denial/spoofing, promotion to primary GPS substitute, and output failure. It keeps FC behavior explicit and makes QGC telemetry a status surface, not a control-plane dependency.

Preconditions

• FC is configured by F1.
• Runtime has access to FC GPS/EKF health telemetry.
• Mission cache is loaded for cold-start matching.

Sequence Diagram

sequenceDiagram
    participant Runtime as GPS-Denied Runtime
    participant FC as ArduPilot FC
    participant Reloc as F4 Re-Localization
    participant QGC as QGroundControl
    participant FDR as C-10 FDR

    Runtime->>FC: Connect with signed MAVLink
    FC-->>Runtime: Last EKF position + GPS/EKF health
    Runtime->>Reloc: Cold-start first fix
    Reloc-->>Runtime: Valid anchor or no-fix
    alt GPS denial/spoofing detected
        FC-->>Runtime: GPS health degraded
        Runtime->>FC: Promote signed GPS_INPUT within <3 s
        Runtime->>QGC: STATUSTEXT promotion status via FC
    end
    alt No output >3 s
        FC->>FC: Fall back to IMU-only dead reckoning
        Runtime->>QGC: Degraded/failsafe status via FC
    end
    Runtime->>FDR: Boot, promotion, failsafe events

Flowchart

flowchart TD
    boot([Runtime boot]) --> connect[Signed MAVLink connect]
    connect --> init[Read last FC EKF position]
    init --> firstFix[Run cold-start re-localization]
    firstFix --> ttff{First fix <30s?}
    ttff -->|Yes| normal[Normal GPS_INPUT output]
    ttff -->|No| degraded[Degraded status and continued re-loc]
    normal --> gpsHealth{FC reports GPS denial/spoofing?}
    gpsHealth -->|Yes| promote[Promote our GPS_INPUT primary within <3s]
    gpsHealth -->|No| monitor[Monitor output age]
    promote --> monitor
    degraded --> monitor
    monitor --> gap{No position >3s?}
    gap -->|Yes| failsafe[FC IMU-only dead reckoning + log]
    gap -->|No| normal

Data Flow

Step	From	To	Data	Format
1	FC	Runtime	EKF position, GPS health, status	MAVLink
2	Runtime	FC	Signed GPS_INPUT	MAVLink
3	Runtime	QGC	Status summary / STATUSTEXT via FC	MAVLink
4	Runtime	FDR	Boot, promotion, failsafe events	FlatBuffers record

Error Scenarios

Error	Where	Detection	Recovery
Cold-start no fix	First re-loc	TTFF budget exceeded	Continue re-loc, report degraded, FC continues own fallback behavior.
Spoofing not promoted	Health monitor	Promotion >3 s	Fails AC-NEW-2; record and investigate.
Output gap	Runtime output	>3 s without fix	FC falls back to IMU-only dead reckoning.
Signing failure	MAVLink link	FC rejects frames	Do not bypass signing in flight; report unsafe state.

Performance Expectations

Metric	Target	Notes
Cold-start first fix	<30 s p95	From companion boot to first valid GPS_INPUT.
Spoofing promotion	<3 s p95	From FC GPS-denial signal.
Failsafe output gap	>3 s	FC fallback threshold.

---

Flow F8: AI-Camera Object Localization

Description

Other onboard AI systems can request the coordinates of an object detected by the AI camera. The system projects the object using current GPS-Denied position, altitude, AI-camera gimbal angle, zoom, and level-flight assumptions.

Preconditions

• Current GPS-Denied position estimate is available with confidence.
• AI-camera gimbal angle and zoom are available.
• Flight altitude is available.
• Request is scoped to level flight accuracy unless the caller accepts the published maneuvering error bound.

Sequence Diagram

sequenceDiagram
    participant AI as AI Detection System
    participant Obj as C-8 Object Localization
    participant Pose as C-5 Current Pose
    participant FC as FC Telemetry
    participant FDR as C-10 FDR

    AI->>Obj: Object pixel/box + camera metadata
    Obj->>Pose: Request current GPS-Denied pose
    Pose-->>Obj: WGS84 position + sigma_xy + source label
    FC-->>Obj: Altitude and attitude
    Obj->>Obj: Project object ray to ground plane
    Obj-->>AI: Object WGS84 coordinate + error bound
    Obj->>FDR: Object localization audit record

Flowchart

flowchart TD
    request([AI object request]) --> pose[Read current GPS-Denied pose]
    pose --> poseOk{Pose acceptable?}
    poseOk -->|No| reject[Return unavailable with reason]
    poseOk -->|Yes| inputs[Read gimbal angle, zoom, altitude]
    inputs --> level{Bank/pitch <5 deg?}
    level -->|Yes| project[Project object to ground plane]
    level -->|No| bound[Compute maneuvering error bound]
    bound --> project
    project --> result[Return WGS84 + confidence/error bound]

Data Flow

Step	From	To	Data	Format
1	AI system	Object localization	Object detection and camera metadata	Local API/topic
2	Output stage	Object localization	Current pose and confidence	Runtime state/topic
3	FC	Object localization	Altitude and attitude	MAVLink/ROS 2
4	Object localization	AI system	Object WGS84 and error bound	Response DTO/message

Error Scenarios

Error	Where	Detection	Recovery
Pose unavailable	C-5 current state	No current estimate or high sigma_xy	Return unavailable; do not invent coordinates.
Maneuvering flight	FC attitude	bank/pitch >=5 degrees	Publish bounded error, lower confidence.
Missing gimbal/zoom	AI-camera metadata	Required field absent	Reject request with explicit missing input.

Performance Expectations

Metric	Target	Notes
Response latency	Near-real-time local call	Not on FC safety-critical path.
Accuracy	Consistent with frame-center accuracy in level flight	AC-7.1/AC-7.2 scoped behavior.