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

Pose-free thermal components using caller-owned bounded scratch storage. More...

#include "lwir_detection.h"
#include <math.h>
Include dependency graph for lwir_detection.c:

Go to the source code of this file.

Enumerations

enum  { lwir_hotspot_radius = 5 }

Functions

static uint16_t read_u16_le (const uint8_t *bytes)
 Decode one unsigned 16-bit little-endian value.
static bool valid_code (uint16_t raw)
 Whether a raw code is a real measurement rather than a sensor endpoint code.
static bool bit_is_set (const struct lwir_detection_workspace *workspace, size_t pixel)
 Test a pixel's visited bit.
static void mark_bit (struct lwir_detection_workspace *workspace, size_t pixel)
 Set a pixel's visited bit.
static void histogram_clear (struct lwir_detection_workspace *workspace)
 Zero all 65536 histogram bins.
static double histogram_median (const struct lwir_detection_workspace *workspace, uint64_t count)
 Exact median of the values counted in the histogram.
static bool candidate_better (const struct lwir_hotspot *candidate, const struct lwir_hotspot *current, bool tray_order)
 Ranking predicate for retained candidates.
static void retain_candidate (struct lwir_hotspot candidates[2], size_t *count, const struct lwir_hotspot *candidate, bool tray_order)
 Insert a candidate into a sorted top-two list.
bool lwir_detect_hotspots (const uint8_t *temperature, size_t bytes, unsigned width, unsigned height, struct lwir_detection_workspace *workspace, struct lwir_hotspot_set *result)
 Detect and rank hot connected components in a native temperature plane.

Detailed Description

Pose-free thermal components using caller-owned bounded scratch storage.

Analysis builds only (LWIR_ENABLE_ANALYSIS=1). Operates on the exact native Kelvin*64 plane recovered from a saved LWIR JPEG. Algorithm outline:

  1. Robust frame statistics: exact median (background) and median absolute deviation (noise) via 65536-bin histograms, so no sorting buffer is needed.
  2. Global threshold combining an absolute floor with a robust rise over background.
  3. 8-connected flood fill (breadth-first) of above-threshold pixels.
  4. Per component: local background, contrast gate, excess-weighted subpixel centroid and shape features.
  5. Keep the top two generic and top two tray-like components; report trays if any.

Cost trade-off: every component clears and scans the full 65536-bin histogram for its local median, so frames with many small components cost roughly 65536 operations per component in addition to the per-pixel work.

Definition in file lwir_detection.c.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
lwir_hotspot_radius 

Definition at line 39 of file lwir_detection.c.

Function Documentation

◆ bit_is_set()

bool bit_is_set ( const struct lwir_detection_workspace * workspace,
size_t pixel )
static

Test a pixel's visited bit.

Parameters
workspaceScratch storage holding the bitset.
pixelRow-major native index within the current frame.
Returns
True when the pixel was already queued.

Definition at line 70 of file lwir_detection.c.

◆ candidate_better()

bool candidate_better ( const struct lwir_hotspot * candidate,
const struct lwir_hotspot * current,
bool tray_order )
static

Ranking predicate for retained candidates.

Generic order: higher contrast first, then larger excess heat. Tray order: larger excess heat first (presumably favouring an extended hot tray over a small very hot point), then contrast. A full tie returns false, so the earlier-found component (row-major seed order) keeps its place.

Parameters
candidateNewly evaluated component.
currentRetained component it is compared against.
tray_orderSelect the tray ordering instead of the generic one.
Returns
True when candidate should rank strictly above current.

Definition at line 130 of file lwir_detection.c.

◆ histogram_clear()

void histogram_clear ( struct lwir_detection_workspace * workspace)
static

Zero all 65536 histogram bins.

Parameters
workspaceScratch storage holding the histogram.

Definition at line 90 of file lwir_detection.c.

◆ histogram_median()

double histogram_median ( const struct lwir_detection_workspace * workspace,
uint64_t count )
static

Exact median of the values counted in the histogram.

Walks the cumulative count once to find the lower and upper middle ranks; for an even count the result is their mean, so it can end in .5. Exact for integer inputs, avoiding a sort and a pixel-sized copy.

Parameters
workspaceScratch storage whose histogram holds exactly count samples.
countNumber of samples; must be at least 1 ((count - 1) would wrap).
Returns
Median value in histogram-bin units.

Definition at line 104 of file lwir_detection.c.

◆ lwir_detect_hotspots()

bool lwir_detect_hotspots ( const uint8_t * temperature,
size_t bytes,
unsigned width,
unsigned height,
struct lwir_detection_workspace * workspace,
struct lwir_hotspot_set * result )

Detect and rank hot connected components in a native temperature plane.

Rank native thermal components without touching hardware, pose or files.

See lwir_detection.h for the contract and the file overview for the algorithm. All arithmetic stays in raw Kelvin*64 codes until results are converted to Celsius (code / 64 - 273.15); temperature differences convert by dividing by 64 only.

Returns
True for a valid plane (even with zero candidates); false for invalid arguments.

Definition at line 172 of file lwir_detection.c.

◆ mark_bit()

void mark_bit ( struct lwir_detection_workspace * workspace,
size_t pixel )
static

Set a pixel's visited bit.

A bitset (rather than a byte per pixel) keeps the workspace small.

Parameters
workspaceScratch storage holding the bitset.
pixelRow-major native index within the current frame.

Definition at line 81 of file lwir_detection.c.

◆ read_u16_le()

uint16_t read_u16_le ( const uint8_t * bytes)
static

Decode one unsigned 16-bit little-endian value.

Parameters
bytesAt least two readable bytes; no alignment requirement.
Returns
The decoded value, independent of host endianness.

Definition at line 46 of file lwir_detection.c.

◆ retain_candidate()

void retain_candidate ( struct lwir_hotspot candidates[2],
size_t * count,
const struct lwir_hotspot * candidate,
bool tray_order )
static

Insert a candidate into a sorted top-two list.

Insertion sort over a fixed two-slot array: while fewer than two are held the list grows; afterwards a candidate must beat the current second place to enter, and the displaced second place is dropped.

Parameters
candidatesSorted list, best first.
[in,out]countValid entries (0..2); incremented while below 2.
candidateComponent to consider; copied by value.
tray_orderOrdering passed to candidate_better().

Definition at line 150 of file lwir_detection.c.

◆ valid_code()

bool valid_code ( uint16_t raw)
static

Whether a raw code is a real measurement rather than a sensor endpoint code.

0 and 65535 (about 751 C, beyond the Tiny1C range) mark invalid or missing samples, never real temperatures, so they must not shape statistics or become hotspots.

Parameters
rawKelvin*64 code.
Returns
True for codes 1..65534.

Definition at line 59 of file lwir_detection.c.