Native frame arithmetic and camera measurements; no codec or flight dependencies. More...
#include <stdbool.h>#include <stddef.h>#include <stdint.h>

Go to the source code of this file.
Data Structures | |
| struct | lwir_roi |
| Native rectangle; a zero width/height pair selects the full image. More... | |
| struct | lwir_measurement |
| One native-coordinate measurement request. More... | |
| struct | lwir_thresholds |
| Optional coverage band counted alongside measurement statistics. More... | |
| struct | lwir_temperature_stats |
| Raw-unit measurement results; derive mean/variance from the sums and pixels. More... | |
Macros | |
| #define | LWIR_MAX_WIDTH 640U |
| Largest supported native width in pixels. | |
| #define | LWIR_MAX_HEIGHT 512U |
| Largest supported native height in pixels. | |
| #define | LWIR_MAX_FRAME_BYTES (LWIR_MAX_WIDTH * LWIR_MAX_HEIGHT * 4U) |
| Largest combined frame: two planes of 2 bytes per pixel. | |
Enumerations | |
| enum | lwir_frame_layout { LWIR_COMBINED , LWIR_YUYV_IMAGE } |
| Buffer content kinds: full image+thermal frame, or the YUYV image plane alone. More... | |
| enum | lwir_measurement_kind { LWIR_RECTANGLE , LWIR_POINT , LWIR_LINE } |
| Ordinary camera measurements, independent of optional hotspot analysis. More... | |
Functions | |
| size_t | lwir_frame_bytes (unsigned width, unsigned height) |
| Bounded combined-frame size, or zero for unsupported native geometry. | |
| bool | lwir_roi_valid (unsigned width, unsigned height, const struct lwir_roi *roi) |
| Validate a native rectangle without clipping an operator's request. | |
| bool | lwir_measurement_valid (unsigned width, unsigned height, const struct lwir_measurement *measurement) |
| Validate ROI/point/line geometry before any sample is accessed. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
Detailed Description
Native frame arithmetic and camera measurements; no codec or flight dependencies.
Combined frames contain packed YUY2 followed by LE uint16 Kelvin*64. Display transforms never change these coordinates or original samples.
Tiny1-C combined frame layout (width W, height H, W even):
- Bytes [0, 2WH): YUYV image plane, Y0 U Y1 V per horizontal pixel pair; both pixels of a pair share U and V.
- Bytes [2WH, 4WH): thermal plane, one little-endian uint16 per pixel in raster order. raw / 64 - 273.15 is degC as reported by the device; calibration is unverified. Codes 0 and 65535 are endpoint/invalid codes.
Invariants: sizes are exact (lwir_frame_bytes()), all coordinates are native and unrotated, inputs are borrowed read-only and nothing is allocated. Live capture qualifies frames with lwir_frame_capture_valid() (and optionally lwir_frame_plausible()/ lwir_frame_settled()) before rendering or measuring; replay only needs lwir_frame_valid().
Measurements have a scalar reference path; on little-endian ARM64 NEON processes eight-pixel blocks with identical results (exact integer averages, first-occurrence extrema), verified by parity tests.
Definition in file lwir_frame.h.
Macro Definition Documentation
◆ LWIR_MAX_FRAME_BYTES
| #define LWIR_MAX_FRAME_BYTES (LWIR_MAX_WIDTH * LWIR_MAX_HEIGHT * 4U) |
Largest combined frame: two planes of 2 bytes per pixel.
Definition at line 51 of file lwir_frame.h.
◆ LWIR_MAX_HEIGHT
| #define LWIR_MAX_HEIGHT 512U |
Largest supported native height in pixels.
Definition at line 49 of file lwir_frame.h.
◆ LWIR_MAX_WIDTH
| #define LWIR_MAX_WIDTH 640U |
Largest supported native width in pixels.
Definition at line 47 of file lwir_frame.h.
Enumeration Type Documentation
◆ lwir_frame_layout
| enum lwir_frame_layout |
Buffer content kinds: full image+thermal frame, or the YUYV image plane alone.
| Enumerator | |
|---|---|
| LWIR_COMBINED | |
| LWIR_YUYV_IMAGE | |
Definition at line 54 of file lwir_frame.h.
◆ lwir_measurement_kind
Ordinary camera measurements, independent of optional hotspot analysis.
Definition at line 69 of file lwir_frame.h.
Function Documentation
◆ lwir_frame_bytes()
| size_t lwir_frame_bytes | ( | unsigned | width, |
| unsigned | height ) |
Bounded combined-frame size, or zero for unsupported native geometry.
- Parameters
-
width Even native width from 2 through LWIR_MAX_WIDTH. height Native height from 1 through LWIR_MAX_HEIGHT.
- Returns
- width * height * 4, or zero.
Bounded combined-frame size, or zero for unsupported native geometry.
Two planes of 2 bytes per pixel. Width must be even because YUYV stores pixel pairs.
- Returns
- width * height * 4, or 0 for unsupported geometry (also the geometry check used throughout this module).
Definition at line 56 of file lwir_frame.c.
◆ lwir_frame_capture_valid()
| 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.
Structural replay validation remains independent. This is not physical calibration. Legitimate uniform scenes pass as long as one thermal code is neither 0 nor 65535.
- Parameters
-
frame Borrowed bytes. bytes Accessible size. width Native width. height Native height.
- Returns
- True for a structurally valid, non-fill frame with at least one valid temperature.
Qualify live combined data, rejecting neutral fill and an entirely invalid thermal plane.
Rejects structurally invalid frames, neutral fill and frames whose thermal plane holds only endpoint codes; stops at the first valid code. Uniform real scenes pass.
- Returns
- True when the frame carries at least one usable temperature.
Definition at line 446 of file lwir_frame.c.
◆ lwir_frame_is_neutral_fill()
| 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.
This whole-frame signature contains no usable sensor information. An isolated 0x8000 temperature or any other uniform scene is not rejected. Every byte pair in BOTH planes must be (0x00, 0x80): Y = 0 with neutral chroma in the image, little-endian 0x8000 in the thermal plane.
- Parameters
-
frame Borrowed bytes. bytes Accessible size. width Native width. height Native height.
- Returns
- True only for a structurally valid frame that is entirely neutral fill.
Recognize the all-black YUYV/0x8000 thermal fill observed during camera transitions.
Scans both planes as byte pairs; any pair other than (0x00, 0x80) ends the scan early, so real frames are usually rejected after a few bytes.
- Returns
- True only for a valid frame consisting entirely of fill.
Definition at line 432 of file lwir_frame.c.
◆ lwir_frame_plausible()
| 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.
Rejects frames where more than 1% of image chroma bytes leave 120..136, the mean absolute horizontal luma step exceeds 45, or more than 10% of every-eighth-pixel thermal samples fall outside raw 14000..40000 (about -54..352 degC).
- Parameters
-
frame Borrowed bytes. bytes Accessible size. width Native width. height Native height.
- Returns
- True for a structurally valid frame that passes all three heuristics.
Optional conservative scene check; unusual valid scenes may be rejected.
- Chroma: every odd image byte is U or V; more than 1% outside 128 +/- 8 fails.
- Roughness: sum of |Y(x) - Y(x+1)| must average at most 45 per adjacent pair.
- Temperature: every eighth thermal sample; more than 10% outside raw 14000..40000 (about -54..352 degC, endpoint codes included) fails.
- Returns
- True when all checks pass. Unusual but genuine scenes may fail.
Definition at line 465 of file lwir_frame.c.
◆ lwir_frame_settled()
| 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.
- Parameters
-
frame Current combined frame. previous_image Previous image half (width * height * 2 bytes), kept by the acquisition owner. width Native width. height Native height.
- Returns
- True when bounded luma change meets the existing settling policy (mean absolute luma difference <= 12); false for NULL inputs or bad geometry.
Optional image-stability heuristic, never exposure or shutter certification.
Sums absolute luma differences (even image bytes only) and accepts a mean of at most 12 per pixel. Chroma and thermal data are ignored.
- Returns
- True when settled; false for NULL inputs or unsupported geometry.
Definition at line 498 of file lwir_frame.c.
◆ lwir_frame_valid()
| 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.
- Parameters
-
frame Borrowed bytes. bytes Accessible size. width Native width. height Native height.
- Returns
- True for a structurally valid combined frame.
Check pointer, geometry and exact combined layout, not physical accuracy.
- Returns
- True for a structurally valid combined frame; says nothing about content.
Definition at line 420 of file lwir_frame.c.
◆ lwir_measure_temperature()
| 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.
- Parameters
-
frame Immutable combined frame. bytes Exact frame size. width Native width. height Native height. measurement ROI/point/line and optional measurement-only averaging. thresholds Optional inclusive raw coverage band, not a display window. statistics Output; ignore on failure. Endpoint codes remain in raw extrema/sums.
- Returns
- True on success. No surface correction or object identity is inferred. False (errno untouched) for NULL pointers, invalid geometry or measurement, a size mismatch, or enabled thresholds with low >= high.
Measure apparent device temperatures, keeping diagnostic coverage separate.
Lines use integer Bresenham traversal of every center from start to end inclusive. Rectangles are visited in raster order; on ARM64 NEON handles eight-center blocks and scalar code handles the first column (when averaging), the right border and the tail. Results are built in a local copy and published only on success.
- Returns
- False for NULL pointers, invalid request/geometry, size mismatch or an empty threshold band; errno is not set.
Definition at line 326 of file lwir_frame.c.
◆ lwir_measurement_valid()
| bool lwir_measurement_valid | ( | unsigned | width, |
| unsigned | height, | ||
| const struct lwir_measurement * | measurement ) |
Validate ROI/point/line geometry before any sample is accessed.
- Parameters
-
width Native width. height Native height. measurement Requested native measurement.
- Returns
- True when the request is supported and in bounds.
Validate ROI/point/line geometry before any sample is accessed.
Rectangles must be in bounds, or entirely zero to mean the full image (a zero width with any other non-zero field is rejected as ambiguous). Points need an in-bounds start; lines need in-bounds start and end.
- Returns
- True when the request can be measured.
Definition at line 84 of file lwir_frame.c.
◆ lwir_roi_valid()
| bool lwir_roi_valid | ( | unsigned | width, |
| unsigned | height, | ||
| const struct lwir_roi * | roi ) |
Validate a native rectangle without clipping an operator's request.
- Parameters
-
width Native width. height Native height. roi Requested region.
- Returns
- True when every requested sample is within the image.
Validate a native rectangle without clipping an operator's request.
- Returns
- True when every sample is in bounds.
- Note
- Extents are compared as width <= image_width - x so x + width cannot wrap.
Definition at line 70 of file lwir_frame.c.
◆ lwir_temperature_statistics()
| 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.
- Parameters
-
frame Combined frame. bytes Exact size. width Native width. height Native height. roi Native region. statistics Output, valid only on success.
- Returns
- True on success.
Rectangle convenience interface to lwir_measure_temperature.
- Returns
- False for an invalid roi or any lwir_measure_temperature() failure.
Definition at line 394 of file lwir_frame.c.