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.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 loom_features.c
19 * @brief Bounded LOOM feature validation and exact binary EXIF transport.
20 * @details The capture owner supplies immutable same-exposure buffers; this
21 * core neither acquires a camera nor decides whether a navigation match exists. */
22#include "loom_features.h"
23#include "imx500_tensor.h"
24
25#include <float.h>
26#include <math.h>
27
28/** @brief Read four checked little-endian bytes without an unaligned cast.
29 * @param data At least four bytes inside validated tensor metadata.
30 * @return Unsigned component value in host representation. */
31static uint32_t feature_u32(const uint8_t *data)
32{
33 return (uint32_t)data[0] | (uint32_t)data[1] << 8
34 | (uint32_t)data[2] << 16 | (uint32_t)data[3] << 24;
35}
36
37/** @brief Read a bounded shape extent from one driver tensor record.
38 * @param record Full accessible tensor-info record.
39 * @param dimension Validated zero-based dimension below the rank limit.
40 * @return The little-endian unsigned 16-bit extent, widened for checked arithmetic. */
41static uint32_t feature_extent(const uint8_t *record, uint32_t dimension)
42{
43 const size_t offset = IMX500_TENSOR_DIMENSIONS_OFFSET + dimension * IMX500_TENSOR_DIMENSION_BYTES;
44 return (uint32_t)record[offset] | (uint32_t)record[offset + 1] << 8;
45}
46
47bool loom_features_valid(const float *values, size_t count,
48 const uint8_t *information, size_t information_size)
49{
50 if (!values || !information || information_size < IMX500_TENSOR_INFO_BYTES
52 return false;
53 }
54 const uint32_t tensors = feature_u32(information + IMX500_TENSOR_COUNT_OFFSET);
55 if (tensors == 0 || tensors > IMX500_TENSOR_MAX_COUNT) {
56 return false;
57 }
58
59 size_t total = 0;
60 for (uint32_t index = 0; index < tensors; ++index) {
61 const uint8_t *record = information + IMX500_TENSOR_FIRST_RECORD_OFFSET
63 const uint32_t length = feature_u32(record + IMX500_TENSOR_LENGTH_OFFSET);
64 const uint32_t rank = feature_u32(record + IMX500_TENSOR_RANK_OFFSET);
65 if (length == 0 || length > IMX500_TENSOR_ELEMENT_LIMIT
66 || rank == 0 || rank > IMX500_TENSOR_MAX_RANK) {
67 return false;
68 }
69 uint32_t product = 1;
70 /* Shape metadata is untrusted. Check with division before multiplication,
71 * and check the cumulative budget before adding another tensor's elements. */
72 for (uint32_t dimension = 0; dimension < rank; ++dimension) {
73 const uint32_t extent = feature_extent(record, dimension);
74 if (extent == 0 || product > IMX500_TENSOR_ELEMENT_LIMIT / extent) {
75 return false;
76 }
77 product *= extent;
78 }
79 if (product != length || total > IMX500_TENSOR_ELEMENT_LIMIT - length) {
80 return false;
81 }
82 total += length;
83 }
84 if (total != count) {
85 return false;
86 }
87 for (size_t index = 0; index < count; ++index) {
88 /* NaN/infinity cannot be valid feature evidence or a useful input
89 * to future similarity/geometric checks. Transport validity is still not a match. */
90 if (!isfinite(values[index])) {
91 return false;
92 }
93 }
94 return true;
95}
96
97_Static_assert(sizeof(float) == 4 && FLT_RADIX == 2 && FLT_MANT_DIG == 24 && FLT_MAX_EXP == 128,
98 "LOOM evidence requires IEEE binary32");
99
101{
103}
104
105/** @brief Encode one little-endian field in a LOOM evidence record.
106 * @param[out] data Storage validated by the caller for @p bytes octets.
107 * @param value Unsigned bits to write.
108 * @param bytes Field width, at most eight.
109 * @details Pack explicit bytes so persisted data does not depend on host
110 * byte order or alignment. */
111static void feature_put(unsigned char *data, uint64_t value, size_t bytes)
112{
113 for (size_t index = 0; index < bytes; ++index) data[index] = (unsigned char)(value >> (8 * index));
114}
115
116bool loom_features_pack(unsigned char *record, size_t capacity, const float *values, size_t count,
117 const uint8_t *information, size_t information_size,
118 uint64_t sequence, uint64_t sensor_timestamp_ns)
119{
120 const size_t size = loom_features_size(count);
121 if (!record || !size || capacity < size || !loom_features_valid(values, count, information, information_size)) return false;
122 const char magic[] = "LOOMNN02";
123 for (size_t index = 0; index < 8; ++index) record[index] = (unsigned char)magic[index];
124 feature_put(record + 8, sequence, 8);
125 feature_put(record + 16, sensor_timestamp_ns, 8);
126 feature_put(record + 24, count, 4);
128 for (size_t index = 0; index < IMX500_TENSOR_INFO_BYTES; ++index) record[32 + index] = information[index];
129 for (size_t index = 0; index < count; ++index) {
130 union { float floating; uint32_t bits; } value = {.floating = values[index]};
131 feature_put(record + 32 + IMX500_TENSOR_INFO_BYTES + index * 4, value.bits, 4);
132 }
133 return true;
134}
135
136bool loom_features_unpack(const unsigned char *record, size_t size, float *values, size_t capacity,
137 uint8_t *information, size_t information_size, size_t *count,
138 uint64_t *sequence, uint64_t *sensor_timestamp_ns)
139{
140 if (count) *count = 0;
141 if (!record || size < 32 || !values || !information || !count || !sequence || !sensor_timestamp_ns
142 || information_size < IMX500_TENSOR_INFO_BYTES) return false;
143 const char magic[] = "LOOMNN02";
144 for (size_t index = 0; index < 8; ++index) if (record[index] != (unsigned char)magic[index]) return false;
145 const size_t total = feature_u32(record + 24);
146 if (!loom_features_size(total) || size != loom_features_size(total) || total > capacity
147 || feature_u32(record + 28) != IMX500_TENSOR_INFO_BYTES) return false;
148 for (size_t index = 0; index < IMX500_TENSOR_INFO_BYTES; ++index) information[index] = record[32 + index];
149 for (size_t index = 0; index < total; ++index) {
150 union { uint32_t bits; float floating; } value = {.bits = feature_u32(record + 32 + IMX500_TENSOR_INFO_BYTES + index * 4)};
151 values[index] = value.floating;
152 }
153 if (!loom_features_valid(values, total, information, information_size)) return false;
154 *count = total;
155 *sequence = (uint64_t)feature_u32(record + 8) | (uint64_t)feature_u32(record + 12) << 32;
156 *sensor_timestamp_ns = (uint64_t)feature_u32(record + 16) | (uint64_t)feature_u32(record + 20) << 32;
157 return true;
158}
static unsigned capacity[COVERAGE_CAMERAS]
size_t size
Definition chdk_pipe.c:143
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
static int record(const union dc_shot_union *shot)
Retrieve a point and admit a new observation only when its credit is free.
Shared IMX500 tensor-info wire layout and bounded decoding policy.
#define IMX500_TENSOR_RANK_OFFSET
Shape rank offset within a record.
#define IMX500_TENSOR_DIMENSION_BYTES
Each extent is a little-endian unsigned 16-bit value.
#define IMX500_TENSOR_DIMENSIONS_OFFSET
First shape extent follows the two 32-bit fields.
#define IMX500_TENSOR_COUNT_OFFSET
Little-endian 32-bit tensor count starts after the fixed header.
#define IMX500_TENSOR_ELEMENT_LIMIT
Sensoraia's accepted element budget, not a claim about every RPK model.
#define IMX500_TENSOR_INFO_BYTES
Full accessible metadata required before following record offsets.
#define IMX500_TENSOR_FIRST_RECORD_OFFSET
First record starts after the count, keeping offset arithmetic in one place.
#define IMX500_TENSOR_MAX_COUNT
Metadata reserves sixteen records even when a model uses fewer outputs.
#define IMX500_TENSOR_LENGTH_OFFSET
Element count offset within a record, distinct from its byte length.
#define IMX500_TENSOR_MAX_RANK
Fixed shape capacity in the driver ABI; reject greater ranks before indexing.
#define IMX500_TENSOR_RECORD_BYTES
One record contains length, rank and sixteen 16-bit shape extents.
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.
static uint32_t feature_u32(const uint8_t *data)
Read four checked little-endian bytes without an unaligned cast.
static void feature_put(unsigned char *data, uint64_t value, size_t bytes)
Encode one little-endian field in a LOOM evidence record.
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.
static uint32_t feature_extent(const uint8_t *record, uint32_t dimension)
Read a bounded shape extent from one driver tensor record.
LOOM-owned bounded feature validation and evidence serialization.
static size_t count
Definition pose_log.c:79