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

Deterministic attitude-based JPEG transform used by local USHER simulation. More...

#include "image_mock_transform.h"
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <math.h>
#include <pthread.h>
#include <setjmp.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <unistd.h>
#include <jpeglib.h>
#include "jpeg_marker_guard.h"
Include dependency graph for image_mock_transform.c:

Go to the source code of this file.

Data Structures

struct  projection_fit
struct  transform_jpeg_error
struct  decoded_image
struct  image_mock_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 JPEG_COMPONENTS   3U
#define JPEG_QUALITY   95
#define FOCAL_LENGTH_FACTOR   0.9
#define PROJECTION_EPSILON   1e-9
#define PROJECTION_MIN_DEPTH   1e-4
#define PROJECTION_FOV_SAMPLES   192
#define PROJECTION_REFINE_STEPS   48
#define PROJECTION_MIN_RAY_SCALE   1e-4
#define COVER_SAFETY_FACTOR   0.999
#define IMAGE_MOCK_MAX_DIMENSION   8192U
#define IMAGE_MOCK_MAX_PIXELS   (2028U * 1520U)
#define IMAGE_MOCK_RGB_CAPACITY   ((size_t)IMAGE_MOCK_MAX_PIXELS * JPEG_COMPONENTS)
#define MAP_TILE_SIZE   256U
#define MAP_MOSAIC_DIMENSION   (3U * MAP_TILE_SIZE)
#define MAP_MOSAIC_CAPACITY   ((size_t)MAP_MOSAIC_DIMENSION * MAP_MOSAIC_DIMENSION * JPEG_COMPONENTS)
#define near_horizon_case_black   0
#define near_horizon_roll_deg   75.0
#define near_horizon_pitch_deg   75.0
#define near_horizon_combined_tilt_deg   70.0

Functions

static void transform_jpeg_error_exit (j_common_ptr jpeg_info)
 Redirect a fatal libjpeg error to the active codec operation.
static bool is_near_horizon (double roll_rad, double pitch_rad)
 Apply both axis-specific and combined near-horizon limits.
static bool dimensions_fit (size_t width, size_t height)
 Check that an image can fit the bounded RGB workspace.
static int read_jpeg_dimensions (FILE *input, struct decoded_image *image)
 Read bounded image dimensions without decoding pixels.
static int decode_jpeg (FILE *input, struct decoded_image *image)
 Decode bounded RGB scanlines from an open JPEG stream.
static int encode_jpeg (FILE *output, const struct decoded_image *image)
 Encode a bounded interleaved RGB image at the simulation quality setting.
static int transform_pixels (const struct decoded_image *source, struct decoded_image *destination, double roll_rad, double pitch_rad, double yaw_rad, bool synthesize_terrain)
 Resample a fixture into a camera view at the supplied attitude.
static void build_rotation (double roll_rad, double pitch_rad, double yaw_rad, double rotation[3][3])
 Construct the body-to-north/east/down attitude rotation.
static bool project_point (double rotation[3][3], double focal_length, double center_x, double center_y, double ray_scale, double destination_x, double destination_y, double *source_x, double *source_y)
 Map a destination pixel back into the fixture JPEG.
static bool projection_corners_valid (const struct decoded_image *source, double rotation[3][3], double focal_length, double center_x, double center_y, double ray_scale)
 Check for a horizon crossing in the candidate projection.
static int compute_projection_fit_at_scale (const struct decoded_image *source, double rotation[3][3], double focal_length, double center_x, double center_y, double ray_scale, struct projection_fit *fit)
 Fit one projected destination rectangle into the source raster.
static int compute_projection_fit (const struct decoded_image *source, double rotation[3][3], double focal_length, double center_x, double center_y, struct projection_fit *fit)
 Find a fitted projection with low effective zoom.
static void bilinear_sample_rgb (const struct decoded_image *image, double source_x, double source_y, unsigned char output[JPEG_COMPONENTS])
 Sample the RGB raster at an in-bounds fractional position.
