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_frame.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 LWIRCAM_LWIR_FRAME_H
19#define LWIRCAM_LWIR_FRAME_H
20
21/** @file
22 * @brief Native frame arithmetic and camera measurements; no codec or flight dependencies.
23 * @details Combined frames contain packed YUY2 followed by LE uint16 Kelvin*64.
24 * Display transforms never change these coordinates or original samples.
25 *
26 * Tiny1-C combined frame layout (width W, height H, W even):
27 * - Bytes [0, 2WH): YUYV image plane, `Y0 U Y1 V` per horizontal pixel pair; both pixels
28 * of a pair share U and V.
29 * - Bytes [2WH, 4WH): thermal plane, one little-endian uint16 per pixel in raster order.
30 * raw / 64 - 273.15 is degC as reported by the device; calibration is unverified.
31 * Codes 0 and 65535 are endpoint/invalid codes.
32 *
33 * Invariants: sizes are exact (lwir_frame_bytes()), all coordinates are native and
34 * unrotated, inputs are borrowed read-only and nothing is allocated. Live capture qualifies
35 * frames with lwir_frame_capture_valid() (and optionally lwir_frame_plausible()/
36 * lwir_frame_settled()) before rendering or measuring; replay only needs lwir_frame_valid().
37 *
38 * Measurements have a scalar reference path; on little-endian ARM64 NEON processes
39 * eight-pixel blocks with identical results (exact integer averages, first-occurrence
40 * extrema), verified by parity tests.
41 */
42#include <stdbool.h>
43#include <stddef.h>
44#include <stdint.h>
45
46/** @brief Largest supported native width in pixels. */
47#define LWIR_MAX_WIDTH 640U
48/** @brief Largest supported native height in pixels. */
49#define LWIR_MAX_HEIGHT 512U
50/** @brief Largest combined frame: two planes of 2 bytes per pixel. */
51#define LWIR_MAX_FRAME_BYTES (LWIR_MAX_WIDTH * LWIR_MAX_HEIGHT * 4U)
52
53/** @brief Buffer content kinds: full image+thermal frame, or the YUYV image plane alone. */
55
56#ifdef __cplusplus
57extern "C" {
58#endif
59
60/** @brief Native rectangle; a zero width/height pair selects the full image. */
61struct lwir_roi {
62 unsigned x;
63 unsigned y;
64 unsigned width;
65 unsigned height;
66};
67
68/** @brief Ordinary camera measurements, independent of optional hotspot analysis. */
70 LWIR_RECTANGLE, /**< roi rectangle; an all-zero roi means the full image. */
71 LWIR_POINT, /**< Single pixel at roi.x, roi.y; roi width/height ignored. */
72 LWIR_LINE /**< Inclusive line from roi.x, roi.y to end_x, end_y. */
73};
74
75/** @brief One native-coordinate measurement request. */
78 /** Rectangle, or the start point for LWIR_POINT/LWIR_LINE. */
79 struct lwir_roi roi;
80 /** Line end point; unused otherwise. */
81 unsigned end_x;
82 unsigned end_y;
83 /** Replace each valid center by the rounded mean of the valid samples in its
84 * edge-clipped 3x3 neighbourhood; coverage still uses the original center. */
86};
87
88/** @brief Optional coverage band counted alongside measurement statistics. */
90 /* Inclusive raw Kelvin*64 band, NOT a display window or detector gain range. */
91 uint16_t low;
92 uint16_t high;
93 /** When false the below/within/above counters stay zero. Enabled requires low < high. */
94 bool enabled;
95};
96
97/** @brief Raw-unit measurement results; derive mean/variance from the sums and pixels. */
99 /** Extremes of measured samples (after optional averaging), in Kelvin*64. */
100 uint16_t min_raw;
101 uint16_t max_raw;
102 /* Native coordinates; ties keep the first visited sample (raster order for ROI). */
103 unsigned min_x;
104 unsigned min_y;
105 unsigned max_x;
106 unsigned max_y;
107 /** Sum and sum of squares of measured samples; 64-bit cannot overflow at max geometry. */
108 uint64_t sum_raw;
110 /** Number of measured samples (centers visited). */
111 size_t pixels;
112 /** Samples whose code is 0 or 65535. */
114 /* Endpoints 0/65535 are excluded ONLY from coverage, not raw sums/extrema. */
115 size_t below;
116 size_t within;
117 size_t above;
118};
119
120
121/** @brief Bounded combined-frame size, or zero for unsupported native geometry.
122 * @param width Even native width from 2 through LWIR_MAX_WIDTH.
123 * @param height Native height from 1 through LWIR_MAX_HEIGHT.
124 * @return width * height * 4, or zero.
125 */
126size_t lwir_frame_bytes(unsigned width, unsigned height);
127/** @brief Validate a native rectangle without clipping an operator's request.
128 * @param width Native width.
129 * @param height Native height.
130 * @param roi Requested region.
131 * @return True when every requested sample is within the image.
132 */
133bool lwir_roi_valid(unsigned width, unsigned height, const struct lwir_roi *roi);
134/** @brief Validate ROI/point/line geometry before any sample is accessed.
135 * @param width Native width.
136 * @param height Native height.
137 * @param measurement Requested native measurement.
138 * @return True when the request is supported and in bounds.
139 */
140bool lwir_measurement_valid(unsigned width, unsigned height, const struct lwir_measurement *measurement);
141/** @brief Measure apparent device temperatures, keeping diagnostic coverage separate.
142 * @param frame Immutable combined frame.
143 * @param bytes Exact frame size.
144 * @param width Native width.
145 * @param height Native height.
146 * @param measurement ROI/point/line and optional measurement-only averaging.
147 * @param thresholds Optional inclusive raw coverage band, not a display window.
148 * @param statistics Output; ignore on failure. Endpoint codes remain in raw extrema/sums.
149 * @return True on success. No surface correction or object identity is inferred.
150 * False (errno untouched) for NULL pointers, invalid geometry or measurement, a size
151 * mismatch, or enabled thresholds with low >= high.
152 */
153bool lwir_measure_temperature(const uint8_t *frame, size_t bytes, unsigned width, unsigned height,
154 const struct lwir_measurement *measurement, const struct lwir_thresholds *thresholds,
155 struct lwir_temperature_stats *statistics);
156/** @brief Rectangle convenience interface to lwir_measure_temperature.
157 * @param frame Combined frame.
158 * @param bytes Exact size.
159 * @param width Native width.
160 * @param height Native height.
161 * @param roi Native region.
162 * @param statistics Output, valid only on success.
163 * @return True on success.
164 */
165bool lwir_temperature_statistics(const uint8_t *frame, size_t bytes, unsigned width, unsigned height,
166 const struct lwir_roi *roi, struct lwir_temperature_stats *statistics);
167/** @brief Check pointer, geometry and exact combined layout, not physical accuracy.
168 * @param frame Borrowed bytes.
169 * @param bytes Accessible size.
170 * @param width Native width.
171 * @param height Native height.
172 * @return True for a structurally valid combined frame.
173 */
174bool lwir_frame_valid(const uint8_t *frame, size_t bytes, unsigned width, unsigned height);
175/** @brief Recognize the all-black YUYV/0x8000 thermal fill observed during camera transitions.
176 * @details This whole-frame signature contains no usable sensor information.
177 * An isolated 0x8000 temperature or any other uniform scene is not rejected.
178 * Every byte pair in BOTH planes must be (0x00, 0x80): Y = 0 with neutral chroma in the
179 * image, little-endian 0x8000 in the thermal plane.
180 * @param frame Borrowed bytes.
181 * @param bytes Accessible size.
182 * @param width Native width.
183 * @param height Native height.
184 * @return True only for a structurally valid frame that is entirely neutral fill.
185 */
186bool lwir_frame_is_neutral_fill(const uint8_t *frame, size_t bytes, unsigned width, unsigned height);
187/** @brief Qualify live combined data, rejecting neutral fill and an entirely invalid thermal plane.
188 * @details Structural replay validation remains independent. This is not physical calibration.
189 * Legitimate uniform scenes pass as long as one thermal code is neither 0 nor 65535.
190 * @param frame Borrowed bytes.
191 * @param bytes Accessible size.
192 * @param width Native width.
193 * @param height Native height.
194 * @return True for a structurally valid, non-fill frame with at least one valid temperature.
195 */
196bool lwir_frame_capture_valid(const uint8_t *frame, size_t bytes, unsigned width, unsigned height);
197/** @brief Optional conservative scene check; unusual valid scenes may be rejected.
198 * @details Rejects frames where more than 1% of image chroma bytes leave 120..136, the
199 * mean absolute horizontal luma step exceeds 45, or more than 10% of every-eighth-pixel
200 * thermal samples fall outside raw 14000..40000 (about -54..352 degC).
201 * @param frame Borrowed bytes.
202 * @param bytes Accessible size.
203 * @param width Native width.
204 * @param height Native height.
205 * @return True for a structurally valid frame that passes all three heuristics.
206 */
207bool lwir_frame_plausible(const uint8_t *frame, size_t bytes, unsigned width, unsigned height);
208/** @brief Optional image-stability heuristic, never exposure or shutter certification.
209 * @param frame Current combined frame.
210 * @param previous_image Previous image half (width * height * 2 bytes), kept by the acquisition owner.
211 * @param width Native width.
212 * @param height Native height.
213 * @return True when bounded luma change meets the existing settling policy
214 * (mean absolute luma difference <= 12); false for NULL inputs or bad geometry.
215 */
216bool lwir_frame_settled(const uint8_t *frame, const uint8_t *previous_image,
217 unsigned width, unsigned height);
218
219#ifdef __cplusplus
220}
221#endif
222
223#endif
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
struct latest_measurement measurement
bool lwir_frame_is_neutral_fill(const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
Recognize the all-black YUYV/0x8000 thermal fill observed during camera transitions.
Definition lwir_frame.c:432
lwir_measurement_kind
Ordinary camera measurements, independent of optional hotspot analysis.
Definition lwir_frame.h:69
@ LWIR_POINT
Definition lwir_frame.h:71
@ LWIR_LINE
Definition lwir_frame.h:72
@ LWIR_RECTANGLE
Definition lwir_frame.h:70
bool lwir_measurement_valid(unsigned width, unsigned height, const struct lwir_measurement *measurement)
Validate ROI/point/line geometry before any sample is accessed.
Definition lwir_frame.c:84
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 apparent device temperatures, keeping diagnostic coverage separate.
Definition lwir_frame.c:326
bool lwir_frame_valid(const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
Check pointer, geometry and exact combined layout, not physical accuracy.
Definition lwir_frame.c:420
bool lwir_frame_capture_valid(const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
Qualify live combined data, rejecting neutral fill and an entirely invalid thermal plane.
Definition lwir_frame.c:446
bool lwir_frame_plausible(const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
Optional conservative scene check; unusual valid scenes may be rejected.
Definition lwir_frame.c:465
bool lwir_roi_valid(unsigned width, unsigned height, const struct lwir_roi *roi)
Validate a native rectangle without clipping an operator's request.
Definition lwir_frame.c:70
lwir_frame_layout
Buffer content kinds: full image+thermal frame, or the YUYV image plane alone.
Definition lwir_frame.h:54
@ LWIR_YUYV_IMAGE
Definition lwir_frame.h:54
@ LWIR_COMBINED
Definition lwir_frame.h:54
bool lwir_temperature_statistics(const uint8_t *frame, size_t bytes, unsigned width, unsigned height, const struct lwir_roi *roi, struct lwir_temperature_stats *statistics)
Rectangle convenience interface to lwir_measure_temperature.
Definition lwir_frame.c:394
size_t lwir_frame_bytes(unsigned width, unsigned height)
Bounded combined-frame size, or zero for unsupported native geometry.
Definition lwir_frame.c:56
bool lwir_frame_settled(const uint8_t *frame, const uint8_t *previous_image, unsigned width, unsigned height)
Optional image-stability heuristic, never exposure or shutter certification.
Definition lwir_frame.c:498
uint8_t frame[LWIR_MAX_FRAME_BYTES]
Definition lwir_mock.c:58
One native-coordinate measurement request.
Definition lwir_frame.h:76
struct lwir_roi roi
Definition lwir_frame.h:79
enum lwir_measurement_kind kind
Definition lwir_frame.h:77
Native rectangle; a zero width/height pair selects the full image.
Definition lwir_frame.h:61
unsigned y
Definition lwir_frame.h:63
unsigned width
Definition lwir_frame.h:64
unsigned height
Definition lwir_frame.h:65
unsigned x
Definition lwir_frame.h:62
Raw-unit measurement results; derive mean/variance from the sums and pixels.
Definition lwir_frame.h:98
Optional coverage band counted alongside measurement statistics.
Definition lwir_frame.h:89
uint16_t high
Definition lwir_frame.h:92