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_profile.c
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/** @file
19 * @brief Strict loader for measured LWIR display-correction profiles.
20 *
21 * @details Parses a flat INI file whose format key is "LWIR_CORRECTIONS_V1":
22 * serial, gain label, width, height, scale_ppm (500000..1500000), offset_mk
23 * (-50000..50000), range_min_raw/range_max_raw (supported raw code range,
24 * excluding the endpoint codes 0 and 65535), bad_pixel_count and
25 * bad_pixel_0..bad_pixel_N-1 as "column,row" pairs.
26 *
27 * The renderer applies these corrections to display pixels only; native
28 * temperatures, measurements and stored APP15 data are never altered. The
29 * SHA-256 of the exact file bytes becomes the profile identity recorded in
30 * each JPEG's provenance text.
31 *
32 * Invariants: the whole file is bounded to 8192 bytes; all fields are
33 * mandatory and unique; bad pixels are bounded by LWIR_MAX_BAD_PIXELS,
34 * inside the profile geometry, sorted ascending and duplicate-free. The
35 * caller's struct is written only after every check passed (all-or-nothing),
36 * using a byte loop rather than memcpy per project policy.
37 */
38#include "lwir_render.h"
39#include "bounded_ini.h"
40#include "sha256fst.h"
41
42/** @brief Parse state; kept apart from the caller's profile until fully validated. */
44 struct lwir_profile profile; /**< Candidate profile under construction. */
45 bool fields[10]; /**< Seen flags for the ten mandatory keys, indexed as in profile_field(). */
46 bool bad_seen[LWIR_MAX_BAD_PIXELS]; /**< Seen flags per bad_pixel_N index; detects duplicates and gaps. */
47 uint16_t bad_x[LWIR_MAX_BAD_PIXELS]; /**< Bad-pixel columns; linearized only once width is known. */
48 uint16_t bad_y[LWIR_MAX_BAD_PIXELS]; /**< Bad-pixel rows. */
49};
50
51/** @brief Copy a serial or gain label after validating it.
52 * @param destination Label buffer in the candidate profile.
53 * @param capacity Buffer size including the terminator.
54 * @param value NUL-terminated label text.
55 * @return False for empty, too long, control characters or DEL, or "unknown".
56 * @details "unknown" is the placeholder written to evidence when a label is
57 * missing, so a profile must not match a camera whose label was never given.
58 */
59static bool copy_label(char *destination, size_t capacity, const char *value)
60{
61 const size_t length = strlen(value);
62 if (!length || length >= capacity || !strcmp(value, "unknown")) return false;
63 for (size_t index = 0; index < length; ++index) if ((unsigned char)value[index] < 32 || value[index] == 127) return false;
64 for (size_t index = 0; index <= length; ++index) destination[index] = value[index];
65 return true;
66}
67
68/** @brief ini_parse() callback for one profile key.
69 * @param context struct profile_parser.
70 * @param key INI key.
71 * @param value NUL-terminated value.
72 * @return False aborts the load: unknown or repeated key, wrong format string,
73 * invalid label, malformed number or a value out of range.
74 * @details Unlike the provenance reader, unknown keys are errors: a profile
75 * changes rendered output, so a misspelled key must not be silently ignored.
76 * Bad-pixel coordinates are only bounded by LWIR_MAX_WIDTH/HEIGHT here because
77 * width and height may appear later in the file; lwir_profile_load() rechecks
78 * them against the declared geometry.
79 */
80static bool profile_field(void *context, const char *key, const char *value)
81{
82 struct profile_parser *parser = context;
83 static const char *const keys[] = {"format", "serial", "gain", "width", "height", "scale_ppm", "offset_mk", "range_min_raw", "range_max_raw", "bad_pixel_count"};
84 unsigned field = 0;
85 while (field < 10 && strcmp(key, keys[field])) ++field;
86 if (field == 10) {
87 /* Not a fixed key: must be bad_pixel_N with N below the list capacity. */
88 const char prefix[] = "bad_pixel_";
89 uint64_t index;
90 if (strncmp(key, prefix, sizeof(prefix) - 1) || !ini_uint(key + sizeof(prefix) - 1, &index) ||
91 index >= LWIR_MAX_BAD_PIXELS || parser->bad_seen[index] || strlen(value) >= 32) return false;
92 char coordinates[32];
93 /* Local copy so the comma can be split without touching the parser's buffer. */
94 for (size_t position = 0; position <= strlen(value); ++position) coordinates[position] = value[position];
95 char *separator = strchr(coordinates, ',');
96 if (!separator) return false;
97 *separator++ = '\0';
98 uint64_t column, row;
99 if (!ini_uint(coordinates, &column) || !ini_uint(separator, &row) || column >= LWIR_MAX_WIDTH || row >= LWIR_MAX_HEIGHT) return false;
100 parser->bad_seen[index] = true;
101 parser->bad_x[index] = (uint16_t)column; parser->bad_y[index] = (uint16_t)row;
102 return true;
103 }
104 if (parser->fields[field]) return false;
105 parser->fields[field] = true;
106 if (field == 0) return !strcmp(value, "LWIR_CORRECTIONS_V1");
107 if (field == 1) return copy_label(parser->profile.serial, sizeof(parser->profile.serial), value);
108 if (field == 2) return copy_label(parser->profile.gain, sizeof(parser->profile.gain), value);
109 uint64_t number;
110 /* Only offset_mk may be negative; ini_uint() itself accepts unsigned text only. */
111 const bool negative = field == 6 && value[0] == '-';
112 if (!ini_uint(value + (negative ? 1 : 0), &number)) return false;
113 switch (field) {
114 /* Width must be even and at least 2, matching the native frame width rule. */
115 case 3: if (number < 2 || number > LWIR_MAX_WIDTH || number % 2) return false; parser->profile.width = (unsigned)number; break;
116 case 4: if (number == 0 || number > LWIR_MAX_HEIGHT) return false; parser->profile.height = (unsigned)number; break;
117 case 5: if (number < 500000 || number > 1500000) return false; parser->profile.scale_ppm = (unsigned)number; break;
118 case 6: if (number > 50000) return false; parser->profile.offset_mk = negative ? -(int)number : (int)number; break;
119 /* Raw codes 0 and 65535 are reserved invalid endpoints and cannot be supported. */
120 case 7: if (number == 0 || number >= UINT16_MAX) return false; parser->profile.range_min = (uint16_t)number; break;
121 case 8: if (number == 0 || number >= UINT16_MAX) return false; parser->profile.range_max = (uint16_t)number; break;
122 case 9: if (number > LWIR_MAX_BAD_PIXELS) return false; parser->profile.bad_count = (unsigned)number; break;
123 default: return false;
124 }
125 return true;
126}
127
128/** @brief Load and fully validate a profile; see lwir_render.h.
129 * @details Steps: bounded read (8192-byte buffer) -> SHA-256 of the raw bytes ->
130 * strict parse -> completeness and range checks -> bad-pixel geometry check
131 * and linearization -> sort -> duplicate rejection -> byte copy to caller.
132 * On any failure errno is EINVAL, including read failures, whose original
133 * errno is not preserved; @p profile is then left untouched.
134 * @note The digest covers comments and whitespace too, so any byte change
135 * yields a new profile identity.
136 */
137bool lwir_profile_load(const char *path, struct lwir_profile *profile)
138{
139 if (!profile) { errno = EINVAL; return false; }
140 char data[8192];
141 size_t length;
142 struct profile_parser parser = {0};
143 if (!ini_read_file(path, data, sizeof(data), &length)) { errno = EINVAL; return false; }
144 /* Hash before parsing: the identity is the file as stored, not as interpreted. */
145 sha256_hex(data, length, parser.profile.sha256);
146 if (!ini_parse(data, length, profile_field, &parser)) { errno = EINVAL; return false; }
147 for (unsigned field = 0; field < 10; ++field) if (!parser.fields[field]) { errno = EINVAL; return false; }
148 if (parser.profile.range_min >= parser.profile.range_max) { errno = EINVAL; return false; }
149 for (unsigned index = 0; index < LWIR_MAX_BAD_PIXELS; ++index) {
150 /* Indices 0..bad_pixel_count-1 must all be present and nothing beyond: no gaps or extras. */
151 if (parser.bad_seen[index] != (index < parser.profile.bad_count)) { errno = EINVAL; return false; }
152 if (index < parser.profile.bad_count) {
153 if (parser.bad_x[index] >= parser.profile.width || parser.bad_y[index] >= parser.profile.height) { errno = EINVAL; return false; }
154 parser.profile.bad_pixels[index] = (uint32_t)parser.bad_y[index] * parser.profile.width + parser.bad_x[index];
155 }
156 }
157 /* Insertion sort: at most LWIR_MAX_BAD_PIXELS entries, no heap. The renderer
158 * binary-searches the ascending list, and sorting turns duplicate detection
159 * into a neighbour comparison. */
160 for (unsigned index = 1; index < parser.profile.bad_count; ++index) {
161 const uint32_t value = parser.profile.bad_pixels[index];
162 unsigned position = index;
163 while (position && parser.profile.bad_pixels[position - 1] > value) { parser.profile.bad_pixels[position] = parser.profile.bad_pixels[position - 1]; --position; }
164 parser.profile.bad_pixels[position] = value;
165 }
166 for (unsigned index = 1; index < parser.profile.bad_count; ++index) if (parser.profile.bad_pixels[index] == parser.profile.bad_pixels[index - 1]) { errno = EINVAL; return false; }
167 /* Publish only now, after every check: callers never see a half-valid profile. */
168 unsigned char *destination = (unsigned char *)profile;
169 const unsigned char *source = (const unsigned char *)&parser.profile;
170 for (size_t index = 0; index < sizeof(*profile); ++index) destination[index] = source[index];
171 return true;
172}
173
174/** @brief Exact match of geometry, serial and gain label; see lwir_render.h.
175 * @details Plain string equality: no case folding or trimming, so a profile
176 * never silently applies to a different camera or gain setting.
177 */
178bool lwir_profile_matches(const struct lwir_profile *profile, unsigned width, unsigned height,
179 const char *serial, const char *gain)
180{
181 return profile && serial && gain && profile->width == width && profile->height == height &&
182 !strcmp(profile->serial, serial) && !strcmp(profile->gain, gain);
183}
Allocation-free flat key=value mechanics; callers own schemas and storage.
static bool ini_uint(const char *text, uint64_t *number)
Parse digits-only uint64; overflow and signs are rejected.
Definition bounded_ini.h:52
static bool ini_read_file(const char *filename, char *buffer, size_t capacity, size_t *length)
Read a nonempty regular file smaller than capacity and append NUL.
Definition bounded_ini.h:98
static bool ini_parse(char *buffer, size_t length, ini_field_handler handler, void *context)
Destructively parse flat fields with blank lines and #/; comment lines.
static unsigned capacity[COVERAGE_CAMERAS]
#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
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
bool lwir_profile_load(const char *path, struct lwir_profile *profile)
Load and fully validate a profile; see lwir_render.h.
static bool copy_label(char *destination, size_t capacity, const char *value)
Copy a serial or gain label after validating it.
bool lwir_profile_matches(const struct lwir_profile *profile, unsigned width, unsigned height, const char *serial, const char *gain)
Exact match of geometry, serial and gain label; see lwir_render.h.
static bool profile_field(void *context, const char *key, const char *value)
ini_parse() callback for one profile key.
Display rendering of Tiny1-C frames into JPEG-ready Y/Cb/Cr scanlines.
#define LWIR_MAX_BAD_PIXELS
Capacity of the sorted bad-pixel list in struct lwir_profile.
Definition lwir_render.h:64
static struct usher_camera_profile profile
void sha256_hex(const void *data, size_t length, char *output)
Hash one memory region to a lowercase hexadecimal string.
Definition sha256fst.c:272
Allocation-free, portable SHA-256 checksums for memory and streams.
Measured display-correction profile for one camera, gain label and geometry.
Definition lwir_render.h:70
uint32_t bad_pixels[LWIR_MAX_BAD_PIXELS]
Definition lwir_render.h:82
char sha256[65]
Definition lwir_render.h:73
unsigned height
Definition lwir_render.h:75
unsigned scale_ppm
Definition lwir_render.h:76
unsigned bad_count
Definition lwir_render.h:80
uint16_t range_max
Definition lwir_render.h:79
unsigned width
Definition lwir_render.h:74
uint16_t range_min
Definition lwir_render.h:78
char serial[64]
Definition lwir_render.h:71
char gain[32]
Definition lwir_render.h:72
Parse state; kept apart from the caller's profile until fully validated.
bool fields[10]
struct lwir_profile profile
uint16_t bad_x[LWIR_MAX_BAD_PIXELS]
bool bad_seen[LWIR_MAX_BAD_PIXELS]
uint16_t bad_y[LWIR_MAX_BAD_PIXELS]