static double mirror_coordinate (double coordinate, size_t extent)
 Reflect a sample coordinate into the source image.
static int create_black_frame (const char *filename)
 Replace the fixture with a black JPEG of the same dimensions.
static int replace_image_atomically (const char *filename, const struct decoded_image *image)
 Publish a complete simulated JPEG in place of its fixture.
static int image_mock_map_locked (const char *filename, const char *cache_directory, const union dc_shot_union *shot, size_t width, size_t height, double horizontal_fov_deg, double vertical_fov_deg)
 Render a simulated camera view from cached map tiles.
static int image_mock_transform_locked (const char *filename, const union dc_shot_union *shot)
 Apply simulated attitude to the existing fixture JPEG.
static bool map_project (double rotation[3][3], double forward, double right, double altitude_pixels, double center_x, double center_y, double *map_x, double *map_y)
 Intersect a camera ray with a local flat ground plane.
int image_mock_map (const char *filename, const char *cache_directory, const union dc_shot_union *shot, size_t width, size_t height, double horizontal_fov_deg, double vertical_fov_deg)
 Render a map-backed simulated exposure.
int image_mock_transform (const char *filename, const union dc_shot_union *shot)
 Rewrite a local test JPEG to simulate the shot attitude.
static void transform_jpeg_message (j_common_ptr state, int level)
 Check marker bounds before forwarding a libjpeg diagnostic.

Variables

static struct image_mock_workspace workspace
static pthread_mutex_t workspace_mutex = PTHREAD_MUTEX_INITIALIZER

Detailed Description

Deterministic attitude-based JPEG transform used by local USHER simulation.

Definition in file image_mock_transform.c.

Macro Definition Documentation

◆ ANGLE_BFP_SCALE

#define ANGLE_BFP_SCALE   4096.0

Definition at line 40 of file image_mock_transform.c.

◆ COVER_SAFETY_FACTOR

#define COVER_SAFETY_FACTOR   0.999

Definition at line 52 of file image_mock_transform.c.

◆ FOCAL_LENGTH_FACTOR

#define FOCAL_LENGTH_FACTOR   0.9

Definition at line 46 of file image_mock_transform.c.

◆ IMAGE_MOCK_MAX_DIMENSION

#define IMAGE_MOCK_MAX_DIMENSION   8192U

Definition at line 53 of file image_mock_transform.c.

◆ IMAGE_MOCK_MAX_PIXELS

#define IMAGE_MOCK_MAX_PIXELS   (2028U * 1520U)

Definition at line 54 of file image_mock_transform.c.

◆ IMAGE_MOCK_RGB_CAPACITY

#define IMAGE_MOCK_RGB_CAPACITY   ((size_t)IMAGE_MOCK_MAX_PIXELS * JPEG_COMPONENTS)

Definition at line 55 of file image_mock_transform.c.

◆ JPEG_COMPONENTS

#define JPEG_COMPONENTS   3U

Definition at line 44 of file image_mock_transform.c.

◆ JPEG_QUALITY

#define JPEG_QUALITY   95

Definition at line 45 of file image_mock_transform.c.

◆ MAP_MOSAIC_CAPACITY

#define MAP_MOSAIC_CAPACITY   ((size_t)MAP_MOSAIC_DIMENSION * MAP_MOSAIC_DIMENSION * JPEG_COMPONENTS)

Definition at line 58 of file image_mock_transform.c.

◆ MAP_MOSAIC_DIMENSION

#define MAP_MOSAIC_DIMENSION   (3U * MAP_TILE_SIZE)

Definition at line 57 of file image_mock_transform.c.

◆ MAP_TILE_SIZE

#define MAP_TILE_SIZE   256U

Definition at line 56 of file image_mock_transform.c.

◆ near_horizon_case_black

#define near_horizon_case_black   0

Definition at line 61 of file image_mock_transform.c.

