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
earcam_core.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/**
19 * @file earcam_core.h
20 * @brief Sensor-independent acoustic samples and ground-source estimates.
21 * @details Supply geotagged audio windows from any capture adapter. This API
22 * does not acquire audio, own a flight session, or know about USHER/UART.
23 * Positions and heights must use a consistent navigation reference; the solver
24 * cannot repair microphone gain changes, unsynchronized poses or bad terrain data.
25 */
26#ifndef EARCAM_CORE_H
27#define EARCAM_CORE_H
28
29#include <stdbool.h>
30#include <stddef.h>
31#include <stdint.h>
32
33/** Bounded solver capacity; USHER reserves sample storage separately from this workspace. */
34#define EAR_MAX_SAMPLES 16384U
35
36/** @brief Estimated ground source, not a surveyed target or guaranteed alarm detection. */
38 bool valid; /**< A numerical estimate was produced; apply mission acceptance checks. */
39 double lat_deg; /**< Estimated source latitude, degrees. */
40 double lon_deg; /**< Estimated source longitude, degrees. */
41 double agl_m; /**< Representative microphone height from selected loud windows, metres. */
42 double alt_m; /**< Ground altitude: peak-window navigation altitude minus its AGL. */
43 double level_db; /**< Strongest retained level; dBFS unless the capture chain is calibrated. */
44 double confidence; /**< Relative prominence/concentration/support score, not a probability. */
45 uint32_t sample_count; /**< Input window count, including windows later rejected. */
46 uint32_t used_count; /**< Window count remaining after clipping, pose and quiet-outlier gates. */
47};
48
49/**
50 * @brief One audio window associated with microphone position and provenance.
51 * @details Keep gain fixed across a session: relative level differences drive
52 * localization. False pose_aligned preserves legacy arrival-time association;
53 * it must not be reported as exposure/audio-window synchronization.
54 */
55struct ear_sample {
56 uint64_t timestamp_ms; /**< Producer monotonic report timestamp, milliseconds; capture bounds are separate. */
57 int32_t shot_nr; /**< Associated FC photo/request number; not the audio sequence. */
58 double lat_deg; /**< Microphone latitude from associated navigation evidence, degrees. */
59 double lon_deg; /**< Microphone longitude from associated navigation evidence, degrees. */
60 double agl_m; /**< Height above the supplied ground reference, metres. */
61 double alt_m; /**< Microphone navigation altitude, metres; datum supplied by caller. */
62 double level_db; /**< Band loudness, dBFS or calibrated dB SPL; never mix conventions. */
63 double trend_db; /**< Fast-minus-slow envelope level used to favor approaching evidence. */
64 double contrast_db; /**< Tone prominence against the capture detector's background estimate. */
65 double frequency_hz; /**< Dominant detector-bank frequency, hertz. */
66 bool alarm; /**< Capture detector's tone-like alarm flag, not solver confidence. */
67 bool clipped; /**< ADC saturation makes level comparisons unreliable. */
68 bool pose_aligned; /**< Pose association used bounded audio-window timing evidence. */
69 double pose_uncertainty_m; /**< Adapter-supplied spatial uncertainty, metres; not solver error. */
70 /** Audio-window bounds in host monotonic microseconds, followed by producer sequence. */
72 /** Original FC coordinates in 1e7 degrees, retained for timing/pose diagnostics. */
74 bool classifier; /**< Distinguish PCM model acceptance from the native tone detector's alarm rule. */
75 double classifier_score; /**< Model probability, never the acoustic level or localization confidence. */
76 unsigned classifier_class; /**< Model-owned class index; compare only within a fixed assignment. */
77};
78
79/**
80 * @brief Estimate a ground source from relative loudness along a survey track.
81 * @param samples Caller-owned immutable windows; never modified or retained.
82 * @param count Input count, bounded by EAR_MAX_SAMPLES.
83 * @param result Required destination; cleared before validation when non-NULL.
84 * @return Zero for an estimate, -1 for invalid input or insufficient retained evidence.
85 * @details A robust centroid seeds a damped inverse-distance fit; unstable fits
86 * fall back to that centroid. Shared bounded scratch storage is mutex-protected,
87 * so concurrent calls serialize without allocating another survey-sized buffer.
88 * @warning A valid result is not an absolute alarm gate. With too few alarm
89 * windows the solver deliberately uses other finite levels, even silent ones.
90 * Mission policy must consider level, quality, geometry and independent evidence.
91 * The legacy near-zero-latitude placeholder gate also excludes equatorial tracks.
92 */
93int calculated_loudestspot(const struct ear_sample *samples, size_t count, struct ear_loudest_spot *result);
94
95#endif
static struct ear_sample samples[EAR_MAX_SAMPLES]
int calculated_loudestspot(const struct ear_sample *samples, size_t count, struct ear_loudest_spot *result)
Estimate a ground source from relative loudness along a survey track.
Definition ear_fusion.c:129
static size_t count
Definition pose_log.c:79
Estimated ground source, not a surveyed target or guaranteed alarm detection.
Definition earcam_core.h:37
uint32_t sample_count
Definition earcam_core.h:45
uint32_t used_count
Definition earcam_core.h:46
One audio window associated with microphone position and provenance.
Definition earcam_core.h:55
int32_t shot_nr
Definition earcam_core.h:57
double lat_deg
Definition earcam_core.h:58
double trend_db
Definition earcam_core.h:63
int32_t request_lat
Definition earcam_core.h:73
uint64_t window_latest_us
Definition earcam_core.h:71
int32_t request_lon
Definition earcam_core.h:73
bool classifier
Definition earcam_core.h:74
double pose_uncertainty_m
Definition earcam_core.h:69
uint64_t window_sequence
Definition earcam_core.h:71
double frequency_hz
Definition earcam_core.h:65
double agl_m
Definition earcam_core.h:60
double lon_deg
Definition earcam_core.h:59
double contrast_db
Definition earcam_core.h:64
double alt_m
Definition earcam_core.h:61
unsigned classifier_class
Definition earcam_core.h:76
double level_db
Definition earcam_core.h:62
bool pose_aligned
Definition earcam_core.h:68
double classifier_score
Definition earcam_core.h:75
uint64_t window_earliest_us
Definition earcam_core.h:71
uint64_t timestamp_ms
Definition earcam_core.h:56
struct usher_control_result result
Definition usher.c:377