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_container.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_CONTAINER_H
19#define SENSORAIA_LWIR_CONTAINER_H
20
21/** @file
22 * @brief Exact thermal evidence in JPEG containers, independent of analysis.
23 *
24 * @details Read side of the format written by lwir_image.c. A saved LWIR JPEG
25 * keeps the native temperature plane, little-endian Kelvin*64 per sample, in
26 * APP15 chunks signed "LWIRRAW1" (live camera) or "LWIRSIM1" (synthetic
27 * replay). Because those bytes bypass the lossy DCT path, temperatures read
28 * back here are bit-identical to the captured plane at any JPEG quality.
29 *
30 * Used after capture by analysis, geolocation and validation tools that need
31 * temperatures from a stored photo. Only marker segments up to the first
32 * scan are parsed; compressed pixels are never decoded.
33 *
34 * Invariants enforced by the reader:
35 * - Chunks share one signature kind and one width/height, and their offsets
36 * are contiguous from zero; the layer must be complete.
37 * - Native dimensions are independent of display orientation.
38 * - The file must be a regular file that does not change while being read.
39 * - Image-only JPEGs (TDK layout) have no layer: the layer/stream readers
40 * return 0 for them.
41 */
42#include <stdbool.h>
43#include <stddef.h>
44#include <stdint.h>
45#include <stdio.h>
46
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/** @brief Existing APP15 wire layout, shared by the reader and image writer.
52 * @details The eight-byte signature is followed by little-endian uint32 width,
53 * height and byte offset into the native temperature plane. Samples start at
54 * byte 20. Chunk capacity is the writer's policy, not a reader acceptance limit.
55 */
57 LWIR_THERMAL_APP_MARKER = 0xef, /**< APP15 marker code. */
58 LWIR_THERMAL_SIGNATURE_BYTES = 8, /**< Signature length, no terminator. */
59 LWIR_THERMAL_WIDTH_OFFSET = 8, /**< uint32 LE native width. */
60 LWIR_THERMAL_HEIGHT_OFFSET = 12, /**< uint32 LE native height. */
61 LWIR_THERMAL_DATA_OFFSET = 16, /**< uint32 LE byte offset of this chunk within the plane. */
62 LWIR_THERMAL_HEADER_BYTES = 20, /**< Header size; samples follow immediately. */
63 LWIR_THERMAL_CHUNK_CAPACITY = 65000 /**< Writer's sample bytes per chunk; header + capacity stays within one APPn segment. */
64};
65
66/** @brief Signature of a temperature plane read from the live camera. */
67#define LWIR_THERMAL_SENSOR_SIGNATURE "LWIRRAW1"
68/** @brief Signature of a temperature plane produced by synthetic replay. */
69#define LWIR_THERMAL_SYNTHETIC_SIGNATURE "LWIRSIM1"
70
71/** @brief Native geometry and identity recovered from the APP14 "LWIREV02" text.
72 * @details Fields: @c width, @c height native thermal size; @c rotation
73 * clockwise display rotation (0/90/180/270); @c mirror, @c flip display
74 * transforms; @c legend whether a legend strip was drawn; @c camera true for
75 * source=camera, false for replay; @c sequence frame sequence; @c arrival_us
76 * host arrival time; @c boot_id boot identity text; @c frame_sha256 64
77 * lowercase hex digits plus NUL. All are validated against the APP15 layer
78 * and the JPEG dimensions before being returned.
79 */
81 unsigned width, height, rotation;
84 char boot_id[64];
85 char frame_sha256[65];
86};
87
88/** @brief Extract the temperature plane plus its recorded provenance geometry.
89 * @param filename Regular JPEG path; symlinks are refused (O_NOFOLLOW).
90 * @param destination Caller-owned sample storage; ignore on failure.
91 * @param capacity Writable bytes in destination.
92 * @param geometry Written only on a complete, consistent result.
93 * @return 1 for a complete layer with matching APP14 evidence, otherwise -1
94 * (invalid input, missing or duplicate APP14 evidence, any inconsistency, or
95 * I/O failure).
96 * @details Stricter than lwir_read_temperature_layer(): exactly one LWIREV02
97 * record with all eleven geometry keys must be present; its native size must
98 * equal the layer, its source must match the signature kind, and the JPEG
99 * dimensions must equal the native size after the recorded rotation.
100 * @note Never returns 0: without a layer the geometry cross-checks cannot pass,
101 * so image-only or layer-less JPEGs report -1 here.
102 */
103int lwir_read_temperature_evidence(const char *filename, uint8_t *destination, size_t capacity,
104 struct lwir_saved_geometry *geometry);
105
106/** @brief Extract native little-endian Kelvin*64 samples without decoding pixels.
107 * @param filename Regular JPEG containing LWIRRAW1 or LWIRSIM1 APP15 chunks.
108 * @param destination Caller-owned temperature storage; no intermediate plane is kept.
109 * @param capacity Writable bytes in destination.
110 * @param width Native thermal width, written only when a complete layer is found.
111 * @param height Native thermal height, independent of JPEG display orientation.
112 * @param synthetic True for simulated evidence, written only on success.
113 * @return 1 for a complete layer, 0 when absent, -1 for invalid input or I/O failure.
114 * @warning Ignore destination on failure; a partial layer may have been written.
115 * @details Chunk order, dimensions, provenance and file stability are checked.
116 * This validates the container header, not the compressed display's pixel content.
117 */
118int lwir_read_temperature_layer(const char *filename, uint8_t *destination, size_t capacity,
119 unsigned *width, unsigned *height, bool *synthetic);
120/** @brief Extract thermal evidence from an already-open regular JPEG stream.
121 * @param input Borrowed seekable stream; rewound to SOI, never closed here.
122 * @param destination Caller-owned sample storage; ignore on failure.
123 * @param capacity Available writable bytes.
124 * @param width Native width, written on success only.
125 * @param height Native height, written on success only.
126 * @param synthetic Native versus simulated evidence, written on success only.
127 * @return Same 1/0/-1 contract as lwir_read_temperature_layer.
128 * @details Reusing an owned stream avoids reopening a path after identity checks.
129 */
130int lwir_read_temperature_stream(FILE *input, uint8_t *destination, size_t capacity,
131 unsigned *width, unsigned *height, bool *synthetic);
132
133#ifdef __cplusplus
134}
135#endif
136#endif
static unsigned capacity[COVERAGE_CAMERAS]
int lwir_read_temperature_layer(const char *filename, uint8_t *destination, size_t capacity, unsigned *width, unsigned *height, bool *synthetic)
Extract native little-endian Kelvin*64 samples without decoding pixels.
int lwir_read_temperature_stream(FILE *input, uint8_t *destination, size_t capacity, unsigned *width, unsigned *height, bool *synthetic)
Extract thermal evidence from an already-open regular JPEG stream.
int lwir_read_temperature_evidence(const char *filename, uint8_t *destination, size_t capacity, struct lwir_saved_geometry *geometry)
Extract the temperature plane plus its recorded provenance geometry.
lwir_thermal_layout
Existing APP15 wire layout, shared by the reader and image writer.
@ LWIR_THERMAL_HEADER_BYTES
@ LWIR_THERMAL_APP_MARKER
@ LWIR_THERMAL_DATA_OFFSET
@ LWIR_THERMAL_SIGNATURE_BYTES
@ LWIR_THERMAL_WIDTH_OFFSET
@ LWIR_THERMAL_CHUNK_CAPACITY
@ LWIR_THERMAL_HEIGHT_OFFSET
Native geometry and identity recovered from the APP14 "LWIREV02" text.