◆ near_horizon_combined_tilt_deg

#define near_horizon_combined_tilt_deg   70.0

Definition at line 73 of file image_mock_transform.c.

◆ near_horizon_pitch_deg

#define near_horizon_pitch_deg   75.0

Definition at line 69 of file image_mock_transform.c.

◆ near_horizon_roll_deg

#define near_horizon_roll_deg   75.0

Definition at line 65 of file image_mock_transform.c.

◆ POSITION_BFP_SCALE

#define POSITION_BFP_SCALE   256.0

Definition at line 42 of file image_mock_transform.c.

◆ PROJECTION_EPSILON

#define PROJECTION_EPSILON   1e-9

Definition at line 47 of file image_mock_transform.c.

◆ PROJECTION_FOV_SAMPLES

#define PROJECTION_FOV_SAMPLES   192

Definition at line 49 of file image_mock_transform.c.

◆ PROJECTION_MIN_DEPTH

#define PROJECTION_MIN_DEPTH   1e-4

Definition at line 48 of file image_mock_transform.c.

◆ PROJECTION_MIN_RAY_SCALE

#define PROJECTION_MIN_RAY_SCALE   1e-4

Definition at line 51 of file image_mock_transform.c.

◆ PROJECTION_REFINE_STEPS

#define PROJECTION_REFINE_STEPS   48

Definition at line 50 of file image_mock_transform.c.

◆ RAD_TO_DEG

#define RAD_TO_DEG   57.29577951308232

Definition at line 43 of file image_mock_transform.c.

◆ SPEED_BFP_SCALE

#define SPEED_BFP_SCALE   524288.0

Definition at line 41 of file image_mock_transform.c.

Function Documentation

◆ bilinear_sample_rgb()

void bilinear_sample_rgb ( const struct decoded_image * image,
double source_x,
double source_y,
unsigned char output[JPEG_COMPONENTS] )
static

Sample the RGB raster at an in-bounds fractional position.

Parameters
imageSource RGB raster.
source_xFractional pixel column in the valid raster range.
source_yFractional pixel row in the valid raster range.
[out]outputThree-byte RGB sample.

Interpolate channel values along each axis and collapse the neighbor to the edge pixel on the last row or column.

Definition at line 1054 of file image_mock_transform.c.

◆ build_rotation()

void build_rotation ( double roll_rad,
double pitch_rad,
double yaw_rad,
double rotation[3][3] )
static

Construct the body-to-north/east/down attitude rotation.

Parameters
roll_radRoll about the forward axis, in radians.
pitch_radPitch about the right axis, in radians.
yaw_radHeading rotation about the down axis, in radians.
[out]rotationRow-major 3 by 3 rotation.

Compose yaw, pitch, and roll in that order. The map renderer uses the forward mapping; the fixture warp uses its transpose.

Definition at line 802 of file image_mock_transform.c.

◆ compute_projection_fit()

int compute_projection_fit ( const struct decoded_image * source,
double rotation[3][3],
double focal_length,
double center_x,
double center_y,
struct projection_fit * fit )
static

Find a fitted projection with low effective zoom.

Parameters
sourceSource raster descriptor.
rotationAttitude rotation.
focal_lengthFocal length in pixels.
center_xPrincipal point column.
center_yPrincipal point row.
[out]fitBest candidate found by the bounded search.
Returns
Zero if a candidate was found, or -1 if none was usable.

Sample ray scales on a logarithmic grid, then refine around the best candidate. This bounds search work without claiming a global optimum.

Definition at line 902 of file image_mock_transform.c.

◆ compute_projection_fit_at_scale()

int compute_projection_fit_at_scale ( const struct decoded_image * source,
double rotation[3][3],
double focal_length,
double center_x,
double center_y,
double ray_scale,
struct projection_fit * fit )
static

Fit one projected destination rectangle into the source raster.

