Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
coverage_scheduler.h File Reference

Fixed-memory geometric coverage accounting, independent of camera I/O. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
Include dependency graph for coverage_scheduler.h:
This graph shows which files directly or indirectly include this file:

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
stateCommitted coverage, left unchanged.
candidatesAt most COVERAGE_CANDIDATES opportunities.
countNumber of opportunities.
now_usEarliest permissible start, monotonic microseconds.
service_usPositive 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]stateInitialized committed ledger.
candidateSaved 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
stateInitialized committed ledger.
candidateObservation 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]stateCaller-owned ledger; allocate off small embedded thread stacks.
eastLower grid edge in local east metres.
northLower grid edge in local north metres.
cell_mCell 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
stateGrid geometry used to discretize the comparison; saved values are not read.
firstCandidate whose bounding-cell count is the denominator.
secondSame-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
cameraMeasured intrinsics and camera-to-body mount.
poseObservation pose with AGL and uncertainty.
origin_latitude_degLocal projection reference latitude, degrees.
origin_longitude_degLocal projection reference longitude, degrees.
[out]footprintResult, 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
cameraDelivered-image calibration and mount.
poseObservation attitude and camera-to-ground height.
columnPixel column within the delivered image.
rowPixel row within the delivered image.
[out]offsetMetres 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
stateInitialized committed ledger.
candidateProposed 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.