Session-scoped survey admission and saved-image evidence for USHER. More...


Go to the source code of this file.
Functions | |
| bool | capture_arbiter_load_camera (const char *filename) |
| Load one camera's measured profile without guessing geometry from its ID. | |
| void | capture_arbiter_set_enforce (bool enforce) |
| Enable coverage-based suppression and limited delay, or observe decisions only. | |
| bool | capture_arbiter_set_overlap (double overlap) |
| Set the overlap floor for deliberate predictive delay, not FC shot spacing. | |
| bool | capture_arbiter_set_camera_capacity (unsigned camera_id, unsigned capacity) |
| Set admission from a backend's actual capacity, independent of camera ID. | |
| uint32_t | capture_arbiter_session_id (void) |
| Return the peer-session token, or zero when survey mode is not configured. | |
| void | capture_arbiter_set_scope (const union usher_capture_arbiter_state_union *scope, uint64_t now_us) |
| Refresh survey authorization or cancel waiting work when scope is withdrawn. | |
| bool | capture_arbiter_offer (const union usher_capture_arbiter_shoot_union *request, uint64_t now_us) |
| Split a survey request into bounded per-camera intentions. | |
| bool | capture_arbiter_take (uint32_t ready_mask, uint64_t now_us, union dc_shot_union *shot, uint8_t *mask) |
| Admit the oldest ready camera intention after optional coverage evaluation. | |
| void | capture_arbiter_complete (const union dc_shot_union *shot, unsigned camera_id, bool saved, bool exposure_pose_valid, double uncertainty_m, uint64_t now_us) |
| Release admission and optionally credit verified saved coverage. | |
| bool | capture_arbiter_result (union usher_capture_arbiter_result_union *result, uint32_t ready_mask) |
| Pop a bounded best-effort result for UART transmission. | |
| void | capture_arbiter_stop (void) |
| Cancel waiting intentions, retaining active-image ownership and saved coverage. | |
| bool | capture_arbiter_pending (void) |
| Check whether waiting or active survey work remains. | |
| bool | capture_arbiter_owns (int32_t number) |
| Identify a shot whose active survey ownership must not be superseded. | |
| void | capture_arbiter_acquired (int32_t number, unsigned camera_id, uint64_t now_us) |
| Learn acquisition latency separately from slower JPEG publication. | |
| void | capture_arbiter_pose_sample (const union usher_pose_sample_union *sample, uint64_t earliest_us, uint64_t latest_us) |
| Add a pose only after the caller has established bounded clock alignment. | |
| void | capture_arbiter_pose_invalidate (void) |
| Forget pose history when synchronization is lost; keep saved coverage. | |
| bool | capture_arbiter_pose_at (uint64_t time_us, uint64_t time_error_us, union dc_shot_union *shot, double *uncertainty_m) |
| Interpolate within trusted nearby pose samples, never across a long gap. | |
| bool | capture_arbiter_observation_pose (struct capture_observation *observation, uint64_t wait_us) |
| Resolve one bounded observation; wait_us is 0 on the serial thread, at most 200000 in workers. | |
| bool | capture_arbiter_frame_timing (const char *filename, unsigned camera_id, struct capture_observation *observation) |
| Read embedded capture identity from a stable JPEG; true need not qualify timing. | |
| bool | capture_arbiter_frame_pose (const char *filename, unsigned camera_id, const union dc_shot_union *request, union dc_shot_union *exposure, double *uncertainty_m) |
| Associate embedded exposure evidence with this JPEG before geotagging. | |
Detailed Description
Session-scoped survey admission and saved-image evidence for USHER.
The serial owner offers intentions and takes ready work; camera workers return acquisition and publication results. Public state access is mutex-protected. The implementation is C11 with pthread locking and explicit resource cleanup; the C linkage guards also permit existing C++ callers and regression fixtures. Configure profiles before starting workers. No function here operates a camera, changes FC distance rules, or assumes that a request contains recoverable pixels.
- Note
- Times are MORA CLOCK_MONOTONIC microseconds unless explicitly stated. Queues and coverage are session memory, not a restart-persistent mission database.
Definition in file capture_arbiter.h.
Function Documentation
◆ capture_arbiter_acquired()
| void capture_arbiter_acquired | ( | int32_t | number, |
| unsigned | camera_id, | ||
| uint64_t | now_us ) |
Learn acquisition latency separately from slower JPEG publication.
- Parameters
-
number Original FC shot number. camera_id Backend that now owns the selected pixels. now_us Acquisition-complete time in MORA's monotonic domain.
The first plausible receipt updates service time; publication still owes capture_arbiter_complete() and no coverage is credited at this point.
Definition at line 536 of file capture_arbiter.c.
◆ capture_arbiter_complete()
| void capture_arbiter_complete | ( | const union dc_shot_union * | shot, |
| unsigned | camera_id, | ||
| bool | saved, | ||
| bool | exposure_pose_valid, | ||
| double | uncertainty_m, | ||
| uint64_t | now_us ) |
Release admission and optionally credit verified saved coverage.
- Parameters
-
shot Matching request number, with exposure pose when valid. camera_id Camera completing this observation. saved Original and required metadata were successfully published. exposure_pose_valid Pose is backed by frame timing, not just trigger time. uncertainty_m Nonnegative position margin associated with that pose. now_us Completion time; used for fallback service-time estimation.
Call on startup and metadata failures too, or that camera remains busy. Unknown pose still permits a SAVED result but never trusted coverage credit.
Definition at line 459 of file capture_arbiter.c.
◆ capture_arbiter_frame_pose()
| bool capture_arbiter_frame_pose | ( | const char * | filename, |
| unsigned | camera_id, | ||
| const union dc_shot_union * | request, | ||
| union dc_shot_union * | exposure, | ||
| double * | uncertainty_m ) |
Associate embedded exposure evidence with this JPEG before geotagging.
- Parameters
-
filename Published JPEG path, exclusively owned during inspection. camera_id Sensor identity; configured profile dimensions must match the JPEG and record. request Original request; its number is retained in the returned exposure record. [out] exposure Pose estimate at the frame's bounded observation time. [out] uncertainty_m Ground-position margin carried into coverage accounting.
- Returns
- False when evidence is missing, stale, inconsistent or outside supported bounds.
- Warning
- Identity checks prevent accidental mismatches, not hostile file replacement. Do not recycle or edit capture paths concurrently. Failure must not discard the JPEG.
Definition at line 795 of file capture_arbiter.c.
◆ capture_arbiter_frame_timing()
| bool capture_arbiter_frame_timing | ( | const char * | filename, |
| unsigned | camera_id, | ||
| struct capture_observation * | observation ) |
Read embedded capture identity from a stable JPEG; true need not qualify timing.
frame_bound may be true while kind remains UNKNOWN. Profiles are optional; when configured their dimensions must match. Call before the EXIF inode replacement.
Definition at line 739 of file capture_arbiter.c.
◆ capture_arbiter_load_camera()
| bool capture_arbiter_load_camera | ( | const char * | filename | ) |
Load one camera's measured profile without guessing geometry from its ID.
- Parameters
-
filename Bounded PANGEA_CAMERA_V1 flat key=value file; prefix c/a/l identifies the sensor.
- Returns
- True on acceptance; false with a diagnostic on invalid input or allocation failure.
The first valid profile allocates the fixed ledger and random peer session. Replacing calibration is a startup operation, not a way to reinterpret existing coverage. Input is a nonempty regular file of at most 1 KiB containing one key=value per line. Blank lines and # comments are allowed; duplicate/unknown keys and invalid decimal fields are rejected without allocation. Invalid input leaves existing calibration and session state intact.
Definition at line 238 of file capture_arbiter.c.
◆ capture_arbiter_observation_pose()
| bool capture_arbiter_observation_pose | ( | struct capture_observation * | observation, |
| uint64_t | wait_us ) |
Resolve one bounded observation; wait_us is 0 on the serial thread, at most 200000 in workers.
Definition at line 712 of file capture_arbiter.c.
◆ capture_arbiter_offer()
| bool capture_arbiter_offer | ( | const union usher_capture_arbiter_shoot_union * | request, |
| uint64_t | now_us ) |
Split a survey request into bounded per-camera intentions.
- Parameters
-
request Session-tagged shot and camera mask from the FC. now_us Receipt time used for intent age and scope freshness.
- Returns
- True when handled, including expiry or no image-camera bits; not a saved-photo ACK. False indicates an invalid request/session. Overflow replaces only the same camera's oldest waiting record, so another sensor's backlog cannot be evicted by this one.
Definition at line 334 of file capture_arbiter.c.
◆ capture_arbiter_owns()
| bool capture_arbiter_owns | ( | int32_t | number | ) |
Identify a shot whose active survey ownership must not be superseded.
- Parameters
-
number FC shot number to look up across image cameras.
- Returns
- True if any active camera owns this number; not evidence of publication.
Definition at line 526 of file capture_arbiter.c.
◆ capture_arbiter_pending()
| bool capture_arbiter_pending | ( | void | ) |
Check whether waiting or active survey work remains.
- Returns
- A synchronized snapshot, not a wait primitive or a readiness guarantee.
Definition at line 516 of file capture_arbiter.c.
◆ capture_arbiter_pose_at()
| bool capture_arbiter_pose_at | ( | uint64_t | time_us, |
| uint64_t | time_error_us, | ||
| union dc_shot_union * | shot, | ||
| double * | uncertainty_m ) |
Interpolate within trusted nearby pose samples, never across a long gap.
- Parameters
-
time_us Desired observation time in MORA's monotonic domain. time_error_us Observation-time uncertainty in microseconds. [out] shot Interpolated raw FC pose; caller must restore the observation's shot number. [out] uncertainty_m Conservative ground-position margin in metres.
- Returns
- True when all timing, motion and uncertainty checks pass. Ignore outputs on false.
Definition at line 707 of file capture_arbiter.c.
◆ capture_arbiter_pose_invalidate()
| void capture_arbiter_pose_invalidate | ( | void | ) |
Forget pose history when synchronization is lost; keep saved coverage.
Definition at line 562 of file capture_arbiter.c.
◆ capture_arbiter_pose_sample()
| void capture_arbiter_pose_sample | ( | const union usher_pose_sample_union * | sample, |
| uint64_t | earliest_us, | ||
| uint64_t | latest_us ) |
Add a pose only after the caller has established bounded clock alignment.
- Parameters
-
sample FC pose/GPS evidence, including raw fixed-point shot fields. earliest_us Earliest possible local sample time. latest_us Latest possible local sample time.
Invalid evidence clears interpolation history rather than bridging a clock discontinuity with seemingly precise coordinates.
Definition at line 571 of file capture_arbiter.c.
◆ capture_arbiter_result()
| bool capture_arbiter_result | ( | union usher_capture_arbiter_result_union * | result, |
| uint32_t | ready_mask ) |
Pop a bounded best-effort result for UART transmission.
- Parameters
-
[out] result Result whose storage is independent of the internal queue. ready_mask Current readiness snapshot to attach.
- Returns
- True if a record was popped; false when empty or result is NULL.
- Note
- Retain the popped record locally if UART transmission must be retried.
Definition at line 501 of file capture_arbiter.c.
◆ capture_arbiter_session_id()
| uint32_t capture_arbiter_session_id | ( | void | ) |
Return the peer-session token, or zero when survey mode is not configured.
- Returns
- Random nonzero token after successful profile initialization; not an authentication key.
Definition at line 304 of file capture_arbiter.c.
◆ capture_arbiter_set_camera_capacity()
| bool capture_arbiter_set_camera_capacity | ( | unsigned | camera_id, |
| unsigned | capacity ) |
Set admission from a backend's actual capacity, independent of camera ID.
- Parameters
-
camera_id One-based image-camera identity. capacity Maximum active captures, 1..2.
- Returns
- False for invalid input. Lowering capacity does not cancel active captures.
Definition at line 295 of file capture_arbiter.c.
◆ capture_arbiter_set_enforce()
| void capture_arbiter_set_enforce | ( | bool | enforce | ) |
Enable coverage-based suppression and limited delay, or observe decisions only.
- Parameters
-
enforce True permits conservative enforcement; false is the default.
- Note
- Observation still uses bounded admission and expiry, not the legacy queue policy.
Definition at line 279 of file capture_arbiter.c.
◆ capture_arbiter_set_overlap()
| bool capture_arbiter_set_overlap | ( | double | overlap | ) |
Set the overlap floor for deliberate predictive delay, not FC shot spacing.
- Parameters
-
overlap Fraction within 0..0.9.
- Returns
- False for invalid input, leaving the previous setting intact.
Definition at line 286 of file capture_arbiter.c.
◆ capture_arbiter_set_scope()
| void capture_arbiter_set_scope | ( | const union usher_capture_arbiter_state_union * | scope, |
| uint64_t | now_us ) |
Refresh survey authorization or cancel waiting work when scope is withdrawn.
- Parameters
-
scope Validated wire structure; wrong sessions and malformed values are ignored. now_us Local receipt time, not a remote FC timestamp.
A stop or removed mask bit affects waiting intentions only. An acquired original still deserves to be saved even when the survey has just ended.
Definition at line 312 of file capture_arbiter.c.
◆ capture_arbiter_stop()
| void capture_arbiter_stop | ( | void | ) |
Cancel waiting intentions, retaining active-image ownership and saved coverage.
Definition at line 553 of file capture_arbiter.c.
◆ capture_arbiter_take()
| bool capture_arbiter_take | ( | uint32_t | ready_mask, |
| uint64_t | now_us, | ||
| union dc_shot_union * | shot, | ||
| uint8_t * | mask ) |
Admit the oldest ready camera intention after optional coverage evaluation.
- Parameters
-
ready_mask Backend readiness snapshot; active-capacity limits are also enforced here. now_us Current local time for expiry and short-horizon prediction. [out] shot Original FC request, not the predicted future exposure pose. [out] mask Image camera admitted for this shot.
- Returns
- True when the caller must dispatch work and eventually call capture_arbiter_complete(). False means no admission; expiry or redundancy results may still have been queued.
Definition at line 450 of file capture_arbiter.c.