Parameters
sourceSource raster descriptor.
rotationAttitude rotation.
focal_lengthFocal length in pixels.
center_xPrincipal point column.
center_yPrincipal point row.
ray_scaleCandidate field-of-view contraction.
[out]fitSampling scale and offsets; use only on success.
Returns
Zero for a usable fit, or -1 for a singular or degenerate projection.

Measure the projected corner bounds and fit both axes with a common scale to avoid stretching. Preserve a full-scale fit that is already covered; otherwise center the bounds with a numerical margin.

Definition at line 985 of file image_mock_transform.c.

◆ create_black_frame()

int create_black_frame ( const char * filename)
static

Replace the fixture with a black JPEG of the same dimensions.

Parameters
filenameFixture JPEG path.
Returns
Zero on replacement, or -1 on header, codec, or I/O failure.

Read only the original header: near-horizon black frames do not need any source pixels.

Definition at line 772 of file image_mock_transform.c.

◆ decode_jpeg()

int decode_jpeg ( FILE * input,
struct decoded_image * image )
static

Decode bounded RGB scanlines from an open JPEG stream.

Parameters
inputJPEG stream positioned at the start of the image.
[in,out]imageDestination descriptor; a null pixel buffer selects the shared source buffer. A supplied buffer must fit the image.
Returns
Zero for a complete decode, or -1 on failure; discard partial output.

Validate both header and output dimensions before indexing the RGB buffer. The caller holds the workspace mutex and owns the input stream.

Definition at line 546 of file image_mock_transform.c.

◆ dimensions_fit()

bool dimensions_fit ( size_t width,
size_t height )
static

Check that an image can fit the bounded RGB workspace.

Parameters
widthPixel columns.
heightPixel rows.
Returns
True for dimensions of at least two pixels within axis and area limits.

Test area by division so a malformed header cannot overflow the check.

Definition at line 494 of file image_mock_transform.c.

◆ encode_jpeg()

int encode_jpeg ( FILE * output,
const struct decoded_image * image )
static

Encode a bounded interleaved RGB image at the simulation quality setting.

Parameters
outputOpen output stream, closed by the caller.
imagePopulated RGB image descriptor.
Returns
Zero on completion, or -1 for an invalid image or codec failure.

Reuse the locked encoder workspace. Publication is the caller's responsibility: a failed encode may leave partial output on the stream.

Definition at line 606 of file image_mock_transform.c.

◆ image_mock_map()

int image_mock_map ( const char * filename,
const char * cache_directory,
const union dc_shot_union * shot,
size_t width,
size_t height,
double horizontal_fov_deg,
double vertical_fov_deg )

Render a map-backed simulated exposure.

Parameters
filenameDestination JPEG path.
cache_directoryLocal map tile cache root.
shotTrigger containing position, attitude and AGL.
widthOutput columns.
heightOutput rows.
horizontal_fov_degHorizontal field of view in degrees.
vertical_fov_degVertical field of view in degrees.
Returns
Zero on publication, or -1 on lock, geometry, cache, or I/O failure.

Serialize rendering with fixture transforms because both reuse the same codec and pixel workspace.

Definition at line 186 of file image_mock_transform.c.

◆ image_mock_map_locked()

int image_mock_map_locked ( const char * filename,
const char * cache_directory,
const union dc_shot_union * shot,
size_t width,
size_t height,
double horizontal_fov_deg,
double vertical_fov_deg )
static

Render a simulated camera view from cached map tiles.

Parameters
filenameDestination JPEG path.
cache_directoryRoot of the local map tile cache.
shotTrigger containing the position, attitude, and height above ground.
widthOutput width in pixels.
heightOutput height in pixels.
horizontal_fov_degHorizontal field of view in degrees.
vertical_fov_degVertical field of view in degrees.
Returns
Zero on publication, or -1 on invalid geometry, missing data, or I/O failure.

With the workspace mutex held, project the image footprint onto the zoom-18 map, load its required tiles, and inverse-sample the footprint. Reject views outside the bounded tile workspace rather than filling gaps.

