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
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#ifndef USHER_COVERAGE_SCHEDULER_H
19#define USHER_COVERAGE_SCHEDULER_H
20
21/**
22 * @file coverage_scheduler.h
23 * @brief Fixed-memory geometric coverage accounting, independent of camera I/O.
24 * @details This layer compares footprints rather than decoding photographs. Keep
25 * predicted observations separate from committed coverage: only the capture owner
26 * knows whether an original and its metadata were successfully published.
27 * @note Functions do not lock. Serialize access to a shared state at the caller.
28 * Invalid geometry means "unknown", never "already photographed".
29 */
30
31#include <stdbool.h>
32#include <stddef.h>
33#include <stdint.h>
34
35#define COVERAGE_SIDE 1024 /**< Cells per axis; memory does not grow with flight duration. */
36#define COVERAGE_CAMERAS 3 /**< Image-camera IDs 1..3; EARcam audio is not image coverage. */
37#define COVERAGE_CANDIDATES 4 /**< Bounded lookahead set, not a queue of retained image pixels. */
38#define COVERAGE_SCAN_LIMIT 4096 /**< Maximum cells per footprint scan, limiting decision work. */
39
40/** @brief Measured pinhole calibration for the delivered image, including its mount. */
42 unsigned width, height; /**< Delivered dimensions in pixels, after any camera crop or resize. */
43 double fx, fy, cx, cy; /**< Focal lengths and principal point in delivered-image pixels. */
44 double mount_roll_deg, mount_pitch_deg, mount_yaw_deg; /**< Camera-to-body rotation, degrees, Rz*Ry*Rx. */
45};
46/** @var coverage_camera::width
47 * @brief Delivered width in pixels; must agree with the saved image, not the sensor mode alone. */
48/** @var coverage_camera::fx
49 * @brief Horizontal focal length in delivered-image pixels. */
50/** @var coverage_camera::fy
51 * @brief Vertical focal length in delivered-image pixels. */
52/** @var coverage_camera::cx
53 * @brief Principal-point column in delivered-image pixels. */
54/** @var coverage_camera::mount_roll_deg
55 * @brief Camera-to-body roll in degrees; mounting is applied before aircraft attitude. */
56/** @var coverage_camera::mount_pitch_deg
57 * @brief Camera-to-body pitch in degrees, using the same convention as PANGEA. */
58/** @brief Pose estimate and its positional margin for a single observation. */
60 double latitude_deg, longitude_deg, agl_m; /**< Geographic degrees and height above the local ground plane. */
61 double roll_deg, pitch_deg, yaw_deg; /**< Body attitude in degrees using the USHER/PANGEA convention. */
62 double uncertainty_m; /**< Nonnegative ground-position margin; not a statistical confidence level. */
63};
64/** @var coverage_pose::latitude_deg
65 * @brief Observation latitude in geographic degrees, not FC fixed-point units. */
66/** @var coverage_pose::longitude_deg
67 * @brief Observation longitude in geographic degrees. */
68/** @var coverage_pose::roll_deg
69 * @brief Aircraft roll in degrees. */
70/** @var coverage_pose::pitch_deg
71 * @brief Aircraft pitch in degrees. */
72/** @brief Local ground coordinates in metres, east and north of the projection origin. */
73struct coverage_point { double east, north; };
74/** @var coverage_point::east
75 * @brief Metres east of the shared local geographic reference. */
76/** @var coverage_point::north
77 * @brief Metres north of the shared local geographic reference. */
78/** @brief Convex ground quadrilateral with a conservative boundary margin. */
80 struct coverage_point corner[4]; /**< Cyclic vertices, either winding; never a crossed polygon. */
81 double uncertainty_m; /**< Metres to exclude from credit and include when testing redundancy. */
82};
83/** @brief One feasible observation; deadlines constrain acquisition start, not saving. */
85 struct coverage_footprint footprint; /**< Predicted or saved footprint, according to the caller's operation. */
86 uint64_t ready_us, deadline_us; /**< Earliest/latest start in the caller's monotonic microsecond domain. */
87 unsigned camera_id; /**< One-based image-camera identity; coverage is never shared between sensors. */
88 uint8_t quality; /**< Positive comparable detail score, 1..255; not an object-detection probability. */
89};
90/** @var coverage_candidate::ready_us
91 * @brief Earliest acquisition start; all candidates must share a monotonic time domain. */
92/** @brief Fixed coverage ledger; zero cells are unknown, not necessarily unphotographed. */
94 double origin_east, origin_north, cell_m; /**< Grid lower corner and cell edge, all in metres. */
95 uint8_t saved[COVERAGE_CAMERAS][COVERAGE_SIDE * COVERAGE_SIDE]; /**< Best committed detail per camera and cell. */
96};
97/** @var coverage_state::origin_east
98 * @brief Lower east grid edge in metres relative to the projection origin. */
99/** @var coverage_state::origin_north
100 * @brief Lower north grid edge in metres relative to the projection origin. */
101
102#ifdef __cplusplus
103extern "C" {
104#endif
105/** @brief Project delivered-image corners onto a local flat ground plane.
106 * @param camera Measured intrinsics and camera-to-body mount.
107 * @param pose Observation pose with AGL and uncertainty.
108 * @param origin_latitude_deg Local projection reference latitude, degrees.
109 * @param origin_longitude_deg Local projection reference longitude, degrees.
110 * @param[out] footprint Result, written only on success.
111 * @return False for invalid, near-horizon or excessively distant geometry.
112 * @warning A plausible footprint does not establish terrain visibility, focus or
113 * exposure synchronization. Zero mount means image-up forward and optical-axis down.
114 */
115bool coverage_project(const struct coverage_camera *camera, const struct coverage_pose *pose,
116 double origin_latitude_deg, double origin_longitude_deg, struct coverage_footprint *footprint);
117/** @brief Project an image pixel onto the same ground plane as the coverage footprint.
118 * @param camera Delivered-image calibration and mount.
119 * @param pose Observation attitude and camera-to-ground height.
120 * @param column Pixel column within the delivered image.
121 * @param row Pixel row within the delivered image.
122 * @param[out] offset Metres east/north relative to the observation position.
123 * @return False for invalid pixels or geometry, leaving offset unchanged.
124 * @details Reuses whole-footprint qualification and the existing mount/body rotation order. */
125bool coverage_project_pixel(const struct coverage_camera *camera, const struct coverage_pose *pose,
126 double column, double row, struct coverage_point *offset);
127/** @brief Clear the ledger and set its fixed spatial domain.
128 * @param[out] state Caller-owned ledger; allocate off small embedded thread stacks.
129 * @param east Lower grid edge in local east metres.
130 * @param north Lower grid edge in local north metres.
131 * @param cell_m Cell edge in metres, within 0.25..100.
132 * @return True on initialization; false leaves state unchanged.
133 */
134bool coverage_init(struct coverage_state *state, double east, double north, double cell_m);
135/** @brief Score additional detail in conservatively contained cells without mutation.
136 * @param state Initialized committed ledger.
137 * @param candidate Observation to evaluate.
138 * @return Quality-weighted square metres, zero for no credited gain, or -1 for
139 * unknown geometry. Zero alone is not permission to skip; use coverage_wholly_saved().
140 */
141double coverage_gain(const struct coverage_state *state, const struct coverage_candidate *candidate);
142/** @brief Credit a successfully saved observation, retaining the best detail per cell.
143 * @param[in,out] state Initialized committed ledger.
144 * @param candidate Saved image footprint with trusted pose and detail score.
145 * @return True for a valid bounded update, even if no cells improve; false for unknown geometry.
146 * @pre The caller has verified publication. Never call this for a mere capture request.
147 */
148bool coverage_commit(struct coverage_state *state, const struct coverage_candidate *candidate);
149/** @brief Check whether skipping this observation is geometrically conservative.
150 * @param state Initialized committed ledger.
151 * @param candidate Proposed observation.
152 * @return True only when the uncertainty-expanded bounding region already has at
153 * least the requested detail. Outside the grid or work budget, return false.
154 */
155bool coverage_wholly_saved(const struct coverage_state *state, const struct coverage_candidate *candidate);
156/** @brief Estimate conservative overlap for deciding whether a delay is acceptable.
157 * @param state Grid geometry used to discretize the comparison; saved values are not read.
158 * @param first Candidate whose bounding-cell count is the denominator.
159 * @param second Same-camera footprint to overlap with.
160 * @return Conservative fraction in 0..1, or -1 if the comparison is unknown.
161 * @note This is asymmetric and deliberately stricter than exact polygon overlap.
162 */
163double coverage_overlap(const struct coverage_state *state, const struct coverage_candidate *first,
164 const struct coverage_candidate *second);
165/** @brief Choose the first observation of the best feasible one- or two-shot plan.
166 * @param state Committed coverage, left unchanged.
167 * @param candidates At most COVERAGE_CANDIDATES opportunities.
168 * @param count Number of opportunities.
169 * @param now_us Earliest permissible start, monotonic microseconds.
170 * @param service_us Positive serialized acquisition interval used between choices.
171 * @return First candidate index, or -1 when no positive feasible gain is known.
172 * @details Union scoring avoids double-counting repeated ground in the second
173 * view. Ties favor an earlier start, then greater first-shot gain. The caller still
174 * enforces overlap, uncertainty and delay limits; this is not a global flight planner.
175 */
176int coverage_choose(const struct coverage_state *state, const struct coverage_candidate *candidates,
177 size_t count, uint64_t now_us, uint64_t service_us);
178#ifdef __cplusplus
179}
180#endif
181
182#endif
static uint64_t service_us[COVERAGE_CAMERAS]
#define COVERAGE_CAMERAS
double coverage_gain(const struct coverage_state *state, const struct coverage_candidate *candidate)
Score additional detail in conservatively contained cells without mutation.
#define COVERAGE_SIDE
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_init(struct coverage_state *state, double east, double north, double cell_m)
Clear the ledger and set its fixed spatial domain.
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.
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.
bool coverage_wholly_saved(const struct coverage_state *state, const struct coverage_candidate *candidate)
Check whether skipping this observation is geometrically conservative.
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.
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.
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
static size_t count
Definition pose_log.c:79
Measured pinhole calibration for the delivered image, including its mount.
double cx
Principal-point column in delivered-image pixels.
double mount_roll_deg
Camera-to-body roll in degrees; mounting is applied before aircraft attitude.
double mount_pitch_deg
Camera-to-body pitch in degrees, using the same convention as PANGEA.
unsigned width
Delivered width in pixels; must agree with the saved image, not the sensor mode alone.
double fy
Vertical focal length in delivered-image pixels.
double fx
Horizontal focal length in delivered-image pixels.
One feasible observation; deadlines constrain acquisition start, not saving.
struct coverage_footprint footprint
uint64_t ready_us
Earliest acquisition start; all candidates must share a monotonic time domain.
Convex ground quadrilateral with a conservative boundary margin.
struct coverage_point corner[4]
Local ground coordinates in metres, east and north of the projection origin.
double north
Metres north of the shared local geographic reference.
double east
Metres east of the shared local geographic reference.
Pose estimate and its positional margin for a single observation.
double pitch_deg
Aircraft pitch in degrees.
double latitude_deg
Observation latitude in geographic degrees, not FC fixed-point units.
double roll_deg
Aircraft roll in degrees.
double longitude_deg
Observation longitude in geographic degrees.
Fixed coverage ledger; zero cells are unknown, not necessarily unphotographed.
uint8_t saved[COVERAGE_CAMERAS][COVERAGE_SIDE *COVERAGE_SIDE]
double origin_north
Lower north grid edge in metres relative to the projection origin.
double origin_east
Lower east grid edge in metres relative to the projection origin.
static struct camera_backend camera
Definition usher.c:521