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_return.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_return.h
19 * @brief Bounded direction-to-target policy, independent of inference and FC transport. */
20#ifndef SENSORAIA_LOOM_RETURN_H
21#define SENSORAIA_LOOM_RETURN_H
22
23#include <stdbool.h>
24#include <stdint.h>
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
30/** @brief Local ground point in metres east/north of the reference origin. */
31struct loom_return_point { double east, north; };
32
33/** @brief Wire metric values distinguishing active vector steering from arrival. */
40
41/** @brief Limits applied before a neural direction may become a target. */
43 double home_radius_m; /**< Destination arrival / protection radius in metres. */
44 double lookahead_m; /**< Carrot step distance ahead of the vehicle along a unit vector, metres. */
45 double maximum_step_m; /**< Terminal per-observation target refinement bound, metres. */
46 double minimum_confidence; /**< Required model confidence in 0..1. */
47 double maximum_tilt_deg; /**< Maximum absolute roll or pitch accepted for a photo, degrees. */
48};
49
50/** @brief Caller-owned sequence and smoothing state; first observation seeds target. */
55
56/** @brief Explicit model-vector coordinates; embeddings are never guessed to be bearings. */
63
64/** @brief Module-owned inference settings, separate from universal runtime settings. */
68 double home_latitude, home_longitude; /**< Optional live-sortie destination, geographic degrees. */
69 unsigned seen;
70};
71
72/** @brief Initialize return limits with feature-only semantics by default. */
74/** @brief Parse one LOOM-owned settings field, rejecting duplicates and unknown keys. */
75bool loom_return_setting(void *context, const char *key, const char *value);
76/** @brief Check that optional destination coordinates are either both present or both omitted. */
78/** @brief Convert a declared two-component vector to earth-frame east/north with attitude gating.
79 * @param frame Declared model coordinate system.
80 * @param first North or forward component.
81 * @param second East or right component.
82 * @param roll_deg Aircraft roll, right wing down positive, degrees.
83 * @param pitch_deg Aircraft pitch, nose up positive, degrees.
84 * @param yaw_deg Aircraft magnetometer heading, clockwise from north, degrees.
85 * @param max_tilt_deg Maximum allowed absolute roll or pitch in degrees.
86 * @param direction Written only for finite supported coordinates within tilt limits. */
87bool loom_return_vector_attitude(enum loom_return_frame frame, double first, double second,
88 double roll_deg, double pitch_deg, double yaw_deg,
89 double max_tilt_deg, struct loom_return_point *direction);
90/** @brief Convert a level declared two-component vector to earth-frame east/north.
91 * @param frame Declared model coordinate system.
92 * @param first North or forward component.
93 * @param second East or right component.
94 * @param yaw_deg Aircraft heading, clockwise from north, degrees.
95 * @param direction Written only for finite supported coordinates. */
96bool loom_return_vector(enum loom_return_frame frame, double first, double second,
97 double yaw_deg, struct loom_return_point *direction);
98/** @brief Generate a slightly noisy body-frame simulated homing vector seeded by neural feature output. */
99void loom_return_simulated_vector(uint64_t seed, struct loom_return_point position,
100 double yaw_deg, float vector[3]);
101
102/** @brief Conservative return-policy defaults, not aircraft flight settings.
103 * @param config Writable destination. */
104void loom_return_defaults(struct loom_return_config *config);
105/** @brief Validate finite limits and their cross-field relationships. */
106bool loom_return_config_valid(const struct loom_return_config *config);
107
108/** @brief Convert an earth-frame direction into a HOME-bounded target.
109 * @param config Valid policy limits.
110 * @param position Vehicle east/north relative to HOME, metres.
111 * @param direction Earth-frame east/north components; magnitude is not distance.
112 * @param confidence Finite model confidence in 0..1.
113 * @param target Written only for an accepted, nonzero direction toward HOME.
114 * @return False for invalid, away-facing or inconsistent geometry. */
115bool loom_return_direction(const struct loom_return_config *config,
116 struct loom_return_point position,
117 struct loom_return_point direction, double confidence,
118 struct loom_return_point *target);
119
120/** @brief Admit a fresh bounded target and limit its movement.
121 * @param state Exclusive caller state; not shared between sorties.
122 * @param config Valid policy limits.
123 * @param sequence Strictly increasing positive observation number.
124 * @param candidate Proposed point within the HOME radius.
125 * @param target Smoothed accepted point, unchanged on rejection.
126 * @return True only when the state advances. Transport owners must commit a
127 * copied state only after their waypoint transaction succeeds. */
128bool loom_return_update(struct loom_return_state *state, const struct loom_return_config *config,
129 uint32_t sequence, struct loom_return_point candidate,
130 struct loom_return_point *target);
131
132/** @brief Produce small mean-reverting target fluctuations for explicit PC simulation.
133 * @param state Caller state; random seed zero selects a deterministic seed.
134 * @param config Valid policy limits.
135 * @param sequence Strictly increasing observation number.
136 * @param target Simulated point, never represented as a neural observation.
137 * @return True only for a fresh bounded update. */
138bool loom_return_simulate(struct loom_return_state *state, const struct loom_return_config *config,
139 uint32_t sequence, struct loom_return_point *target);
140
141#ifdef __cplusplus
142}
143#endif
144#endif
loom_return_metric
Wire metric values distinguishing active vector steering from arrival.
Definition loom_return.h:34
@ 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_METRIC_NONE
Definition loom_return.h:35
loom_return_frame
Explicit model-vector coordinates; embeddings are never guessed to be bearings.
Definition loom_return.h:57
@ 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
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(enum loom_return_frame frame, double first, double second, double yaw_deg, struct loom_return_point *direction)
Convert a level declared two-component vector to earth-frame east/north.
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
void loom_return_simulated_vector(uint64_t seed, struct loom_return_point position, double yaw_deg, float vector[3])
Generate a slightly noisy body-frame simulated homing vector seeded by neural feature output.
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_config_valid(const struct loom_return_config *config)
Validate finite limits and their cross-field relationships.
Definition loom_return.c:26
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.
void loom_return_defaults(struct loom_return_config *config)
Conservative return-policy defaults, not aircraft flight settings.
Definition loom_return.c:35
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.
uint8_t frame[LWIR_MAX_FRAME_BYTES]
Definition lwir_mock.c:58
Limits applied before a neural direction may become a target.
Definition loom_return.h:42
double minimum_confidence
Definition loom_return.h:46
Module-owned inference settings, separate from universal runtime settings.
Definition loom_return.h:65
struct loom_return_config limits
Definition loom_return.h:66
enum loom_return_frame frame
Definition loom_return.h:67
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
struct loom_return_point target
Definition loom_return.h:52
uint32_t random_state
Definition loom_return.h:53
Validated capture and reporting policy, fixed before the sample loop.
Definition earcam.c:137