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
lwir_geolocation.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 SENSORAIA_LWIR_GEOLOCATION_H
19#define SENSORAIA_LWIR_GEOLOCATION_H
20
21/** @file
22 * @brief Optional camera calibration and native pixel-to-ground geometry only.
23 *
24 * @details Compiled only in analysis builds (`LWIR_ENABLE_ANALYSIS=1`). Used by
25 * lwir_analysis.c to turn hotspot centroids found in the native temperature plane
26 * of a saved LWIR JPEG into estimated WGS84 positions. No detection, JPEG or EXIF
27 * code lives here, so the geometry can be tested with synthetic poses.
28 *
29 * Frames (all right-handed):
30 * - camera: x right, y down, z forward along the optical axis (OpenCV);
31 * - body: x forward, y right, z down;
32 * - local NED at the navigation reference: north, east, down.
33 *
34 * Model limits callers must respect:
35 * - pinhole plus Brown-Conrady distortion; strong fisheye lenses are outside it;
36 * - the ground is a horizontal plane `agl_m` below the navigation reference, so
37 * terrain relief and slope translate directly into horizontal error;
38 * - pose quality is the caller's responsibility: a pose stamped at frame arrival
39 * rather than over the exposure interval can be displaced by aircraft motion,
40 * so projection results must be qualified with the pose timing evidence;
41 * - an unverified calibration yields plausible-looking but unqualified numbers.
42 */
43#include <stdbool.h>
44#include <stddef.h>
45#include <stdint.h>
46
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/** @brief Projection calibration in native coordinates, never display coordinates.
52 * @details Lens coefficients follow OpenCV's pinhole/Brown-Conrady convention.
53 * Keeping them in the stored native pixel frame prevents display rotation or
54 * preview enlargement from silently changing the ray being projected.
55 */
57 double fx, fy, cx, cy;
58 double k1, k2, p1, p2, k3;
59 double camera_to_body[9]; ///< Row-major rotation: camera right/down/forward to body forward/right/down.
60 double lever_arm_body_m[3]; ///< Navigation reference to camera origin, in body forward/right/down metres.
61 double minimum_ground_cosine; ///< Minimum normalized downward ray component; rejects unstable horizon intersections.
63 bool verified; ///< Operator verification claim; loading coefficients does not establish it.
64};
65
66/** @var lwir_camera_geometry::fx
67 * @brief Horizontal focal length in native pixels; must be positive.
68 */
69/** @var lwir_camera_geometry::fy
70 * @brief Vertical focal length in native pixels; must be positive.
71 */
72/** @var lwir_camera_geometry::cx
73 * @brief Principal-point column in native pixel coordinates.
74 */
75/** @var lwir_camera_geometry::cy
76 * @brief Principal-point row in native pixel coordinates.
77 */
78/** @var lwir_camera_geometry::k1
79 * @brief Dimensionless radial coefficient multiplying normalized radius squared.
80 */
81/** @var lwir_camera_geometry::k2
82 * @brief Dimensionless radial coefficient multiplying normalized radius to the fourth power.
83 */
84/** @var lwir_camera_geometry::p1
85 * @brief First dimensionless tangential-distortion coefficient in OpenCV order.
86 */
87/** @var lwir_camera_geometry::p2
88 * @brief Second dimensionless tangential-distortion coefficient in OpenCV order.
89 */
90/** @var lwir_camera_geometry::k3
91 * @brief Dimensionless radial coefficient multiplying normalized radius to the sixth power.
92 */
93/** @var lwir_camera_geometry::image_width
94 * @brief Native stored-image column count; resizing requires adjusted intrinsics.
95 */
96/** @var lwir_camera_geometry::image_height
97 * @brief Native stored-image row count, before display orientation changes.
98 */
99/** @var lwir_camera_geometry::camera_to_body
100 * @details Must be a proper rotation (orthonormal, determinant +1); projection
101 * rejects anything else. The loader default `{0,-1,0, 1,0,0, 0,0,1}` maps camera
102 * forward to body down and camera up (-y) to body forward: a nadir camera with
103 * the image top toward the nose.
104 */
105/** @var lwir_camera_geometry::minimum_ground_cosine
106 * @details Accepted range 0.05..1; 0.2 means rays more than about 78.5 degrees
107 * from straight down are rejected.
108 */
109
110/** @brief Observation pose; geographic angles are degrees, attitude angles radians. */
114 double uncertainty_m; ///< Observation uncertainty retained for caller qualification, not applied by projection.
115 bool synchronized; ///< Timing qualification retained for caller policy, not inferred by geometry.
116};
117
118/** @var lwir_camera_pose::latitude_deg
119 * @brief Navigation reference latitude in WGS84 degrees.
120 */
121/** @var lwir_camera_pose::longitude_deg
122 * @brief Navigation reference longitude in WGS84 degrees.
123 */
124/** @var lwir_camera_pose::altitude_ellipsoid_m
125 * @brief Navigation reference height above the WGS84 ellipsoid in metres.
126 * @details USHER's `alt_m` is the flight controller's LLA altitude, which is
127 * ellipsoidal, not mean-sea-level; the ECEF conversion requires exactly this.
128 */
129/** @var lwir_camera_pose::agl_m
130 * @brief Positive height of the navigation reference above the local ground plane.
131 */
132/** @var lwir_camera_pose::roll_rad
133 * @brief Body roll in radians for the body-to-NED attitude rotation.
134 */
135/** @var lwir_camera_pose::pitch_rad
136 * @brief Body pitch in radians for the body-to-NED attitude rotation.
137 */
138/** @var lwir_camera_pose::yaw_rad
139 * @brief Body yaw in radians, measured from north toward east.
140 */
141/** @var lwir_camera_pose::uncertainty_m
142 * @details Negative means unknown; lwir_analysis.c then reports the pose as unsynchronized.
143 */
144/** @var lwir_camera_pose::synchronized
145 * @details True only when the pose was associated with an exposure-bounding time
146 * interval. An arrival-time pose is not exposure-qualified; geometry still runs,
147 * so callers must decide whether such results are usable.
148 */
149
150/** @brief WGS84 estimate on a local horizontal plane, not a surveyed accuracy claim. */
155
156/** @var lwir_ground_point::latitude_deg
157 * @brief Estimated ground-intersection latitude in WGS84 degrees.
158 */
159/** @var lwir_ground_point::longitude_deg
160 * @brief Estimated ground-intersection longitude in WGS84 degrees.
161 */
162/** @var lwir_ground_point::altitude_ellipsoid_m
163 * @brief Assumed ground-plane height above the WGS84 ellipsoid: observation height minus AGL.
164 */
165/** @var lwir_ground_point::north_m
166 * @brief Northward ground-intersection offset from the navigation reference.
167 */
168/** @var lwir_ground_point::east_m
169 * @brief Eastward ground-intersection offset from the navigation reference.
170 */
171/** @var lwir_ground_point::slant_range_m
172 * @brief Camera-origin to ground-intersection distance along the projected ray.
173 */
174
175/** @brief Load bounded projection calibration, requiring exact native dimensions.
176 * @param[in] path Nonempty regular calibration file, at most 8192 bytes.
177 * @param width Expected native image width, within the supported LWIR bounds.
178 * @param height Expected native image height, within the supported LWIR bounds.
179 * @param[out] geometry Result, unchanged on failure.
180 * @return True for structurally valid calibration, not proof of physical accuracy.
181 * @details This is a bounded profile reader, not a general YAML implementation.
182 * Each scalar or bracketed numeric array must fit on one line. Required fields
183 * include all lens coefficients, dimensions, verification flag and the nine-value
184 * rotation; duplicate known fields fail. Optional lever arm defaults to zero and
185 * minimum_ground_cosine to 0.2. Unknown keys are ignored.
186 * @note An unverified profile is intentionally loadable for workshop checks.
187 * Loading does not validate rotation orthonormality; projection checks it before
188 * use. Neither operation establishes that a mount was physically measured.
189 * @note Lines longer than 511 characters, a missing ':' on a non-comment line,
190 * `verified` other than 0/1, nonpositive focal lengths, or a
191 * minimum_ground_cosine outside 0.05..1 all fail. Lines starting with '#',
192 * '%' or consisting of `---` are skipped. errno is not part of the failure contract.
193 */
194bool lwir_geolocation_load_calibration(const char *path, unsigned width, unsigned height,
195 struct lwir_camera_geometry *geometry);
196/** @brief Project a native subpixel location using distortion, mount and observation pose.
197 * @param pixel_x Native column, independent of JPEG rotation.
198 * @param pixel_y Native row.
199 * @param[in] camera Intrinsics and proper camera-to-body rotation.
200 * @param[in] pose Observation position, attitude and positive height above the ground plane.
201 * @param[out] point Result, unchanged on failure.
202 * @return False for invalid/nonfinite geometry, nonconvergence or near-horizon rays.
203 * @details Inverse distortion is solved in camera coordinates before mount and
204 * attitude rotations. A finite iteration budget rejects nonconvergent rays, and
205 * the downward-cosine guard avoids arbitrarily long intersections near the
206 * horizon. The intersection uses a local horizontal plane, not a terrain model.
207 * The local north/east offset is converted to latitude/longitude on the WGS84
208 * ellipsoid via ECEF, so no small-angle flat-earth approximation is involved.
209 * @warning The caller must enforce verification, observation synchronization and
210 * uncertainty policy; this geometry function does not gate on those flags.
211 */
212bool lwir_geolocation_project(double pixel_x, double pixel_y,
213 const struct lwir_camera_geometry *geometry,
214 const struct lwir_camera_pose *pose,
215 struct lwir_ground_point *point);
216#ifdef __cplusplus
217}
218#endif
219
220#endif
bool lwir_geolocation_project(double pixel_x, double pixel_y, const struct lwir_camera_geometry *geometry, const struct lwir_camera_pose *pose, struct lwir_ground_point *point)
Project a native subpixel location using distortion, mount and observation pose.
bool lwir_geolocation_load_calibration(const char *path, unsigned width, unsigned height, struct lwir_camera_geometry *geometry)
Load bounded projection calibration, requiring exact native dimensions.
Projection calibration in native coordinates, never display coordinates.
double k2
Dimensionless radial coefficient multiplying normalized radius to the fourth power.
double minimum_ground_cosine
Minimum normalized downward ray component; rejects unstable horizon intersections.
double k1
Dimensionless radial coefficient multiplying normalized radius squared.
double cx
Principal-point column in native pixel coordinates.
double k3
Dimensionless radial coefficient multiplying normalized radius to the sixth power.
double camera_to_body[9]
Row-major rotation: camera right/down/forward to body forward/right/down.
unsigned image_height
Native stored-image row count, before display orientation changes.
double fx
Horizontal focal length in native pixels; must be positive.
double p1
First dimensionless tangential-distortion coefficient in OpenCV order.
double cy
Principal-point row in native pixel coordinates.
double p2
Second dimensionless tangential-distortion coefficient in OpenCV order.
bool verified
Operator verification claim; loading coefficients does not establish it.
double fy
Vertical focal length in native pixels; must be positive.
double lever_arm_body_m[3]
Navigation reference to camera origin, in body forward/right/down metres.
unsigned image_width
Native stored-image column count; resizing requires adjusted intrinsics.
Observation pose; geographic angles are degrees, attitude angles radians.
double agl_m
Positive height of the navigation reference above the local ground plane.
double yaw_rad
Body yaw in radians, measured from north toward east.
double longitude_deg
Navigation reference longitude in WGS84 degrees.
double altitude_ellipsoid_m
Navigation reference height above the WGS84 ellipsoid in metres.
double pitch_rad
Body pitch in radians for the body-to-NED attitude rotation.
double roll_rad
Body roll in radians for the body-to-NED attitude rotation.
double uncertainty_m
Observation uncertainty retained for caller qualification, not applied by projection.
double latitude_deg
Navigation reference latitude in WGS84 degrees.
WGS84 estimate on a local horizontal plane, not a surveyed accuracy claim.
double slant_range_m
Camera-origin to ground-intersection distance along the projected ray.
double east_m
Eastward ground-intersection offset from the navigation reference.
double latitude_deg
Estimated ground-intersection latitude in WGS84 degrees.
double north_m
Northward ground-intersection offset from the navigation reference.
double altitude_ellipsoid_m
Assumed ground-plane height above the WGS84 ellipsoid: observation height minus AGL.
double longitude_deg
Estimated ground-intersection longitude in WGS84 degrees.
One timestamped geographic position for a replay annotation.