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 File Reference

Native frame arithmetic and camera measurements; no codec or flight dependencies. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
Include dependency graph for lwir_frame.h:
This graph shows which files directly or indirectly include this file:

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

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.

Enumerator
LWIR_RECTANGLE 

roi rectangle; an all-zero roi means the full image.

LWIR_POINT 

Single pixel at roi.x, roi.y; roi width/height ignored.

LWIR_LINE 

Inclusive line from roi.x, roi.y to end_x, end_y.

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
widthEven native width from 2 through LWIR_MAX_WIDTH.
heightNative 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
frameBorrowed bytes.
bytesAccessible size.
widthNative width.
heightNative 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
frameBorrowed bytes.
bytesAccessible size.
widthNative width.
heightNative 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
frameBorrowed bytes.
bytesAccessible size.
widthNative width.
heightNative height.
Returns
True for a structurally valid frame that passes all three heuristics.

Optional conservative scene check; unusual valid scenes may be rejected.

  1. Chroma: every odd image byte is U or V; more than 1% outside 128 +/- 8 fails.
  2. Roughness: sum of |Y(x) - Y(x+1)| must average at most 45 per adjacent pair.
  3. 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
frameCurrent combined frame.
previous_imagePrevious image half (width * height * 2 bytes), kept by the acquisition owner.
widthNative width.
heightNative 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
frameBorrowed bytes.
bytesAccessible size.
widthNative width.
heightNative 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
frameImmutable combined frame.
bytesExact frame size.
widthNative width.
heightNative height.
measurementROI/point/line and optional measurement-only averaging.
thresholdsOptional inclusive raw coverage band, not a display window.
statisticsOutput; 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
widthNative width.
heightNative height.
measurementRequested 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
widthNative width.
heightNative height.
roiRequested 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
frameCombined frame.
bytesExact size.
widthNative width.
heightNative height.
roiNative region.
statisticsOutput, 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.