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_spotter.c
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 lwir_spotter.c
20 * @brief Associate detections with the native thermal samples of a saved LWIR frame.
21 * @details Reuse the Spottercam analysis worker on already-published captures.
22 * Keep display coordinates, native sensor coordinates, and optional geographic
23 * estimates distinct. The image is checked again before the sidecar is published
24 * so a replaced capture is not silently paired with another frame's detections.
25 */
26#include "lwir_spotter.h"
27#include "spotter_cam_pipe.h"
28#include "imx500_pipe.h"
29#include "camera_profile.h"
30#include "bounded_ini.h"
31#include "lwir_container.h"
32#include "lwir_render.h"
33
34#include <errno.h>
35#include <limits.h>
36#include <math.h>
37#include <stdio.h>
38#include <string.h>
39#include <sys/stat.h>
40#include <unistd.h>
41
42#ifndef USHER_SPOTTERCAM_COMMAND
43#define USHER_SPOTTERCAM_COMMAND "./bin/spottercam"
44#endif
45
47static const char *selected_settings;
49static bool profile_loaded;
50static unsigned request_sequence;
51static uint64_t maximum_interval_us = 5000;
52static double maximum_uncertainty_m = 1.0;
53static uint8_t combined[256U * 192U * 4U];
55
56bool lwir_spotter_settings(const char *settings)
57{
58 if (!settings || !settings[0] || analysis.pid > 0) return false;
59 selected_settings = settings;
60 return true;
61}
62
63bool lwir_spotter_profile(const char *filename)
64{
65 struct usher_camera_profile candidate;
66 if (analysis.pid > 0 || !usher_camera_profile_read(filename, &candidate)
67 || candidate.camera_id != USHER_CAMERA_LWIRCAM || candidate.calibration.width != 256
68 || candidate.calibration.height != 192) return false;
69 profile = candidate;
70 profile_loaded = true;
71 return true;
72}
73
74bool lwir_spotter_limits(const char *limits)
75{
76 if (!limits || strlen(limits) >= 96 || analysis.pid > 0) return false;
77 char text[96];
78 for (size_t index = 0; index <= strlen(limits); ++index) text[index] = limits[index];
79 char *comma = strchr(text, ',');
80 if (!comma) return false;
81 *comma++ = '\0';
82 uint64_t interval;
83 double uncertainty;
84 if (!ini_uint(text, &interval) || !interval || interval > 200000
85 || !ini_real(comma, &uncertainty) || uncertainty <= 0 || uncertainty > 100) return false;
86 maximum_interval_us = interval;
87 maximum_uncertainty_m = uncertainty;
88 return true;
89}
90
92{
93 return selected_settings != NULL;
94}
95
100
101/**
102 * @brief Check whether an image still matches its pre-analysis metadata.
103 * @param before Metadata captured before reading the image.
104 * @param after Metadata captured after a later processing step.
105 * @return True if the later file is regular and the identity and metadata match.
106 * @details Device and inode catch replacement; size, modification time and
107 * change time detect ordinary in-place edits without rereading the image.
108 * This check is not a content hash.
109 */
110static bool same_file(const struct stat *before, const struct stat *after)
111{
112 return S_ISREG(after->st_mode) && before->st_dev == after->st_dev && before->st_ino == after->st_ino
113 && before->st_size == after->st_size && before->st_mtim.tv_sec == after->st_mtim.tv_sec
114 && before->st_mtim.tv_nsec == after->st_mtim.tv_nsec && before->st_ctim.tv_sec == after->st_ctim.tv_sec
115 && before->st_ctim.tv_nsec == after->st_ctim.tv_nsec;
116}
117
118int lwir_spotter_analyze(const char *filename, const union dc_shot_union *shot,
119 const struct capture_timing *timing, const volatile sig_atomic_t *running)
120{
121 if (!selected_settings) return 0;
122 if (!filename || !shot || !timing || shot->data.nr <= 0 || !capture_timing_valid(timing)) return -1;
123 struct stat before, after;
124 if (lstat(filename, &before) || !S_ISREG(before.st_mode)) return -1;
125 struct lwir_saved_geometry geometry;
126 /* Match the embedded frame to delivery evidence before invoking inference. */
127 if (lwir_read_temperature_evidence(filename, combined + sizeof(combined) / 2,
128 sizeof(combined) / 2, &geometry) != 1 || !geometry.camera || geometry.width != 256
129 || geometry.height != 192 || geometry.legend || !geometry.sequence
130 || geometry.arrival_us != timing->arrival_monotonic_us
131 || (timing->callback_arrival && geometry.sequence != timing->callback_sequence)) return -1;
132 if (analysis.pid <= 0 || request_sequence == UINT_MAX) {
135 analysis.settings = selected_settings;
136 analysis.analyze = true;
137 analysis.running = running;
138 if (imx500_pipe_start(&analysis)) return -1;
140 }
141 const unsigned request = ++request_sequence;
142 if (imx500_pipe_analyze(&analysis, filename, request)
144 || lstat(filename, &after) || !same_file(&before, &after)) return -1;
145 const struct capture_observation *observation = &timing->observation;
146 /* Unqualified pose evidence still permits pixel and temperature results. */
147 const bool aligned = profile_loaded && capture_observation_exposure(observation) && observation->pose_valid
148 && observation->sequence == geometry.sequence && isfinite(observation->pose_uncertainty_m)
149 && observation->pose_uncertainty_m >= 0 && observation->pose_uncertainty_m <= maximum_uncertainty_m
150 && observation->latest_us - observation->earliest_us <= maximum_interval_us;
151 const union dc_shot_union *pose_shot = &observation->pose;
152 const double radians_to_degrees = 57.29577951308232;
153 const struct coverage_pose pose = {
154 .latitude_deg = pose_shot->data.lat / 1e7, .longitude_deg = pose_shot->data.lon / 1e7,
155 .agl_m = pose_shot->data.groundalt / 256.0,
156 .roll_deg = pose_shot->data.phi / 4096.0 * radians_to_degrees,
157 .pitch_deg = pose_shot->data.theta / 4096.0 * radians_to_degrees,
158 .yaw_deg = pose_shot->data.psi / 4096.0 * radians_to_degrees,
159 .uncertainty_m = observation->pose_uncertainty_m
160 };
161 char output_path[PATH_MAX], pending_path[PATH_MAX];
162 const size_t length = strnlen(filename, PATH_MAX);
163 if (length < 4 || length >= PATH_MAX || strcmp(filename + length - 4, ".jpg")) return -1;
164 int count = snprintf(output_path, sizeof(output_path), "%.*s.lwir-objects.ini", (int)length - 4, filename);
165 if (count < 0 || (size_t)count >= sizeof(output_path)) return -1;
166 count = snprintf(pending_path, sizeof(pending_path), "%s.pending", output_path);
167 if (count < 0 || (size_t)count >= sizeof(pending_path)) return -1;
168 FILE *output = fopen(pending_path, "wx");
169 if (!output) return -1;
170 fprintf(output, "schema=USHER_LWIR_OBJECTS_V1\nphoto_number=%d\nanalysis_sequence=%u\n"
171 "frame_sequence=%llu\nframe_arrival_us=%llu\nboot_id=%s\nframe_sha256=%s\nimage_sha256=%s\n"
172 "count=%u\ncoordinate_space=native_sensor\ncalibration=unverified\n"
173 "projection_qualified=%u\ntiming_kind=%s\nexposure_earliest_us=%llu\nexposure_latest_us=%llu\n"
174 "pose_valid=%u\npose_uncertainty_m=%.9g\nmaximum_interval_us=%llu\nmaximum_uncertainty_m=%.9g\n"
175 "latitude_deg=%.9f\nlongitude_deg=%.9f\nagl_m=%.9g\nroll_deg=%.9g\npitch_deg=%.9g\nyaw_deg=%.9g\n"
176 "projection_model=local_flat_ground_pinhole\n",
177 shot->data.nr, request, (unsigned long long)geometry.sequence, (unsigned long long)geometry.arrival_us,
178 geometry.boot_id, geometry.frame_sha256, detections.image_sha256, detections.count, aligned ? 1U : 0U,
179 capture_time_name(observation->kind), (unsigned long long)observation->earliest_us,
180 (unsigned long long)observation->latest_us, observation->pose_valid ? 1U : 0U, observation->pose_uncertainty_m,
181 (unsigned long long)maximum_interval_us, maximum_uncertainty_m,
182 pose.latitude_deg, pose.longitude_deg, pose.agl_m, pose.roll_deg, pose.pitch_deg, pose.yaw_deg);
183 fprintf(output, "model_sha256=%s\nmodel_descriptor_sha256=%s\n", detections.model_sha256, detections.descriptor_sha256);
184 struct lwir_render_options orientation = {.rotation = geometry.rotation, .mirror = geometry.mirror, .flip = geometry.flip};
185 bool valid = true;
186 for (unsigned index = 0; index < detections.count && valid; ++index) {
187 const struct spotter_detection *box = &detections.objects[index];
188 unsigned first_x, first_y, last_x, last_y;
189 if (!lwir_render_native_coordinate(256, 192, &orientation, box->x, box->y, &first_x, &first_y)
190 || !lwir_render_native_coordinate(256, 192, &orientation, box->x + box->width - 1,
191 box->y + box->height - 1, &last_x, &last_y)) { valid = false; break; }
192 double center_x = (first_x + last_x) / 2.0, center_y = (first_y + last_y) / 2.0;
193 if (box->precise_center) {
194 /* Map the display basis into sensor space to retain the subpixel center
195 * through rotation and reflection; round only for the temperature sample. */
196 unsigned origin_x, origin_y, right_x, right_y, down_x, down_y;
197 if (!lwir_render_native_coordinate(256, 192, &orientation, 0, 0, &origin_x, &origin_y)
198 || !lwir_render_native_coordinate(256, 192, &orientation, 1, 0, &right_x, &right_y)
199 || !lwir_render_native_coordinate(256, 192, &orientation, 0, 1, &down_x, &down_y)) { valid = false; break; }
200 center_x = origin_x + box->center_x * ((double)right_x - origin_x) + box->center_y * ((double)down_x - origin_x);
201 center_y = origin_y + box->center_x * ((double)right_y - origin_y) + box->center_y * ((double)down_y - origin_y);
202 }
203 const unsigned native_x = (unsigned)lround(center_x), native_y = (unsigned)lround(center_y);
204 struct lwir_measurement measurement = {.kind = LWIR_POINT, .roi = {.x = native_x, .y = native_y}};
206 if (!lwir_measure_temperature(combined, sizeof(combined), 256, 192, &measurement, NULL, &temperature)) { valid = false; break; }
207 fprintf(output, "detection.%u.label=%s\ndetection.%u.confidence=%.9g\ndetection.%u.native_x=%u\n"
208 "detection.%u.native_y=%u\ndetection.%u.temperature_valid=%u\ndetection.%u.raw_kelvin64=%u\n",
209 index, box->label, index, box->confidence, index, native_x, index, native_y,
210 index, temperature.endpoint_codes ? 0U : 1U, index, temperature.min_raw);
211 fprintf(output, "detection.%u.center_native_x=%.9g\ndetection.%u.center_native_y=%.9g\n"
212 "detection.%u.box_display=%u,%u,%u,%u\ndetection.%u.temperature_sample_method=nearest_native_pixel\n",
213 index, center_x, index, center_y, index, box->x, box->y, box->width, box->height, index);
214 if (!temperature.endpoint_codes) fprintf(output, "detection.%u.reported_celsius=%.9g\n", index, temperature.min_raw / 64.0 - 273.15);
215 struct coverage_point offset;
216 const bool projected = aligned && coverage_project_pixel(&profile.calibration, &pose, center_x, center_y, &offset);
217 fprintf(output, "detection.%u.position_valid=%u\n", index, projected ? 1U : 0U);
218 if (projected) {
219 const double degrees_per_metre = 180.0 / (3.14159265358979323846 * 6378137.0);
220 fprintf(output, "detection.%u.latitude_deg=%.10f\ndetection.%u.longitude_deg=%.10f\n",
221 index, pose.latitude_deg + offset.north * degrees_per_metre,
222 index, pose.longitude_deg + offset.east * degrees_per_metre / cos(pose.latitude_deg / radians_to_degrees));
223 }
224 }
225 if (ferror(output) || fflush(output) || fsync(fileno(output))) valid = false;
226 if (fclose(output)) valid = false;
227 if (lstat(filename, &after) || !same_file(&before, &after)) valid = false;
228 /* Publish the complete sidecar without replacing an earlier result. */
229 if (valid && link(pending_path, output_path)) valid = false;
230 if (unlink(pending_path)) valid = false;
231 return valid ? 0 : -1;
232}
Allocation-free flat key=value mechanics; callers own schemas and storage.
static bool ini_uint(const char *text, uint64_t *number)
Parse digits-only uint64; overflow and signs are rejected.
Definition bounded_ini.h:52
static bool ini_real(const char *text, double *number)
Parse finite decimal/exponent notation, rejecting range errors and suffixes.
Definition bounded_ini.h:67
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.
static bool capture_timing_valid(const struct capture_timing *timing)
Check whether timing evidence is internally consistent and recent.
static const char * capture_time_name(enum capture_time_kind kind)
Get the text label used when recording observation timing.
static bool capture_observation_exposure(const struct capture_observation *observation)
Distinguish exposure evidence from other valid observation times.
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.
struct latest_measurement measurement
union dc_shot_union request
void imx500_pipe_stop(struct imx500_pipe *pipe)
Close the channel, allow an exit grace period, then kill/reap if needed.
int imx500_pipe_start(struct imx500_pipe *pipe)
Replace any owned worker and require its exact READY response.
int imx500_pipe_analyze(struct imx500_pipe *pipe, const char *filename, unsigned number)
Submit one saved-picture request to a warm analysis worker without recapturing pixels.
READY/SHOT/OK process ownership without model-analysis semantics.
#define IMX500_PIPE_INITIALIZER
Safe empty lifecycle state: descriptor zero must never mean uninitialized.
Definition imx500_pipe.h:49
static const volatile sig_atomic_t * running
int lwir_read_temperature_evidence(const char *filename, uint8_t *destination, size_t capacity, struct lwir_saved_geometry *geometry)
Open filename safely and read layer plus geometry; see lwir_container.h.
Exact thermal evidence in JPEG containers, independent of analysis.
bool lwir_measure_temperature(const uint8_t *frame, size_t bytes, unsigned width, unsigned height, const struct lwir_measurement *measurement, const struct lwir_thresholds *thresholds, struct lwir_temperature_stats *statistics)
Measure a point, line or rectangle in native coordinates.
Definition lwir_frame.c:326
@ LWIR_POINT
Definition lwir_frame.h:71
static uint16_t temperature(const uint8_t *frame, size_t pixels, size_t pixel)
Read one little-endian thermal code.
Definition lwir_render.c:63
bool lwir_render_native_coordinate(unsigned width, unsigned height, const struct lwir_render_options *options, unsigned display_x, unsigned display_y, unsigned *native_x, unsigned *native_y)
Convert a display coordinate into native sensor coordinates.
Display rendering of Tiny1-C frames into JPEG-ready Y/Cb/Cr scanlines.
static bool profile_loaded
static unsigned request_sequence
static uint8_t combined[256U *192U *4U]
void lwir_spotter_stop(void)
Stop the exclusively owned model worker.
#define USHER_SPOTTERCAM_COMMAND
static double maximum_uncertainty_m
bool lwir_spotter_profile(const char *filename)
Load a native LWIR intrinsics and mount profile.
static uint64_t maximum_interval_us
int lwir_spotter_analyze(const char *filename, const union dc_shot_union *shot, const struct capture_timing *timing, const volatile sig_atomic_t *running)
Analyse one immutable image with copied capture evidence; no camera is acquired.
static struct usher_camera_profile profile
static bool same_file(const struct stat *before, const struct stat *after)
Check whether an image still matches its pre-analysis metadata.
bool lwir_spotter_enabled(void)
Test whether saved-LWIR analysis was explicitly selected.
static struct spotter_detections detections
static struct imx500_pipe analysis
bool lwir_spotter_settings(const char *settings)
Select a separate ONNX detector assignment.
static const char * selected_settings
bool lwir_spotter_limits(const char *limits)
Set the timing and pose uncertainty limits for projection.
Serialized saved-LWIR object analysis with immutable frame and exposure evidence.
#define PATH_MAX
Definition path_utils.h:39
static size_t count
Definition pose_log.c:79
static FILE * output
Definition pose_log.c:77
bool spotter_cam_pipe_read_detections(const char *filename, struct spotter_detections *detections)
Read the full detector result associated with a JPEG.
Native USHER adapter for on-sensor detection or photo-only capture.
enum capture_time_kind kind
union dc_shot_union pose
Shared observation evidence with optional LWIR request/frame-delivery timing.
struct capture_observation observation
uint64_t arrival_monotonic_us
uint64_t callback_sequence
unsigned width
Delivered width in pixels; must agree with the saved image, not the sensor mode alone.
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.
One caller-serialized native worker and its borrowed configuration.
Definition imx500_pipe.h:35
One native-coordinate measurement request.
Definition lwir_frame.h:76
Display policy for one rendering request; never affects stored samples.
Native geometry and identity recovered from the APP14 "LWIREV02" text.
Raw-unit measurement results; derive mean/variance from the sums and pixels.
Definition lwir_frame.h:98
char label[SPOTTER_LABEL_CAPACITY]
One measured camera calibration loaded from the flat PANGEA profile format.
struct coverage_camera calibration
struct dc_shot_union::@351207206061007345226276304225222200157171312155 data
bool valid
Definition usher.c:537
union dc_shot_union shot
Definition usher.c:534
#define USHER_CAMERA_LWIRCAM