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_inference.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/** @file lwir_inference.c
19 * @brief Classifier evidence with explicit display-versus-radiometric model inputs.
20 * @details A class probability is neither a temperature correction nor a geographic hotspot result.
21 * One model is held in module-static storage (no heap here; the inference context
22 * owns its own storage). Pixel-domain models read the display JPEG; other models
23 * require the embedded temperature layer. Results go to an exclusively created
24 * "<photo>.lwir.ini" sidecar; the photograph itself is never modified. */
25#include "lwir_inference.h"
26#include "lwir_container.h"
27#include "lwir_frame.h"
28#include "inference_jpeg.h"
29
30#include <math.h>
31#include <stdio.h>
32#include <string.h>
33#include <unistd.h>
34
35static struct inference_context network; ///< The single open classifier; storage != NULL means open.
36static unsigned char thermal_plane[LWIR_MAX_WIDTH * LWIR_MAX_HEIGHT * 2]; ///< Kelvin*64 samples for radiometric models.
37static double score_threshold; ///< Inclusive acceptance threshold set at open.
38static unsigned class_index; ///< Reported class within the probability vector.
39
40/**
41 * @brief Open and qualify the LWIR classifier (see lwir_inference.h).
42 * @return True if open (or already open); false on bad arguments, open failure or
43 * an unsupported model contract, leaving nothing open.
44 * @details Requires exactly one input and one float32 output of at most 4096
45 * classes containing @p category; non-pixel (temperature) inputs must be single
46 * channel.
47 * @note Already open: returns true immediately and keeps the earlier threshold/category.
48 */
49bool lwir_inference_open(const struct inference_settings *settings, double threshold, unsigned category,
50 char *error, size_t capacity)
51{
52 if (!error || !capacity) return false;
53 /* Pre-filled so every early false return carries a diagnostic. */
54 snprintf(error, capacity, "Invalid LWIR classifier settings or probability threshold");
55 if (!settings || !isfinite(threshold) || threshold < 0 || threshold > 1) return false;
56 if (network.storage) return true;
57 if (!inference_context_open(&network, settings, "lwir_classifier_v1", error, capacity)) return false;
58 if (network.model.input_count != 1 || network.model.output_count != 1 || !network.model.image.channels ||
59 network.model.outputs[0].type != ONNX_FLOAT32 || network.model.outputs[0].bytes / sizeof(float) > 4096 ||
60 category >= network.model.outputs[0].bytes / sizeof(float) ||
61 (network.model.image.units != INFERENCE_PIXEL && network.model.image.channels != 1)) {
62 snprintf(error, capacity, "LWIR classifier requires one declared image/temperature input and float probabilities");
64 return false;
65 }
66 score_threshold = threshold;
67 class_index = category;
68 return true;
69}
70
71/**
72 * @brief Classify one saved photo and publish its evidence sidecar.
73 * @return True once the sidecar is fully written and fsynced. False if the model
74 * is not open, input is missing/invalid, any probability is outside [0,1],
75 * hashing fails, or the sidecar exists or cannot be written (a partial sidecar
76 * is removed). The photograph is untouched in every case.
77 * @details Records image and model hashes, input units, synthetic-temperature
78 * flag, source size, class, probability and accepted (probability >= threshold).
79 * @note synthetic_temperature is only meaningful for temperature-input models;
80 * pixel-input models always record 0.
81 * @note The image hash is computed after inference by a separate file read.
82 */
83bool lwir_inference_image(const char *filename, unsigned long long sequence, char *error, size_t capacity)
84{
85 if (!error || !capacity) return false;
86 snprintf(error, capacity, "LWIR classifier is unavailable or its input is invalid");
87 if (!filename || !network.storage) return false;
88 const size_t length = strnlen(filename, INFERENCE_PATH_CAPACITY);
89 if (length < 4 || length >= INFERENCE_PATH_CAPACITY || strcmp(filename + length - 4, ".jpg")) {
90 snprintf(error, capacity, "LWIR classifier requires a bounded .jpg input path");
91 return false;
92 }
93 bool synthetic = false;
94 if (network.model.image.units == INFERENCE_PIXEL) {
95 if (!inference_jpeg_prepare(&network, filename, error, capacity)) return false;
96 } else {
97 /* A display JPEG cannot replace missing physical temperature samples, even if it looks thermal. */
98 unsigned width = 0, height = 0;
99 if (lwir_read_temperature_layer(filename, thermal_plane, sizeof(thermal_plane), &width, &height, &synthetic) != 1) {
100 snprintf(error, capacity, "Model requires a valid radiometric temperature plane; display pixels are not temperatures");
101 return false;
102 }
103 const struct inference_image image = {.planes = {thermal_plane}, .lengths = {(size_t)width * height * 2},
104 .strides = {(size_t)width * 2}, .width = width, .height = height, .format = INFERENCE_KELVIN64};
106 }
107 if (!inference_context_run(&network, error, capacity)) return false;
108 const float *scores = network.model.outputs[0].data;
109 const size_t classes = network.model.outputs[0].bytes / sizeof(float);
110 /* Range check only; probabilities are not required to sum to 1. */
111 for (size_t index = 0; index < classes; ++index) {
112 if (!isfinite(scores[index]) || scores[index] < 0 || scores[index] > 1) {
113 snprintf(error, capacity, "Invalid thermal classifier probability");
114 return false;
115 }
116 }
117 char output_path[INFERENCE_PATH_CAPACITY], digest[65];
118 if (!inference_file_sha256(filename, digest)) return false;
119 const int count = snprintf(output_path, sizeof(output_path), "%.*s.lwir.ini", (int)(length - 4), filename);
120 if (count < 0 || (size_t)count >= sizeof(output_path)) return false;
121 /* Exclusive creation prevents a retry from silently replacing evidence for an earlier input. */
122 FILE *output = fopen(output_path, "wx");
123 if (!output) { snprintf(error, capacity, "Cannot exclusively create LWIR classifier evidence: %s", output_path); return false; }
124 fprintf(output, "schema=LWIR_ONNX_CLASS_V1\nsequence=%llu\nimage_sha256=%s\nmodel_sha256=%s\n"
125 "model_descriptor_sha256=%s\ninput_units=%u\nsynthetic_temperature=%u\n"
126 "source_width=%u\nsource_height=%u\nclass=%u\nprobability=%.9g\naccepted=%u\n",
127 sequence, digest, network.model.graph_sha256, network.model.descriptor_sha256,
128 (unsigned)network.model.image.units, synthetic ? 1U : 0U,
129 network.transform.source_width, network.transform.source_height, class_index,
130 (double)scores[class_index], scores[class_index] >= score_threshold ? 1U : 0U);
131 bool valid = !ferror(output) && fflush(output) == 0 && fsync(fileno(output)) == 0;
132 if (fclose(output)) valid = false;
133 /* Never leave a truncated sidecar that a reader could mistake for evidence. */
134 if (!valid) { unlink(output_path); snprintf(error, capacity, "Cannot publish LWIR classifier evidence"); }
135 return valid;
136}
137
138/** @brief Release the classifier; harmless when not open. Threshold/category are reset by the next open. */
static unsigned capacity[COVERAGE_CAMERAS]
static double score_threshold
static unsigned class_index
static struct inference_context network
@ INFERENCE_PIXEL
@ INFERENCE_KELVIN64
bool inference_jpeg_prepare(struct inference_context *context, const char *filename, char *error, size_t capacity)
Stream a JPEG into an open context's single declared image input.
Bounded JPEG-to-tensor preparation without running the graph or modifying the input file.
bool inference_context_run(struct inference_context *context, char *error, size_t capacity)
Run the currently prepared tensors using the context's timeout policy.
bool inference_context_open(struct inference_context *context, const struct inference_settings *settings, const char *adapter, char *error, size_t capacity)
Verify a bundle, map bounded tensors and bind one warm session.
bool inference_context_prepare_image(struct inference_context *context, const struct inference_image *image, char *error, size_t capacity)
Prepare a single image input without running the model, so camera leases can be released first.
bool inference_file_sha256(const char *filename, char digest[65])
Hash a stable nonempty regular file using bounded streaming scratch.
void inference_context_close(struct inference_context *context)
Release the session before unmapping its borrowed tensor storage.
#define INFERENCE_PATH_CAPACITY
int lwir_read_temperature_layer(const char *filename, uint8_t *destination, size_t capacity, unsigned *width, unsigned *height, bool *synthetic)
Open filename safely and read the layer only; see lwir_container.h.
Exact thermal evidence in JPEG containers, independent of analysis.
Native frame arithmetic and camera measurements; no codec or flight dependencies.
#define LWIR_MAX_WIDTH
Largest supported native width in pixels.
Definition lwir_frame.h:47
#define LWIR_MAX_HEIGHT
Largest supported native height in pixels.
Definition lwir_frame.h:49
struct jpeg_error_mgr error
Definition lwir_image.c:60
static unsigned char thermal_plane[LWIR_MAX_WIDTH *LWIR_MAX_HEIGHT *2]
Kelvin*64 samples for radiometric models.
void lwir_inference_close(void)
Release the classifier; harmless when not open. Threshold/category are reset by the next open.
bool lwir_inference_image(const char *filename, unsigned long long sequence, char *error, size_t capacity)
Classify one saved photo and publish its evidence sidecar.
bool lwir_inference_open(const struct inference_settings *settings, double threshold, unsigned category, char *error, size_t capacity)
Open and qualify the LWIR classifier (see lwir_inference.h).
Optional serialized LWIR model adapter, separate from USB capture and calibration.
@ ONNX_FLOAT32
static size_t count
Definition pose_log.c:79
static FILE * output
Definition pose_log.c:77
Independent, noncopyable model owner; mapped tensor buffers and session are reused between jobs.
Borrowed immutable planes; lengths/strides prove all addressed rows are available.
Per-application configuration; all resolved paths belong to this caller-owned value.
bool valid
Definition usher.c:537
struct captured_image image
Definition usher.c:371