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
loomcam.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/**
19 * @file loomcam.c
20 * @brief Guarded retained-vector return processing and transactional T1 policy.
21 * @details Declared model vectors, aligned observation metadata and configured
22 * HOME produce bounded point proposals from explicitly declared model vectors.
23 * Outbound references are archived; reference-image matching is not implemented.
24 */
25#include "camera_backend.h"
26#include "loom_return.h"
27#include "loom_features.h"
31#include "../../src/exifite.h"
33
34#include <errno.h>
35#include <inttypes.h>
36#include <math.h>
37#include <poll.h>
38#include <stdio.h>
39#include <stdlib.h>
40#include <string.h>
41#include <sys/stat.h>
42#include <time.h>
43#include <unistd.h>
44
45/** @brief The CLI accepts decimal photo numbers, never signed or truncated IDs. */
46#define LOOM_DECIMAL_RADIX 10
47/** @brief argv[0] is the program name; a sole flag gives two total arguments. */
50/** @brief Nonzero fixtures deliberately expose failure to clear previous state. */
51#define LOOM_SELF_TEST_SEQUENCE UINT32_C(1)
52/** @brief Nonzero latitude fixture checks that no-match clears stale evidence. */
53#define LOOM_SELF_TEST_LATITUDE INT32_C(1)
54/** @brief First integer outside the accepted uint32_t correlation range. */
55#define LOOM_SELF_TEST_SEQUENCE_OVERFLOW "4294967296"
56
57/**
58 * @brief Borrowed per-invocation input; no member owns or acquires a camera.
59 * @details The selected model/descriptor identifies the current photo's retained
60 * vector. The outbound reference path is carried by the invocation but is not
61 * read or compared by this vector adapter.
62 */
63struct loom_frame {
64 const char *image; /**< Readable saved photograph, immutable during matching. */
65 const char *references; /**< Optional outbound reference directory; not compared. */
66 const char *model; /**< Optional model config used to validate this photo's vector. */
67 const char *settings; /**< Executable-owned settings, resolved through common code. */
68 uint32_t sequence; /**< Positive FC photo number echoed in every result. */
69};
70
71static bool return_settings(const char *path, struct inference_settings *settings,
73
74/** @brief Read one bounded observation field from an already-fetched EXIF description. */
75static bool description_lookup(const struct exif_value *description, const char *key,
76 char value[64], bool *found)
77{
78 *found = false;
79 if (!description || description->format != EXIF_ASCII || !description->data) return false;
80 const size_t length = strlen(key);
81 char selected[64];
82 size_t selected_length = 0;
83 for (size_t index = 0; index + length < description->size; ++index) {
84 if (index && description->data[index - 1] != ' ' && description->data[index - 1] != ';') continue;
85 if (memcmp(description->data + index, key, length)) continue;
86 if (*found) return false;
87 size_t used = 0, cursor = index + length;
88 while (cursor < description->size && description->data[cursor] && description->data[cursor] != ';' &&
89 description->data[cursor] != ' ') {
90 if (used + 1 == 64) return false;
91 selected[used++] = (char)description->data[cursor++];
92 }
93 if (!used) return false;
94 selected[used] = '\0';
95 selected_length = used;
96 *found = true;
97 }
98 if (*found) {
99 for (size_t index = 0; index <= selected_length; ++index) value[index] = selected[index];
100 }
101 return true;
102}
103
104/** @brief Require a uniquely identified flight-description value.
105 * @param description EXIF description to scan.
106 * @param key Exact field prefix including the equals sign.
107 * @param[out] value Buffer for up to 63 characters and the terminator.
108 * @return True only if a well-formed matching field was found.
109 * @details Use the duplicate-aware lookup even when absence is an error. */
110static bool description_field(const struct exif_value *description, const char *key, char value[64])
111{
112 bool found = false;
113 return description_lookup(description, key, value, &found) && found;
114}
115
116/** @brief Read a required finite numeric metadata field.
117 * @param description EXIF description to scan.
118 * @param key Exact field prefix including the equals sign.
119 * @param[out] number Parsed value, written on success.
120 * @return True for a present, fully parsed number.
121 * @details Reject missing and malformed fields alike when no default is allowed. */
122static bool description_number(const struct exif_value *description, const char *key, double *number)
123{
124 char value[64];
125 return description_field(description, key, value) && ini_real(value, number);
126}
127
128/** @brief Read numeric metadata with a default for absence only.
129 * @param description EXIF description to scan.
130 * @param key Exact field prefix including the equals sign.
131 * @param default_value Result if the key is absent.
132 * @param[out] number Parsed or default value on success.
133 * @return False for malformed or duplicate evidence, even if a default exists.
134 * @details Keep corrupt evidence distinct from older records missing an optional field. */
135static bool description_optional_number(const struct exif_value *description, const char *key,
136 double default_value, double *number)
137{
138 char value[64];
139 bool found = false;
140 if (!description_lookup(description, key, value, &found)) return false;
141 if (!found) {
142 *number = default_value;
143 return true;
144 }
145 return ini_real(value, number);
146}
147
148/** @brief Read the graph and descriptor identities declared by the model metadata.
149 * @param settings Selected model and descriptor paths.
150 * @param[out] graph Buffer for the declared graph digest.
151 * @param[out] descriptor Buffer for the descriptor digest.
152 * @return True after parsing the bounded descriptor and checking model readability.
153 * @details Read descriptor identity without creating a runtime session. This
154 * helper does not hash the graph file itself. */
155static bool read_onnx_descriptor_identity(const struct inference_settings *settings,
156 char graph[65], char descriptor[65])
157{
158 struct stat model_status;
159 if (!settings || !settings->model[0] || !settings->descriptor[0] ||
160 stat(settings->model, &model_status) != 0 || !S_ISREG(model_status.st_mode) ||
161 model_status.st_size <= 0 || access(settings->model, R_OK) != 0) return false;
162 static char contents[16385];
163 static struct inference_model model;
164 char error[256];
165 size_t length = 0;
166 if (!ini_read_file(settings->descriptor, contents, sizeof(contents), &length) ||
167 !inference_model_parse(&model, contents, length, error, sizeof(error))) return false;
168 for (size_t index = 0; index <= 64; ++index) {
169 graph[index] = model.graph_sha256[index];
170 descriptor[index] = model.descriptor_sha256[index];
171 }
172 return true;
173}
174
175/** @brief Decode an unsigned field from LOOM's little-endian record.
176 * @param bytes At least eight readable bytes.
177 * @return Decoded unsigned value.
178 * @details Assemble bytes rather than reading a native word at a potentially
179 * unaligned record offset. */
180static uint64_t feature_u64(const unsigned char *bytes)
181{
182 uint64_t number = 0;
183 for (unsigned index = 0; index < 8; ++index) number |= (uint64_t)bytes[index] << (8 * index);
184 return number;
185}
186
187/** @brief Generate bounded LOOM feature evidence for an existing JPEG.
188 * @param settings ONNX model assignment and runtime configuration.
189 * @param options Contract that governs acceptable output shape.
190 * @param image Input JPEG path.
191 * @param sequence Frame identity to embed.
192 * @param timestamp_ns Sensor timestamp in nanoseconds to embed.
193 * @param[out] record Destination for packed feature evidence.
194 * @param capacity Available bytes in @p record.
195 * @param[out] record_size Packed length; use only on success.
196 * @return True after successful inference and packing.
197 * @details Validate tensor shape before inference, enforce the stricter
198 * direction-vector shape when required, and serialize before closing the session.
199 * Calls must not overlap because the context is shared. */
200static bool run_onnx_in_memory(const struct inference_settings *settings,
201 const struct loom_return_options *options,
202 const char *image, uint64_t sequence, uint64_t timestamp_ns,
203 unsigned char *record, size_t capacity, size_t *record_size)
204{
205 static struct inference_context context;
206 char error[512];
207 context = (struct inference_context){0};
208 if (!inference_context_open(&context, settings, "loom_features_v1", error, sizeof(error))) return false;
209 size_t values = 0;
210 bool valid_shape = context.model.input_count == 1 && context.model.image.channels != 0;
211 for (size_t index = 0; valid_shape && index < context.model.output_count; ++index) {
212 const struct onnx_tensor *tensor = &context.model.outputs[index];
213 if (tensor->type != ONNX_FLOAT32 || tensor->bytes / sizeof(float) > 4096 - values) valid_shape = false;
214 else values += tensor->bytes / sizeof(float);
215 }
216 if (options->frame != LOOM_RETURN_NONE && options->frame != LOOM_RETURN_SIMULATED &&
217 (context.model.output_count != 1 || (values != 2 && values != 3))) valid_shape = false;
218 bool ok = valid_shape &&
219 inference_jpeg_prepare(&context, image, error, sizeof(error)) &&
220 inference_context_run(&context, error, sizeof(error));
221 if (ok) {
222 *record_size = loom_onnx_features_pack(record, capacity, &context.model, sequence, timestamp_ns);
223 ok = *record_size != 0;
224 }
225 inference_context_close(&context);
226 return ok;
227}
228
229/**
230 * @brief Interpret retained same-photo neural vectors under the declared return contract.
231 * @param frame Current saved AIcam photo and reference/model configuration.
232 * @param point Required destination in camera-point wire units.
233 * @return False when model/pose/identity/direction validation rejects the photo.
234 * @warning Never replace no-match with the current pose, home position or guessed
235 * direction: those would look like valid navigation evidence on the FC.
236 * @details Generic embeddings are never guessed to be return directions. Only
237 * the PC simulation harness may turn them into an explicitly marked mock vector.
238 * The persistent owner subsequently limits movement and suppresses stale phases.
239 */
241{
242 *point = (struct camera_point_result) {.session_id = frame->sequence};
243 struct inference_settings settings;
245 if (!return_settings(frame->settings, &settings, &options) || options.frame == LOOM_RETURN_NONE) return false;
246 static unsigned char payload[EXIF_MAX_PAYLOAD], information[IMX500_TENSOR_INFO_BYTES];
247 static unsigned char onnx_record[LOOM_ONNX_FEATURE_CAPACITY];
248 static float features[4096];
249 size_t size = 0;
250 struct exif_view view;
251 struct exif_value description;
252 if (exif_read_jpeg(frame->image, payload, sizeof(payload), &size) || exif_parse(&view, payload, size) ||
253 !exif_get(&view, EXIF_PRIMARY, EXIF_IMAGE_DESCRIPTION, &description) ||
254 description.format != EXIF_ASCII || !description.data)
255 return false;
256 char aligned_value[64];
257 bool aligned_found = false;
258 if (!description_lookup(&description, "observation_pose_aligned=", aligned_value, &aligned_found)) return false;
259 if (aligned_found && strcmp(aligned_value, "true") && strcmp(aligned_value, "false")) return false;
260 const bool aligned = aligned_found && !strcmp(aligned_value, "true");
261 const unsigned home_fields = (1U << 5) | (1U << 6);
262 const bool home_configured = (options.seen & home_fields) == home_fields;
263 double latitude = 0, longitude = 0, altitude = 0, agl = 0, roll = 0, pitch = 0, yaw = 0;
264 if (aligned) {
265 if (!description_number(&description, "observation_lat_deg=", &latitude) || fabs(latitude) > 85 ||
266 !description_number(&description, "observation_lon_deg=", &longitude) || fabs(longitude) > 180 ||
267 !description_number(&description, "observation_alt_m=", &altitude) || fabs(altitude) > 2000000 ||
268 !description_number(&description, "observation_agl_m=", &agl) || agl < 0 || agl > 10000 ||
269 !description_optional_number(&description, "observation_roll_deg=", 0, &roll) ||
270 !description_optional_number(&description, "observation_pitch_deg=", 0, &pitch) ||
271 !description_number(&description, "observation_yaw_deg=", &yaw)) return false;
272 } else {
273 if (!description_optional_number(&description, "lat_deg=",
274 home_configured ? options.home_latitude : NAN, &latitude) ||
275 !isfinite(latitude) || fabs(latitude) > 85 ||
276 !description_optional_number(&description, "lon_deg=",
277 home_configured ? options.home_longitude : NAN, &longitude) ||
278 !isfinite(longitude) || fabs(longitude) > 180 ||
279 !description_number(&description, "alt_m=", &altitude) || fabs(altitude) > 2000000 ||
280 !description_number(&description, "groundalt_m=", &agl) || agl < 0 || agl > 10000 ||
281 !description_optional_number(&description, "roll_deg=", 0, &roll) ||
282 !description_optional_number(&description, "pitch_deg=", 0, &pitch) ||
283 !description_number(&description, "yaw_deg=", &yaw)) return false;
284 if (!latitude && !longitude && home_configured) {
285 latitude = options.home_latitude;
286 longitude = options.home_longitude;
287 }
288 }
289 if (!isfinite(roll) || !isfinite(pitch) || !isfinite(yaw) ||
290 fabs(roll) > options.limits.maximum_tilt_deg ||
291 fabs(pitch) > options.limits.maximum_tilt_deg ||
292 fabs(yaw) > 36000) return false;
293 char identity[64];
294 uint64_t observed_sequence = 0, observed_time = 0, shot_number = 0;
295 if (!description_field(&description, "observation_sequence=", identity) || !ini_uint(identity, &observed_sequence) ||
296 !description_field(&description, "sensor_timestamp_ns=", identity) || !ini_uint(identity, &observed_time))
297 return false;
298 if (observed_sequence) {
299 if (observed_sequence != frame->sequence) return false;
300 } else if (!description_field(&description, "nr=", identity) || !ini_uint(identity, &shot_number) ||
301 shot_number != frame->sequence) {
302 return false;
303 }
304 float vector[3];
305 uint64_t feature_sequence = 0, feature_time = 0;
306 struct exif_value record;
307 if (settings.backend == INFERENCE_ONNX) {
308 char graph[65], descriptor[65];
309 if (!read_onnx_descriptor_identity(&settings, graph, descriptor)) return false;
311 size_t packed_size = 0;
312 if (!run_onnx_in_memory(&settings, &options, frame->image,
313 observed_sequence ? observed_sequence : frame->sequence,
314 observed_time, onnx_record, sizeof(onnx_record), &packed_size))
315 return false;
316 record.data = onnx_record;
317 record.size = packed_size;
318 }
319 if (options.frame == LOOM_RETURN_SIMULATED) {
320 if (!loom_onnx_features_valid(record.data, record.size, graph, descriptor)) return false;
321 } else if (!loom_onnx_return_vector(record.data, record.size, graph, descriptor, vector)) {
322 return false;
323 }
324 feature_sequence = feature_u64(record.data + 136);
325 feature_time = feature_u64(record.data + 144);
326 } else if (settings.backend == INFERENCE_IMX500) {
327 size_t count = 0;
328 uint64_t sequence, sensor_timestamp_ns;
330 !loom_features_unpack(record.data, record.size, features, 4096, information, sizeof(information),
331 &count, &sequence, &sensor_timestamp_ns) ||
332 !count || (options.frame != LOOM_RETURN_SIMULATED && count != 2 && count != 3) ||
333 !sequence || !sensor_timestamp_ns) return false;
334 if (options.frame != LOOM_RETURN_SIMULATED) {
335 vector[0] = features[0]; vector[1] = features[1]; vector[2] = count == 3 ? features[2] : 1;
336 }
337 feature_sequence = sequence;
338 feature_time = sensor_timestamp_ns;
339 } else return false;
340 if (feature_time != observed_time ||
341 feature_sequence != (observed_sequence ? observed_sequence : frame->sequence))
342 return false;
343 const bool use_home_position = (aligned || options.frame == LOOM_RETURN_SIMULATED) && home_configured;
344 const double origin_latitude = use_home_position ? options.home_latitude : latitude;
345 const double origin_longitude = use_home_position ? options.home_longitude : longitude;
346 const double radians = 0.017453292519943295, earth = 6378137;
347 const double scale = cos(origin_latitude * radians);
348 const struct loom_return_point position = use_home_position ? (struct loom_return_point){
349 earth * scale * remainder(longitude - origin_longitude, 360) * radians,
350 earth * (latitude - origin_latitude) * radians
351 } : (struct loom_return_point){0, 0};
352 if (options.frame == LOOM_RETURN_SIMULATED) {
353 uint64_t seed = UINT64_C(1469598103934665603) ^ frame->sequence;
354 for (size_t index = 0; index < record.size; ++index)
355 seed = (seed ^ record.data[index]) * UINT64_C(1099511628211);
356 loom_return_simulated_vector(seed, position, yaw, vector);
357 }
358 struct loom_return_point direction, target;
359 if (!loom_return_vector_attitude(options.frame, vector[0], vector[1], roll, pitch, yaw,
360 options.limits.maximum_tilt_deg, &direction) ||
361 !loom_return_direction(&options.limits, position, direction, vector[2], &target)) return false;
362 const double target_latitude = origin_latitude + target.north / earth / radians;
363 const double target_longitude = remainder(origin_longitude + target.east / (earth * scale) / radians, 360);
364 if (!isfinite(target_latitude) || !isfinite(target_longitude) ||
365 fabs(target_latitude) > 85 || fabs(target_longitude) > 180 ||
366 (!llround(target_latitude * 1e7) && !llround(target_longitude * 1e7))) return false;
367 const double step_m = hypot(target.east - position.east, target.north - position.north);
368 const bool arrived = step_m <= options.limits.maximum_step_m;
369 *point = (struct camera_point_result){.session_id = frame->sequence, .valid = true,
370 .lat = (int32_t)llround(target_latitude * 1e7), .lon = (int32_t)llround(target_longitude * 1e7),
371 .alt_mm = (int32_t)llround(altitude * 1000), .agl_mm = (int32_t)llround(agl * 1000),
372 .quality = (int32_t)llround(vector[2] * 1000),
373 .metric = arrived ? LOOM_METRIC_ARRIVED
374 : (use_home_position ? LOOM_METRIC_STEERING : LOOM_METRIC_BARO_MAGNETO)};
375 return true;
376}
377
378/**
379 * @brief Parse a nonzero correlation sequence without truncation or signed input.
380 * @param text Entire decimal token; no whitespace, sign or suffix is accepted.
381 * @param[out] sequence Destination, written only on successful validation.
382 * @return True for a positive uint32_t photo number; false otherwise.
383 */
384static bool parse_sequence(const char *text, uint32_t *sequence)
385{
386 if (!text || *text < '0' || *text > '9') return false;
387 char *end = NULL;
388 errno = 0;
389 const unsigned long value = strtoul(text, &end, LOOM_DECIMAL_RADIX);
390 if (errno || *end || !value || value > UINT32_MAX) return false;
391 *sequence = (uint32_t)value;
392 return true;
393}
394
395/** @brief Reuse common path/INI policy without opening a model or camera. */
396static bool return_settings(const char *path, struct inference_settings *settings,
398{
399 if (path && !strcmp(path, "-")) path = NULL;
400 char discovered[INFERENCE_PATH_CAPACITY], error[2048];
403 if (!path) {
404 if (!inference_settings_find("loomcam", "loom_cam", discovered, sizeof(discovered))) return true;
405 path = discovered;
406 }
407 if (inference_settings_read(settings, path, loom_return_setting, options, error, sizeof(error))) {
408 if (loom_return_options_valid(options)) return true;
409 fprintf(stderr, "loomcam: inconsistent return limits\n");
410 return false;
411 }
412 fprintf(stderr, "loomcam: %s\n", error);
413 return false;
414}
415
416/** @brief Describe whether PC imagery can run a selected ONNX graph. */
417static int simulation_mode(int argc, char **argv)
418{
419 const char *path = NULL;
420 bool strict = false;
421 for (int index = 2; index < argc; ++index) {
422 if (!strcmp(argv[index], "--strict") && !strict) strict = true;
423 else if (!strcmp(argv[index], "--settings") && !path && ++index < argc) path = argv[index];
424 else return 2;
425 }
426 struct inference_settings settings;
428 if (!return_settings(path, &settings, &options)) return 1;
429 if (strict && (settings.backend != INFERENCE_ONNX || !settings.model[0] ||
432 fprintf(stderr, "loomcam: strict return requires an ONNX model and a declared return_vector_frame\n");
433 return 1;
434 }
435 if (!settings.model[0] || settings.backend == INFERENCE_IMX500) {
436 puts(settings.model[0] ? "RANDOM rpk_requires_ai_camera" : "RANDOM model_not_set");
437 return 0;
438 }
439 if (settings.backend != INFERENCE_ONNX) return 1;
440 struct stat status;
441 if (stat(settings.model, &status)) {
442 if (!strict && (errno == ENOENT || errno == ENOTDIR)) { puts("RANDOM onnx_model_missing"); return 0; }
443 fprintf(stderr, "loomcam: cannot access ONNX model: %s\n", strerror(errno));
444 return 1;
445 }
446 if (!S_ISREG(status.st_mode) || access(settings.model, R_OK)) return 1;
447 puts("ONNX");
448 return 0;
449}
450
451/** @brief Split one bounded ASCII command, rejecting binary/trailing/oversized input. */
452static int return_line(char *line, size_t capacity, unsigned timeout_ms)
453{
454 struct timespec started;
455 if (timeout_ms && clock_gettime(CLOCK_MONOTONIC, &started)) return -1;
456 size_t length = 0;
457 for (;;) {
458 if (timeout_ms) {
459 struct timespec now;
460 if (clock_gettime(CLOCK_MONOTONIC, &now)) return -1;
461 const int64_t elapsed = (int64_t)(now.tv_sec - started.tv_sec) * 1000 +
462 (now.tv_nsec - started.tv_nsec) / 1000000;
463 if (elapsed < 0 || elapsed >= timeout_ms) return -1;
464 struct pollfd input = {.fd = STDIN_FILENO, .events = POLLIN};
465 const int ready = poll(&input, 1, (int)(timeout_ms - elapsed));
466 if (ready < 0 && errno == EINTR) continue;
467 if (ready <= 0) return -1;
468 }
469 const int character = fgetc(stdin);
470 if (character == EOF) return length ? -1 : 0;
471 if (character == '\n') { line[length] = '\0'; return length ? 1 : -1; }
472 if (character < 32 || character >= 127 || length + 1 >= capacity) return -1;
473 line[length++] = (char)character;
474 }
475}
476
477/** @brief Keep bounded T1 state separate from the waypoint transport transaction. */
478static int return_server(int argc, char **argv)
479{
480 const char *path = NULL;
481 bool simulation = false;
482 uint32_t seed = 19;
483 for (int index = 2; index < argc; ++index) {
484 if (!strcmp(argv[index], "--simulation") && !simulation) simulation = true;
485 else if (!strcmp(argv[index], "--settings") && !path && ++index < argc) path = argv[index];
486 else if (!strcmp(argv[index], "--seed") && ++index < argc && parse_sequence(argv[index], &seed)) {}
487 else return 2;
488 }
489 struct inference_settings settings;
491 if (!return_settings(path, &settings, &options)) return 1;
492 struct loom_return_state state = {.random_state = seed};
493 uint32_t previous = 0;
494 if (setvbuf(stdin, NULL, _IONBF, 0)) return 1;
495 puts("READY LOOM_RETURN_V1");
496 if (fflush(stdout)) return 1;
497 char line[256];
498 int line_status;
499 while ((line_status = return_line(line, sizeof(line), 0)) > 0) {
500 char *fields[10];
501 unsigned count = 1;
502 fields[0] = line;
503 for (char *cursor = line; *cursor; ++cursor) {
504 if (*cursor != ' ') continue;
505 *cursor = '\0';
506 if (count == 10 || !cursor[1] || cursor[1] == ' ') return 2;
507 fields[count++] = cursor + 1;
508 }
509 uint32_t sequence;
510 if (count < 2 || !parse_sequence(fields[1], &sequence) || sequence <= previous) return 2;
511 previous = sequence;
512 const bool simulated_request = !strcmp(fields[0], "SIM");
513 const bool mocked_observation = !strcmp(fields[0], "SIMOBS");
514 const bool model_observation = !strcmp(fields[0], "OBS");
515 if ((!simulated_request && !mocked_observation && !model_observation) ||
516 (model_observation && count != 8 && count != 10) || (mocked_observation && (!simulation || count != 7)) ||
517 (simulated_request && (count != 2 || !simulation))) return 2;
518 double values[8] = {0};
519 if (model_observation || mocked_observation) {
520 const unsigned value_count = model_observation ? count - 2 : 5;
521 for (unsigned index = 0; index < value_count; ++index)
522 if (!ini_real(fields[index + 2], &values[index])) return 2;
523 }
524 struct loom_return_state proposed = state;
525 struct loom_return_point target, direction;
526 bool accepted_vector = false;
527 if (model_observation) {
528 accepted_vector = loom_return_vector_attitude(options.frame, values[2], values[3],
529 values[6], values[7], values[5],
530 options.limits.maximum_tilt_deg, &direction) &&
531 loom_return_direction(&options.limits, (struct loom_return_point){values[0], values[1]},
532 direction, values[4], &target);
533 } else if (mocked_observation) {
534 direction = (struct loom_return_point){values[2], values[3]};
535 accepted_vector = loom_return_direction(&options.limits,
536 (struct loom_return_point){values[0], values[1]}, direction, values[4], &target);
537 }
538 accepted_vector = accepted_vector &&
539 loom_return_update(&proposed, &options.limits, sequence, target, &target);
540 const bool simulated_fallback = !accepted_vector && !mocked_observation && simulation &&
541 loom_return_simulate(&proposed, &options.limits, sequence, &target);
542 if (!accepted_vector && !simulated_fallback) {
543 printf("SKIP %" PRIu32 " invalid_direction\n", sequence);
544 if (fflush(stdout)) return 1;
545 continue;
546 }
547 printf("MOVE %" PRIu32 " %.9f %.9f %s\n", sequence, target.east, target.north,
548 accepted_vector ? (mocked_observation ? "simulated" : "neural") : "simulated");
549 if (fflush(stdout)) return 1;
550 char expected[64];
551 snprintf(expected, sizeof(expected), "ACK %" PRIu32, sequence);
552 if (return_line(line, sizeof(line), LOOM_CONFIRMATION_TIMEOUT_MS) != 1) return 1;
553 if (!strcmp(line, expected)) {
554 state = proposed;
555 printf("OK %" PRIu32 "\n", sequence);
556 } else printf("SKIP %" PRIu32 " unconfirmed\n", sequence);
557 if (fflush(stdout)) return 1;
558 }
559 return line_status < 0 || ferror(stdin) ? 2 : 0;
560}
561
562/**
563 * @brief Hardware-free check that the empty matcher cannot manufacture a waypoint.
564 * @return EXIT_SUCCESS when clearing, correlation and invalid-ID rejection hold.
565 * @note The image is not opened here; this tests the stub contract, not capture.
566 */
567static int self_test(void)
568{
569 const struct loom_frame frame = {.image = "fixture.jpg", .sequence = LOOM_SELF_TEST_SEQUENCE};
570 struct camera_point_result point = {.valid = true, .lat = LOOM_SELF_TEST_LATITUDE};
571 uint32_t sequence = 0;
572 if (match_previous_photos(&frame, &point) || point.valid || point.lat
573 || point.session_id != frame.sequence || !parse_sequence("1", &sequence)
574 || parse_sequence("0", &sequence) || parse_sequence("-1", &sequence)
575 || parse_sequence(LOOM_SELF_TEST_SEQUENCE_OVERFLOW, &sequence)) return EXIT_FAILURE;
576 puts("LOOM return: absent vector evidence and sequence validation passed");
577 return EXIT_SUCCESS;
578}
579
580/**
581 * @brief Parse one saved-photo request and emit exactly one correlated result line.
582 * @param argc Number of program-name and option/value arguments.
583 * @param argv Borrowed command-line tokens; paths are passed without a shell.
584 * @return EXIT_SUCCESS for a processed photo, including no-match; EXIT_FAILURE
585 * for invalid input or output failure. Diagnostics use stderr, results stdout.
586 * @details The embedded entry point shares the C++ capture executable but does
587 * not acquire the sensor. A syntactically successful reply is not a valid match.
588 */
589#ifdef LOOMCAM_EMBEDDED
590 int loomcam_photo_main(int argc, char **argv)
591#else
592 int main(int argc, char **argv)
593#endif
594{
595 if (argc > 1 && !strcmp(argv[1], "--return-server")) return return_server(argc, argv);
596 if (argc > 1 && !strcmp(argv[1], "--simulation-mode")) return simulation_mode(argc, argv);
597 struct loom_frame frame = {0};
598 for (int index = LOOM_FIRST_OPTION_INDEX; index < argc; ++index) {
599 if (strcmp(argv[index], "--self-test") == 0 && argc == LOOM_SINGLE_OPTION_ARGC) return self_test();
600 if (strcmp(argv[index], "--help") == 0 && argc == LOOM_SINGLE_OPTION_ARGC) {
601 puts("Usage: loomcam --image FILE --sequence N [--reference-dir DIR] [--model FILE]\n"
602 "Uses this photo's retained ONNX/RPK vector when configured; outbound references are not compared.");
603 return EXIT_SUCCESS;
604 }
605 const char *option = argv[index];
606 if (++index >= argc) return EXIT_FAILURE;
607 const char *value = argv[index];
608 if (strcmp(option, "--image") == 0) frame.image = value;
609 else if (strcmp(option, "--settings") == 0) frame.settings = value;
610 else if (strcmp(option, "--reference-dir") == 0) frame.references = value;
611 else if (strcmp(option, "--model") == 0) frame.model = value;
612 else if (strcmp(option, "--sequence") == 0) {
613 if (!parse_sequence(value, &frame.sequence)) return EXIT_FAILURE;
614 } else return EXIT_FAILURE;
615 }
616 struct stat status;
617 /* Require one readable saved photo; output identity and capture alignment are
618 * separately validated before a retained vector can authorize a point. */
619 if (!frame.image || !frame.sequence || stat(frame.image, &status) != 0
620 || !S_ISREG(status.st_mode) || access(frame.image, R_OK) != 0) {
621 fprintf(stderr, "loomcam: a readable photo and nonzero sequence are required\n");
622 return EXIT_FAILURE;
623 }
625 /* Processing success and match validity are different outcomes. Echo the
626 * requested photo number even on no-match so the parent can reject stale replies. */
628 printf("LOOM_POINT_V1 sequence=%" PRIu32 " valid=%d lat=%" PRId32 " lon=%" PRId32
629 " alt_mm=%" PRId32 " agl_mm=%" PRId32 " quality=%" PRId32 " metric=%" PRId32 "\n",
630 point.session_id, point.valid, point.lat, point.lon, point.alt_mm,
631 point.agl_mm, point.quality, point.metric);
632 return ferror(stdout) ? EXIT_FAILURE : EXIT_SUCCESS;
633}
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_real(const char *text, double *number)
Parse finite decimal/exponent notation, rejecting range errors and suffixes.
Definition bounded_ini.h:67
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
Shared capability and lifecycle contract for USHER camera backends.
static unsigned capacity[COVERAGE_CAMERAS]
static double latitude
static double longitude
size_t size
Definition chdk_pipe.c:143
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
int descriptor
Definition chdk_pipe.c:142
static int record(const union dc_shot_union *shot)
Retrieve a point and admit a new observation only when its credit is free.
static bool started
static bool ready
Bounded C11 EXIF metadata and JPEG streaming interfaces.
int exif_parse(struct exif_view *view, const unsigned char *payload, size_t size)
Validate an EXIF APP1 payload and create a borrowed view.
Definition exifite.c:257
bool exif_get(const struct exif_view *view, enum exif_directory directory, uint16_t tag, struct exif_value *value)
Look up a directory-local tag without copying its bytes.
Definition exifite.c:310
int exif_read_jpeg(const char *filename, unsigned char *payload, size_t capacity, size_t *size)
Read the single EXIF APP1 segment before the first JPEG scan.
Definition exifite.c:1022
#define EXIF_MAX_PAYLOAD
APP1 payload ceiling: the JPEG length includes its own two bytes.
Definition exifite.h:51
@ EXIF_ASCII
Definition exifite.h:66
@ EXIF_CAMERA
Definition exifite.h:59
@ EXIF_PRIMARY
Definition exifite.h:59
@ EXIF_IMAGE_DESCRIPTION
Definition exifite.h:80
Shared IMX500 tensor-info wire layout and bounded decoding policy.
#define IMX500_TENSOR_INFO_BYTES
Full accessible metadata required before following record offsets.
bool inference_jpeg_prepare(struct inference_context *context, const char *filename, char *error, size_t capacity)
Stream a JPEG into an open context's single declared image input.
Bounded JPEG-to-tensor preparation without running the graph or modifying the input file.
bool inference_context_run(struct inference_context *context, char *error, size_t capacity)
Run the currently prepared tensors using the context's timeout policy.
bool inference_context_open(struct inference_context *context, const struct inference_settings *settings, const char *adapter, char *error, size_t capacity)
Verify a bundle, map bounded tensors and bind one warm session.
void inference_context_close(struct inference_context *context)
Release the session before unmapping its borrowed tensor storage.
bool inference_model_parse(struct inference_model *model, char *contents, size_t length, char *error, size_t capacity)
Parse a descriptor, not graph bytes; graph integrity remains a separate read-time check.
Integrity-checked model contracts and independently owned tensor workspaces.
bool inference_settings_find(const char *application, const char *module, char *filename, size_t capacity)
Discover application_settings.ini in adjacent, development-module, then installed-share order.
bool inference_settings_read(struct inference_settings *settings, const char *filename, ini_field_handler extra, void *context, char *error, size_t capacity)
Parse one flat INI, delegate application keys and resolve paths against the selected file.
void inference_settings_init(struct inference_settings *settings, enum inference_backend backend)
Reset storage and select conservative thread/timeout defaults.
Shared application_settings.ini discovery with module-owned extra keys.
#define INFERENCE_PATH_CAPACITY
@ INFERENCE_AUTO
@ INFERENCE_ONNX
@ INFERENCE_IMX500
int loomcam_photo_main(int argc, char **argv)
Dispatch the saved-photo CLI through its C linkage boundary.
bool loom_features_unpack(const unsigned char *record, size_t size, float *values, size_t capacity, uint8_t *information, size_t information_size, size_t *count, uint64_t *sequence, uint64_t *sensor_timestamp_ns)
Validate and decode an exact-sized binary record into bounded output.
LOOM-owned bounded feature validation and evidence serialization.
#define LOOM_ONNX_FEATURE_CAPACITY
#define LOOM_FEATURES_TAG
LOOM-owned camera-directory tag; its value is a LOOMNN02 opaque record.
bool loom_onnx_features_valid(const unsigned char *record, size_t size, const char *model_sha256, const char *descriptor_sha256)
Validate the exact binary layout and optionally require the same trained feature space.
size_t loom_onnx_features_pack(unsigned char *record, size_t capacity, const struct inference_model *model, uint64_t sequence, uint64_t sensor_timestamp_ns)
Encode a complete LOOMOX01 record without fabricating an IMX500 metadata header.
#define LOOM_ONNX_FEATURES_TAG
bool loom_onnx_return_vector(const unsigned char *record, size_t size, const char *model_sha256, const char *descriptor_sha256, float values[3])
Decode an explicitly declared two/three-value return-vector record.
void loom_return_options_init(struct loom_return_options *options)
Initialize return limits with feature-only semantics by default.
Definition loom_return.c:40
bool loom_return_options_valid(const struct loom_return_options *options)
Check that optional destination coordinates are either both present or both omitted.
Definition loom_return.c:47
bool loom_return_vector_attitude(enum loom_return_frame frame, double first, double second, double roll_deg, double pitch_deg, double yaw_deg, double max_tilt_deg, struct loom_return_point *direction)
Convert a declared two-component vector to earth-frame east/north with attitude gating.
Definition loom_return.c:86
bool loom_return_update(struct loom_return_state *state, const struct loom_return_config *config, uint32_t sequence, struct loom_return_point candidate, struct loom_return_point *target)
Admit a fresh bounded target and limit its movement.
bool loom_return_setting(void *context, const char *key, const char *value)
Parse one LOOM-owned settings field, rejecting duplicates and unknown keys.
Definition loom_return.c:55
bool loom_return_simulate(struct loom_return_state *state, const struct loom_return_config *config, uint32_t sequence, struct loom_return_point *target)
Produce small mean-reverting target fluctuations for explicit PC simulation.
bool loom_return_direction(const struct loom_return_config *config, struct loom_return_point position, struct loom_return_point direction, double confidence, struct loom_return_point *target)
Convert an earth-frame direction into a HOME-bounded target.
Bounded direction-to-target policy, independent of inference and FC transport.
@ LOOM_METRIC_BARO_MAGNETO
Definition loom_return.h:38
@ LOOM_METRIC_ARRIVED
Definition loom_return.h:37
@ LOOM_METRIC_STEERING
Definition loom_return.h:36
@ LOOM_RETURN_NONE
Definition loom_return.h:58
@ LOOM_RETURN_BODY_FORWARD_RIGHT
Definition loom_return.h:60
@ LOOM_RETURN_NORTH_EAST
Definition loom_return.h:59
@ LOOM_RETURN_SIMULATED
Definition loom_return.h:61
static int simulation_mode(int argc, char **argv)
Describe whether PC imagery can run a selected ONNX graph.
Definition loomcam.c:417
static bool description_number(const struct exif_value *description, const char *key, double *number)
Read a required finite numeric metadata field.
Definition loomcam.c:122
#define LOOM_SELF_TEST_SEQUENCE
Nonzero fixtures deliberately expose failure to clear previous state.
Definition loomcam.c:51
static int return_line(char *line, size_t capacity, unsigned timeout_ms)
Split one bounded ASCII command, rejecting binary/trailing/oversized input.
Definition loomcam.c:452
int main(int argc, char **argv)
Parse one saved-photo request and emit exactly one correlated result line.
Definition loomcam.c:592
#define LOOM_SELF_TEST_SEQUENCE_OVERFLOW
First integer outside the accepted uint32_t correlation range.
Definition loomcam.c:55
static bool match_previous_photos(const struct loom_frame *frame, struct camera_point_result *point)
Interpret retained same-photo neural vectors under the declared return contract.
Definition loomcam.c:240
static bool run_onnx_in_memory(const struct inference_settings *settings, const struct loom_return_options *options, const char *image, uint64_t sequence, uint64_t timestamp_ns, unsigned char *record, size_t capacity, size_t *record_size)
Generate bounded LOOM feature evidence for an existing JPEG.
Definition loomcam.c:200
#define LOOM_SELF_TEST_LATITUDE
Nonzero latitude fixture checks that no-match clears stale evidence.
Definition loomcam.c:53
static int return_server(int argc, char **argv)
Keep bounded T1 state separate from the waypoint transport transaction.
Definition loomcam.c:478
static bool read_onnx_descriptor_identity(const struct inference_settings *settings, char graph[65], char descriptor[65])
Read the graph and descriptor identities declared by the model metadata.
Definition loomcam.c:155
#define LOOM_DECIMAL_RADIX
The CLI accepts decimal photo numbers, never signed or truncated IDs.
Definition loomcam.c:46
static uint64_t feature_u64(const unsigned char *bytes)
Decode an unsigned field from LOOM's little-endian record.
Definition loomcam.c:180
loom_cli_layout
argv[0] is the program name; a sole flag gives two total arguments.
Definition loomcam.c:48
@ LOOM_FIRST_OPTION_INDEX
Definition loomcam.c:48
@ LOOM_SINGLE_OPTION_ARGC
Definition loomcam.c:48
static int self_test(void)
Hardware-free check that the empty matcher cannot manufacture a waypoint.
Definition loomcam.c:567
static bool parse_sequence(const char *text, uint32_t *sequence)
Parse a nonzero correlation sequence without truncation or signed input.
Definition loomcam.c:384
static bool description_field(const struct exif_value *description, const char *key, char value[64])
Require a uniquely identified flight-description value.
Definition loomcam.c:110
static bool description_optional_number(const struct exif_value *description, const char *key, double default_value, double *number)
Read numeric metadata with a default for absence only.
Definition loomcam.c:135
static bool description_lookup(const struct exif_value *description, const char *key, char value[64], bool *found)
Read one bounded observation field from an already-fetched EXIF description.
Definition loomcam.c:75
static bool return_settings(const char *path, struct inference_settings *settings, struct loom_return_options *options)
Reuse common path/INI policy without opening a model or camera.
Definition loomcam.c:396
@ LOOM_CONFIRMATION_TIMEOUT_MS
Definition loomcam.c:49
struct jpeg_error_mgr error
Definition lwir_image.c:60
uint8_t frame[LWIR_MAX_FRAME_BYTES]
Definition lwir_mock.c:58
@ ONNX_FLOAT32
static size_t count
Definition pose_log.c:79
Borrowed bytes plus enough type information for safe interpretation.
Definition exifite.h:119
const unsigned char * data
Definition exifite.h:120
size_t size
Definition exifite.h:121
uint16_t format
Definition exifite.h:123
Borrowed view of a validated APP1 payload.
Definition exifite.h:131
Independent, noncopyable model owner; mapped tensor buffers and session are reused between jobs.
struct inference_model model
Parsed descriptor with self-referencing tensor-name pointers; do not copy after parsing.
struct inference_image_spec image
char descriptor_sha256[65]
struct onnx_tensor outputs[ONNX_TENSOR_LIMIT]
Per-application configuration; all resolved paths belong to this caller-owned value.
enum inference_backend backend
char model[INFERENCE_PATH_CAPACITY]
char descriptor[INFERENCE_PATH_CAPACITY]
Borrowed per-invocation input; no member owns or acquires a camera.
Definition loomcam.c:63
uint32_t sequence
Definition loomcam.c:68
const char * settings
Definition loomcam.c:67
const char * references
Definition loomcam.c:65
const char * image
Definition loomcam.c:64
const char * model
Definition loomcam.c:66
Module-owned inference settings, separate from universal runtime settings.
Definition loom_return.h:65
Local ground point in metres east/north of the reference origin.
Definition loom_return.h:31
Caller-owned sequence and smoothing state; first observation seeds target.
Definition loom_return.h:51
Named concrete tensor view; its aligned backing storage must outlive the session.
enum onnx_element_type type
Validated capture and reporting policy, fixed before the sample loop.
Definition earcam.c:137
One timestamped geographic position for a replay annotation.
struct captured_image image
Definition usher.c:371