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
loom_capture.cpp
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 loom_capture.cpp
19 * @brief LOOM executable entry point and neural-feature capture policy.
20 * @details Shared IMX500 mechanics know nothing about feature interpretation or
21 * waypoint selection. This application never calls the object-box decoder. */
22#include "../../src/version.h"
25#include "loom_features.h"
26#include "loom_return.h"
27
28#include <cstdio>
29#include <cstring>
30#include <cmath>
31#include <unistd.h>
32#include <cerrno>
33#include <sys/stat.h>
34
35#ifndef SENSORAIA_INFERENCE_ONLY
38#endif
39
40/** @brief Dispatch the saved-photo CLI through its C linkage boundary.
41 * @param argc Argument count including the command name.
42 * @param argv Arguments for the saved-photo path.
43 * @return CLI exit status; successful processing may report no match.
44 * @details This entry does not acquire a sensor. Keep the saved-photo CLI
45 * separate from the native capture worker. */
46extern "C" int loomcam_photo_main(int argc, char **argv);
47
48namespace {
49
50/** @brief Establish finite-storage feature transport limits without claiming a trained visual match. */
51bool validate_onnx_features(void *configuration, const inference_context *context, char *error, size_t capacity)
52{
53 const auto &options = *static_cast<const loom_return_options *>(configuration);
55 std::snprintf(error, capacity, "Inconsistent LOOM return limits");
56 return false;
57 }
58 if (context->model.input_count != 1 || !context->model.image.channels) {
59 std::snprintf(error, capacity, "LOOM requires one declared image input");
60 return false;
61 }
62 size_t values = 0;
63 for (size_t index = 0; index < context->model.output_count; ++index) {
64 const auto &tensor = context->model.outputs[index];
65 if (tensor.type != ONNX_FLOAT32 || tensor.bytes / sizeof(float) > 4096 - values) {
66 std::snprintf(error, capacity, "LOOM requires bounded float32 feature outputs");
67 return false;
68 }
69 values += tensor.bytes / sizeof(float);
70 }
71 if (options.frame != LOOM_RETURN_NONE && options.frame != LOOM_RETURN_SIMULATED &&
72 (context->model.output_count != 1 || (values != 2 && values != 3))) {
73 std::snprintf(error, capacity, "Declared LOOM return vectors require one float32 output with two or three values");
74 return false;
75 }
76 return true;
77}
78
79/** @brief Embed only in an exclusively owned private JPEG so published or hard-linked references stay immutable. */
80bool embed_onnx_features(const inference_context *context, const char *image, uint32_t sequence)
81{
82 /* The worker serializes callbacks; reusable bounded EXIF storage avoids a large per-request stack frame. */
83 static exif_document document;
84 static unsigned char payload[EXIF_MAX_PAYLOAD], record[LOOM_ONNX_FEATURE_CAPACITY];
85 const size_t record_size = loom_onnx_features_pack(record, sizeof(record), &context->model,
86 context->capture_identity ? context->frame_sequence : sequence, context->sensor_timestamp_ns);
87 if (!record_size) return false;
88 exif_document_init(&document);
89 size_t payload_size = 0;
90 if (exif_read_jpeg(image, payload, sizeof(payload), &payload_size) == 0) {
91 exif_view view;
92 if (exif_parse(&view, payload, payload_size) || image_exif_import(&document, &view)) return false;
93 } else if (errno != ENODATA) return false;
94 unsigned char *destination = exif_document_reserve(&document, EXIF_CAMERA, LOOM_ONNX_FEATURES_TAG,
95 EXIF_UNDEFINED, static_cast<uint32_t>(record_size));
96 if (!destination) return false;
97 for (size_t index = 0; index < record_size; ++index) destination[index] = record[index];
98 if (exif_serialize(&document, payload, sizeof(payload), &payload_size)) return false;
99 FILE *output = std::fopen(image, "r+b");
100 if (!output) return false;
101 struct stat info{};
102 bool valid = !fstat(fileno(output), &info) && S_ISREG(info.st_mode) && info.st_nlink == 1 &&
103 exif_update_jpeg(output, payload, payload_size) == 0 && !std::fflush(output) && !fsync(fileno(output));
104 if (std::fclose(output)) valid = false;
105 return valid;
106}
107
108/** @brief Retain exact model/preprocessing identity with features; ordinary offline analysis never mutates its input. */
109bool write_onnx_features(void *configuration, const inference_context *context,
110 const char *image, uint32_t sequence, char *error, size_t capacity)
111{
112 const auto &options = *static_cast<const loom_return_options *>(configuration);
113 const auto &model = context->model;
114 size_t total = 0;
115 for (size_t slot = 0; slot < model.output_count; ++slot) {
116 if (model.outputs[slot].type != ONNX_FLOAT32 || model.outputs[slot].bytes / sizeof(float) > 4096 - total) {
117 std::snprintf(error, capacity, "LOOM features require at most 4096 float32 output values");
118 return false;
119 }
120 total += model.outputs[slot].bytes / sizeof(float);
121 const auto *values = static_cast<const float *>(model.outputs[slot].data);
122 for (size_t index = 0; index < model.outputs[slot].bytes / sizeof(float); ++index)
123 if (!std::isfinite(values[index])) { std::snprintf(error, capacity, "Nonfinite LOOM feature"); return false; }
124 }
125 if (context->private_image && !embed_onnx_features(context, image, sequence)) {
126 std::snprintf(error, capacity, "Cannot embed model-identified LOOM feature evidence");
127 return false;
128 }
129 char filename[INFERENCE_PATH_CAPACITY], digest[65];
130 const size_t length = std::strlen(image);
131 if (length < 4 || std::strcmp(image + length - 4, ".jpg") || !inference_file_sha256(image, digest)) return false;
132 const int count = std::snprintf(filename, sizeof(filename), "%.*s.loom.ini", static_cast<int>(length - 4), image);
133 if (count < 0 || static_cast<size_t>(count) >= sizeof(filename)) return false;
134 FILE *output = std::fopen(filename, "wx");
135 if (!output) { std::snprintf(error, capacity, "Cannot exclusively create LOOM features: %s", filename); return false; }
136 std::fprintf(output, "schema=LOOM_ONNX_FEATURES_V1\nsequence=%u\nimage_sha256=%s\n"
137 "model_sha256=%s\nmodel_descriptor_sha256=%s\noutput_count=%zu\n",
138 sequence, digest, model.graph_sha256, model.descriptor_sha256, model.output_count);
140 const auto *values = static_cast<const float *>(model.outputs[0].data);
141 std::fprintf(output, "return_vector_frame=%s\nreturn_first=%.9g\nreturn_second=%.9g\nreturn_confidence=%.9g\n",
142 options.frame == LOOM_RETURN_NORTH_EAST ? "north_east" : "body_forward_right",
143 static_cast<double>(values[0]), static_cast<double>(values[1]),
144 model.outputs[0].bytes == 3 * sizeof(float) ? static_cast<double>(values[2]) : 1.0);
145 } else if (options.frame == LOOM_RETURN_SIMULATED) {
146 std::fprintf(output, "return_vector_frame=simulated\n");
147 }
148 for (size_t slot = 0; slot < model.output_count; ++slot) {
149 const auto &tensor = model.outputs[slot];
150 std::fprintf(output, "output.%zu.name=%s\noutput.%zu.shape=", slot, tensor.name, slot);
151 for (size_t axis = 0; axis < tensor.rank; ++axis)
152 std::fprintf(output, "%s%lld", axis ? "," : "", static_cast<long long>(tensor.dimensions[axis]));
153 std::fprintf(output, "\noutput.%zu.values=", slot);
154 const auto *values = static_cast<const float *>(tensor.data);
155 for (size_t index = 0; index < tensor.bytes / sizeof(float); ++index)
156 std::fprintf(output, "%s%.9g", index ? "," : "", static_cast<double>(values[index]));
157 std::fputc('\n', output);
158 }
159 bool written = !std::ferror(output) && std::fflush(output) == 0 && fsync(fileno(output)) == 0;
160 if (std::fclose(output)) written = false;
161 if (!written) { unlink(filename); std::snprintf(error, capacity, "Cannot publish LOOM features"); }
162 return written;
163}
164
165#ifndef SENSORAIA_INFERENCE_ONLY
166
167/** @brief Qualify feature transport without interpreting it as a return direction.
168 * @param frame Borrowed same-exposure neural values and shape metadata.
169 * @return True for a bounded finite tensor contract, not a navigable match. */
170bool features_ready(const imx500::FrameView &frame)
171{
172 return loom_features_valid(frame.tensor.data(), frame.tensor.size(),
173 frame.tensor_info.data(), frame.tensor_info.size());
174}
175
176/** @brief Serialize only this retained exposure's feature evidence.
177 * @param frame Immutable view whose lease remains alive during serialization.
178 * @param filename Exclusive-create analysis path supplied by the publication owner.
179 * @return True when the core publishes complete feature evidence.
180 * @details Keep camera request identity separate from the FC photo number;
181 * downstream code must establish their association rather than guessing it. */
182bool write_features(const imx500::FrameView &frame, exif_document *document)
183{
184 if (!features_ready(frame)) return true;
185 const size_t size = loom_features_size(frame.tensor.size());
187 static_cast<uint32_t>(size));
188 return record && loom_features_pack(record, size, frame.tensor.data(), frame.tensor.size(),
189 frame.tensor_info.data(), frame.tensor_info.size(),
190 frame.sequence, frame.sensor_timestamp_ns);
191}
192#endif
193
194} // namespace
195
196/** @brief Dispatch saved-photo processing without opening a second camera owner.
197 * @param argc Command-line token count.
198 * @param argv Saved-photo or neutral capture-worker mode arguments.
199 * @return Zero for success, two for syntax errors, one for capture runtime failure.
200 * @details Capture retains features; saved-photo mode validates declared return
201 * vectors and observation identity. Generic tensors are not navigation evidence. */
202int main(int argc, char **argv)
203{
204 if (argc == 2 && !std::strcmp(argv[1], "--help")) {
205 std::puts(LOOMCAM_BUILD_VERSION);
206 std::puts("Usage: loomcam --analyze FILE.jpg | --analyze-server | --check-model [--settings FILE]\n"
207 " loomcam --capture --settings FILE /absolute/photo.jpg\n"
208 " loomcam --serve --settings FILE WIDTH HEIGHT\n"
209 " loomcam --image FILE --sequence N [--reference-dir DIR]\n"
210 " loomcam --return-server [--settings FILE] [--simulation] [--seed N]\n"
211 " loomcam --simulation-mode [--settings FILE] [--strict]\n"
212 " loomcam --self-test | --version\n"
213 "Feature-only is the default; declared return vectors use guarded T1 policy.\n"
214 "Strict model selection rejects unavailable/feature-only assignments.\n"
215 "Return-server skips rejected vectors unless --simulation is explicit; ACK budget is 4 seconds.");
216 return 0;
217 }
220 const inference_image_processor onnx_processor{"loomcam", "loom_cam", "loom_features_v1",
221 loom_return_setting, &options, write_onnx_features, validate_onnx_features, ".loom.ini"};
222 const int analyzed = inference_worker_cli(argc, argv, &onnx_processor);
223 if (analyzed >= 0) return analyzed;
224 if (argc > 1 && (std::strcmp(argv[1], "--image") == 0
225 || std::strcmp(argv[1], "--return-server") == 0
226 || std::strcmp(argv[1], "--simulation-mode") == 0
227 || std::strcmp(argv[1], "--self-test") == 0
228 || std::strcmp(argv[1], "--help") == 0)) {
229 return loomcam_photo_main(argc, argv);
230 }
231 if (argc == 2 && std::strcmp(argv[1], "--version") == 0) {
232 std::puts(LOOMCAM_BUILD_VERSION);
233 return 0;
234 }
235#ifdef SENSORAIA_INFERENCE_ONLY
236 std::fprintf(stderr, "Usage: loomcam --analyze FILE.jpg | --analyze-server | --check-model [--settings FILE]\n");
237 return 2;
238#else
239 const imx500::FrameProcessor processor{nullptr, features_ready, nullptr, write_features};
240 const int configured = inference_capture_cli(argc, argv, onnx_processor, processor);
241 if (configured >= 0) return configured;
242 if (argc < 3 || (std::strcmp(argv[1], "--probe") != 0
243 && std::strcmp(argv[1], "--serve") != 0
244 && std::strcmp(argv[1], "--capture") != 0)) {
245 std::fprintf(stderr,
246 "Usage: loomcam --probe nn_loom.rpk\n"
247 " loomcam --serve nn_loom.rpk WIDTH HEIGHT\n"
248 " loomcam --capture nn_loom.rpk /absolute/photo.jpg\n"
249 " loomcam --image FILE --sequence N [--reference-dir DIR] [--model FILE]\n"
250 " loomcam --self-test | --version\n");
251 return 2;
252 }
253 return imx500::run_worker(argc, argv, processor, "loomcam");
254#endif
255}
static unsigned capacity[COVERAGE_CAMERAS]
size_t size
Definition chdk_pipe.c:143
static int record(const union dc_shot_union *shot)
Retrieve a point and admit a new observation only when its credit is free.
int exif_serialize(const struct exif_document *document, unsigned char *payload, size_t capacity, size_t *size)
Serialize a document into one complete EXIF APP1 payload.
Definition exifite.c:736
void exif_document_init(struct exif_document *document)
Start a fresh upright sRGB/Y-Cb-Cr document with EXIF 2.32 defaults.
Definition exifite.c:412
unsigned char * exif_document_reserve(struct exif_document *document, enum exif_directory directory, uint16_t tag, enum exif_format format, uint32_t count)
Create or replace a field with zeroed, bounded value storage.
Definition exifite.c:508
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
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
int exif_update_jpeg(FILE *file, const unsigned char *payload, size_t size)
Replace EXIF in a regular JPEG file without a temporary file.
Definition exifite.c:1649
@ EXIF_UNDEFINED
Definition exifite.h:70
@ EXIF_CAMERA
Definition exifite.h:59
Flight, timing, and thermal-analysis metadata writing for captured JPEGs.
static int image_exif_import(struct exif_document *document, const struct exif_view *view)
Import standard metadata plus the application's approved capture evidence.
Definition image_exif.h:58
Neutral IMX500 frame ownership, JPEG publication and worker protocol.
int inference_capture_cli(int argc, char **argv, const inference_image_processor &processor, const imx500::FrameProcessor &sensor_processor)
Dispatch configured RPK/ONNX capture while preserving one physical camera owner.
Settings-driven capture bridge; neutral camera mechanics never interpret neural outputs.
bool inference_file_sha256(const char *filename, char digest[65])
Hash a stable nonempty regular file using bounded streaming scratch.
#define INFERENCE_PATH_CAPACITY
int inference_worker_cli(int argc, char **argv, const struct inference_image_processor *processor)
Dispatch one-shot analysis, model checks or the persistent ANALYZE protocol.
Warm saved-picture processing without acquiring a camera or interpreting CAM results.
int main(int argc, char **argv)
Dispatch saved-photo processing without opening a second camera owner.
int loomcam_photo_main(int argc, char **argv)
Dispatch the saved-photo CLI through its C linkage boundary.
bool loom_features_pack(unsigned char *record, size_t capacity, const float *values, size_t count, const uint8_t *information, size_t information_size, uint64_t sequence, uint64_t sensor_timestamp_ns)
Pack validated same-exposure shapes, exact uint64 identities and float bits.
size_t loom_features_size(size_t count)
Required bytes for 1..4096 floats, or zero for unsupported counts.
bool loom_features_valid(const float *values, size_t count, const uint8_t *information, size_t information_size)
Validate finite features against the shared IMX500 shape metadata.
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.
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
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_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
Bounded direction-to-target policy, independent of inference and FC transport.
@ 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
struct jpeg_error_mgr error
Definition lwir_image.c:60
uint8_t frame[LWIR_MAX_FRAME_BYTES]
Definition lwir_mock.c:58
int run_worker(int argc, char **argv, const FrameProcessor &processor, const char *application)
Run the shared probe/capture/READY-SHOT-OK worker with supplied model policy.
std::string digest(const void *data, size_t size)
Definition pangea.cpp:615
@ ONNX_FLOAT32
static size_t count
Definition pose_log.c:79
static FILE * output
Definition pose_log.c:77
Compile-time build identity strings for USHER executables.
#define LOOMCAM_BUILD_VERSION
Definition version.h:80
Caller-owned bounded writer with no heap allocation.
Definition exifite.h:156
Borrowed view of a validated APP1 payload.
Definition exifite.h:131
Stack-owned model-specific operations; no dynamic plugin allocation.
Borrowed same-exposure evidence, without object or navigation semantics.
Independent, noncopyable model owner; mapped tensor buffers and session are reused between jobs.
uint64_t sensor_timestamp_ns
struct inference_model model
Borrowed module callbacks; the worker serializes calls and retains no per-request pixel pointers.
struct inference_image_spec image
struct onnx_tensor outputs[ONNX_TENSOR_LIMIT]
Module-owned inference settings, separate from universal runtime settings.
Definition loom_return.h:65
Validated capture and reporting policy, fixed before the sample loop.
Definition earcam.c:137
bool valid
Definition usher.c:537
struct captured_image image
Definition usher.c:371