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_features.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/** @file loom_features.h
19 * @brief LOOM-owned bounded feature validation and evidence serialization.
20 * @details Raw immutable buffers keep this core independent of libcamera and
21 * USHER process ownership. Valid feature transport is never navigation evidence. */
22#ifndef LOOM_FEATURES_H
23#define LOOM_FEATURES_H
24
25#include <stdbool.h>
26#include <stddef.h>
27#include <stdint.h>
28
29/** @brief LOOM-owned camera-directory tag; its value is a LOOMNN02 opaque record. */
30#define LOOM_FEATURES_TAG 0xc7a2U
31#define LOOM_ONNX_FEATURES_TAG 0xc7a3U
32#define LOOM_ONNX_FEATURE_CAPACITY 32768U
33
34struct inference_model;
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/** @brief Validate finite features against the shared IMX500 shape metadata.
41 * @param values Borrowed immutable float array for one exposure.
42 * @param count Accessible float count.
43 * @param information Borrowed tensor-info bytes from that same exposure.
44 * @param information_size Accessible metadata bytes.
45 * @return True for bounded, consistent shapes and finite values; false otherwise.
46 * @details Check shape products and cumulative length before reading values;
47 * rank/count limits bound both work and metadata access. No buffer is retained.
48 * @note This does not validate model semantics, feature similarity or a route. */
49bool loom_features_valid(const float *values, size_t count,
50 const uint8_t *information, size_t information_size);
51
52/** @brief Required bytes for 1..4096 floats, or zero for unsupported counts. */
53size_t loom_features_size(size_t count);
54/** @brief Pack validated same-exposure shapes, exact uint64 identities and float bits.
55 * @pre Inputs remain immutable and do not overlap the destination.
56 * @details Writes the LOOMNN02 format described in docs/exif.md. Invalid inputs
57 * leave output unchanged. The caller reserves this value in the JPEG's EXIF
58 * document; there is no filesystem access or feature-sized allocation here. */
59bool loom_features_pack(unsigned char *record, size_t capacity, const float *values, size_t count,
60 const uint8_t *information, size_t information_size,
61 uint64_t sequence, uint64_t sensor_timestamp_ns);
62/** @brief Validate and decode an exact-sized binary record into bounded output.
63 * @pre Inputs and writable outputs do not overlap; capacity is a float count.
64 * @details On failure count is zero; other outputs must be discarded. Structural
65 * validity is not a model match. Check identity against the JPEG capture record
66 * before consuming features. No buffer is retained or allocated. */
67bool loom_features_unpack(const unsigned char *record, size_t size, float *values, size_t capacity,
68 uint8_t *information, size_t information_size, size_t *count,
69 uint64_t *sequence, uint64_t *sensor_timestamp_ns);
70/** @brief Encode a complete LOOMOX01 record without fabricating an IMX500 metadata header.
71 * @param record Writable destination, unchanged when validation rejects the input.
72 * @param capacity Available bytes; records cannot exceed LOOM_ONNX_FEATURE_CAPACITY.
73 * @param model Completed immutable float outputs and their exact graph/descriptor identities.
74 * @param sequence Source correlation, retained separately from any flight-controller shot number.
75 * @param sensor_timestamp_ns Physical sensor time when available; zero explicitly means unavailable.
76 * @return Encoded byte count, or zero for invalid/nonfinite/oversized features.
77 * @pre Input tensors and destination do not overlap. This transport does not establish a visual match. */
78size_t loom_onnx_features_pack(unsigned char *record, size_t capacity, const struct inference_model *model,
79 uint64_t sequence, uint64_t sensor_timestamp_ns);
80/** @brief Validate the exact binary layout and optionally require the same trained feature space.
81 * @param record Immutable LOOMOX01 bytes.
82 * @param size Exact record length; truncation and trailing bytes are rejected.
83 * @param model_sha256 Required graph digest, or NULL for structural validation only.
84 * @param descriptor_sha256 Required preprocessing digest, or NULL for structural validation only.
85 * @return True for bounded finite features and matching supplied identities, not navigation validity. */
86bool loom_onnx_features_valid(const unsigned char *record, size_t size,
87 const char *model_sha256, const char *descriptor_sha256);
88/** @brief Decode an explicitly declared two/three-value return-vector record.
89 * @param record Retained LOOMOX01 bytes from this JPEG.
90 * @param size Exact record length.
91 * @param model_sha256 Required graph identity, or NULL.
92 * @param descriptor_sha256 Required descriptor identity, or NULL.
93 * @param values Three floats: first component, second component, confidence.
94 * @return False unless exactly one finite two/three-value tensor is present.
95 * @details A two-value model has no confidence output; 1 then means valid
96 * computation, not a measured probability. Frame semantics remain caller-owned. */
97bool loom_onnx_return_vector(const unsigned char *record, size_t size,
98 const char *model_sha256, const char *descriptor_sha256, float values[3]);
99
100#ifdef __cplusplus
101}
102#endif
103#endif
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.
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.
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.
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.
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.
static size_t count
Definition pose_log.c:79
Parsed descriptor with self-referencing tensor-name pointers; do not copy after parsing.
char descriptor_sha256[65]