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.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_return.c
19 * @brief Constant-storage return geometry with explicit simulation-only fallback. */
20#include "loom_return.h"
21
22#include <math.h>
23#include <string.h>
25
27{
28 return config && isfinite(config->home_radius_m) && config->home_radius_m >= 1 && config->home_radius_m <= 300 &&
29 isfinite(config->lookahead_m) && config->lookahead_m >= 1 && config->lookahead_m <= config->home_radius_m &&
30 isfinite(config->maximum_step_m) && config->maximum_step_m > 0 && config->maximum_step_m <= config->home_radius_m &&
31 isfinite(config->minimum_confidence) && config->minimum_confidence >= 0 && config->minimum_confidence <= 1 &&
32 isfinite(config->maximum_tilt_deg) && config->maximum_tilt_deg >= 1 && config->maximum_tilt_deg <= 60;
33}
34
36{
37 if (config) *config = (struct loom_return_config) {60, 50, 5, 0.6, 25};
38}
39
41{
42 if (!options) return;
43 *options = (struct loom_return_options){0};
45}
46
48{
49 if (!options || !loom_return_config_valid(&options->limits)) return false;
50 const unsigned home_fields = (1U << 5) | (1U << 6);
51 const unsigned present = options->seen & home_fields;
52 return present == 0 || present == home_fields;
53}
54
55bool loom_return_setting(void *context, const char *key, const char *value)
56{
57 struct loom_return_options *options = context;
58 const char *const names[] = {"return_vector_frame", "return_home_radius_m", "return_lookahead_m",
59 "return_max_step_m", "return_min_confidence", "return_home_latitude",
60 "return_home_longitude", "return_max_tilt_deg"};
61 unsigned field = 0;
62 while (field < 8 && strcmp(key, names[field])) ++field;
63 if (!options || field == 8 || (options->seen & (1U << field))) return false;
64 options->seen |= 1U << field;
65 if (!field) {
66 if (!strcmp(value, "none")) options->frame = LOOM_RETURN_NONE;
67 else if (!strcmp(value, "north_east")) options->frame = LOOM_RETURN_NORTH_EAST;
68 else if (!strcmp(value, "body_forward_right")) options->frame = LOOM_RETURN_BODY_FORWARD_RIGHT;
69 else if (!strcmp(value, "simulated")) options->frame = LOOM_RETURN_SIMULATED;
70 else return false;
71 return true;
72 }
73 double number;
74 if (!ini_real(value, &number)) return false;
75 if (field == 1 && number >= 1 && number <= 300) options->limits.home_radius_m = number;
76 else if (field == 2 && number >= 1 && number <= 300) options->limits.lookahead_m = number;
77 else if (field == 3 && number > 0 && number <= 300) options->limits.maximum_step_m = number;
78 else if (field == 4 && number >= 0 && number <= 1) options->limits.minimum_confidence = number;
79 else if (field == 5 && fabs(number) <= 85) options->home_latitude = number;
80 else if (field == 6 && fabs(number) <= 180) options->home_longitude = number;
81 else if (field == 7 && number >= 1 && number <= 60) options->limits.maximum_tilt_deg = number;
82 else return false;
83 return true;
84}
85
86bool loom_return_vector_attitude(enum loom_return_frame frame, double first, double second,
87 double roll_deg, double pitch_deg, double yaw_deg,
88 double max_tilt_deg, struct loom_return_point *direction)
89{
90 if (!direction || !isfinite(first) || !isfinite(second) ||
91 !isfinite(roll_deg) || !isfinite(pitch_deg) || !isfinite(yaw_deg) ||
92 !isfinite(max_tilt_deg) || max_tilt_deg < 1 || max_tilt_deg > 60 ||
93 fabs(roll_deg) > max_tilt_deg || fabs(pitch_deg) > max_tilt_deg ||
94 fabs(yaw_deg) > 36000) return false;
95 if (frame == LOOM_RETURN_NORTH_EAST) *direction = (struct loom_return_point){second, first};
97 const double radians = 0.017453292519943295;
98 const double roll = roll_deg * radians;
99 const double pitch = pitch_deg * radians;
100 const double yaw = remainder(yaw_deg, 360) * radians;
101 const double forward = first * cos(pitch) + second * sin(roll) * sin(pitch);
102 const double right = second * cos(roll);
103 *direction = (struct loom_return_point){forward * sin(yaw) + right * cos(yaw),
104 forward * cos(yaw) - right * sin(yaw)};
105 } else return false;
106 return isfinite(direction->east) && isfinite(direction->north);
107}
108
109void loom_return_simulated_vector(uint64_t seed, struct loom_return_point position,
110 double yaw_deg, float vector[3])
111{
112 if (!vector) return;
113 seed = seed * UINT64_C(6364136223846793005) + UINT64_C(1442695040888963407);
114 const double jitter = ((double)(uint32_t)(seed >> 32) / 4294967295.0 * 2.0 - 1.0) * 0.22;
115 seed = seed * UINT64_C(6364136223846793005) + UINT64_C(1442695040888963407);
116 const double confidence = 0.85 + ((double)(uint32_t)(seed >> 32) / 4294967295.0) * 0.13;
117 const double distance = hypot(position.east, position.north);
118 if (isfinite(distance) && distance > 1e-6 && isfinite(yaw_deg)) {
119 const double bearing = atan2(-position.east, -position.north) + jitter;
120 const double heading = remainder(yaw_deg, 360.0) * 0.017453292519943295;
121 const double relative = bearing - heading;
122 const double scale = distance < 50.0 ? fmax(0.1, distance / 50.0) : 1.0;
123 vector[0] = (float)(cos(relative) * scale);
124 vector[1] = (float)(sin(relative) * scale);
125 } else {
126 vector[0] = (float)cos(jitter);
127 vector[1] = (float)sin(jitter);
128 }
129 vector[2] = (float)confidence;
130}
131
132bool loom_return_vector(enum loom_return_frame frame, double first, double second,
133 double yaw_deg, struct loom_return_point *direction)
134{
135 return loom_return_vector_attitude(frame, first, second, 0, 0, yaw_deg, 25, direction);
136}
137
139 struct loom_return_point position,
140 struct loom_return_point direction, double confidence,
141 struct loom_return_point *target)
142{
143 if (!target || !loom_return_config_valid(config) || !isfinite(position.east) || !isfinite(position.north) ||
144 !isfinite(direction.east) || !isfinite(direction.north) ||
145 !isfinite(confidence) || confidence < config->minimum_confidence || confidence > 1) return false;
146 const double distance = hypot(position.east, position.north);
147 const double magnitude = hypot(direction.east, direction.north);
148 if (!isfinite(distance) || distance > 5000 || !isfinite(magnitude) || magnitude < 1e-6) return false;
149 direction.east /= magnitude;
150 direction.north /= magnitude;
151 const double along = -(position.east * direction.east + position.north * direction.north);
152 if (distance > config->home_radius_m && along <= 0) return false;
153 double step = distance > config->home_radius_m ? fmax(config->lookahead_m, along)
154 : config->lookahead_m * fmin(1.0, magnitude);
155 if (distance > 0 && distance <= config->home_radius_m && along > 0 && along < step) step = along;
156 struct loom_return_point proposed = {
157 position.east + direction.east * step,
158 position.north + direction.north * step
159 };
160 const double proposed_distance = hypot(proposed.east, proposed.north);
161 if (!isfinite(proposed_distance)) return false;
162 if (proposed_distance > config->home_radius_m) {
163 if (distance <= config->home_radius_m || along < distance * 0.95) return false;
164 proposed.east *= config->home_radius_m / proposed_distance;
165 proposed.north *= config->home_radius_m / proposed_distance;
166 }
167 *target = proposed;
168 return true;
169}
170
171bool loom_return_update(struct loom_return_state *state, const struct loom_return_config *config,
172 uint32_t sequence, struct loom_return_point candidate,
173 struct loom_return_point *target)
174{
175 if (!state || !target || !loom_return_config_valid(config) || !sequence || sequence <= state->sequence ||
176 !isfinite(candidate.east) || !isfinite(candidate.north) ||
177 !isfinite(state->target.east) || !isfinite(state->target.north) ||
178 hypot(candidate.east, candidate.north) > config->home_radius_m ||
179 hypot(state->target.east, state->target.north) > config->home_radius_m) return false;
180 const double east = candidate.east - state->target.east, north = candidate.north - state->target.north;
181 const double movement = hypot(east, north);
182 if (movement > config->maximum_step_m) {
183 candidate.east = state->target.east + east * config->maximum_step_m / movement;
184 candidate.north = state->target.north + north * config->maximum_step_m / movement;
185 }
186 state->target = *target = candidate;
187 state->sequence = sequence;
188 return true;
189}
190
191bool loom_return_simulate(struct loom_return_state *state, const struct loom_return_config *config,
192 uint32_t sequence, struct loom_return_point *target)
193{
194 if (!state || !loom_return_config_valid(config)) return false;
195 struct loom_return_state proposed = *state;
196 if (!proposed.random_state) proposed.random_state = 19;
197 proposed.random_state = proposed.random_state * UINT32_C(1664525) + UINT32_C(1013904223);
198 const double east = (double)(proposed.random_state >> 8) / 16777215.0 * 2 - 1;
199 proposed.random_state = proposed.random_state * UINT32_C(1664525) + UINT32_C(1013904223);
200 const double north = (double)(proposed.random_state >> 8) / 16777215.0 * 2 - 1;
201 const double spread = fmin(15, config->home_radius_m / 3);
202 const struct loom_return_point candidate = {
203 proposed.target.east * 0.85 + east * spread * 0.15,
204 proposed.target.north * 0.85 + north * spread * 0.15
205 };
206 if (!loom_return_update(&proposed, config, sequence, candidate, target)) return false;
207 *state = proposed;
208 return true;
209}
Allocation-free flat key=value mechanics; callers own schemas and storage.
static bool ini_real(const char *text, double *number)
Parse finite decimal/exponent notation, rejecting range errors and suffixes.
Definition bounded_ini.h:67
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.
Bounded direction-to-target policy, independent of inference and FC transport.
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
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
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