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
usher_frame_timing.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 usher_frame_timing.h
19 * @brief C interface for conservative frame-time estimation and EXIF evidence.
20 * @details Camera timestamps use BOOTTIME while USHER pose history uses
21 * MONOTONIC. Preserve original sensor evidence and conversion uncertainty so a
22 * consumer can decline pose alignment instead of treating an estimate as a
23 * measurement. The implementation is C11; C++ camera code links through this
24 * stable C ABI.
25 */
26#ifndef USHER_FRAME_TIMING_H
27#define USHER_FRAME_TIMING_H
28
29#include <stdbool.h>
30#include <stdint.h>
31
32#include "exifite.h"
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/** @brief Timing evidence for one exposure, with microsecond uncertainty.
39 * @details A zero monotonic_us and time_error_us of 100001 leave timing
40 * unqualified for the 100000-us acceptance limit. Raw exposure evidence is
41 * retained on estimation failure; never replace a rejected estimate with now.
42 */
44 uint64_t sequence; ///< Camera frame sequence, not a flight-controller shot number.
45 uint64_t sensor_ns; ///< Original sensor timestamp in BOOTTIME nanoseconds; zero if invalid.
46 uint64_t monotonic_us; ///< Estimated exposure/readout-window midpoint in MONOTONIC microseconds.
47 uint64_t time_error_us; ///< Conservative alignment allowance, not calibrated accuracy.
48 int64_t exposure_us; ///< Reported exposure duration, retained even when rejected.
49 int64_t duration_us; ///< Reported frame duration used as a readout allowance.
50};
51
52/** @brief Translate fresh sensor evidence into a cautious pose-alignment time.
53 * @param sequence Camera sequence belonging to this exposure.
54 * @param sensor_ns Sensor timestamp in the local BOOTTIME domain.
55 * @param exposure_us Exposure duration in microseconds; accepted range 0..100000.
56 * @param duration_us Frame duration in microseconds; accepted range 1..200000.
57 * @return Original evidence plus an estimated midpoint and uncertainty, or
58 * unqualified defaults when clock sampling or plausibility checks fail.
59 * @details Bracketing BOOTTIME with MONOTONIC samples avoids assuming equal
60 * clock origins, including after suspend. The returned record is a value, so
61 * callers can retain it with the exact frame without allocation or shared state.
62 * @warning Sensor timestamps must follow BOOTTIME. Frame duration is not a
63 * measured rolling-shutter readout time; this estimate alone proves neither
64 * shutter synchronization nor geolocation accuracy.
65 */
67 int64_t exposure_us, int64_t duration_us);
68
69/** @brief Initialize capture EXIF for the JPEG encoded from this exposure.
70 * @param[in] timing Same-exposure evidence, qualified or not.
71 * @param width Actual encoded image width.
72 * @param height Actual encoded image height.
73 * @param[out] document Caller-owned bounded destination; previous contents are replaced.
74 * @return False for a null argument, invalid boot identity/dimensions or failed reservation.
75 * @details The capture owner may add model-specific tags before serializing one
76 * APP1 payload. No filesystem operation, sidecar or feature-sized allocation is
77 * performed here. The consumer still checks boot, dimensions and timing bounds.
78 * @warning Embedded identity is not a checksum or calibrated timing measurement.
79 */
80bool usher_frame_document(const struct usher_frame_timing *timing, unsigned width, unsigned height,
81 struct exif_document *document);
82
83#ifdef __cplusplus
84}
85#endif
86
87#endif
Bounded C11 EXIF metadata and JPEG streaming interfaces.
Caller-owned bounded writer with no heap allocation.
Definition exifite.h:156
Timing evidence for one exposure, with microsecond uncertainty.
uint64_t sensor_ns
Original sensor timestamp in BOOTTIME nanoseconds; zero if invalid.
uint64_t monotonic_us
Estimated exposure/readout-window midpoint in MONOTONIC microseconds.
int64_t exposure_us
Reported exposure duration, retained even when rejected.
int64_t duration_us
Reported frame duration used as a readout allowance.
uint64_t time_error_us
Conservative alignment allowance, not calibrated accuracy.
uint64_t sequence
Camera frame sequence, not a flight-controller shot number.
struct usher_frame_timing usher_frame_timing_estimate(uint64_t sequence, uint64_t sensor_ns, int64_t exposure_us, int64_t duration_us)
Translate fresh sensor evidence into a cautious pose-alignment time.
bool usher_frame_document(const struct usher_frame_timing *timing, unsigned width, unsigned height, struct exif_document *document)
Initialize capture EXIF for the JPEG encoded from this exposure.