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_render.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 LWIR_RENDER_H
19#define LWIR_RENDER_H
20
21/** @file
22 * @brief Display rendering of Tiny1-C frames into JPEG-ready Y/Cb/Cr scanlines.
23 * @details Rendering is strictly a display concern: it reads an immutable combined frame
24 * (see lwir_frame.h) and never reorders, rewrites or calibrates the stored raw thermal
25 * bytes, so measurements and saved data stay in native coordinates.
26 *
27 * Workflow per frame: lwir_render_prepare() validates options and resolves one display
28 * window (struct lwir_render_range); lwir_render_dimensions() gives the oriented size;
29 * lwir_render_row() is then called once per display row to fill a caller-owned buffer
30 * of `display_width * 3` bytes, so no full RGB or rotated frame is ever materialized.
31 *
32 * Views: LWIR_SENSOR passes the camera's own YUYV image through; LWIR_FIXED maps an
33 * operator raw window; LWIR_PERCENTILE derives the window from the frame's histogram.
34 * Thermal views map the window through a palette, flag below/above/invalid samples with
35 * distinct colours, and may draw a legend strip. An optional measured correction profile
36 * applies scale/offset, a support range and bad-pixel replacement for display only.
37 *
38 * Orientation is applied as clockwise rotation, then mirror, then flip; rows are produced
39 * by one inverse transform per scanline and a signed native stride.
40 *
41 * SIMD: NEON (ARM64) and SSSE3 (x86-64, runtime-detected) accelerate +/-1-stride rows and
42 * produce the same bytes as the scalar code, which handles every remaining case.
43 */
44#include "lwir_frame.h"
45
46#ifdef __cplusplus
47extern "C" {
48#endif
49
50/** @brief Source of display intensity. */
52 LWIR_SENSOR, /**< Camera's own YUYV image; no thermal window, profile or denoise. */
53 LWIR_FIXED, /**< Fixed raw Kelvin*64 window from lwir_render_options low/high. */
54 LWIR_PERCENTILE /**< Window from per-frame low/high percentiles of valid samples. */
55};
56/** @brief Thermal palette; ignored by LWIR_SENSOR. */
58 LWIR_WHITE_HOT, /**< Greyscale, warmer is brighter. */
59 LWIR_BLACK_HOT, /**< Greyscale, warmer is darker. */
60 LWIR_IRON /**< Six-anchor black-purple-red-orange-yellow ramp (scalar path only). */
61};
62
63/** @brief Capacity of the sorted bad-pixel list in struct lwir_profile. */
64#define LWIR_MAX_BAD_PIXELS 128U
65/** @brief Measured display-correction profile for one camera, gain label and geometry.
66 * @details Applied only when rendering; raw frames and measurements are unaffected.
67 * Corrected value = round(raw * scale_ppm / 1e6) + offset_mk * 64 / 1000 (truncated),
68 * in the same Kelvin*64 units as raw samples.
69 */
71 char serial[64]; /**< Device serial (or explicit replay identity) the profile applies to. */
72 char gain[32]; /**< Operator gain label the profile was measured with. */
73 char sha256[65]; /**< Hex digest text identifying the profile source (63 chars + NUL). */
74 unsigned width; /**< Native width the bad-pixel indices refer to. */
75 unsigned height; /**< Native height the bad-pixel indices refer to. */
76 unsigned scale_ppm; /**< Gain in parts per million; renderer accepts 500000..1500000. */
77 int offset_mk; /**< Offset in millikelvin; renderer accepts -50000..50000. */
78 uint16_t range_min; /**< Lowest supported raw code (non-zero); smaller samples render invalid. */
79 uint16_t range_max; /**< Highest supported raw code (< 65535); larger samples render invalid. */
80 unsigned bad_count; /**< Used entries of bad_pixels. */
81 /** Native raster indices (row * width + column), strictly ascending for binary search. */
83};
84
85/** @brief Load bounded measured display corrections, never vendor factory tables.
86 * @param path Strict profile file.
87 * @param profile Caller-owned output, valid on success only.
88 * @return True for a valid profile; physical support still requires measurement.
89 */
90bool lwir_profile_load(const char *path, struct lwir_profile *profile);
91/** @brief Require native geometry, serial and operator gain-label agreement.
92 * @param profile Measured corrections.
93 * @param width Native width.
94 * @param height Native height.
95 * @param serial Device identity or explicit replay identity.
96 * @param gain Operator gain label, not an exposure-atomic gain measurement.
97 * @return True for exact support matching; no silently broadened calibration.
98 */
99bool lwir_profile_matches(const struct lwir_profile *profile, unsigned width, unsigned height,
100 const char *serial, const char *gain);
101
102/** @brief Display policy for one rendering request; never affects stored samples. */
106 /** LWIR_FIXED window in corrected Kelvin*64 units; requires 0 <= low < high <= 65535. */
107 int32_t low;
108 int32_t high;
109 /** LWIR_PERCENTILE bounds, 0..100 with low_percentile < high_percentile. */
112 /** Draw a 16-row gradient and degC label strip; thermal views, display >= 112x24 only. */
113 bool legend;
114 /* Display only: clockwise rotation, then left/right mirror, then up/down flip. */
115 unsigned rotation;
116 bool mirror;
117 bool flip;
118 /** Edge-preserving 3x3 mean threshold in raw units (0 disables, max 640 = 10 K). */
119 unsigned denoise_raw;
120 /** JPEG quality 1..100; zero preserves the library's quality-100 default. */
121 unsigned jpeg_quality;
122 /** Optional measured correction, borrowed; must match the native geometry. */
123 const struct lwir_profile *profile;
124};
125
126/** @brief Resolved display window and diagnostic counts from lwir_render_prepare(). */
128 int32_t low; /**< Window start in corrected Kelvin*64 units (0 for LWIR_SENSOR). */
129 int32_t high; /**< Window end, always > low (255 for LWIR_SENSOR). */
130 size_t below; /**< Valid samples below the window (rendered as the below flag colour). */
131 size_t above; /**< Valid samples above the window (rendered as the above flag colour). */
132 size_t invalid; /**< Endpoint, bad-without-neighbours or out-of-profile-support samples. */
133};
134
135/** @brief Resolve one deterministic display window while retaining original samples.
136 * @details LWIR_SENSOR returns {0, 255} without reading samples. LWIR_FIXED copies the
137 * requested window. LWIR_PERCENTILE ranks valid display samples in a 65536-bin histogram.
138 * All thermal views then count invalid/below/above samples for diagnostics.
139 * @param frame Immutable combined frame, or image-only YUYV for LWIR_SENSOR.
140 * @param bytes Exact size.
141 * @param width Native width.
142 * @param height Native height.
143 * @param options Display-only policy.
144 * @param range Resolved bounds/clipping counts, valid only on success.
145 * @return True for a supported rendering request. On failure errno is EINVAL for invalid
146 * arguments/options/profile/legend geometry, or ENODATA when a percentile view finds no
147 * valid sample.
148 * @warning Uses a static histogram: not re-entrant or thread-safe; call serially.
149 */
150bool lwir_render_prepare(const uint8_t *frame, size_t bytes, unsigned width, unsigned height,
151 const struct lwir_render_options *options, struct lwir_render_range *range);
152/** @brief Derive display dimensions; quarter-turns do not change thermal geometry.
153 * @param width Native width.
154 * @param height Native height.
155 * @param options Rotation/mirror/flip policy.
156 * @param display_width Output width.
157 * @param display_height Output height.
158 * @return True for supported native geometry and orientation.
159 */
160bool lwir_render_dimensions(unsigned width, unsigned height, const struct lwir_render_options *options,
161 unsigned *display_width, unsigned *display_height);
162/** @brief Invert display orientation before accessing calibration or native samples.
163 * @param width Native width.
164 * @param height Native height.
165 * @param options Rotate, then mirror, then flip policy.
166 * @param display_x Display column.
167 * @param display_y Display row.
168 * @param native_x Native column, written on success.
169 * @param native_y Native row, written on success.
170 * @return True when both coordinate spaces are in bounds.
171 */
172bool lwir_render_native_coordinate(unsigned width, unsigned height, const struct lwir_render_options *options,
173 unsigned display_x, unsigned display_y, unsigned *native_x, unsigned *native_y);
174/** @brief Emit one bounded Y/Cb/Cr scanline, without a full RGB or rotated frame.
175 * @param frame Immutable combined frame, or image-only YUYV for LWIR_SENSOR.
176 * @param bytes Exact size.
177 * @param width Native width.
178 * @param height Native height.
179 * @param row Display row.
180 * @param options Display policy.
181 * @param range Window resolved by lwir_render_prepare.
182 * @param output Caller-owned interleaved Y/Cb/Cr row.
183 * @param capacity Available bytes, at least display width * 3.
184 * @return True on success; scalar and SIMD paths preserve the same mapping. On failure
185 * errno is EINVAL (invalid arguments, row, capacity, range, profile or legend geometry)
186 * and the output is unspecified.
187 */
188bool lwir_render_row(const uint8_t *frame, size_t bytes, unsigned width, unsigned height, unsigned row,
189 const struct lwir_render_options *options, const struct lwir_render_range *range,
190 uint8_t *output, size_t capacity);
191
192#if defined(__x86_64__)
193/** @brief SSSE3 helper for LWIR_SENSOR rows; internal to lwir_render.c, defined in lwir_ssse3.c.
194 * @param frame Image plane start.
195 * @param first Native pixel index of display column 0.
196 * @param step +1 or -1 native stride.
197 * @param width Display row width.
198 * @param output Y/Cb/Cr destination of at least width * 3 bytes.
199 * @return Columns written (multiple of 8); the caller finishes the tail.
200 * @warning Call only after confirming SSSE3 support at runtime.
201 */
202unsigned lwir_sensor_ssse3(const uint8_t *frame, ptrdiff_t first, ptrdiff_t step,
203 unsigned width, uint8_t *output);
204#endif
205
206#ifdef __cplusplus
207}
208#endif
209#endif
static unsigned capacity[COVERAGE_CAMERAS]
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
static bool range(size_t total, size_t offset, size_t length)
Check a byte span without forming a potentially overflowing end offset.
Definition exifite.c:133
Native frame arithmetic and camera measurements; no codec or flight dependencies.
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
uint8_t frame[LWIR_MAX_FRAME_BYTES]
Definition lwir_mock.c:58
bool lwir_profile_load(const char *path, struct lwir_profile *profile)
Load bounded measured display corrections, never vendor factory tables.
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)
Invert display orientation before accessing calibration or native samples.
bool lwir_render_dimensions(unsigned width, unsigned height, const struct lwir_render_options *options, unsigned *display_width, unsigned *display_height)
Derive display dimensions; quarter-turns do not change thermal geometry.
bool lwir_profile_matches(const struct lwir_profile *profile, unsigned width, unsigned height, const char *serial, const char *gain)
Require native geometry, serial and operator gain-label agreement.
bool lwir_render_prepare(const uint8_t *frame, size_t bytes, unsigned width, unsigned height, const struct lwir_render_options *options, struct lwir_render_range *range)
Resolve one deterministic display window while retaining original samples.
lwir_palette
Thermal palette; ignored by LWIR_SENSOR.
Definition lwir_render.h:57
@ LWIR_IRON
Definition lwir_render.h:60
@ LWIR_BLACK_HOT
Definition lwir_render.h:59
@ LWIR_WHITE_HOT
Definition lwir_render.h:58
#define LWIR_MAX_BAD_PIXELS
Capacity of the sorted bad-pixel list in struct lwir_profile.
Definition lwir_render.h:64
bool lwir_render_row(const uint8_t *frame, size_t bytes, unsigned width, unsigned height, unsigned row, const struct lwir_render_options *options, const struct lwir_render_range *range, uint8_t *output, size_t capacity)
Emit one bounded Y/Cb/Cr scanline, without a full RGB or rotated frame.
lwir_view
Source of display intensity.
Definition lwir_render.h:51
@ LWIR_FIXED
Definition lwir_render.h:53
@ LWIR_SENSOR
Definition lwir_render.h:52
@ LWIR_PERCENTILE
Definition lwir_render.h:54
static struct usher_camera_profile profile
unsigned lwir_sensor_ssse3(const uint8_t *frame, ptrdiff_t first, ptrdiff_t step, unsigned width, uint8_t *output)
Expand eight YUYV pixels per iteration into interleaved Y/Cb/Cr, forwards or reversed.
Definition lwir_ssse3.c:58
static FILE * output
Definition pose_log.c:77
Measured display-correction profile for one camera, gain label and geometry.
Definition lwir_render.h:70
uint32_t bad_pixels[LWIR_MAX_BAD_PIXELS]
Definition lwir_render.h:82
char sha256[65]
Definition lwir_render.h:73
unsigned height
Definition lwir_render.h:75
unsigned scale_ppm
Definition lwir_render.h:76
unsigned bad_count
Definition lwir_render.h:80
uint16_t range_max
Definition lwir_render.h:79
unsigned width
Definition lwir_render.h:74
uint16_t range_min
Definition lwir_render.h:78
char serial[64]
Definition lwir_render.h:71
char gain[32]
Definition lwir_render.h:72
Display policy for one rendering request; never affects stored samples.
const struct lwir_profile * profile
enum lwir_view view
enum lwir_palette palette
Resolved display window and diagnostic counts from lwir_render_prepare().
Validated capture and reporting policy, fixed before the sample loop.
Definition earcam.c:137