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.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/* Request the POSIX clock declarations before any system header is included. */
19#ifndef _POSIX_C_SOURCE
20#define _POSIX_C_SOURCE 200809L
21#endif
22
23/** @file usher_frame_timing.c
24 * @brief C implementation of frame-clock conversion and capture EXIF setup.
25 * @details Sampling MONOTONIC on both sides of BOOTTIME bounds offset-read
26 * latency. Implausible sensor age, duration or sampling cost leaves the original
27 * evidence available but keeps its alignment timestamp explicitly unqualified.
28 */
29#include "usher_frame_timing.h"
30
31#include "boot_id.h"
32#include "sensor_capture.h"
33
34#include <sys/types.h>
35#include <time.h>
36#include <unistd.h>
37
38enum {
44};
45
46/** @brief Convert a validated POSIX clock sample to nanoseconds without overflow.
47 * @param[in] value Clock sample returned by clock_gettime().
48 * @param[out] result Nanoseconds from that clock's origin.
49 * @return True only for normalized, nonnegative values representable in uint64_t.
50 * @note A malformed sample must invalidate alignment rather than wrap the age.
51 */
52static bool timespec_to_nanoseconds(const struct timespec *value, uint64_t *result)
53{
54 if (!value || !result || value->tv_sec < 0 || value->tv_nsec < 0
55 || value->tv_nsec >= 1000000000L) {
56 return false;
57 }
58 const uint64_t seconds = (uint64_t)value->tv_sec;
59 const uint64_t nanoseconds = (uint64_t)value->tv_nsec;
60 if (seconds > (UINT64_MAX - nanoseconds) / UINT64_C(1000000000)) {
61 return false;
62 }
63 *result = seconds * UINT64_C(1000000000) + nanoseconds;
64 return true;
65}
66
68 int64_t exposure_us, int64_t duration_us)
69{
70 struct usher_frame_timing result = {
71 .sequence = sequence,
72 .sensor_ns = sensor_ns,
73 .monotonic_us = 0,
74 .time_error_us = unqualified_time_error_us,
75 .exposure_us = exposure_us,
76 .duration_us = duration_us
77 };
78 struct timespec mono_before, boot, mono_after;
79 uint64_t before_ns, boot_ns, after_ns;
80
81 /* Reject implausible input before any unsigned conversion or clock work. */
84 || clock_gettime(CLOCK_MONOTONIC, &mono_before) != 0
85 || clock_gettime(CLOCK_BOOTTIME, &boot) != 0
86 || clock_gettime(CLOCK_MONOTONIC, &mono_after) != 0
87 || !timespec_to_nanoseconds(&mono_before, &before_ns)
88 || !timespec_to_nanoseconds(&boot, &boot_ns)
89 || !timespec_to_nanoseconds(&mono_after, &after_ns)) {
90 return result;
91 }
92
93 /* Slow or impossible samples cannot safely translate one clock into the other. */
94 if (after_ns < before_ns || after_ns - before_ns > maximum_clock_sample_ns
95 || boot_ns < result.sensor_ns || boot_ns - result.sensor_ns > maximum_sensor_age_ns
96 || before_ns < boot_ns - result.sensor_ns) {
97 return result;
98 }
99
100 /* Frame age maps the BOOTTIME stamp into MONOTONIC; center exposure/readout. */
101 const uint64_t age_ns = boot_ns - result.sensor_ns;
102 const uint64_t monotonic_midpoint_ns = before_ns + (after_ns - before_ns) / 2 - age_ns;
103 const uint64_t interval_us = (uint64_t)exposure_us + (uint64_t)duration_us;
104 const uint64_t midpoint_us = monotonic_midpoint_ns / 1000;
105 const uint64_t exposure_offset_us = interval_us / 2;
106 if (UINT64_MAX - midpoint_us < exposure_offset_us) {
107 return result;
108 }
109 result.monotonic_us = midpoint_us + exposure_offset_us;
110 result.time_error_us = (after_ns - before_ns + 1999) / 2000 + (interval_us + 1) / 2 + 2;
111 return result;
112}
113
114bool usher_frame_document(const struct usher_frame_timing *timing, unsigned width, unsigned height,
115 struct exif_document *document)
116{
117 if (!timing || !document) {
118 return false;
119 }
120 struct sensor_capture record = {0};
121 usher_boot_id(record.boot_id);
122 record.width = width;
123 record.height = height;
124 record.process_id = (uint32_t)getpid();
125 record.sequence = timing->sequence;
126 record.sensor_timestamp_ns = timing->sensor_ns;
127 record.monotonic_us = timing->monotonic_us;
128 record.time_error_us = timing->time_error_us;
129 record.exposure_us = timing->exposure_us;
130 record.frame_duration_us = timing->duration_us;
131
132 exif_document_init(document);
133 unsigned char *data = exif_document_reserve(document, EXIF_CAMERA, SENSOR_CAPTURE_TAG,
135 return data && sensor_capture_encode(&record, data, SENSOR_CAPTURE_BYTES);
136}
Read Linux's boot-unique identifier for pose-log session provenance.
static void usher_boot_id(char result[37])
Fill a 36-character boot UUID or the stable fallback "unknown".
Definition boot_id.h:36
static int record(const union dc_shot_union *shot)
Retrieve a point and admit a new observation only when its credit is free.
void exif_document_init(struct exif_document *document)
Start a fresh upright sRGB/Y-Cb-Cr document with EXIF 2.32 defaults.
Definition exifite.c:412
unsigned char * exif_document_reserve(struct exif_document *document, enum exif_directory directory, uint16_t tag, enum exif_format format, uint32_t count)
Create or replace a field with zeroed, bounded value storage.
Definition exifite.c:508
@ EXIF_UNDEFINED
Definition exifite.h:70
@ EXIF_CAMERA
Definition exifite.h:59
Exact bounded SENSOR02 capture evidence, independent of TIFF byte order.
#define SENSOR_CAPTURE_BYTES
static bool sensor_capture_encode(const struct sensor_capture *record, unsigned char *data, size_t capacity)
Encode a SENSOR02 record in the fixed on-disk layout.
#define SENSOR_CAPTURE_TAG
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.
static double seconds(Clock::duration duration)
Convert a monotonic interval without truncating fractional seconds.
Definition survey.cpp:100
struct usher_control_result result
Definition usher.c:377
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.
static bool timespec_to_nanoseconds(const struct timespec *value, uint64_t *result)
Convert a validated POSIX clock sample to nanoseconds without overflow.
@ maximum_exposure_us
@ maximum_clock_sample_ns
@ unqualified_time_error_us
@ maximum_sensor_age_ns
@ maximum_frame_duration_us
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.
C interface for conservative frame-time estimation and EXIF evidence.