Contract: Geometry And Time Sync Helpers

Component: shared/geo_geometry, shared/time_sync Producer task: AZ-221 — AZ-221_shared_geometry_time_sync.md Consumer tasks: AZ-223, AZ-225, AZ-226, AZ-228, AZ-230, AZ-231, AZ-232 Version: 1.0.0 Status: draft Last Updated: 2026-05-03

Purpose

Defines shared geospatial and timestamp helper behavior used by runtime components to avoid duplicated math and inconsistent frame/IMU alignment.

Shape

API Area	Shape	Errors
Coordinate conversion	WGS84/local tangent conversions and distance calculations	invalid CRS, missing origin
Camera footprint	intrinsics/extrinsics/attitude/altitude to footprint and GSD	invalid calibration, missing altitude
Homography metrics	homography/covariance conversions and MRE support	invalid geometry
Time sync	monotonic checks, frame-to-IMU window selection, replay ordering	timestamp mismatch, gap/jitter exceeded

Invariants

Helpers are deterministic for the same calibration, pose, and timestamp inputs.
Time helpers report gaps/jitter instead of silently dropping samples.
Geometry helpers do not decide safety policy; callers decide degrade/reject behavior.

Non-Goals

No VIO state estimation.
No MAVLink parsing beyond normalized timestamp fields.
No tile freshness or cache policy decisions.

Versioning Rules

Breaking changes to units, coordinate frames, or timestamp semantics require a major version bump.
New helper outputs may be added as optional fields in minor versions.

Test Cases

Case	Input	Expected	Notes
valid-wgs84-local	known WGS84 point and origin	round-trip within tolerance	Uses representative coordinates
frame-imu-window	frame timestamp plus IMU samples	correct aligned window	Includes gap metrics
invalid-calibration	missing intrinsics/extrinsics	explicit error	No silent fallback

Change Log

Version	Date	Change	Author
1.0.0	2026-05-03	Initial contract	autodev

2.1 KiB Raw Permalink Blame History