JPEG EXIF updates for USHER flight and thermal-capture provenance. More...
#include "image_exif.h"#include "boot_id.h"#include "exifite.h"#include "motion_compensation.h"#include <errno.h>#include <fcntl.h>#include <inttypes.h>#include <limits.h>#include <math.h>#include <stdbool.h>#include <stdatomic.h>#include <stddef.h>#include <stdint.h>#include <stdio.h>#include <stdlib.h>#include <string.h>#include <sys/stat.h>#include <unistd.h>
Go to the source code of this file.
Data Structures | |
| struct | exif_workspace |
Macros | |
| #define | ANGLE_BFP_SCALE 4096.0 |
| #define | SPEED_BFP_SCALE 524288.0 |
| #define | POSITION_BFP_SCALE 256.0 |
| #define | RAD_TO_DEG 57.29577951308232 |
| #define | ASCII_COMMENT_PREFIX_SIZE 8U |
| #define | EXIF_WORKSPACE_COUNT 8U |
| #define | EXIF_SCRATCH_CAPACITY 8192U |
| #define | SHOT_COMMENT_CAPACITY 1536U |
| #define | COMPLETE_RECORD_CAPACITY 4096U |
Functions | |
| static struct exif_workspace * | workspace_acquire (void) |
| Claim a bounded EXIF editing slot for the current thread. | |
| static void | workspace_release (struct exif_workspace *workspace) |
| Return an editing slot to the shared pool. | |
| static struct exif_document * | load_exif (const char *filename) |
| Import an existing JPEG EXIF block into the active editing slot. | |
| static int | set_coordinate (struct exif_document *exif, uint16_t reference_tag, uint16_t coordinate_tag, int32_t coordinate, int32_t limit, char positive, char negative) |
| Encode one signed GPS coordinate as EXIF hemisphere and DMS tags. | |
| static double | normalized_degrees (int32_t angle_bfp) |
| Convert a flight-controller heading to the EXIF angular range. | |
| static uint32_t | scaled_unsigned (double value, double scale) |
| Form a nonnegative numerator for an EXIF rational. | |
| static int | add_shot_tags (struct exif_document *exif, const union dc_shot_union *original, double delay, int compensate, const struct capture_timing *timing) |
| Add GPS fields and the flight-pose description to an editable document. | |
| static int | save_exif (const char *filename, struct exif_document *exif) |
| Replace metadata while streaming the original compressed payload unchanged. | |
| static int | set_tagged_comment (struct exif_document *exif, const char *tag, const char *information) |
| Write an EXIF UserComment composed of flight and analysis records. | |
| static int | write_tagged_comment (const char *filename, const char *tag, const char *information) |
| Compatibility wrapper for analysis that becomes available after the flight EXIF write. | |
| int | image_exif_write_hotspots (const char *filename, const char *information) |
| Append structured thermal hotspot/geolocation evidence to JPEG EXIF. | |
| int | image_exif_write_object_detections (const char *filename, const char *information) |
| Append structured object-detection evidence (AICam) to JPEG EXIF. | |
| 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. | |
| int | image_exif_write (const char *filename, const union dc_shot_union *shot) |
| Add standard USHER flight metadata to a JPEG. | |
| 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. | |
| 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. | |
| static int | add_observation_tags (struct exif_document *exif, const struct capture_timing *timing, bool aligned) |
| Extend the flight description with observation provenance. | |
| int | image_exif_write_complete (const char *filename, const union dc_shot_union *shot, double capture_delay_s, 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. | |
Variables | |
| static struct exif_workspace | exif_workspaces [EXIF_WORKSPACE_COUNT] |
| static _Thread_local struct exif_workspace * | active_workspace |
Detailed Description
JPEG EXIF updates for USHER flight and thermal-capture provenance.
Existing JPEG markers are copied while prior EXIF is replaced by a standards compliant APP1 block. Default in-place updates avoid temporary files and leave equal-position image bytes untouched. IMAGE_EXIF_ATOMIC_REPLACE selects the older sibling-file/fsync/rename method when original-file retention is more important. In-place writes are not atomic; interrupted mutation can damage the JPEG. Neither method promises full power-loss durability, since the parent directory is not synced.
Definition in file image_exif.c.
Macro Definition Documentation
◆ ANGLE_BFP_SCALE
| #define ANGLE_BFP_SCALE 4096.0 |
Definition at line 48 of file image_exif.c.
◆ ASCII_COMMENT_PREFIX_SIZE
| #define ASCII_COMMENT_PREFIX_SIZE 8U |
Definition at line 52 of file image_exif.c.
◆ COMPLETE_RECORD_CAPACITY
| #define COMPLETE_RECORD_CAPACITY 4096U |
Definition at line 56 of file image_exif.c.
◆ EXIF_SCRATCH_CAPACITY
| #define EXIF_SCRATCH_CAPACITY 8192U |
Definition at line 54 of file image_exif.c.
◆ EXIF_WORKSPACE_COUNT
| #define EXIF_WORKSPACE_COUNT 8U |
Definition at line 53 of file image_exif.c.
◆ POSITION_BFP_SCALE
| #define POSITION_BFP_SCALE 256.0 |
Definition at line 50 of file image_exif.c.
◆ RAD_TO_DEG
| #define RAD_TO_DEG 57.29577951308232 |
Definition at line 51 of file image_exif.c.
◆ SHOT_COMMENT_CAPACITY
| #define SHOT_COMMENT_CAPACITY 1536U |
Definition at line 55 of file image_exif.c.
◆ SPEED_BFP_SCALE
| #define SPEED_BFP_SCALE 524288.0 |
Definition at line 49 of file image_exif.c.
Function Documentation
◆ add_observation_tags()
|
static |
Extend the flight description with observation provenance.
- Parameters
-
[in,out] exif Active document containing the existing description. timing Optional timing, frame-identity and pose evidence. aligned Whether the primary capture pose came from synchronized evidence.
- Returns
- Zero on success, or -1 on malformed metadata or insufficient storage.
Record frame identity separately from timing and pose alignment. A bound frame may lack a valid exposure interval; navigation uncertainty is recorded only when a pose is marked valid.
Definition at line 433 of file image_exif.c.
◆ add_shot_tags()
|
static |
Add GPS fields and the flight-pose description to an editable document.
- Parameters
-
[in,out] exif Document owned by the active workspace. original Pose supplied by the caller; never modified. delay Estimated capture delay in seconds. compensate Nonzero to attempt ground-motion compensation. timing Optional capture delivery evidence.
- Returns
- Zero on success, or -1 if a tag or the bounded description cannot be written.
Apply optional compensation to a local copy. Keep standard EXIF fields for generic viewers and record fixed-point and physical units in the description for consumers that need the full flight pose.
Definition at line 203 of file image_exif.c.
◆ image_exif_write()
| int image_exif_write | ( | const char * | filename, |
| const union dc_shot_union * | shot ) |
Add standard USHER flight metadata to a JPEG.
- Parameters
-
filename Existing JPEG to update using the selected publication method. shot Flight-controller shot payload.
- Returns
- 0 on success or -1 on invalid input, JPEG, metadata, or storage failure.
Fresh capture writes replace prior camera EXIF with supported USHER metadata while preserving supported raw capture/LOOM evidence. Thumbnail and manufacturer records are deliberately discarded.
Definition at line 408 of file image_exif.c.
◆ image_exif_write_capture()
| 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.
- Parameters
-
filename Existing JPEG to update using the selected publication method. shot Flight-controller shot payload. capture_delay_s Fallback latency when timingis absent or invalid.compensate Nonzero to apply conservative constant-velocity ground correction. timing Optional validated server timing evidence; it overrides a supplied delay.
Timing describes request-to-frame arrival, not sensor exposure time; the emitted metadata labels this limitation explicitly.
Definition at line 419 of file image_exif.c.
◆ image_exif_write_complete()
| 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.
- Parameters
-
filename Existing JPEG; the caller exclusively owns metadata updates to this path. shot Pose used for geotags, already exposure-aligned when request is supplied. delay Fallback request-to-arrival latency in seconds; negative means unknown. compensate Nonzero enables the legacy position estimate; use zero for exposure-aligned pose. timing Optional arrival evidence and shared bounded observation-time pose. request Original FC request to preserve alongside an aligned pose, or NULL. uncertainty_m Nonnegative ground-position margin recorded when request is supplied. objects Optional already-produced object summary, or NULL; no inference runs here.
- Returns
- Zero on publication, -1 on invalid metadata, JPEG or storage failure.
Compressed image data is copied, not decoded/re-encoded. Combining tags avoids a second full-file rewrite but does not remove the camera's original JPEG write. Validate frame identity before calling. In-place updates retain the inode; optional atomic replacement changes it. In-place I/O failures can damage the file.
Definition at line 473 of file image_exif.c.
◆ image_exif_write_hotspots()
| int image_exif_write_hotspots | ( | const char * | filename, |
| const char * | information ) |
Append structured thermal hotspot/geolocation evidence to JPEG EXIF.
- Parameters
-
filename Existing JPEG. information Bounded UTF-8/ASCII analysis record.
- Returns
- 0 on metadata update success, otherwise -1.
Definition at line 372 of file image_exif.c.
◆ image_exif_write_mock_map()
| 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.
- Parameters
-
filename Existing mock JPEG. horizontal_fov Horizontal field of view in degrees, strictly between 0 and 179. vertical_fov Vertical field of view in degrees, strictly between 0 and 179.
- Returns
- Zero on metadata update success, otherwise -1.
Writes Sensoraia-owned geometry only; it does not write a tile-provider attribution.
Definition at line 382 of file image_exif.c.
◆ image_exif_write_object_detections()
| int image_exif_write_object_detections | ( | const char * | filename, |
| const char * | information ) |
Append structured object-detection evidence (AICam) to JPEG EXIF.
- Parameters
-
filename Existing JPEG. information Bounded UTF-8/ASCII analysis record.
- Returns
- 0 on metadata update success, otherwise -1.
Definition at line 377 of file image_exif.c.
◆ image_exif_write_timed()
| 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.
- Parameters
-
filename Existing JPEG to update using the selected publication method. shot Flight-controller shot payload. capture_delay_s Nonnegative request-to-frame latency, or a negative value when unknown. compensate Nonzero to estimate ground displacement from speed/course and latency.
Original coordinates remain in the textual record so downstream analysis can audit the correction rather than treating the constant-velocity estimate as ground truth.
Definition at line 413 of file image_exif.c.
◆ load_exif()
|
static |
Import an existing JPEG EXIF block into the active editing slot.
- Parameters
-
filename JPEG to read.
- Returns
- Borrowed editable document, or NULL if the slot or metadata is unavailable.
Parse the bounded payload before importing its entries so a metadata-only update can retain the image's existing tags.
Definition at line 112 of file image_exif.c.
◆ normalized_degrees()
|
static |
Convert a flight-controller heading to the EXIF angular range.
- Parameters
-
angle_bfp Angle in flight-controller fixed-point radians.
- Returns
- Degrees in [0, 360).
Wrap negative headings before encoding unsigned EXIF rationals.
Definition at line 172 of file image_exif.c.
◆ save_exif()
|
static |
Replace metadata while streaming the original compressed payload unchanged.
- Parameters
-
filename Existing image, exclusively owned by the caller during publication. exif Metadata ownership is consumed on every exit.
- Returns
- Zero after replacement, -1 on failure with the original path retained.
The temporary sits beside the original so rename stays on one filesystem. Flush and file sync happen before rename. This helper does not sync the parent directory, so do not treat success as a complete power-loss durability guarantee.
Definition at line 556 of file image_exif.c.
◆ scaled_unsigned()
|
static |
Form a nonnegative numerator for an EXIF rational.
- Parameters
-
value Quantity to encode. scale Positive finite denominator scale.
- Returns
- Rounded numerator, saturated at UINT32_MAX; zero for nonpositive or nonfinite input.
Saturate before converting so an out-of-range value cannot wrap.
Definition at line 184 of file image_exif.c.
◆ set_coordinate()
|
static |
Encode one signed GPS coordinate as EXIF hemisphere and DMS tags.
- Parameters
-
[in,out] exif Editable EXIF document. reference_tag GPS tag for the hemisphere letter. coordinate_tag GPS tag for the three unsigned rationals. coordinate Signed coordinate in units of 10^-7 degrees. limit Inclusive absolute bound in the same units. positive Hemisphere for nonnegative values. negative Hemisphere for negative values.
- Returns
- Zero on success, or -1 on invalid range or insufficient tag storage.
Split the magnitude with integer arithmetic so coordinate conversion does not introduce floating-point rollover between DMS fields. A failure after setting the hemisphere can leave the document modified.
Definition at line 135 of file image_exif.c.
◆ set_tagged_comment()
|
static |
Write an EXIF UserComment composed of flight and analysis records.
- Parameters
-
[in,out] exif Document already carrying the flight description. tag Optional section label as an empty or nonempty string, never NULL. information Null-terminated analysis text, at most 8192 bytes.
- Returns
- Zero on success, or -1 on invalid input or insufficient storage.
Snapshot the description before reserving another entry so rebuilding the tag storage cannot invalidate the bytes being copied.
Definition at line 321 of file image_exif.c.
◆ workspace_acquire()
|
static |
Claim a bounded EXIF editing slot for the current thread.
- Returns
- Owned slot, or NULL with EBUSY for reentry or EAGAIN for exhaustion.
Keep large scratch buffers off worker stacks. Acquire ordering pairs with release so a new owner does not race the previous user.
Definition at line 73 of file image_exif.c.
◆ workspace_release()
|
static |
Return an editing slot to the shared pool.
- Parameters
-
workspace Thread-owned slot, or NULL.
Clear the thread-local reference before making the slot available. All borrowed document and scratch pointers expire here.
Definition at line 98 of file image_exif.c.
◆ write_tagged_comment()
|
static |
Compatibility wrapper for analysis that becomes available after the flight EXIF write.
Prefer the combined writer when the result is already available, so the original need not be streamed to a replacement file twice.
Definition at line 353 of file image_exif.c.
Variable Documentation
◆ active_workspace
|
static |
Definition at line 67 of file image_exif.c.
◆ exif_workspaces
|
static |
Definition at line 66 of file image_exif.c.