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_image.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_IMAGE_H
19#define SENSORAIA_LWIR_IMAGE_H
20/** @file
21 * @brief JPEG encoding and durable no-overwrite publication of LWIR frames.
22 *
23 * @details Final stage of the LWIR capture pipeline. Acquisition and frame
24 * arithmetic (lwir_frame.h) yield an immutable frame, the renderer
25 * (lwir_render.h) converts it into display rows, and this module wraps those
26 * rows in a JPEG together with the evidence needed to interpret it later.
27 * Frame arithmetic never depends on this module.
28 *
29 * Input frames:
30 * - Combined (LWIR_COMBINED): packed YUYV display plane followed by an equally
31 * sized little-endian Kelvin*64 temperature plane; see lwir_frame_bytes().
32 * - Image-only (LWIR_YUYV_IMAGE, TDK device): the limited-range YUYV plane
33 * alone, half the combined size, with no temperatures.
34 *
35 * JPEG output, produced by the bundled IJG libjpeg 9f (lwir_jpeg_provider()):
36 * - APP14 "LWIREV02" key=value provenance text, when evidence is supplied.
37 * - APP1 EXIF holding the sensor-capture record, for live frames only.
38 * - APP15 chunks carrying the exact native temperature plane, signed
39 * "LWIRRAW1" (live) or "LWIRSIM1" (synthetic replay); see lwir_container.h.
40 * - Sequential scan, 4:4:4 sampling, quality 1..100 (0 means legacy 100).
41 *
42 * Invariants:
43 * - Temperatures survive bit-exact at any JPEG quality; only the display is lossy.
44 * - Image-only frames carry no thermal markers and are expanded from limited
45 * to full-range YCbCr before encoding.
46 * - Publication never replaces an existing path and is durable on success.
47 * - Encoding uses one static workspace: single-threaded and not re-entrant.
48 */
49#include "lwir_frame.h"
50#include "sensor_capture.h"
51#include "lwir_state.h"
52#include <stdio.h>
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57/** @brief Borrowed provenance for one publication; strings must outlive encoding.
58 * @details User labels, post-frame state and unknown exposure timing stay distinct.
59 * Every field is copied into the APP14 text as-is; nothing here is validated
60 * against the device. NULL strings are recorded as fixed placeholders so a
61 * reader can tell "not supplied" from an empty value.
62 */
64 struct sensor_capture capture; /**< Boot id and sequence go to APP14; the whole record becomes the EXIF sensor-capture tag on live frames. */
65 uint64_t request_us; /**< Host time the capture was requested, microseconds. */
66 uint64_t arrival_us; /**< Host time the frame arrived, microseconds; arrival is not exposure time. */
67 uint64_t request_id; /**< Caller request identifier, recorded verbatim. */
68 uint64_t kernel_monotonic_us; /**< Kernel buffer timestamp; recorded but explicitly not a qualified exposure time. */
69 unsigned kernel_timestamp_flags; /**< Kernel buffer timestamp flags, recorded verbatim. */
70 const char *serial; /**< Camera serial; NULL is recorded as "unknown". */
71 const char *gain; /**< Operator gain label, not a device readback; NULL is recorded as "unknown". */
72 const char *raw_path; /**< Raw companion path; NULL is recorded as "none". Must be NULL for image-only frames. */
73 const char *rendering; /**< Rendering description; NULL is recorded as "sensor". */
74 const struct lwir_measurement *measurement; /**< Optional measurement geometry; written only together with statistics. */
75 const struct lwir_thresholds *thresholds; /**< Optional coverage band; NULL is recorded as disabled. */
76 const struct lwir_temperature_stats *statistics; /**< Optional measurement results; must be NULL for image-only frames. */
77 const struct lwir_device_state *device_state; /**< Optional post-frame device snapshot; dropped for synthetic output, must be NULL for image-only frames. */
78 unsigned warn_percent; /**< Advisory coverage warning percentage, recorded verbatim. */
79 char frame_sha256[65]; /**< NUL-terminated hex SHA-256 of the frame; readers require 64 lowercase hex digits. */
80 enum lwir_frame_layout layout; /**< LWIR_YUYV_IMAGE selects image-only encoding and validation. */
81};
82/* Defined in lwir_render.h; only pointers are used here. */
84
85/** @brief Encode into an existing stream without owning its publication policy.
86 * @param output Caller-owned writable stream; caller handles flush/sync/close.
87 * @param frame Immutable combined frame, or packed YUYV when evidence selects LWIR_YUYV_IMAGE.
88 * @param bytes Exact frame size.
89 * @param width Native width.
90 * @param height Native height.
91 * @param synthetic Whether thermal evidence is simulated.
92 * @param evidence Optional capture provenance; required for display orientation.
93 * @param render Optional display policy; NULL keeps the sensor image.
94 * @return True on successful encoding. Discard partial output on failure.
95 * @details Serial encoder, bounded scanline workspace. The codec may
96 * allocate internally. Image-only evidence permits sensor-view rendering only,
97 * expands limited-range YUYV for JPEG, and emits no thermal markers. Otherwise
98 * JPEG display is lossy; embedded native temperatures are exact.
99 *
100 * Failures set errno: EINVAL for bad arguments, quality above 100 or display
101 * orientation without evidence; ENOTSUP for image-only frames combined with
102 * thermal rendering, synthetic output or thermal evidence; ENOSPC when the
103 * provenance text does not fit its fixed buffer; EIO for codec failures.
104 * Renderer failures keep the renderer's errno.
105 * @note A NULL render, or jpeg_quality 0, encodes at the legacy quality 100.
106 * @warning Uses process-wide static encoder state: never call concurrently or
107 * from a signal handler.
108 */
109bool lwir_encode_jpeg(FILE *output, const uint8_t *frame, size_t bytes, unsigned width, unsigned height,
110 bool synthetic, const struct lwir_evidence *evidence, const struct lwir_render_options *render);
111/** @brief Identify the compiled codec provider for diagnostics and benchmark logs.
112 * @return Static string "ijg-9f" (bundled IJG libjpeg 9f); never NULL, never freed.
113 */
114const char *lwir_jpeg_provider(void);
115/** @brief Remove a file previously published by this process and sync its directory.
116 * @param path File name returned as published by one of the writers below.
117 * @return True when the name was removed and the removal persisted; errno otherwise.
118 * @details Used to undo a raw companion when the matching JPEG could not be
119 * published, so a failed capture leaves neither file behind.
120 * @warning Only pass names this process published; it removes whatever the path names.
121 */
122bool lwir_remove_published(const char *path);
123
124/** @brief Publish a sensor-view JPEG with exact native thermal markers.
125 * @param path New destination, never an existing file.
126 * @param frame Immutable combined frame.
127 * @param bytes Exact combined size.
128 * @param width Native width.
129 * @param height Native height.
130 * @param synthetic Select simulated versus live thermal evidence.
131 * @return True after exclusive publication and directory sync. On failure
132 * errno holds the first error; EEXIST means the destination already existed.
133 * @details Writes a private temporary "PATH.part.XXXXXX", syncs it, then
134 * hard-links it to @p path so the name appears atomically and only when
135 * complete. Without evidence no APP14/EXIF is written, but the thermal
136 * markers still are.
137 * @warning A failure after linking may leave a final file. Inspect; never auto-retry.
138 */
139bool lwir_write_jpeg(const char *path, const uint8_t *frame, size_t bytes,
140 unsigned width, unsigned height, bool synthetic);
141/** @brief Publish the sensor view plus borrowed capture provenance.
142 * @param path New destination, never an existing file.
143 * @param frame Immutable combined frame or image-only YUYV.
144 * @param bytes Exact byte count for the selected layout.
145 * @param width Native width.
146 * @param height Native height.
147 * @param synthetic True for simulated rather than live evidence.
148 * @param evidence Optional capture record; simulated output strips live state.
149 * @return True after exclusive publication and directory sync.
150 * @details Uses the same temporary-file and no-overwrite publication
151 * contract as lwir_write_jpeg().
152 * @warning A failure after linking may leave a final file; inspect before retrying.
153 * @note Image-only evidence (LWIR_YUYV_IMAGE) expects the half-size YUYV frame.
154 */
155bool lwir_write_jpeg_evidence(const char *path, const uint8_t *frame, size_t bytes,
156 unsigned width, unsigned height, bool synthetic,
157 const struct lwir_evidence *evidence);
158/** @brief Publish an exact combined frame with the same no-overwrite contract.
159 * @param path New raw destination.
160 * @param frame Immutable combined frame.
161 * @param bytes Exact combined size.
162 * @param width Native width.
163 * @param height Native height.
164 * @return True after publication; ambiguous failures must not be retried blindly.
165 * @details Bytes are written verbatim through the same temporary/link/sync
166 * sequence as the JPEG writers, so the companion is equally durable and never
167 * overwrites. Always expects the full combined size.
168 */
169bool lwir_write_raw(const char *path, const uint8_t *frame, size_t bytes,
170 unsigned width, unsigned height);
171/** @brief Publish a rendered view without altering original temperature samples.
172 * @param path New destination, never an existing file.
173 * @param frame Immutable native frame.
174 * @param bytes Exact frame byte count for its layout.
175 * @param width Native width before orientation.
176 * @param height Native height before orientation.
177 * @param synthetic True for simulated rather than live evidence.
178 * @param evidence Optional capture record, required when orientation changes.
179 * @param render Display policy; orientation requires evidence for its native mapping.
180 * @return True after exclusive publication and directory sync.
181 * @details Use the same no-overwrite publication as lwir_write_jpeg_evidence().
182 * @warning A failure after linking may leave a final file; inspect before retrying.
183 * @note Rendering changes only display pixels; the APP15 temperature plane is
184 * always the unmodified native data.
185 */
186bool lwir_write_jpeg_rendered(const char *path, const uint8_t *frame, size_t bytes,
187 unsigned width, unsigned height, bool synthetic,
188 const struct lwir_evidence *evidence, const struct lwir_render_options *render);
189
190#ifdef __cplusplus
191}
192#endif
193#endif
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
Native frame arithmetic and camera measurements; no codec or flight dependencies.
lwir_frame_layout
Buffer content kinds: full image+thermal frame, or the YUYV image plane alone.
Definition lwir_frame.h:54
char evidence[8192]
Definition lwir_image.c:66
bool lwir_write_raw(const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
Publish an exact combined frame with the same no-overwrite contract.
Definition lwir_image.c:516
bool lwir_write_jpeg(const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic)
Publish a sensor-view JPEG with exact native thermal markers.
Definition lwir_image.c:501
bool lwir_write_jpeg_rendered(const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic, const struct lwir_evidence *evidence, const struct lwir_render_options *render)
Publish a rendered view without altering original temperature samples.
Definition lwir_image.c:522
bool lwir_remove_published(const char *path)
Remove a file previously published by this process and sync its directory.
Definition lwir_image.c:488
bool lwir_write_jpeg_evidence(const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic, const struct lwir_evidence *evidence)
Publish the sensor view plus borrowed capture provenance.
Definition lwir_image.c:508
const char * lwir_jpeg_provider(void)
Identify the compiled codec provider for diagnostics and benchmark logs.
Definition lwir_image.c:380
bool lwir_encode_jpeg(FILE *output, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic, const struct lwir_evidence *evidence, const struct lwir_render_options *render)
Encode into an existing stream without owning its publication policy.
Definition lwir_image.c:390
uint8_t frame[LWIR_MAX_FRAME_BYTES]
Definition lwir_mock.c:58
Tiny1-C vendor mailbox: bounded device-state snapshots and verified setting controls.
static FILE * output
Definition pose_log.c:77
Exact bounded SENSOR02 capture evidence, independent of TIFF byte order.
One post-capture snapshot of all lwir_state_field values.
Definition lwir_state.h:135
Borrowed provenance for one publication; strings must outlive encoding.
Definition lwir_image.h:63
uint64_t kernel_monotonic_us
Definition lwir_image.h:68
enum lwir_frame_layout layout
Definition lwir_image.h:80
const struct lwir_device_state * device_state
Definition lwir_image.h:77
const char * raw_path
Definition lwir_image.h:72
const struct lwir_measurement * measurement
Definition lwir_image.h:74
const char * serial
Definition lwir_image.h:70
const char * gain
Definition lwir_image.h:71
const struct lwir_temperature_stats * statistics
Definition lwir_image.h:76
const struct lwir_thresholds * thresholds
Definition lwir_image.h:75
unsigned warn_percent
Definition lwir_image.h:78
const char * rendering
Definition lwir_image.h:73
uint64_t request_us
Definition lwir_image.h:65
char frame_sha256[65]
Definition lwir_image.h:79
uint64_t arrival_us
Definition lwir_image.h:66
unsigned kernel_timestamp_flags
Definition lwir_image.h:69
uint64_t request_id
Definition lwir_image.h:67
struct sensor_capture capture
Definition lwir_image.h:64
One native-coordinate measurement request.
Definition lwir_frame.h:76
Display policy for one rendering request; never affects stored samples.
Raw-unit measurement results; derive mean/variance from the sums and pixels.
Definition lwir_frame.h:98
Optional coverage band counted alongside measurement statistics.
Definition lwir_frame.h:89