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
image_exif.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 image_exif.h
20 * @brief Flight, timing, and thermal-analysis metadata writing for captured JPEGs. */
21#ifndef USHER_IMAGE_EXIF_H
22#define USHER_IMAGE_EXIF_H
23
24#include "usher_protocol.h"
25#include "capture_timing.h"
26#include "exifite.h"
27#include "sensor_capture.h"
29
30#ifdef __cplusplus
31extern "C" {
32#endif
33
34/** @brief Application-owned opaque evidence retained by photo metadata updates. */
36
37/** @brief Select additional image evidence, without teaching EXIFite its schemas.
38 * @param context Unused; the application policy needs no mutable state.
39 * @param directory Directory containing the field.
40 * @param tag Directory-local identifier owned by the producing module.
41 * @return True only for the application's relocatable camera evidence records. */
42static inline bool image_exif_capture_tag(void *context, enum exif_directory directory, uint16_t tag)
43{
44 (void)context;
45 if (directory != EXIF_CAMERA) return false;
46 for (size_t index = 0; index < sizeof(image_exif_capture_tags) / sizeof(image_exif_capture_tags[0]); ++index) {
47 if (tag == image_exif_capture_tags[index]) return true;
48 }
49 return false;
50}
51
52/** @brief Import standard metadata plus the application's approved capture evidence.
53 * @param document Caller-owned bounded destination.
54 * @param view Validated source with nonoverlapping backing storage.
55 * @return Zero on success, otherwise -1 with EXIFite's import rollback rules.
56 * @details A small inline policy wrapper keeps standalone image tools independent
57 * of the flight writer's workspaces. Unknown vendor structures remain excluded. */
58static inline int image_exif_import(struct exif_document *document, const struct exif_view *view)
59{
60 return exif_document_import_custom(document, view, image_exif_capture_tag, NULL);
61}
62
63/** @brief Select sibling-file atomic replacement instead of the default in-place update.
64 * @details Set to 1 for original-file retention on publication failure. The default
65 * 0 avoids temporary files but cannot recover from interrupted block moves or writes.
66 * Both methods validate JPEG framing, retain compressed bytes and sync the result.
67 * The caller must exclusively own updates to the file and its hard-linked aliases.
68 */
69#ifndef IMAGE_EXIF_ATOMIC_REPLACE
70#define IMAGE_EXIF_ATOMIC_REPLACE 0
71#endif
72#if IMAGE_EXIF_ATOMIC_REPLACE != 0 && IMAGE_EXIF_ATOMIC_REPLACE != 1
73#error "IMAGE_EXIF_ATOMIC_REPLACE must be 0 or 1"
74#endif
75
76/** @brief Add standard USHER flight metadata to a JPEG.
77 * @param filename Existing JPEG to update using the selected publication method.
78 * @param shot Flight-controller shot payload.
79 * @return 0 on success or -1 on invalid input, JPEG, metadata, or storage failure.
80 * @details Fresh capture writes replace prior camera EXIF with supported USHER
81 * metadata while preserving supported raw capture/LOOM evidence. Thumbnail and
82 * manufacturer records are deliberately discarded. */
83int image_exif_write(const char *filename, const union dc_shot_union *shot);
84/** @brief Add flight metadata with optional capture-delay motion compensation.
85 * @param filename Existing JPEG to update using the selected publication method.
86 * @param shot Flight-controller shot payload.
87 * @param capture_delay_s Nonnegative request-to-frame latency, or a negative value when unknown.
88 * @param compensate Nonzero to estimate ground displacement from speed/course and latency.
89 * @details Original coordinates remain in the textual record so downstream analysis can audit
90 * the correction rather than treating the constant-velocity estimate as ground truth. */
91int image_exif_write_timed(const char *filename, const union dc_shot_union *shot,
92 double capture_delay_s, int compensate);
93/** @brief Append structured thermal hotspot/geolocation evidence to JPEG EXIF.
94 * @param filename Existing JPEG.
95 * @param information Bounded UTF-8/ASCII analysis record.
96 * @return 0 on metadata update success, otherwise -1. */
97int image_exif_write_hotspots(const char *filename, const char *information);
98/** @brief Append structured object-detection evidence (AICam) to JPEG EXIF.
99 * @param filename Existing JPEG.
100 * @param information Bounded UTF-8/ASCII analysis record.
101 * @return 0 on metadata update success, otherwise -1. */
102int image_exif_write_object_detections(const char *filename, const char *information);
103/** @brief Label a synthetic map fixture with its geometry and provider-neutral XYZ tile scheme.
104 * @param filename Existing mock JPEG.
105 * @param horizontal_fov Horizontal field of view in degrees, strictly between 0 and 179.
106 * @param vertical_fov Vertical field of view in degrees, strictly between 0 and 179.
107 * @return Zero on metadata update success, otherwise -1.
108 * @details Writes Sensoraia-owned geometry only; it does not write a tile-provider attribution.
109 */
110int image_exif_write_mock_map(const char *filename, double horizontal_fov, double vertical_fov);
111/** @brief Add flight metadata using authoritative capture timing when available.
112 * @param filename Existing JPEG to update using the selected publication method.
113 * @param shot Flight-controller shot payload.
114 * @param capture_delay_s Fallback latency when @p timing is absent or invalid.
115 * @param compensate Nonzero to apply conservative constant-velocity ground correction.
116 * @param timing Optional validated server timing evidence; it overrides a supplied delay.
117 * @details Timing describes request-to-frame arrival, not sensor exposure time; the emitted
118 * metadata labels this limitation explicitly. */
119int image_exif_write_capture(const char *filename, const union dc_shot_union *shot,
120 double capture_delay_s, int compensate, const struct capture_timing *timing);
121/** @brief Write flight provenance and an available object-detection result in one metadata transaction.
122 * @param filename Existing JPEG; the caller exclusively owns metadata updates to this path.
123 * @param shot Pose used for geotags, already exposure-aligned when request is supplied.
124 * @param delay Fallback request-to-arrival latency in seconds; negative means unknown.
125 * @param compensate Nonzero enables the legacy position estimate; use zero for exposure-aligned pose.
126 * @param timing Optional arrival evidence and shared bounded observation-time pose.
127 * @param request Original FC request to preserve alongside an aligned pose, or NULL.
128 * @param uncertainty_m Nonnegative ground-position margin recorded when request is supplied.
129 * @param objects Optional already-produced object summary, or NULL; no inference runs here.
130 * @return Zero on publication, -1 on invalid metadata, JPEG or storage failure.
131 * @details Compressed image data is copied, not decoded/re-encoded. Combining tags
132 * avoids a second full-file rewrite but does not remove the camera's original JPEG
133 * write. Validate frame identity before calling. In-place updates retain the inode;
134 * optional atomic replacement changes it. In-place I/O failures can damage the file.
135 */
136int image_exif_write_complete(const char *filename, const union dc_shot_union *shot,
137 double delay, int compensate, const struct capture_timing *timing,
138 const union dc_shot_union *request, double uncertainty_m, const char *objects);
139
140#ifdef __cplusplus
141}
142#endif
143
144#endif
Sensor observation times, aligned poses, and optional frame-arrival evidence.
union dc_shot_union request
Bounded C11 EXIF metadata and JPEG streaming interfaces.
exif_directory
Directory identities, not on-disk tag numbers or offsets.
Definition exifite.h:59
int exif_document_import_custom(struct exif_document *document, const struct exif_view *view, exif_tag_selector select, void *context)
Import standard fields plus additional tags selected by the caller.
Definition exifite.c:671
@ EXIF_CAMERA
Definition exifite.h:59
int image_exif_write_hotspots(const char *filename, const char *information)
Append structured thermal hotspot/geolocation evidence to JPEG EXIF.
Definition image_exif.c:372
int image_exif_write_complete(const char *filename, const union dc_shot_union *shot, double delay, int compensate, const struct capture_timing *timing, const union dc_shot_union *request, double uncertainty_m, const char *objects)
Write flight provenance and an available object-detection result in one metadata transaction.
Definition image_exif.c:473
int image_exif_write_timed(const char *filename, const union dc_shot_union *shot, double capture_delay_s, int compensate)
Add flight metadata with optional capture-delay motion compensation.
Definition image_exif.c:413
static int image_exif_import(struct exif_document *document, const struct exif_view *view)
Import standard metadata plus the application's approved capture evidence.
Definition image_exif.h:58
int image_exif_write_capture(const char *filename, const union dc_shot_union *shot, double capture_delay_s, int compensate, const struct capture_timing *timing)
Add flight metadata using authoritative capture timing when available.
Definition image_exif.c:419
int image_exif_write_object_detections(const char *filename, const char *information)
Append structured object-detection evidence (AICam) to JPEG EXIF.
Definition image_exif.c:377
int image_exif_write(const char *filename, const union dc_shot_union *shot)
Add standard USHER flight metadata to a JPEG.
Definition image_exif.c:408
static const uint16_t image_exif_capture_tags[]
Application-owned opaque evidence retained by photo metadata updates.
Definition image_exif.h:35
int image_exif_write_mock_map(const char *filename, double horizontal_fov, double vertical_fov)
Label a synthetic map fixture with its geometry and provider-neutral XYZ tile scheme.
Definition image_exif.c:382
static bool image_exif_capture_tag(void *context, enum exif_directory directory, uint16_t tag)
Select additional image evidence, without teaching EXIFite its schemas.
Definition image_exif.h:42
LOOM-owned bounded feature validation and evidence serialization.
#define LOOM_FEATURES_TAG
LOOM-owned camera-directory tag; its value is a LOOMNN02 opaque record.
#define LOOM_ONNX_FEATURES_TAG
static double capture_delay_s
Exact bounded SENSOR02 capture evidence, independent of TIFF byte order.
#define SENSOR_CAPTURE_TAG
Shared observation evidence with optional LWIR request/frame-delivery timing.
Caller-owned bounded writer with no heap allocation.
Definition exifite.h:156
Borrowed view of a validated APP1 payload.
Definition exifite.h:131
union dc_shot_union shot
Definition usher.c:534
Shared FC/MORA byte-stream UART framing, messages and payload layouts.