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.c File Reference

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>
Include dependency graph for image_exif.c:

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()

int add_observation_tags ( struct exif_document * exif,
const struct capture_timing * timing,
bool aligned )
static

Extend the flight description with observation provenance.

Parameters
[in,out]exifActive document containing the existing description.
timingOptional timing, frame-identity and pose evidence.
alignedWhether 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()

int add_shot_tags ( struct exif_document * exif,
const union dc_shot_union * original,
double delay,
int compensate,
const struct capture_timing * timing )
static

Add GPS fields and the flight-pose description to an editable document.

Parameters
[in,out]exifDocument owned by the active workspace.
originalPose supplied by the caller; never modified.
delayEstimated capture delay in seconds.
compensateNonzero to attempt ground-motion compensation.
timingOptional 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
filenameExisting JPEG to update using the selected publication method.
shotFlight-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
filenameExisting JPEG to update using the selected publication method.
shotFlight-controller shot payload.
capture_delay_sFallback latency when timing is absent or invalid.
compensateNonzero to apply conservative constant-velocity ground correction.
timingOptional 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
filenameExisting JPEG; the caller exclusively owns metadata updates to this path.
shotPose used for geotags, already exposure-aligned when request is supplied.
delayFallback request-to-arrival latency in seconds; negative means unknown.
compensateNonzero enables the legacy position estimate; use zero for exposure-aligned pose.
timingOptional arrival evidence and shared bounded observation-time pose.
requestOriginal FC request to preserve alongside an aligned pose, or NULL.
uncertainty_mNonnegative ground-position margin recorded when request is supplied.
objectsOptional 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
filenameExisting JPEG.
informationBounded 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
filenameExisting mock JPEG.
horizontal_fovHorizontal field of view in degrees, strictly between 0 and 179.
vertical_fovVertical 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
filenameExisting JPEG.
informationBounded 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
filenameExisting JPEG to update using the selected publication method.
shotFlight-controller shot payload.
capture_delay_sNonnegative request-to-frame latency, or a negative value when unknown.
compensateNonzero 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()

struct exif_document * load_exif ( const char * filename)
static

Import an existing JPEG EXIF block into the active editing slot.

Parameters
filenameJPEG 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()

double normalized_degrees ( int32_t angle_bfp)
static

Convert a flight-controller heading to the EXIF angular range.

Parameters
angle_bfpAngle 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()

int save_exif ( const char * filename,
struct exif_document * exif )
static

Replace metadata while streaming the original compressed payload unchanged.

Parameters
filenameExisting image, exclusively owned by the caller during publication.
exifMetadata 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()

uint32_t scaled_unsigned ( double value,
double scale )
static

Form a nonnegative numerator for an EXIF rational.

Parameters
valueQuantity to encode.
scalePositive 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()

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 )
static

Encode one signed GPS coordinate as EXIF hemisphere and DMS tags.

Parameters
[in,out]exifEditable EXIF document.
reference_tagGPS tag for the hemisphere letter.
coordinate_tagGPS tag for the three unsigned rationals.
coordinateSigned coordinate in units of 10^-7 degrees.
limitInclusive absolute bound in the same units.
positiveHemisphere for nonnegative values.
negativeHemisphere 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()

int set_tagged_comment ( struct exif_document * exif,
const char * tag,
const char * information )
static

Write an EXIF UserComment composed of flight and analysis records.

Parameters
[in,out]exifDocument already carrying the flight description.
tagOptional section label as an empty or nonempty string, never NULL.
informationNull-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()

struct exif_workspace * workspace_acquire ( void )
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()

void workspace_release ( struct exif_workspace * workspace)
static

Return an editing slot to the shared pool.

Parameters
workspaceThread-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()

int write_tagged_comment ( const char * filename,
const char * tag,
const char * information )
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

_Thread_local struct exif_workspace* active_workspace
static

Definition at line 67 of file image_exif.c.

◆ exif_workspaces

struct exif_workspace exif_workspaces[EXIF_WORKSPACE_COUNT]
static

Definition at line 66 of file image_exif.c.