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 File Reference

Optional camera calibration and native pixel-to-ground geometry only. More...

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

Go to the source code of this file.

Data Structures

struct  lwir_camera_geometry
 Projection calibration in native coordinates, never display coordinates. More...
struct  lwir_camera_pose
 Observation pose; geographic angles are degrees, attitude angles radians. More...
struct  lwir_ground_point
 WGS84 estimate on a local horizontal plane, not a surveyed accuracy claim. More...

Functions

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.
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.

Detailed Description

Optional camera calibration and native pixel-to-ground geometry only.

Compiled only in analysis builds (LWIR_ENABLE_ANALYSIS=1). Used by lwir_analysis.c to turn hotspot centroids found in the native temperature plane of a saved LWIR JPEG into estimated WGS84 positions. No detection, JPEG or EXIF code lives here, so the geometry can be tested with synthetic poses.

Frames (all right-handed):

  • camera: x right, y down, z forward along the optical axis (OpenCV);
  • body: x forward, y right, z down;
  • local NED at the navigation reference: north, east, down.

Model limits callers must respect:

  • pinhole plus Brown-Conrady distortion; strong fisheye lenses are outside it;
  • the ground is a horizontal plane agl_m below the navigation reference, so terrain relief and slope translate directly into horizontal error;
  • pose quality is the caller's responsibility: a pose stamped at frame arrival rather than over the exposure interval can be displaced by aircraft motion, so projection results must be qualified with the pose timing evidence;
  • an unverified calibration yields plausible-looking but unqualified numbers.

Definition in file lwir_geolocation.h.

Function Documentation

◆ lwir_geolocation_load_calibration()

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.

Parameters
[in]pathNonempty regular calibration file, at most 8192 bytes.
widthExpected native image width, within the supported LWIR bounds.
heightExpected native image height, within the supported LWIR bounds.
[out]geometryResult, unchanged on failure.
Returns
True for structurally valid calibration, not proof of physical accuracy.

This is a bounded profile reader, not a general YAML implementation. Each scalar or bracketed numeric array must fit on one line. Required fields include all lens coefficients, dimensions, verification flag and the nine-value rotation; duplicate known fields fail. Optional lever arm defaults to zero and minimum_ground_cosine to 0.2. Unknown keys are ignored.

Note
An unverified profile is intentionally loadable for workshop checks. Loading does not validate rotation orthonormality; projection checks it before use. Neither operation establishes that a mount was physically measured.
Lines longer than 511 characters, a missing ':' on a non-comment line, verified other than 0/1, nonpositive focal lengths, or a minimum_ground_cosine outside 0.05..1 all fail. Lines starting with '#', '' or consisting of --- are skipped. errno is not part of the failure contract.

Load bounded projection calibration, requiring exact native dimensions.

Reads key: value lines (a YAML-like subset) into a local copy and publishes it only after all checks pass, so geometry is never half-written. A bitmask of seen keys detects duplicates and missing required keys.

Returns
True for a structurally valid profile; false for I/O errors, a non-regular/empty/oversized file, syntax errors, duplicates, missing keys or out-of-range values.

Definition at line 137 of file lwir_geolocation.c.

◆ lwir_geolocation_project()

bool lwir_geolocation_project ( double pixel_x,
double pixel_y,
const struct lwir_camera_geometry * camera,
const struct lwir_camera_pose * pose,
struct lwir_ground_point * point )

Project a native subpixel location using distortion, mount and observation pose.

Parameters
pixel_xNative column, independent of JPEG rotation.
pixel_yNative row.
[in]cameraIntrinsics and proper camera-to-body rotation.
[in]poseObservation position, attitude and positive height above the ground plane.
[out]pointResult, unchanged on failure.
Returns
False for invalid/nonfinite geometry, nonconvergence or near-horizon rays.

Inverse distortion is solved in camera coordinates before mount and attitude rotations. A finite iteration budget rejects nonconvergent rays, and the downward-cosine guard avoids arbitrarily long intersections near the horizon. The intersection uses a local horizontal plane, not a terrain model. The local north/east offset is converted to latitude/longitude on the WGS84 ellipsoid via ECEF, so no small-angle flat-earth approximation is involved.

Warning
The caller must enforce verification, observation synchronization and uncertainty policy; this geometry function does not gate on those flags.

Project a native subpixel location using distortion, mount and observation pose.

Steps:

  1. Validate every input (finite, in range, proper rotation).
  2. Pixel -> distorted normalized coordinates via intrinsics.
  3. Invert Brown-Conrady distortion by fixed-point iteration.
  4. Build the camera ray (x, y, 1), rotate camera -> body -> NED.
  5. Intersect with the plane agl_m below the navigation reference, starting from the lever-arm-offset camera origin.
  6. Convert the NED offset to WGS84 latitude/longitude via ECEF.
    Returns
    False for invalid inputs, an improper mount rotation, nonconvergent undistortion, a ray too close to the horizon, or a camera origin at/below the ground plane.
    Note
    Pixel coordinates are combined with cx/cy as-is, so they must follow the calibration's convention (OpenCV: integer coordinates at pixel centres).

Definition at line 275 of file lwir_geolocation.c.