Fixed-memory geometric coverage accounting, independent of camera I/O. More...
#include <stdbool.h>#include <stddef.h>#include <stdint.h>

Go to the source code of this file.
Data Structures | |
| struct | coverage_camera |
| Measured pinhole calibration for the delivered image, including its mount. More... | |
| struct | coverage_pose |
| Pose estimate and its positional margin for a single observation. More... | |
| struct | coverage_point |
| Local ground coordinates in metres, east and north of the projection origin. More... | |
| struct | coverage_footprint |
| Convex ground quadrilateral with a conservative boundary margin. More... | |
| struct | coverage_candidate |
| One feasible observation; deadlines constrain acquisition start, not saving. More... | |
| struct | coverage_state |
| Fixed coverage ledger; zero cells are unknown, not necessarily unphotographed. More... | |
Macros | |
| #define | COVERAGE_SIDE 1024 |
| #define | COVERAGE_CAMERAS 3 |
| #define | COVERAGE_CANDIDATES 4 |
| #define | COVERAGE_SCAN_LIMIT 4096 |
Functions | |
| bool | coverage_project (const struct coverage_camera *camera, const struct coverage_pose *pose, double origin_latitude_deg, double origin_longitude_deg, struct coverage_footprint *footprint) |
| Project delivered-image corners onto a local flat ground plane. | |
| bool | coverage_project_pixel (const struct coverage_camera *camera, const struct coverage_pose *pose, double column, double row, struct coverage_point *offset) |
| Project an image pixel onto the same ground plane as the coverage footprint. | |
| bool | coverage_init (struct coverage_state *state, double east, double north, double cell_m) |
| Clear the ledger and set its fixed spatial domain. | |
| double | coverage_gain (const struct coverage_state *state, const struct coverage_candidate *candidate) |
| Score additional detail in conservatively contained cells without mutation. | |
| bool | coverage_commit (struct coverage_state *state, const struct coverage_candidate *candidate) |
| Credit a successfully saved observation, retaining the best detail per cell. | |
| bool | coverage_wholly_saved (const struct coverage_state *state, const struct coverage_candidate *candidate) |
| Check whether skipping this observation is geometrically conservative. | |
| double | coverage_overlap (const struct coverage_state *state, const struct coverage_candidate *first, const struct coverage_candidate *second) |
| Estimate conservative overlap for deciding whether a delay is acceptable. | |
| int | coverage_choose (const struct coverage_state *state, const struct coverage_candidate *candidates, size_t count, uint64_t now_us, uint64_t service_us) |
| Choose the first observation of the best feasible one- or two-shot plan. | |
Detailed Description
Fixed-memory geometric coverage accounting, independent of camera I/O.
This layer compares footprints rather than decoding photographs. Keep predicted observations separate from committed coverage: only the capture owner knows whether an original and its metadata were successfully published.
- Note
- Functions do not lock. Serialize access to a shared state at the caller. Invalid geometry means "unknown", never "already photographed".
Definition in file coverage_scheduler.h.
Macro Definition Documentation
◆ COVERAGE_CAMERAS
| #define COVERAGE_CAMERAS 3 |
Image-camera IDs 1..3; EARcam audio is not image coverage.
Definition at line 36 of file coverage_scheduler.h.
◆ COVERAGE_CANDIDATES
| #define COVERAGE_CANDIDATES 4 |
Bounded lookahead set, not a queue of retained image pixels.
Definition at line 37 of file coverage_scheduler.h.
◆ COVERAGE_SCAN_LIMIT
| #define COVERAGE_SCAN_LIMIT 4096 |
Maximum cells per footprint scan, limiting decision work.
Definition at line 38 of file coverage_scheduler.h.
◆ COVERAGE_SIDE
| #define COVERAGE_SIDE 1024 |
Cells per axis; memory does not grow with flight duration.
Definition at line 35 of file coverage_scheduler.h.
Function Documentation
◆ coverage_choose()
| int coverage_choose | ( | const struct coverage_state * | state, |
| const struct coverage_candidate * | candidates, | ||
| size_t | count, | ||
| uint64_t | now_us, | ||
| uint64_t | service_us ) |
Choose the first observation of the best feasible one- or two-shot plan.
- Parameters
-
state Committed coverage, left unchanged. candidates At most COVERAGE_CANDIDATES opportunities. count Number of opportunities. now_us Earliest permissible start, monotonic microseconds. service_us Positive serialized acquisition interval used between choices.
- Returns
- First candidate index, or -1 when no positive feasible gain is known.
Union scoring avoids double-counting repeated ground in the second view. Ties favor an earlier start, then greater first-shot gain. The caller still enforces overlap, uncertainty and delay limits; this is not a global flight planner.
Definition at line 218 of file coverage_scheduler.c.
◆ coverage_commit()
| bool coverage_commit | ( | struct coverage_state * | state, |
| const struct coverage_candidate * | candidate ) |
Credit a successfully saved observation, retaining the best detail per cell.
- Parameters
-
[in,out] state Initialized committed ledger. candidate Saved image footprint with trusted pose and detail score.
- Returns
- True for a valid bounded update, even if no cells improve; false for unknown geometry.
- Precondition
- The caller has verified publication. Never call this for a mere capture request.
Definition at line 204 of file coverage_scheduler.c.
◆ coverage_gain()
| double coverage_gain | ( | const struct coverage_state * | state, |
| const struct coverage_candidate * | candidate ) |
Score additional detail in conservatively contained cells without mutation.
- Parameters
-
state Initialized committed ledger. candidate Observation to evaluate.
- Returns
- Quality-weighted square metres, zero for no credited gain, or -1 for unknown geometry. Zero alone is not permission to skip; use coverage_wholly_saved().
Definition at line 199 of file coverage_scheduler.c.
◆ coverage_init()
| bool coverage_init | ( | struct coverage_state * | state, |
| double | east, | ||
| double | north, | ||
| double | cell_m ) |
Clear the ledger and set its fixed spatial domain.
- Parameters
-
[out] state Caller-owned ledger; allocate off small embedded thread stacks. east Lower grid edge in local east metres. north Lower grid edge in local north metres. cell_m Cell edge in metres, within 0.25..100.
- Returns
- True on initialization; false leaves state unchanged.
Definition at line 105 of file coverage_scheduler.c.
◆ coverage_overlap()
| double coverage_overlap | ( | const struct coverage_state * | state, |
| const struct coverage_candidate * | first, | ||
| const struct coverage_candidate * | second ) |
Estimate conservative overlap for deciding whether a delay is acceptable.
- Parameters
-
state Grid geometry used to discretize the comparison; saved values are not read. first Candidate whose bounding-cell count is the denominator. second Same-camera footprint to overlap with.
- Returns
- Conservative fraction in 0..1, or -1 if the comparison is unknown.
- Note
- This is asymmetric and deliberately stricter than exact polygon overlap.
Definition at line 269 of file coverage_scheduler.c.
◆ coverage_project()
| bool coverage_project | ( | const struct coverage_camera * | camera, |
| const struct coverage_pose * | pose, | ||
| double | origin_latitude_deg, | ||
| double | origin_longitude_deg, | ||
| struct coverage_footprint * | footprint ) |
Project delivered-image corners onto a local flat ground plane.
- Parameters
-
camera Measured intrinsics and camera-to-body mount. pose Observation pose with AGL and uncertainty. origin_latitude_deg Local projection reference latitude, degrees. origin_longitude_deg Local projection reference longitude, degrees. [out] footprint Result, written only on success.
- Returns
- False for invalid, near-horizon or excessively distant geometry.
- Warning
- A plausible footprint does not establish terrain visibility, focus or exposure synchronization. Zero mount means image-up forward and optical-axis down.
Definition at line 46 of file coverage_scheduler.c.
◆ coverage_project_pixel()
| bool coverage_project_pixel | ( | const struct coverage_camera * | camera, |
| const struct coverage_pose * | pose, | ||
| double | column, | ||
| double | row, | ||
| struct coverage_point * | offset ) |
Project an image pixel onto the same ground plane as the coverage footprint.
- Parameters
-
camera Delivered-image calibration and mount. pose Observation attitude and camera-to-ground height. column Pixel column within the delivered image. row Pixel row within the delivered image. [out] offset Metres east/north relative to the observation position.
- Returns
- False for invalid pixels or geometry, leaving offset unchanged.
Reuses whole-footprint qualification and the existing mount/body rotation order.
Definition at line 88 of file coverage_scheduler.c.
◆ coverage_wholly_saved()
| bool coverage_wholly_saved | ( | const struct coverage_state * | state, |
| const struct coverage_candidate * | candidate ) |
Check whether skipping this observation is geometrically conservative.
- Parameters
-
state Initialized committed ledger. candidate Proposed observation.
- Returns
- True only when the uncertainty-expanded bounding region already has at least the requested detail. Outside the grid or work budget, return false.
Definition at line 252 of file coverage_scheduler.c.