Definition at line 215 of file image_mock_transform.c.

◆ image_mock_transform()

int image_mock_transform ( const char * filename,
const union dc_shot_union * shot )

Rewrite a local test JPEG to simulate the shot attitude.

Parameters
filenameWritable path to the JPEG to transform in place.
shotFlight pose containing fixed-point roll, pitch, yaw, and position fields.
Returns
IMAGE_MOCK_TRANSFORM_APPLIED, IMAGE_MOCK_TRANSFORM_SKIPPED, or -1 on failure.

The transform uses a perspective projection and an atomic temporary-file rename so consumers never observe a partial JPEG. Near-horizon frames are skipped or synthesized by configured policy because planar image projection becomes numerically untrustworthy there.

Warning
This is simulation evidence only; it does not model a calibrated physical camera.

Definition at line 346 of file image_mock_transform.c.

◆ image_mock_transform_locked()

int image_mock_transform_locked ( const char * filename,
const union dc_shot_union * shot )
static

Apply simulated attitude to the existing fixture JPEG.

Parameters
filenameFixture JPEG to replace if a transform is applied.
shotTrigger containing fixed-point aircraft attitude.
Returns
Applied or skipped status, or -1 on failure.

With the workspace mutex held, select the configured horizon policy before full decode. Skip an effectively identity transform to avoid an unnecessary lossy JPEG re-encode.

Definition at line 367 of file image_mock_transform.c.

◆ is_near_horizon()

bool is_near_horizon ( double roll_rad,
double pitch_rad )
static

Apply both axis-specific and combined near-horizon limits.

Parameters
roll_radAircraft roll in radians.
pitch_radAircraft pitch in radians.
Returns
True if any configured tilt threshold is reached.

The down-axis cosine combines roll and pitch, catching attitudes where neither axis alone reaches its limit. Clamp it before inverse cosine.

Definition at line 475 of file image_mock_transform.c.

◆ map_project()

bool map_project ( double rotation[3][3],
double forward,
double right,
double altitude_pixels,
double center_x,
double center_y,
double * map_x,
double * map_y )
static

Intersect a camera ray with a local flat ground plane.

Parameters
rotationBody-to-north/east/down rotation.
forwardForward component of the body ray, with unit down component.
rightRightward component of that ray.
altitude_pixelsHeight above the plane at the local map scale.
center_xWorld pixel column below the aircraft.
center_yWorld pixel row below the aircraft.
[out]map_xProjected world pixel column on success.
[out]map_yProjected world pixel row on success.
Returns
True for a finite intersection in front of the camera.

Divide by the ray's downward component to intersect the plane. Negate north when converting to image rows, which increase southward.

Definition at line 162 of file image_mock_transform.c.

◆ mirror_coordinate()

double mirror_coordinate ( double coordinate,
size_t extent )
static

Reflect a sample coordinate into the source image.

Parameters
coordinateFinite source position, possibly outside the image.
extentAxis length, at least two pixels.
Returns
A reflected coordinate in [0, extent - 1].

Use a triangle wave across repeated reflections so the fallback has no hard seam caused by wrapping from one edge to the opposite edge.

Definition at line 754 of file image_mock_transform.c.

◆ project_point()

bool project_point ( double rotation[3][3],
double focal_length,
double center_x,
double center_y,
double ray_scale,
double destination_x,
double destination_y,
double * source_x,
double * source_y )
static

Map a destination pixel back into the fixture JPEG.

Parameters
rotationAttitude rotation, applied here by its transpose.
focal_lengthPinhole focal length in pixels.
center_xPrincipal point column.
center_yPrincipal point row.
ray_scaleField-of-view contraction applied before rotation.
destination_xOutput pixel column.
destination_yOutput pixel row.
[out]source_xProjected source column on success.
[out]source_yProjected source row on success.
Returns
True for a finite projection with sufficient positive depth.

