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
usher_sources.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/**
19 * @file usher_sources.h
20 * @brief Convert validated USHER AI Camera evidence into GREAT source records.
21 * @details Inputs must be real bounded JPEGs with complete EXIF, profile-matched
22 * dimensions, and qualified pose evidence. Synthetic map imagery and nominal
23 * lens-only geometry are rejected rather than promoted into survey sources.
24 */
25#ifndef PANGEA_USHER_SOURCES_H
26#define PANGEA_USHER_SOURCES_H
27
28extern "C" {
29#include "camera_profile.h"
30}
31#include "sensor_capture.h"
32#include <charconv>
33#include <sys/stat.h>
34
35namespace pangea_survey {
36/**
37 * @brief Read a photo snapshot and verify each source against profile/evidence.
38 * @param[in] config GREAT session settings, measured camera profile and source directory.
39 * @param[in] manifest Bounded `USHER_AICAM_V1` filename snapshot.
40 * @return Fully validated sources with camera geometry and capture provenance.
41 * @throws std::runtime_error If any JPEG, EXIF field, profile, frame identity,
42 * pose qualification, or shared-coverage check fails.
43 * @details Exposure-aligned pose is required unless configuration explicitly
44 * admits the recorded-pose approximation policy.
45 */
46inline std::vector<OrthoSource> readUsherSources(const MapConfig& config, const std::filesystem::path& manifest) {
48 if (!usher_camera_profile_read(config.cameraProfile.c_str(), &profile) || profile.camera_id != 2)
49 throw std::runtime_error("GREAT requires an AI Camera profile with filename_prefix=a");
50 const auto& calibration = profile.calibration;
51 std::ifstream input(manifest);
52 std::string name;
53 if (!std::getline(input, name) || name != "USHER_AICAM_V1")
54 throw std::runtime_error("AI Camera input requires a GREAT session photo snapshot");
55 std::vector<OrthoSource> result;
56 std::map<std::string, bool> names;
57 while (std::getline(input, name)) {
58 if (result.size() == 4096 || name.empty() || name.size() > 160 || name.front() != 'a' ||
59 name.find_first_not_of("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.-") != std::string::npos ||
60 std::filesystem::path(name).extension() != ".jpg" || !names.emplace(name, true).second)
61 throw std::runtime_error("Invalid or duplicate AI Camera photo basename");
62 OrthoSource source;
63 source.path = (config.sourceDirectory.empty() ? config.photoDirectory : config.sourceDirectory) / name;
64 struct stat status{};
65 if (lstat(source.path.c_str(), &status) || !S_ISREG(status.st_mode) || status.st_size <= 0 ||
66 status.st_size > 128 * 1024 * 1024)
67 throw std::runtime_error("AI Camera input must be a bounded regular JPEG, not a symlink");
68 std::array<unsigned char, EXIF_MAX_PAYLOAD> payload{};
69 std::size_t size = 0;
70 exif_view view{};
71 if (exif_read_jpeg(source.path.c_str(), payload.data(), payload.size(), &size) || exif_parse(&view, payload.data(), size))
72 throw std::runtime_error("AI Camera JPEG has no valid complete EXIF: " + name);
73 const auto text = [&](exif_directory directory, uint16_t tag) {
74 exif_value field{};
75 if (!exif_get(&view, directory, tag, &field)) return std::string();
76 return std::string(reinterpret_cast<const char*>(field.data), exif_text_length(&field));
77 };
78 const auto comment = text(EXIF_CAMERA, EXIF_USER_COMMENT);
79 if (comment.find("USHER_MOCK_MAP_V1") != std::string::npos || comment.find("USHER_LENS_V1") != std::string::npos)
80 throw std::runtime_error("Synthetic or lens-derived photos are not raw AI Camera inputs");
81 const auto description = text(EXIF_PRIMARY, EXIF_IMAGE_DESCRIPTION);
82 if (description.rfind("Paparazzi USHER ", 0) != 0)
83 throw std::runtime_error("AI Camera input lacks USHER provenance");
84 std::map<std::string, std::string> fields;
85 std::istringstream parts(description);
86 std::string part;
87 std::getline(parts, part, ';');
88 while (std::getline(parts, part, ';')) {
89 const auto separator = part.find('=');
90 if (separator == std::string::npos) throw std::runtime_error("Invalid USHER EXIF field");
91 const auto trim = [](std::string value) {
92 const auto first = value.find_first_not_of(" \t\r\n");
93 if (first == std::string::npos) return std::string();
94 return value.substr(first, value.find_last_not_of(" \t\r\n") - first + 1);
95 };
96 if (!fields.emplace(trim(part.substr(0, separator)), trim(part.substr(separator + 1))).second)
97 throw std::runtime_error("Duplicate USHER EXIF field");
98 }
99 const auto required = [&](const char* key) -> const std::string& {
100 const auto found = fields.find(key);
101 if (found == fields.end() || found->second.empty()) throw std::runtime_error(std::string("USHER EXIF lacks ") + key);
102 return found->second;
103 };
104 const auto real = [&](const char* key, double low, double high) {
105 const double value = number(required(key), key);
106 range(value, low, high, key);
107 return value;
108 };
109 const auto integer = [&](const char* key) {
110 const auto& value = required(key);
111 uint64_t parsed = 0;
112 const auto converted = std::from_chars(value.data(), value.data() + value.size(), parsed);
113 if (converted.ec != std::errc() || converted.ptr != value.data() + value.size())
114 throw std::runtime_error(std::string("Invalid USHER integer ") + key);
115 return parsed;
116 };
117 bool exposurePose = true;
118 for (const auto* key : {"capture_pose_synchronized", "observation_pose_aligned", "frame_identity_bound"}) {
119 const auto& value = required(key);
120 if (value != "true" && value != "false") throw std::runtime_error("Invalid USHER pose qualification");
121 exposurePose = exposurePose && value == "true";
122 }
123 if (required("altitude_datum") != "flight_controller_navigation")
124 throw std::runtime_error("AI Camera mapping requires FC navigation altitude");
125 if (!exposurePose && !config.allowRecordedPose)
126 throw std::runtime_error("AI Camera mapping requires exposure-aligned, frame-bound pose; recorded policy is explicitly approximate");
127 if (exposurePose) {
128 if (required("observation_time_kind") != "sensor_exposure_interval")
129 throw std::runtime_error("AI Camera mapping requires sensor exposure timing");
130 const auto earliest = integer("observation_earliest_monotonic_us"), latest = integer("observation_latest_monotonic_us");
131 if (!earliest || latest < earliest || latest - earliest > 50000 || latest > uint64_t(LLONG_MAX / 10))
132 throw std::runtime_error("AI Camera observation interval exceeds 50 ms or is invalid");
137 !capture.sequence || !capture.sensor_timestamp_ns || capture.sequence != integer("observation_sequence") ||
138 capture.sensor_timestamp_ns != integer("sensor_timestamp_ns") || capture.boot_id != required("observation_boot_id") ||
139 capture.width != calibration.width || capture.height != calibration.height ||
140 capture.monotonic_us < earliest || capture.monotonic_us > latest)
141 throw std::runtime_error("AI Camera frame identity/dimensions disagree with its observation pose");
142 source.poseTime = static_cast<long long>(earliest * 10); source.frameTime = static_cast<long long>(latest * 10);
143 }
144 FILE* jpeg = fopen(source.path.c_str(), "rb");
145 uint32_t width = 0, height = 0;
146 unsigned components = 0;
147 const bool dimensions = jpeg && !exif_jpeg_dimensions(jpeg, &width, &height, &components);
148 const int closed = jpeg ? fclose(jpeg) : -1;
149 if (!dimensions || closed || width != calibration.width || height != calibration.height)
150 throw std::runtime_error("AI Camera JPEG dimensions disagree with its profile");
151 exif_value orientation{};
152 uint32_t upright = 1;
153 if (exif_get(&view, EXIF_PRIMARY, EXIF_ORIENTATION, &orientation) &&
154 (!exif_value_unsigned(&orientation, 0, &upright) || upright != 1))
155 throw std::runtime_error("AI Camera input must be upright sensor pixels");
156 source.latitude = real(exposurePose ? "observation_lat_deg" : "lat_deg", -80, 84);
157 source.longitude = real(exposurePose ? "observation_lon_deg" : "lon_deg", -180, 180);
158 source.altitude = real(exposurePose ? "observation_alt_m" : "alt_m", -1000, 20000);
159 source.bank = real(exposurePose ? "observation_roll_deg" : "roll_deg", -180, 180);
160 source.pitch = real(exposurePose ? "observation_pitch_deg" : "pitch_deg", -90, 90);
161 source.heading = real(exposurePose ? "observation_yaw_deg" : "yaw_deg", -360, 360);
162 source.poseUncertainty = exposurePose ? real("observation_pose_uncertainty_m", 0, config.maxPoseUncertainty) :
163 std::numeric_limits<double>::quiet_NaN();
164 source.width = int(calibration.width); source.height = int(calibration.height);
165 source.focal = calibration.fx; source.focalY = calibration.fy;
166 source.cx = calibration.cx; source.cy = calibration.cy;
167 source.referencePlane = config.mosaicReferencePlane;
168 source.distorted = true;
170 coverage_pose pose{};
171 pose.latitude_deg = source.latitude; pose.longitude_deg = source.longitude;
172 pose.agl_m = source.altitude - source.referencePlane;
173 pose.roll_deg = source.bank; pose.pitch_deg = source.pitch; pose.yaw_deg = source.heading;
174 pose.uncertainty_m = exposurePose ? source.poseUncertainty : 0;
175 coverage_footprint footprint{};
176 if (!coverage_project(&calibration, &pose, source.latitude, source.longitude, &footprint))
177 throw std::runtime_error("AI Camera calibration/pose fails shared coverage geometry validation");
178 source.camera.emplace(source.focal, source.focalY, source.cx, source.cy, source.bank, source.pitch, source.heading,
179 calibration.mount_roll_deg, calibration.mount_pitch_deg, calibration.mount_yaw_deg);
180 for (const double column : {0.0, double(source.width - 1)}) for (const double row : {0.0, double(source.height - 1)})
181 source.camera->ground(column, row, source.altitude - source.referencePlane);
182 result.push_back(std::move(source));
183 }
184 if (!input.eof() || result.empty()) throw std::runtime_error("Empty or unreadable AI Camera snapshot");
185 return result;
186}
187}
188#endif
bool usher_camera_profile_read(const char *filename, struct usher_camera_profile *profile)
Read a bounded PANGEA_CAMERA_V1 key=value calibration file.
Public C API for reading PANGEA camera calibration profiles.
size_t size
Definition chdk_pipe.c:143
static bool capture(struct transport *transport, FILE *file, const struct capture_settings *settings)
Capture to the camera's SD card and download the resulting JPEG.
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.
static struct latest_measurement latest
bool exif_value_unsigned(const struct exif_value *value, size_t index, uint32_t *result)
Decode one BYTE, SHORT or LONG component without an unaligned load.
Definition exifite.c:339
int exif_parse(struct exif_view *view, const unsigned char *payload, size_t size)
Validate an EXIF APP1 payload and create a borrowed view.
Definition exifite.c:257
exif_directory
Directory identities, not on-disk tag numbers or offsets.
Definition exifite.h:59
bool exif_get(const struct exif_view *view, enum exif_directory directory, uint16_t tag, struct exif_value *value)
Look up a directory-local tag without copying its bytes.
Definition exifite.c:310
int exif_read_jpeg(const char *filename, unsigned char *payload, size_t capacity, size_t *size)
Read the single EXIF APP1 segment before the first JPEG scan.
Definition exifite.c:1022
int exif_jpeg_dimensions(FILE *input, uint32_t *width, uint32_t *height, unsigned *components)
Inspect the frame header without allocating or decoding image pixels.
Definition exifite.c:1309
size_t exif_text_length(const struct exif_value *value)
Count text bytes after trimming trailing NUL padding only.
Definition exifite.c:399
@ EXIF_CAMERA
Definition exifite.h:59
@ EXIF_PRIMARY
Definition exifite.h:59
@ EXIF_IMAGE_DESCRIPTION
Definition exifite.h:80
@ EXIF_USER_COMMENT
Definition exifite.h:93
@ EXIF_ORIENTATION
Definition exifite.h:81
char evidence[8192]
Definition lwir_image.c:66
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
static struct usher_camera_profile profile
std::string trim(const std::string &text)
Strip the ASCII whitespace allowed around route INI tokens.
Definition route.h:130
void range(double value, double minimum, double maximum, const std::string &name)
Enforce the inclusive policy bounds for a parsed setting.
Definition route.h:160
std::vector< OrthoSource > readUsherSources(const MapConfig &config, const std::filesystem::path &manifest)
Read a photo snapshot and verify each source against profile/evidence.
double number(const std::string &text, const std::string &name)
Read a complete finite numeric route field.
Definition route.h:141
Exact bounded SENSOR02 capture evidence, independent of TIFF byte order.
static bool sensor_capture_decode(struct sensor_capture *record, const unsigned char *data, size_t size)
Decode a complete SENSOR02 record.
#define SENSOR_CAPTURE_TAG
Convex ground quadrilateral with a conservative boundary margin.
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.
Borrowed bytes plus enough type information for safe interpretation.
Definition exifite.h:119
const unsigned char * data
Definition exifite.h:120
Borrowed view of a validated APP1 payload.
Definition exifite.h:131
Fully parsed settings shared by orthomap and XYZ export.
Definition map_config.h:41
std::filesystem::path cameraProfile
Definition map_config.h:60
std::filesystem::path sourceDirectory
Definition map_config.h:59
std::filesystem::path photoDirectory
Definition map_config.h:60
One fixed-session source image and its camera/pose evidence.
Definition ortho_map.h:55
std::filesystem::path path
Definition ortho_map.h:56
std::optional< CameraPlane > camera
Definition ortho_map.h:57
static constexpr double k2
static constexpr double k1
static constexpr double redScale
static constexpr double blueScale
One measured camera calibration loaded from the flat PANGEA profile format.
struct usher_control_result result
Definition usher.c:377