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

Frame geometry, structural/live qualification and native temperature measurements. More...

#include "lwir_frame.h"
#include "exifite.h"
#include "lwir_render.h"
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <setjmp.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
Include dependency graph for lwir_frame.c:

Go to the source code of this file.

Functions

size_t lwir_frame_bytes (unsigned width, unsigned height)
 Combined frame size for supported geometry.
bool lwir_roi_valid (unsigned width, unsigned height, const struct lwir_roi *roi)
 Check that a non-empty rectangle lies entirely inside the image.
bool lwir_measurement_valid (unsigned width, unsigned height, const struct lwir_measurement *measurement)
 Validate a measurement request against native geometry.
static uint16_t thermal_sample (const uint8_t *plane, unsigned width, unsigned column, unsigned row)
 Read one little-endian thermal code.
static uint16_t measurement_sample (const uint8_t *plane, unsigned width, unsigned height, unsigned column, unsigned row, bool average, uint16_t center)
 Measured value of one center, optionally 3x3-averaged.
static void accumulate_temperature (struct lwir_temperature_stats *result, uint16_t raw, unsigned column, unsigned row, const struct lwir_thresholds *thresholds, uint16_t center)
 Add one measured sample to running statistics.
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 a point, line or rectangle in native coordinates.
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 statistics without averaging or thresholds.
static unsigned byte_difference (uint8_t first, uint8_t second)
 Absolute difference of two bytes without signed overflow concerns.
bool lwir_frame_valid (const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
 Structural check: non-NULL, supported geometry, exact combined size.
bool lwir_frame_is_neutral_fill (const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
 Detect the camera's whole-frame neutral fill.
bool lwir_frame_capture_valid (const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
 Live-capture qualification.
bool lwir_frame_plausible (const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
 Conservative scene-plausibility heuristic.
bool lwir_frame_settled (const uint8_t *frame, const uint8_t *previous_image, unsigned width, unsigned height)
 Image-stability heuristic between consecutive frames.

Detailed Description

Frame geometry, structural/live qualification and native temperature measurements.

Operates on borrowed Tiny1-C combined frames: YUYV image plane (Y0 U Y1 V per pixel pair) followed by a thermal plane of little-endian uint16 Kelvin*64 codes, where 0 and 65535 are endpoint/invalid codes. Everything is in native, unrotated coordinates; display orientation and correction profiles (lwir_render.c) never affect these results.

Pipeline role: capture calls lwir_frame_capture_valid() to drop camera transition fill and frames without temperatures; lwir_frame_plausible()/lwir_frame_settled() are optional heuristics; lwir_measure_temperature() serves point, line and rectangle requests.

The scalar measurement code is the reference. On little-endian ARM64 NEON handles eight-pixel rectangle blocks with identical results: exact rounded integer averages, first-occurrence extrema and the same coverage counts (parity-tested). No heap is used.

Definition in file lwir_frame.c.

Function Documentation

◆ accumulate_temperature()

void accumulate_temperature ( struct lwir_temperature_stats * result,
uint16_t raw,
unsigned column,
unsigned row,
const struct lwir_thresholds * thresholds,
uint16_t center )
static

Add one measured sample to running statistics.

Strict comparisons keep the first visited extremum, matching the NEON path. Sums and extrema include endpoint codes; coverage counts exclude them and use the ORIGINAL center, so averaging cannot move a pixel between coverage bins.

Parameters
resultStatistics being accumulated.
rawMeasured sample (possibly averaged).
columnNative column, recorded for extrema.
rowNative row, recorded for extrema.
thresholdsOptional coverage band.
centerOriginal center code used for coverage.
Note
Endpoint status of raw and center always agree, because measurement_sample() returns endpoint centers unchanged and never averages to an endpoint code.

Definition at line 156 of file lwir_frame.c.

◆ byte_difference()

unsigned byte_difference ( uint8_t first,
uint8_t second )
static

Absolute difference of two bytes without signed overflow concerns.

Parameters
firstFirst byte.
secondSecond byte.
Returns
|first - second|, 0..255.

Definition at line 411 of file lwir_frame.c.

◆ lwir_frame_bytes()

size_t lwir_frame_bytes ( unsigned width,
unsigned height )

Combined frame size for supported geometry.

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 )

Live-capture qualification.

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 )

Detect the camera's whole-frame 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 )

Conservative scene-plausibility heuristic.

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 )

Image-stability heuristic between consecutive frames.

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 )

Structural check: non-NULL, supported geometry, exact combined size.

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 a point, line or rectangle in native coordinates.

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 a measurement request against native geometry.

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 )

Check that a non-empty rectangle lies entirely inside 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 statistics without averaging or thresholds.

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.

◆ measurement_sample()

uint16_t measurement_sample ( const uint8_t * plane,
unsigned width,
unsigned height,
unsigned column,
unsigned row,
bool average,
uint16_t center )
static

Measured value of one center, optionally 3x3-averaged.

Averages the valid (non-endpoint) codes of the 3x3 neighbourhood clipped at the sensor edges, rounded half up: (sum + n/2) / n. The valid center guarantees n >= 1.

Parameters
planeThermal plane start.
widthNative width.
heightNative height.
columnCenter column.
rowCenter row.
averageWhether averaging is requested.
centerThe center's raw code.
Returns
center unchanged when not averaging or when it is an endpoint code; otherwise the rounded mean, which stays within 1..65534.

Definition at line 124 of file lwir_frame.c.

◆ thermal_sample()

uint16_t thermal_sample ( const uint8_t * plane,
unsigned width,
unsigned column,
unsigned row )
static

Read one little-endian thermal code.

Parameters
planeThermal plane start.
widthNative width.
columnNative column (caller-checked).
rowNative row (caller-checked).
Returns
Raw Kelvin*64 code, including endpoint codes.

Definition at line 104 of file lwir_frame.c.