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.h
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#ifndef SENSORAIA_LWIR_DETECTION_H
19#define SENSORAIA_LWIR_DETECTION_H
20/** @file
21 * @brief Optional thermal candidate detection, independent of pose and image files.
22 *
23 * @details Compiled only in analysis builds (`LWIR_ENABLE_ANALYSIS=1`). Input is
24 * the exact native Kelvin*64 temperature plane embedded in a saved LWIR JPEG,
25 * never the compressed display pixels, so thresholds operate on sensor values.
26 * The detector does no I/O, uses no heap, and keeps all scratch storage in a
27 * caller-provided lwir_detection_workspace. lwir_analysis.c is the in-tree caller.
28 */
29#include "lwir_frame.h"
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/** @brief A thermal component expressed only in native sensor coordinates.
36 * @details Temperatures are apparent device values, not corrected surface values.
37 * Tray classification is a mission heuristic, not a certified object identity.
38 */
49
50/** @var lwir_hotspot::pixels
51 * @brief 8-connected pixel count at or above the frame threshold.
52 */
53/** @var lwir_hotspot::min_x
54 * @brief Inclusive native bounding box; likewise min_y, max_x and max_y.
55 */
56/** @var lwir_hotspot::peak_x
57 * @brief Column of the first pixel (breadth-first order) holding the peak code; peak_y is its row.
58 */
59/** @var lwir_hotspot::center_x
60 * @brief Subpixel centroid column weighted by excess over local background; center_y likewise.
61 */
62/** @var lwir_hotspot::mean_celsius
63 * @brief Unweighted mean over component pixels.
64 */
65/** @var lwir_hotspot::local_background_celsius
66 * @brief Median of sub-threshold pixels within a 5-pixel margin around the box.
67 * @details Falls back to the frame median when the margin has no such pixels.
68 */
69/** @var lwir_hotspot::contrast_celsius
70 * @brief Peak minus local background; components below 15 C are discarded.
71 */
72/** @var lwir_hotspot::excess_celsius_pixels
73 * @brief Sum of per-pixel excess over local background, an integrated heat score.
74 */
75/** @var lwir_hotspot::touches_edge
76 * @brief Bounding box reaches a frame border, so the object may be truncated.
77 */
78/** @var lwir_hotspot::tray_like
79 * @brief Passed the compact, hot, high-contrast fire-tray heuristic.
80 */
81/** @var lwir_hotspot::fill_ratio
82 * @brief Pixel count divided by bounding-box area.
83 */
84/** @var lwir_hotspot::aspect_ratio
85 * @brief Longer bounding-box side divided by the shorter side (at least 1).
86 */
87
88/** @brief Bounded ranking, retaining the existing two-candidate mission policy.
89 * @details When any tray-like component exists, `candidates` holds the best
90 * tray-like ones (ranked by excess heat) and `tray_pass_selected` is true;
91 * otherwise it holds the best generic components (ranked by contrast).
92 */
99
100/** @var lwir_hotspot_set::candidates
101 * @brief Best first; only the first `count` entries are valid.
102 */
103/** @var lwir_hotspot_set::count
104 * @brief Valid entries in `candidates` (0..2).
105 */
106/** @var lwir_hotspot_set::generic_count
107 * @brief All components that passed the contrast check, not only retained ones.
108 */
109/** @var lwir_hotspot_set::tray_count
110 * @brief Subset of generic_count classified tray-like.
111 */
112/** @var lwir_hotspot_set::tray_pass_selected
113 * @brief True when `candidates` came from the tray ranking.
114 */
115/** @var lwir_hotspot_set::background_celsius
116 * @brief Median of valid (non-endpoint) codes; NaN when the plane has none.
117 */
118/** @var lwir_hotspot_set::threshold_celsius
119 * @brief Frame threshold actually applied; NaN when the plane has no valid codes.
120 */
121
122/** @brief Caller-owned scratch storage; never reserved by an imagery-only build.
123 * @details Use static or otherwise long-lived storage, not a small thread stack.
124 * No initialization is needed. Separate workspaces permit independent detectors.
125 * Size is roughly 4.1 bytes per maximum native pixel plus 256 KiB of histogram.
126 */
128 uint8_t seen[(LWIR_MAX_WIDTH * LWIR_MAX_HEIGHT + 7) / 8]; ///< One visited bit per pixel.
129 uint32_t queue[LWIR_MAX_WIDTH * LWIR_MAX_HEIGHT]; ///< BFS queue; afterwards lists the component's pixels.
130 uint32_t histogram[UINT16_MAX + 1U]; ///< One bin per raw code, used for exact medians.
131};
132
133/** @brief Rank native thermal components without touching hardware, pose or files.
134 * @param temperature Immutable little-endian Kelvin*64 plane.
135 * @param bytes Exact accessible plane length, width * height * 2.
136 * @param width Native width, at most LWIR_MAX_WIDTH.
137 * @param height Native height, at most LWIR_MAX_HEIGHT.
138 * @param workspace Exclusive scratch storage for this call, separate from input/result.
139 * @param result Bounded candidates; ignore on failure.
140 * @return True for a valid plane, including a plane with no candidates or no
141 * valid codes at all (then background_celsius and threshold_celsius are NaN).
142 * False for NULL pointers, zero or oversized dimensions, or a length mismatch.
143 * @details Threshold = max(60 C absolute, frame median + max(20 C, 6 robust
144 * sigma)), where robust sigma is 1.4826 x the median absolute deviation. Pixels
145 * at or above it form 8-connected components; each must exceed its local
146 * background by at least 15 C. See lwir_detection.c for the full algorithm.
147 * Endpoint codes 0 and 65535 are invalid samples: they are excluded from the
148 * frame median, noise estimate, components and local backgrounds.
149 * @note Temperatures are apparent sensor values without emissivity or
150 * atmospheric correction; the 60/100 C limits apply to those values.
151 */
152bool lwir_detect_hotspots(const uint8_t *temperature, size_t bytes, unsigned width, unsigned height,
154
155#ifdef __cplusplus
156}
157#endif
158#endif
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
static struct image_mock_workspace workspace
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)
Rank native thermal components without touching hardware, pose or files.
Native frame arithmetic and camera measurements; no codec or flight dependencies.
#define LWIR_MAX_WIDTH
Largest supported native width in pixels.
Definition lwir_frame.h:47
#define LWIR_MAX_HEIGHT
Largest supported native height in pixels.
Definition lwir_frame.h:49
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
Caller-owned scratch storage; never reserved by an imagery-only build.
uint8_t seen[(LWIR_MAX_WIDTH *LWIR_MAX_HEIGHT+7)/8]
One visited bit per pixel.
uint32_t histogram[UINT16_MAX+1U]
One bin per raw code, used for exact medians.
uint32_t queue[LWIR_MAX_WIDTH *LWIR_MAX_HEIGHT]
BFS queue; afterwards lists the component's pixels.
Bounded ranking, retaining the existing two-candidate mission policy.
bool tray_pass_selected
True when candidates came from the tray ranking.
struct lwir_hotspot candidates[2]
Best first; only the first count entries are valid.
double background_celsius
Median of valid (non-endpoint) codes; NaN when the plane has none.
size_t generic_count
All components that passed the contrast check, not only retained ones.
size_t count
Valid entries in candidates (0..2).
size_t tray_count
Subset of generic_count classified tray-like.
double threshold_celsius
Frame threshold actually applied; NaN when the plane has no valid codes.
A thermal component expressed only in native sensor coordinates.
size_t min_x
Inclusive native bounding box; likewise min_y, max_x and max_y.
size_t peak_x
Column of the first pixel (breadth-first order) holding the peak code; peak_y is its row.
double excess_celsius_pixels
Sum of per-pixel excess over local background, an integrated heat score.
double fill_ratio
Pixel count divided by bounding-box area.
double local_background_celsius
Median of sub-threshold pixels within a 5-pixel margin around the box.
double center_x
Subpixel centroid column weighted by excess over local background; center_y likewise.
double aspect_ratio
Longer bounding-box side divided by the shorter side (at least 1).
double peak_celsius
size_t pixels
8-connected pixel count at or above the frame threshold.
double contrast_celsius
Peak minus local background; components below 15 C are discarded.
bool touches_edge
Bounding box reaches a frame border, so the object may be truncated.
bool tray_like
Passed the compact, hot, high-contrast fire-tray heuristic.
double mean_celsius
Unweighted mean over component pixels.
struct usher_control_result result
Definition usher.c:377