Use inverse mapping to avoid holes between forward-projected pixels. The caller still needs to check source raster bounds.

Definition at line 838 of file image_mock_transform.c.

◆ projection_corners_valid()

bool projection_corners_valid ( const struct decoded_image * source,
double rotation[3][3],
double focal_length,
double center_x,
double center_y,
double ray_scale )
static

Check for a horizon crossing in the candidate projection.

Parameters
sourceImage descriptor defining the candidate raster dimensions.
rotationAttitude rotation.
focal_lengthFocal length in pixels.
center_xPrincipal point column.
center_yPrincipal point row.
ray_scaleCandidate field-of-view contraction.
Returns
True if each corner has a finite, positive-depth projection.

Depth is affine in destination coordinates, so corner checks bound the depth over the whole rectangle. They do not check image coverage.

Definition at line 869 of file image_mock_transform.c.

◆ read_jpeg_dimensions()

int read_jpeg_dimensions ( FILE * input,
struct decoded_image * image )
static

Read bounded image dimensions without decoding pixels.

Parameters
inputOpen JPEG stream positioned at the start of the image.
[out]imageDescriptor whose width and height are set on success.
Returns
Zero on success, or -1 for a codec or dimension error.

The black-frame fallback needs the original size only. Reuse the locked decoder workspace and leave stream ownership with the caller.

Definition at line 509 of file image_mock_transform.c.

◆ replace_image_atomically()

int replace_image_atomically ( const char * filename,
const struct decoded_image * image )
static

Publish a complete simulated JPEG in place of its fixture.

Parameters
filenameFinal JPEG path.
imageRGB raster to encode.
Returns
Zero on replacement, or -1 on an encode or filesystem error.

Encode under a temporary sibling name so readers of the final path do not see a partially written JPEG.

Definition at line 1086 of file image_mock_transform.c.

◆ transform_jpeg_error_exit()

void transform_jpeg_error_exit ( j_common_ptr jpeg_info)
static

Redirect a fatal libjpeg error to the active codec operation.

Parameters
jpeg_infoCodec state with this module's installed error manager.

The codec caller owns cleanup at its recovery point; the callback does not return and must not run without an active recovery frame.

Definition at line 447 of file image_mock_transform.c.

◆ transform_jpeg_message()

void transform_jpeg_message ( j_common_ptr state,
int level )
static

Check marker bounds before forwarding a libjpeg diagnostic.

Parameters
stateCodec state with this module's installed error manager.
levellibjpeg diagnostic level.

Preserve the installed diagnostic behavior for accepted input. A marker rejected by the guard takes the codec's fatal recovery path.

Definition at line 460 of file image_mock_transform.c.

◆ transform_pixels()

int transform_pixels ( const struct decoded_image * source,
struct decoded_image * destination,
double roll_rad,
double pitch_rad,
double yaw_rad,
bool synthesize_terrain )
static

Resample a fixture into a camera view at the supplied attitude.

Parameters
sourceDecoded fixture RGB raster.
[out]destinationSeparate output raster with caller-provided storage.
roll_radAircraft roll in radians.
pitch_radAircraft pitch in radians.
yaw_radAircraft yaw in radians.
synthesize_terrainInitially allow mirrored terrain beyond the fixture.
Returns
IMAGE_MOCK_TRANSFORM_APPLIED on success, or -1 on failure.

Fit a borderless crop when possible. For the near-horizon fallback, reflect out-of-bounds samples instead of claiming the fixture covers the view. In both cases inverse-map the destination and sample the fixture bilinearly.

Definition at line 659 of file image_mock_transform.c.

Variable Documentation

◆ workspace

struct image_mock_workspace workspace
static

Definition at line 109 of file image_mock_transform.c.

◆ workspace_mutex

pthread_mutex_t workspace_mutex = PTHREAD_MUTEX_INITIALIZER
static

Definition at line 110 of file image_mock_transform.c.