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.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
19 * @brief Display window resolution and per-scanline Y/Cb/Cr rendering of LWIR frames.
20 * @details Input is the Tiny1-C combined frame: the first half is the YUYV image plane
21 * (`Y0 U Y1 V` per pixel pair, chroma shared by the pair), the second half the thermal
22 * plane of little-endian uint16 Kelvin*64 codes (raw/64 - 273.15 = degC as reported by the
23 * device, calibration unverified). Codes 0 and 65535 are endpoint/invalid codes.
24 * LWIR_SENSOR also accepts an image-only buffer of half that size.
25 *
26 * Output is one JPEG-ready scanline of interleaved full-range BT.601 (JFIF) Y/Cb/Cr
27 * bytes per call. Orientation is resolved once per scanline by row_source() into a first
28 * native pixel and a signed stride, so the raw thermal bytes are never reordered or copied.
29 *
30 * Optional profile corrections, bad-pixel replacement and denoise act on display values
31 * only. The scalar code is the reference; NEON (ARM64) and SSSE3 (x86-64) cover common
32 * +/-1-stride cases and must yield identical bytes, falling back to scalar for transposed
33 * rows, tails, profiles, denoise, the iron palette and legend rows.
34 *
35 * Storage: no heap. The percentile histogram is a 256 KiB static array, chosen over the
36 * stack (too large for thread stacks) and heap (project policy); this makes
37 * lwir_render_prepare() non-re-entrant.
38 */
39#include "lwir_render.h"
40
41#include <errno.h>
42#include <stdio.h>
43
44#if defined(__x86_64__) && !defined(LWIR_DISABLE_SSSE3)
45#include <cpuid.h>
46#endif
47
48#if defined(__aarch64__) && !defined(LWIR_DISABLE_NEON)
49#include <arm_neon.h>
50#endif
51
52/** Percentile workspace: one counter per possible raw code. Shared, so prepare is serial. */
53static uint32_t histogram[65536];
54
55/**
56 * @brief Read one little-endian thermal code.
57 * @param frame Combined frame start.
58 * @param pixels Native pixel count (width * height); the thermal plane starts at pixels * 2.
59 * @param pixel Native raster index.
60 * @return Raw Kelvin*64 code, including endpoint codes 0/65535.
61 * @note Caller guarantees bounds; byte assembly keeps it independent of host endianness and alignment.
62 */
63static uint16_t temperature(const uint8_t *frame, size_t pixels, size_t pixel)
64{
65 const size_t offset = (pixels + pixel) * 2;
66 return (uint16_t)frame[offset] | (uint16_t)frame[offset + 1] << 8;
67}
68
69#if defined(__aarch64__) && !defined(LWIR_DISABLE_NEON)
70/**
71 * @brief Load eight consecutive thermal codes as uint16 lanes.
72 * @details VLD2 de-interleaves 16 bytes into low bytes (val[0]) and high bytes (val[1]);
73 * widening and `low | high << 8` rebuilds little-endian codes without unaligned u16 loads.
74 * @param plane Thermal plane start.
75 * @param pixel Native raster index of lane 0; pixels pixel..pixel+7 must exist.
76 * @return Raw codes in memory order.
77 */
78static uint16x8_t thermal_block(const uint8_t *plane, size_t pixel)
79{
80 const uint8x8x2_t bytes = vld2_u8(plane + pixel * 2);
81 return vorrq_u16(vmovl_u8(bytes.val[0]), vshlq_n_u16(vmovl_u8(bytes.val[1]), 8));
82}
83
84/**
85 * @brief Lane mask of endpoint codes.
86 * @param raw Eight raw codes.
87 * @return 0xFFFF where the code is 0 or 65535, else 0.
88 */
89static uint16x8_t invalid_block(uint16x8_t raw)
90{
91 return vorrq_u16(vceqq_u16(raw, vdupq_n_u16(0)), vceqq_u16(raw, vdupq_n_u16(UINT16_MAX)));
92}
93#endif
94
95/**
96 * @brief Check pointers, native geometry and buffer size for the requested view.
97 * @param frame Frame bytes.
98 * @param bytes Supplied size.
99 * @param width Native width.
100 * @param height Native height.
101 * @param options Render options (only the view is consulted here).
102 * @return True for an exact combined frame, or an exact image-only half for LWIR_SENSOR.
103 */
104static bool render_frame_valid(const uint8_t *frame, size_t bytes, unsigned width, unsigned height,
105 const struct lwir_render_options *options)
106{
107 const size_t combined_bytes = lwir_frame_bytes(width, height);
108 return frame && combined_bytes && options &&
109 (bytes == combined_bytes || (options->view == LWIR_SENSOR && bytes == combined_bytes / 2U));
110}
111
112/**
113 * @brief Validate enumerations, orientation and view-specific option ranges.
114 * @details Rotation must be a quarter turn 0..270. LWIR_SENSOR rejects profile and denoise
115 * because the camera image has no raw codes to correct. LWIR_FIXED needs
116 * 0 <= low < high <= 65535; LWIR_PERCENTILE needs low < high <= 100. Denoise is capped
117 * at 640 raw (10 K).
118 * @param options Options to check, may be NULL.
119 * @return True when every field is supported.
120 */
121static bool valid_options(const struct lwir_render_options *options)
122{
123 return options != NULL && options->view >= LWIR_SENSOR && options->view <= LWIR_PERCENTILE &&
124 options->palette >= LWIR_WHITE_HOT && options->palette <= LWIR_IRON && options->denoise_raw <= 640 &&
125 options->rotation <= 270 && options->rotation % 90 == 0 &&
126 (options->view != LWIR_SENSOR || (!options->profile && !options->denoise_raw)) &&
127 (options->view != LWIR_FIXED || (options->low >= 0 && options->high <= 65535 && options->low < options->high)) &&
128 (options->view != LWIR_PERCENTILE || (options->low_percentile < options->high_percentile && options->high_percentile <= 100));
129}
130
131/**
132 * @brief Display size after orientation.
133 * @details 90/270 degree rotations swap width and height; mirror and flip do not.
134 * @return False for unsupported geometry, invalid options or NULL outputs (errno untouched).
135 */
136bool lwir_render_dimensions(unsigned width, unsigned height, const struct lwir_render_options *options,
137 unsigned *display_width, unsigned *display_height)
138{
139 if (!lwir_frame_bytes(width, height) || !valid_options(options) || !display_width || !display_height) return false;
140 const bool transpose = options->rotation == 90 || options->rotation == 270;
141 *display_width = transpose ? height : width; *display_height = transpose ? width : height;
142 return true;
143}
144
145/**
146 * @brief Map a display row to its first native pixel and per-column native stride.
147 * @details Display = flip(mirror(rotate_cw(native))), so the inverse is applied in reverse
148 * order. For display (x, row):
149 * 1. Undo flip: `vertical = flip ? display_height-1-row : row`.
150 * 2. Undo mirror: rotated column `x' = horizontal + direction*x`, with
151 * `horizontal = mirror ? display_width-1 : 0` and `direction = mirror ? -1 : +1`.
152 * 3. Undo clockwise rotation of (x', vertical) into native (nx, ny):
153 * - 0: nx = x', ny = vertical -> stride +direction
154 * - 90: nx = vertical, ny = height-1-x' -> stride -direction*width
155 * - 180: nx = width-1-x', ny = height-1-vertical -> stride -direction
156 * - 270: nx = width-1-vertical, ny = x' -> stride +direction*width
157 * Native index ny*width + nx is affine in x, so the result is `first + x*step`.
158 * @param width Native width.
159 * @param height Native height.
160 * @param options Orientation policy (validated).
161 * @param display_width Oriented width.
162 * @param display_height Oriented height.
163 * @param row Display row, < display_height.
164 * @param step Output signed native stride per display column.
165 * @return Native raster index of display column 0.
166 * @note With even native width, forward (+1) rows start at an even native index and
167 * reversed (-1) rows start at an odd one, so `pixel - 7` is even and 8-pixel SIMD blocks
168 * always begin on an intact YUYV pair.
169 */
170static ptrdiff_t row_source(unsigned width, unsigned height, const struct lwir_render_options *options,
171 unsigned display_width, unsigned display_height, unsigned row, ptrdiff_t *step)
172{
173 const unsigned vertical = options->flip ? display_height - 1 - row : row;
174 const unsigned horizontal = options->mirror ? display_width - 1 : 0;
175 const ptrdiff_t direction = options->mirror ? -1 : 1;
176 /* One inverse transform per scanline; the hot loop uses only a signed stride. */
177 switch (options->rotation) {
178 case 90: *step = -direction * width; return (ptrdiff_t)(height - 1 - horizontal) * width + vertical;
179 case 180: *step = -direction; return (ptrdiff_t)(height - 1 - vertical) * width + width - 1 - horizontal;
180 case 270: *step = direction * width; return (ptrdiff_t)horizontal * width + width - 1 - vertical;
181 default: *step = direction; return (ptrdiff_t)vertical * width + horizontal;
182 }
183}
184
185/**
186 * @brief Convert a display coordinate into native sensor coordinates.
187 * @details Uses the same row_source() transform as rendering, so overlays and
188 * measurements picked on the display address exactly the pixel that was shown.
189 * @return False for invalid geometry/options, NULL outputs or out-of-range display points.
190 */
191bool lwir_render_native_coordinate(unsigned width, unsigned height, const struct lwir_render_options *options,
192 unsigned display_x, unsigned display_y, unsigned *native_x, unsigned *native_y)
193{
194 unsigned display_width, display_height;
195 if (!native_x || !native_y || !lwir_render_dimensions(width, height, options, &display_width, &display_height) ||
196 display_x >= display_width || display_y >= display_height) return false;
197 ptrdiff_t step;
198 const ptrdiff_t first = row_source(width, height, options, display_width, display_height, display_y, &step);
199 const size_t pixel = (size_t)(first + (ptrdiff_t)display_x * step);
200 *native_x = (unsigned)(pixel % width); *native_y = (unsigned)(pixel / width);
201 return true;
202}
203
204#if defined(__x86_64__) && !defined(LWIR_DISABLE_SSSE3)
205/**
206 * @brief Runtime SSSE3 detection, cached after the first query.
207 * @return True when CPUID leaf 1 reports SSSE3.
208 * @note The lazy cache is unsynchronized: concurrent first calls would race on the static,
209 * although every caller computes the same value.
210 */
211static bool ssse3_available(void)
212{
213 static int available = -1;
214 if (available < 0) {
215 unsigned leaf, vendor, features, extended;
216 available = __get_cpuid(1, &leaf, &vendor, &features, &extended) && (features & bit_SSSE3) != 0;
217 }
218 return available != 0;
219}
220
221#endif
222
223/**
224 * @brief Copy the camera's own YUYV image row into Y/Cb/Cr output (LWIR_SENSOR).
225 * @details The camera's chroma is reused directly, so no colour conversion is needed:
226 * each output pixel takes its own Y and its pair's shared U (Cb) and V (Cr). SSSE3 or NEON
227 * handle leading 8-pixel blocks of +/-1-stride rows; the scalar loop handles the rest and
228 * all transposed (+/-width stride) rows.
229 * @param frame Image plane start (combined or image-only buffer).
230 * @param first Native index of display column 0.
231 * @param step Signed native stride per display column.
232 * @param width Display width.
233 * @param output Destination of width * 3 bytes.
234 */
235static void sensor_row(const uint8_t *frame, ptrdiff_t first, ptrdiff_t step, unsigned width, uint8_t *output)
236{
237 unsigned column = 0;
238#if defined(__x86_64__) && !defined(LWIR_DISABLE_SSSE3)
239 if ((step == 1 || step == -1) && width >= 8 && ssse3_available()) column = lwir_sensor_ssse3(frame, first, step, width, output);
240#endif
241#if defined(__aarch64__) && !defined(LWIR_DISABLE_NEON)
242 /* ARM64 SIMD fuses eight YUY2 expansions/reversals into the JPEG scanline.
243 * +/-1 rows begin at an intact YUY2 pair; transposed rows use the scalar stride.
244 * Flip only selects another source row: no image copy or camera control write. */
245 if (step == 1 || step == -1) {
246 for (; width - column >= 8; column += 8) {
247 const ptrdiff_t pixel = first + (ptrdiff_t)column * step;
248 const uint8x8x2_t packed = vld2_u8(frame + (size_t)(step < 0 ? pixel - 7 : pixel) * 2);
249 /* val[0] = Y0..Y7; val[1] = U0 V0 U1 V1 U2 V2 U3 V3. Unzipping that vector with
250 * itself puts U0..U3 / V0..V3 in lanes 0..3 (lanes 4..7 are unused copies). */
251 const uint8x8x2_t chroma = vuzp_u8(packed.val[1], packed.val[1]);
252 uint8x8_t luminance = packed.val[0], cb = chroma.val[0], cr = chroma.val[1];
253 /* Reverse 8 Y lanes, but only the four pair-chroma lanes: rev32 reverses each
254 * 4-byte group, and only the low group is consumed below. */
255 if (step < 0) { luminance = vrev64_u8(luminance); cb = vrev32_u8(cb); cr = vrev32_u8(cr); }
256 /* Zipping lanes 0..3 with themselves duplicates each pair chroma for both pixels;
257 * VST3 then interleaves Y/Cb/Cr straight into the JPEG scanline. */
258 const uint8x8x3_t expanded = {.val = {luminance, vzip_u8(cb, cb).val[0], vzip_u8(cr, cr).val[0]}};
259 vst3_u8(output + column * 3, expanded);
260 }
261 }
262#endif
263 for (; column < width; ++column) {
264 /* Y sits at pixel*2; the pair's 4-byte group starts at (pixel/2)*4 with U at +1, V at +3. */
265 const size_t pixel = (size_t)(first + (ptrdiff_t)column * step), pair = pixel / 2 * 4;
266 output[column * 3] = frame[pixel * 2];
267 output[column * 3 + 1] = frame[pair + 1]; output[column * 3 + 2] = frame[pair + 3];
268 }
269}
270
271/**
272 * @brief Test whether a native pixel is listed as bad in the profile.
273 * @details Lower-bound binary search over the strictly ascending bad_pixels list
274 * (ordering is enforced by valid_profile()); O(log n) for at most 128 entries.
275 * @param profile Optional profile; NULL means no bad pixels.
276 * @param pixel Native raster index.
277 * @return True when the pixel is listed.
278 */
279static bool bad_pixel(const struct lwir_profile *profile, size_t pixel)
280{
281 if (!profile) return false;
282 unsigned low = 0, high = profile->bad_count;
283 while (low < high) {
284 const unsigned middle = low + (high - low) / 2;
285 if (profile->bad_pixels[middle] < pixel) low = middle + 1; else high = middle;
286 }
287 return low < profile->bad_count && profile->bad_pixels[low] == pixel;
288}
289
290/**
291 * @brief Read an unreplaced sample usable as-is or as a neighbour.
292 * @param frame Combined frame.
293 * @param width Native width.
294 * @param height Native height.
295 * @param pixel Native raster index.
296 * @param profile Optional profile supplying bad pixels and the supported raw range.
297 * @param raw Output code; written unless the pixel is listed bad.
298 * @return False for listed bad pixels, endpoint codes or codes outside the profile's
299 * support range (these render as invalid rather than being extrapolated).
300 */
301static bool original_sample(const uint8_t *frame, unsigned width, unsigned height, size_t pixel,
302 const struct lwir_profile *profile, uint16_t *raw)
303{
304 if (bad_pixel(profile, pixel)) return false;
305 *raw = temperature(frame, (size_t)width * height, pixel);
306 return *raw && *raw != UINT16_MAX && (!profile || (*raw >= profile->range_min && *raw <= profile->range_max));
307}
308
309/**
310 * @brief Produce the uncorrected display value of one native pixel.
311 * @details
312 * 1. Ordinary pixels use original_sample().
313 * 2. Listed bad pixels take the median of their usable 4-connected neighbours (bad,
314 * endpoint and out-of-support neighbours are skipped; edges have fewer candidates).
315 * 3. If denoise_raw is set, average the value with those of its 8 neighbours whose
316 * original sample lies within +/-denoise_raw of it (edge-preserving: neighbours across
317 * a stronger edge are excluded), rounded to nearest.
318 * @param frame Combined frame.
319 * @param width Native width.
320 * @param height Native height.
321 * @param pixel Native raster index.
322 * @param options Profile and denoise policy.
323 * @param raw Output display value (still uncorrected Kelvin*64).
324 * @return False when no usable value exists; the pixel renders as invalid.
325 * @note Neighbourhoods read original samples only, never replaced or denoised values, so
326 * the result is independent of traversal order.
327 */
328static bool display_sample(const uint8_t *frame, unsigned width, unsigned height, size_t pixel,
329 const struct lwir_render_options *options, uint16_t *raw)
330{
331 if (!bad_pixel(options->profile, pixel)) {
332 if (!original_sample(frame, width, height, pixel, options->profile, raw)) return false;
333 } else {
334 const unsigned column = (unsigned)(pixel % width), row = (unsigned)(pixel / width);
335 uint16_t neighbors[4];
336 unsigned count = 0;
337 /* Off-sensor directions alias to the pixel itself and are skipped below. */
338 const size_t positions[4] = {column ? pixel - 1 : pixel, column + 1 < width ? pixel + 1 : pixel,
339 row ? pixel - width : pixel, row + 1 < height ? pixel + width : pixel};
340 for (unsigned index = 0; index < 4; ++index) {
341 uint16_t candidate;
342 if (positions[index] != pixel && original_sample(frame, width, height, positions[index], options->profile, &candidate)) neighbors[count++] = candidate;
343 }
344 if (!count) return false;
345 /* Insertion sort of <=4 values; count/2 picks the UPPER median for even counts
346 * (no averaging), so the replacement is always a real neighbour's code. */
347 for (unsigned index = 1; index < count; ++index) {
348 const uint16_t value = neighbors[index]; unsigned position = index;
349 while (position && neighbors[position - 1] > value) { neighbors[position] = neighbors[position - 1]; --position; }
350 neighbors[position] = value;
351 }
352 *raw = neighbors[count / 2];
353 }
354 if (options->denoise_raw) {
355 const int column = (int)(pixel % width), row = (int)(pixel / width);
356 unsigned sum = *raw, count = 1;
357 for (int vertical = -1; vertical <= 1; ++vertical) for (int horizontal = -1; horizontal <= 1; ++horizontal) {
358 if ((!vertical && !horizontal) || column + horizontal < 0 || column + horizontal >= (int)width || row + vertical < 0 || row + vertical >= (int)height) continue;
359 uint16_t candidate;
360 const size_t neighbor = (size_t)(row + vertical) * width + (unsigned)(column + horizontal);
361 if (original_sample(frame, width, height, neighbor, options->profile, &candidate)) {
362 const unsigned difference = candidate > *raw ? candidate - *raw : *raw - candidate;
363 if (difference <= options->denoise_raw) { sum += candidate; ++count; }
364 }
365 }
366 *raw = (uint16_t)((sum + count / 2) / count);
367 }
368 return true;
369}
370
371/**
372 * @brief Apply the profile's linear display correction.
373 * @details `round_half_up(raw * scale_ppm / 1e6) + trunc(offset_mk * 64 / 1000)`: one kelvin
374 * is 64 raw units, so one millikelvin is 0.064 raw. 64-bit intermediates avoid overflow.
375 * For the accepted positive scale the mapping is monotone non-decreasing, so ranking raw
376 * values (percentiles) and correcting afterwards preserves order.
377 * @param raw Raw or replaced/denoised display value.
378 * @param profile Optional profile; NULL returns raw unchanged.
379 * @return Corrected value in Kelvin*64 units; may fall outside 0..65535.
380 */
381static int32_t corrected(int32_t raw, const struct lwir_profile *profile)
382{
383 return profile ? (int32_t)(((int64_t)raw * profile->scale_ppm + 500000) / 1000000 + (int64_t)profile->offset_mk * 64 / 1000) : raw;
384}
385
386/**
387 * @brief Check a profile against the native geometry and renderer limits.
388 * @details Requires matching geometry, at most LWIR_MAX_BAD_PIXELS entries, scale
389 * 0.5..1.5, offset +/-50 K, a non-empty support range excluding both endpoint codes, and
390 * in-bounds strictly ascending bad pixels (required by bad_pixel()'s binary search).
391 * @param profile Optional profile; NULL is valid.
392 * @param width Native width.
393 * @param height Native height.
394 * @return True when the profile can be applied.
395 */
396static bool valid_profile(const struct lwir_profile *profile, unsigned width, unsigned height)
397{
398 if (!profile) return true;
399 if (profile->width != width || profile->height != height || profile->bad_count > LWIR_MAX_BAD_PIXELS ||
400 profile->scale_ppm < 500000 || profile->scale_ppm > 1500000 || profile->offset_mk < -50000 || profile->offset_mk > 50000 ||
401 !profile->range_min || profile->range_min >= profile->range_max || profile->range_max == UINT16_MAX) return false;
402 for (unsigned index = 0; index < profile->bad_count; ++index) if (profile->bad_pixels[index] >= (size_t)width * height ||
403 (index && profile->bad_pixels[index] <= profile->bad_pixels[index - 1])) return false;
404 return true;
405}
406
407/**
408 * @brief Validate a render request and resolve its display window and counts.
409 * @details Percentile algorithm: histogram every valid uncorrected display value, then
410 * pick the values at 0-based ranks `floor((samples-1) * percentile / 100)` (lower
411 * nearest-rank) by scanning cumulative counts. The window is corrected afterwards, which
412 * is equivalent to ranking corrected values because correction is monotone. Afterwards
413 * every pixel is classified as invalid, below or above the window.
414 * @return True on success; false with errno EINVAL for invalid input or ENODATA when a
415 * percentile view has no valid sample.
416 * @warning Not re-entrant: shares the static histogram.
417 */
418bool lwir_render_prepare(const uint8_t *frame, size_t bytes, unsigned width, unsigned height,
419 const struct lwir_render_options *options, struct lwir_render_range *range)
420{
421 unsigned display_width, display_height;
422 if (!render_frame_valid(frame, bytes, width, height, options) || !lwir_render_dimensions(width, height, options, &display_width, &display_height) ||
423 !range || !valid_profile(options->profile, width, height) ||
424 (options->legend && (options->view == LWIR_SENSOR || display_width < 112 || display_height < 24))) { errno = EINVAL; return false; }
425 struct lwir_render_range result = {.low = options->low, .high = options->high};
426 if (options->view == LWIR_SENSOR) { *range = (struct lwir_render_range){.high = 255}; return true; }
427 const size_t pixels = (size_t)width * height;
428 if (options->view == LWIR_PERCENTILE) {
429 for (size_t index = 0; index < 65536; ++index) histogram[index] = 0;
430 size_t samples = 0;
431 for (size_t pixel = 0; pixel < pixels; ++pixel) {
432 uint16_t raw;
433 if (display_sample(frame, width, height, pixel, options, &raw)) { ++histogram[raw]; ++samples; }
434 }
435 if (samples == 0) { errno = ENODATA; return false; }
436 /* Rank r means "the (r+1)-th smallest"; the first code whose cumulative count
437 * exceeds r holds it. Integer math keeps percentile windows deterministic. */
438 const size_t low_rank = (samples - 1) * options->low_percentile / 100;
439 const size_t high_rank = (samples - 1) * options->high_percentile / 100;
440 size_t accumulated = 0;
441 bool found_low = false;
442 /* Endpoint bins 0/65535 cannot be filled: display_sample() rejects them and
443 * replacements/denoise only combine valid codes. */
444 for (unsigned raw = 1; raw < UINT16_MAX; ++raw) {
445 accumulated += histogram[raw];
446 if (!found_low && accumulated > low_rank) { result.low = (int32_t)raw; found_low = true; }
447 if (accumulated > high_rank) { result.high = (int32_t)raw; break; }
448 }
449 /* A uniform scene gives equal ranks; +/-32 raw (+/-0.5 K) keeps a usable gradient. */
450 if (result.low == result.high) { result.low -= 32; result.high += 32; }
451 result.low = corrected(result.low, options->profile); result.high = corrected(result.high, options->profile);
452 /* Down-scaling profiles can merge adjacent raw codes; keep the display window non-empty. */
453 if (result.low >= result.high) { result.low -= 32; result.high += 32; }
454 }
455 size_t pixel = 0;
456#if defined(__aarch64__) && !defined(LWIR_DISABLE_NEON)
457 /* Without profile/denoise a display value is the raw code, so lane compares match the
458 * scalar classification; the window must fit uint16 for the vector constants. */
459 if (!options->profile && !options->denoise_raw && result.low >= 0 && result.high <= UINT16_MAX) {
460 for (; pixels - pixel >= 8; pixel += 8) {
461 const uint16x8_t raw = thermal_block(frame + pixels * 2, pixel), invalid = invalid_block(raw), valid = vmvnq_u16(invalid);
462 /* Compare masks are 0xFFFF per true lane; >>15 turns them into 0/1 for horizontal sums. */
463 result.invalid += vaddlvq_u16(vshrq_n_u16(invalid, 15));
464 result.below += vaddlvq_u16(vshrq_n_u16(vandq_u16(valid, vcltq_u16(raw, vdupq_n_u16((uint16_t)result.low))), 15));
465 result.above += vaddlvq_u16(vshrq_n_u16(vandq_u16(valid, vcgtq_u16(raw, vdupq_n_u16((uint16_t)result.high))), 15));
466 }
467 }
468#endif
469 for (; pixel < pixels; ++pixel) {
470 uint16_t raw;
471 if (!display_sample(frame, width, height, pixel, options, &raw)) ++result.invalid;
472 else { const int32_t value = corrected(raw, options->profile); result.below += value < result.low; result.above += value > result.high; }
473 }
474 *range = result;
475 return true;
476}
477
478/**
479 * @brief Map a window intensity to RGB for the selected palette.
480 * @details White-hot is grey `i`, black-hot grey `255-i`. Iron splits 0..255 into five
481 * equal segments between six anchors: `scaled = 5i`, segment `scaled / 255`, weight
482 * `scaled % 255`, then rounded linear interpolation `(a*(255-f) + b*f + 127) / 255`.
483 * At i = 255 the segment is 5 with weight 0, so the last anchor is returned exactly.
484 * @param intensity Window position 0..255.
485 * @param palette Palette.
486 * @param red Output red 0..255.
487 * @param green Output green 0..255.
488 * @param blue Output blue 0..255.
489 */
490static void color(unsigned intensity, enum lwir_palette palette, unsigned *red, unsigned *green, unsigned *blue)
491{
492 if (palette != LWIR_IRON) {
493 *red = *green = *blue = palette == LWIR_BLACK_HOT ? 255 - intensity : intensity;
494 return;
495 }
496 static const uint8_t anchors[6][3] = {{0,0,0}, {40,0,100}, {120,0,100}, {200,40,20}, {255,150,0}, {255,255,150}};
497 const unsigned scaled = intensity * 5;
498 const unsigned segment = scaled / 255;
499 const unsigned fraction = scaled % 255;
500 const unsigned next = segment < 5 ? segment + 1 : 5;
501 *red = (anchors[segment][0] * (255 - fraction) + anchors[next][0] * fraction + 127) / 255;
502 *green = (anchors[segment][1] * (255 - fraction) + anchors[next][1] * fraction + 127) / 255;
503 *blue = (anchors[segment][2] * (255 - fraction) + anchors[next][2] * fraction + 127) / 255;
504}
505
506/**
507 * @brief One row of a built-in 5x7 bitmap font.
508 * @param character Digit, 'C', '-', '.' or anything else (blank).
509 * @param row Font row 0..6.
510 * @return Five-bit row mask; bit 4 is the leftmost column.
511 */
512static uint8_t glyph(char character, unsigned row)
513{
514 static const uint8_t digits[10][7] = {
515 {14,17,19,21,25,17,14}, {4,12,4,4,4,4,14}, {14,17,1,2,4,8,31}, {30,1,1,14,1,1,30},
516 {2,6,10,18,31,2,2}, {31,16,16,30,1,1,30}, {14,16,16,30,17,17,14}, {31,1,2,4,8,8,8},
517 {14,17,17,14,17,17,14}, {14,17,17,15,1,1,14}};
518 static const uint8_t celsius[7] = {14,17,16,16,16,17,14};
519 if (character >= '0' && character <= '9') return digits[(unsigned)(character - '0')][row];
520 if (character == 'C') return celsius[row];
521 if (character == '-') return row == 3 ? 14 : 0;
522 return character == '.' && row == 6 ? 4 : 0;
523}
524
525/**
526 * @brief Format a window bound as degrees Celsius with one decimal.
527 * @details `raw * 1000 / 64` gives millikelvin, minus 273150 gives milli-degC, `/ 100`
528 * gives tenths. Integer division truncates toward zero, so labels are truncated, not
529 * rounded. The value is the device-reported (optionally profile-corrected) scale, not a
530 * verified temperature.
531 * @param text Output buffer of 16 bytes, always NUL-terminated by snprintf.
532 * @param raw Window bound in Kelvin*64 units.
533 */
534static void legend_label(char text[16], int32_t raw)
535{
536 const int32_t tenths = (int32_t)(((int64_t)raw * 1000 / 64 - 273150) / 100);
537 const unsigned magnitude = (unsigned)(tenths < 0 ? -tenths : tenths);
538 snprintf(text, 16, "%s%u.%uC", tenths < 0 ? "-" : "", magnitude / 10, magnitude % 10);
539}
540
541/**
542 * @brief Colour of one pixel inside the 16-row legend strip at the bottom of the display.
543 * @details Strip rows from top: 7 rows of palette gradient across the full width
544 * (`column * 255 / (width-1)`), one black separator row, 7 font rows, one black bottom row.
545 * The low label is left-aligned in the left half, the high label right-aligned; each
546 * glyph uses a 6-pixel cell (5 pixels plus a gap). Positions outside a label stay black.
547 * @param row Display row within the last 16 rows.
548 * @param column Display column.
549 * @param width Display width (>= 112, checked by callers).
550 * @param height Display height (>= 24, checked by callers).
551 * @param options Palette.
552 * @param range Window whose bounds are labelled.
553 * @param red Output red.
554 * @param green Output green.
555 * @param blue Output blue.
556 * @note Labels are re-formatted per legend pixel: simpler than caching across calls and
557 * limited to 16 rows, at the cost of redundant snprintf work.
558 */
559static void legend_pixel(unsigned row, unsigned column, unsigned width, unsigned height,
560 const struct lwir_render_options *options, const struct lwir_render_range *range,
561 unsigned *red, unsigned *green, unsigned *blue)
562{
563 if (row < height - 9) { color(column * 255 / (width - 1), options->palette, red, green, blue); return; }
564 *red = *green = *blue = 0;
565 const unsigned font_row = row - (height - 8);
566 if (row == height - 9 || font_row >= 7) return;
567 char low[16], high[16];
568 legend_label(low, range->low); legend_label(high, range->high);
569 size_t high_length = 0; while (high[high_length]) ++high_length;
570 const unsigned right_start = width - (unsigned)high_length * 6;
571 const char *text = column < width / 2 ? low : high;
572 /* Columns in the right half before the high label get position = width, which is past
573 * any label and therefore blank. */
574 unsigned position = column < width / 2 ? column : column >= right_start ? column - right_start : width;
575 size_t length = 0; while (text[length]) ++length;
576 if (position / 6 < length && position % 6 < 5 && (glyph(text[position / 6], font_row) & (16U >> (position % 6))))
577 *red = *green = *blue = 255;
578}
579
580#if defined(__aarch64__) && !defined(LWIR_DISABLE_NEON)
581/**
582 * @brief Exact `floor(delta * 255 / span)` for four lanes without integer vector division.
583 * @details NEON has no integer divide, so:
584 * 1. numerator = delta * 255 (<= 16711425 < 2^24, exact in float).
585 * 2. q = trunc(numerator * reciprocal); the rounded reciprocal can put q one unit off.
586 * 3. If q * span > numerator, q was one too high: subtract 1 (mask >> 31 is 0 or 1).
587 * 4. If (q+1) * span <= numerator, q was one too low: add 1.
588 * Products stay below 2^32 because q <= 256 and span <= 65535. The result equals the
589 * scalar `(value - low) * 255 / (high - low)`.
590 * @param delta Clamped `raw - low`, 0..span.
591 * @param span Window width high - low, 1..65535.
592 * @param reciprocal 1.0f / span, computed once per row.
593 * @return Intensities 0..255.
594 */
595static uint16x4_t window_intensity(uint16x4_t delta, unsigned span, float reciprocal)
596{
597 const uint32x4_t numerator = vmull_n_u16(delta, 255), denominator = vdupq_n_u32(span);
598 /* Numerator <=16711425 is exactly representable in float. Reciprocal estimates
599 * differ by <1 integer unit; these integer checks recover exact floor division. */
600 uint32x4_t quotient = vcvtq_u32_f32(vmulq_n_f32(vcvtq_f32_u32(numerator), reciprocal));
601 quotient = vsubq_u32(quotient, vshrq_n_u32(vcgtq_u32(vmulq_u32(quotient, denominator), numerator), 31));
602 const uint32x4_t next = vaddq_u32(quotient, vdupq_n_u32(1));
603 quotient = vaddq_u32(quotient, vshrq_n_u32(vcleq_u32(vmulq_u32(next, denominator), numerator), 31));
604 return vmovn_u32(quotient);
605}
606
607/**
608 * @brief NEON greyscale thermal row for +/-1 strides, eight pixels per iteration.
609 * @details Loads eight codes (block ending at the current pixel when reversed, then full
610 * lane reversal), clamps to the window, converts to intensity with window_intensity(),
611 * applies black-hot inversion and writes grey Y/Cb/Cr (Cb = Cr = 128, which is exactly
612 * what the scalar BT.601 formulas yield for R = G = B). Flag colours are then blended in
613 * the scalar priority order: invalid overrides above/below, matching the scalar branch
614 * where invalid is tested first.
615 * @param plane Thermal plane start.
616 * @param first Native index of display column 0.
617 * @param step +1 or -1.
618 * @param width Display width.
619 * @param options Palette (white-hot or black-hot only).
620 * @param range Window with 0 <= low < high <= 65535.
621 * @param output Y/Cb/Cr destination of width * 3 bytes.
622 * @return Columns written, a multiple of 8; the caller finishes the tail.
623 * @warning Only valid without profile, denoise, iron palette or legend rows; the caller
624 * enforces those conditions.
625 */
626static unsigned thermal_neon(const uint8_t *plane, ptrdiff_t first, ptrdiff_t step, unsigned width,
627 const struct lwir_render_options *options, const struct lwir_render_range *range, uint8_t *output)
628{
629 const uint16x8_t low = vdupq_n_u16((uint16_t)range->low), high = vdupq_n_u16((uint16_t)range->high);
630 const unsigned span = (unsigned)(range->high - range->low);
631 const float reciprocal = 1.0f / (float)span;
632 /* Exact full-range YCbCr of the existing cyan, magenta and yellow RGB flags. */
633 static const uint8_t below_color[3] = {134, 196, 32}, above_color[3] = {106, 213, 235}, invalid_color[3] = {226, 1, 149};
634 unsigned column = 0;
635 for (; width - column >= 8; column += 8) {
636 const ptrdiff_t pixel = first + (ptrdiff_t)column * step;
637 uint16x8_t raw = thermal_block(plane, (size_t)(step < 0 ? pixel - 7 : pixel));
638 /* Full 8-lane reversal: reverse each 4-lane half, then swap the halves. */
639 if (step < 0) raw = vcombine_u16(vrev64_u16(vget_high_u16(raw)), vrev64_u16(vget_low_u16(raw)));
640 const uint16x8_t delta = vsubq_u16(vminq_u16(vmaxq_u16(raw, low), high), low);
641 uint8x8_t intensity = vmovn_u16(vcombine_u16(window_intensity(vget_low_u16(delta), span, reciprocal), window_intensity(vget_high_u16(delta), span, reciprocal)));
642 if (options->palette == LWIR_BLACK_HOT) intensity = vsub_u8(vdup_n_u8(255), intensity);
643 uint8x8x3_t expanded = {.val = {intensity, vdup_n_u8(128), vdup_n_u8(128)}};
644 const uint8x8_t below = vmovn_u16(vcltq_u16(raw, low)), above = vmovn_u16(vcgtq_u16(raw, high)), invalid = vmovn_u16(invalid_block(raw));
645 /* Endpoint codes may also test below/above; selecting invalid last gives it priority. */
646 for (unsigned channel = 0; channel < 3; ++channel) {
647 expanded.val[channel] = vbsl_u8(below, vdup_n_u8(below_color[channel]), expanded.val[channel]);
648 expanded.val[channel] = vbsl_u8(above, vdup_n_u8(above_color[channel]), expanded.val[channel]);
649 expanded.val[channel] = vbsl_u8(invalid, vdup_n_u8(invalid_color[channel]), expanded.val[channel]);
650 }
651 vst3_u8(output + column * 3, expanded);
652 }
653 return column;
654}
655#endif
656
657/**
658 * @brief Render one oriented display row as interleaved Y/Cb/Cr.
659 * @details Resolves the row's first native pixel and stride once, then either copies the
660 * camera image (LWIR_SENSOR) or maps each display value through the window: invalid ->
661 * yellow, below -> cyan-blue, above -> magenta, otherwise palette colour; legend rows are
662 * overdrawn. RGB is converted with integer full-range BT.601 coefficients.
663 * @return True on success; false with errno EINVAL for invalid input.
664 */
665bool lwir_render_row(const uint8_t *frame, size_t bytes, unsigned width, unsigned height, unsigned row,
666 const struct lwir_render_options *options, const struct lwir_render_range *range,
667 uint8_t *output, size_t capacity)
668{
669 unsigned display_width, display_height;
670 if (!render_frame_valid(frame, bytes, width, height, options) || !lwir_render_dimensions(width, height, options, &display_width, &display_height) || !range ||
671 !output || row >= display_height || capacity < (size_t)display_width * 3 || range->low >= range->high ||
672 range->low < -65536 || range->high > 131070 ||
673 !valid_profile(options->profile, width, height) ||
674 (options->legend && (options->view == LWIR_SENSOR || display_width < 112 || display_height < 24))) { errno = EINVAL; return false; }
675 ptrdiff_t step;
676 ptrdiff_t source = row_source(width, height, options, display_width, display_height, row, &step);
677 if (options->view == LWIR_SENSOR) { sensor_row(frame, source, step, display_width, output); return true; }
678 unsigned column = 0;
679#if defined(__aarch64__) && !defined(LWIR_DISABLE_NEON)
680 if ((step == 1 || step == -1) && !options->profile && !options->denoise_raw && options->palette != LWIR_IRON &&
681 range->low >= 0 && range->high <= UINT16_MAX && (!options->legend || row < display_height - 16)) {
682 column = thermal_neon(frame + (size_t)width * height * 2, source, step, display_width, options, range, output);
683 source += (ptrdiff_t)column * step;
684 }
685#endif
686 for (; column < display_width; ++column, source += step) {
687 const size_t pixel = (size_t)source;
688 uint8_t *destination = output + column * 3;
689 uint16_t raw = 0;
690 const bool valid = display_sample(frame, width, height, pixel, options, &raw);
691 const int32_t value = corrected(raw, options->profile);
692 unsigned red, green, blue;
693 if (!valid) { red = 255; green = 255; blue = 0; }
694 else if (value < range->low) { red = 0; green = 180; blue = 255; }
695 else if (value > range->high) { red = 255; green = 0; blue = 255; }
696 else {
697 const unsigned intensity = (unsigned)((int64_t)(value - range->low) * 255 / (range->high - range->low));
698 color(intensity, options->palette, &red, &green, &blue);
699 }
700 if (options->legend && row >= display_height - 16) legend_pixel(row, column, display_width, display_height, options, range, &red, &green, &blue);
701 /* Full-range BT.601 (JFIF) in /256 fixed point:
702 * Y = 0.299 R + 0.587 G + 0.114 B -> 77, 150, 29 (sum 256)
703 * Cb = -0.1687 R - 0.3313 G + 0.5 B + 128 -> -43, -85, 128 (sum 0)
704 * Cr = 0.5 R - 0.4187 G - 0.0813 B + 128 -> 128, -107, -21 (sum 0)
705 * 32896 = 128*256 + 128 adds the chroma offset plus rounding. Coefficient sums make
706 * grey map to Y = intensity, Cb = Cr = 128 exactly, and keep numerators >= 0 so C's
707 * truncating division is a floor. NEON flag colours are these formulas' outputs. */
708 destination[0] = (uint8_t)((77 * red + 150 * green + 29 * blue + 128) / 256);
709 destination[1] = (uint8_t)(((int)blue * 128 - (int)red * 43 - (int)green * 85 + 32896) / 256);
710 destination[2] = (uint8_t)(((int)red * 128 - (int)green * 107 - (int)blue * 21 + 32896) / 256);
711 }
712 return true;
713}
static unsigned capacity[COVERAGE_CAMERAS]
bool invalid
Definition chdk_pipe.c:145
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
static struct ear_sample samples[EAR_MAX_SAMPLES]
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
size_t lwir_frame_bytes(unsigned width, unsigned height)
Combined frame size for supported geometry.
Definition lwir_frame.c:56
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
uint8_t frame[LWIR_MAX_FRAME_BYTES]
Definition lwir_mock.c:58
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
static void legend_pixel(unsigned row, unsigned column, unsigned width, unsigned height, const struct lwir_render_options *options, const struct lwir_render_range *range, unsigned *red, unsigned *green, unsigned *blue)
Colour of one pixel inside the 16-row legend strip at the bottom of the display.
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.
bool lwir_render_dimensions(unsigned width, unsigned height, const struct lwir_render_options *options, unsigned *display_width, unsigned *display_height)
Display size after orientation.
static bool valid_options(const struct lwir_render_options *options)
Validate enumerations, orientation and view-specific option ranges.
static bool display_sample(const uint8_t *frame, unsigned width, unsigned height, size_t pixel, const struct lwir_render_options *options, uint16_t *raw)
Produce the uncorrected display value of one native pixel.
static bool original_sample(const uint8_t *frame, unsigned width, unsigned height, size_t pixel, const struct lwir_profile *profile, uint16_t *raw)
Read an unreplaced sample usable as-is or as a neighbour.
static uint8_t glyph(char character, unsigned row)
One row of a built-in 5x7 bitmap font.
static bool bad_pixel(const struct lwir_profile *profile, size_t pixel)
Test whether a native pixel is listed as bad in the profile.
static ptrdiff_t row_source(unsigned width, unsigned height, const struct lwir_render_options *options, unsigned display_width, unsigned display_height, unsigned row, ptrdiff_t *step)
Map a display row to its first native pixel and per-column native stride.
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)
Validate a render request and resolve its display window and counts.
static bool render_frame_valid(const uint8_t *frame, size_t bytes, unsigned width, unsigned height, const struct lwir_render_options *options)
Check pointers, native geometry and buffer size for the requested view.
static void sensor_row(const uint8_t *frame, ptrdiff_t first, ptrdiff_t step, unsigned width, uint8_t *output)
Copy the camera's own YUYV image row into Y/Cb/Cr output (LWIR_SENSOR).
static uint32_t histogram[65536]
Definition lwir_render.c:53
static int32_t corrected(int32_t raw, const struct lwir_profile *profile)
Apply the profile's linear display correction.
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)
Render one oriented display row as interleaved Y/Cb/Cr.
static void color(unsigned intensity, enum lwir_palette palette, unsigned *red, unsigned *green, unsigned *blue)
Map a window intensity to RGB for the selected palette.
static void legend_label(char text[16], int32_t raw)
Format a window bound as degrees Celsius with one decimal.
static bool valid_profile(const struct lwir_profile *profile, unsigned width, unsigned height)
Check a profile against the native geometry and renderer limits.
Display rendering of Tiny1-C frames into JPEG-ready Y/Cb/Cr scanlines.
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
@ 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 pthread_cond_t available
Definition pose_log.c:73
static size_t count
Definition pose_log.c:79
static FILE * output
Definition pose_log.c:77
Measured display-correction profile for one camera, gain label and geometry.
Definition lwir_render.h:70
Display policy for one rendering request; never affects stored samples.
Resolved display window and diagnostic counts from lwir_render_prepare().
Validated capture and reporting policy, fixed before the sample loop.
Definition earcam.c:137
bool valid
Definition usher.c:537
struct usher_control_result result
Definition usher.c:377