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"
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()
|
static |
Sample the RGB raster at an in-bounds fractional position.
- Parameters
-
image Source RGB raster. source_x Fractional pixel column in the valid raster range. source_y Fractional pixel row in the valid raster range. [out] output Three-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()
|
static |
Construct the body-to-north/east/down attitude rotation.
- Parameters
-
roll_rad Roll about the forward axis, in radians. pitch_rad Pitch about the right axis, in radians. yaw_rad Heading rotation about the down axis, in radians. [out] rotation Row-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()
|
static |
Find a fitted projection with low effective zoom.
- Parameters
-
source Source raster descriptor. rotation Attitude rotation. focal_length Focal length in pixels. center_x Principal point column. center_y Principal point row. [out] fit Best 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()
|
static |
Fit one projected destination rectangle into the source raster.
- Parameters
-
source Source raster descriptor. rotation Attitude rotation. focal_length Focal length in pixels. center_x Principal point column. center_y Principal point row. ray_scale Candidate field-of-view contraction. [out] fit Sampling 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()
|
static |
Replace the fixture with a black JPEG of the same dimensions.
- Parameters
-
filename Fixture 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()
|
static |
Decode bounded RGB scanlines from an open JPEG stream.
- Parameters
-
input JPEG stream positioned at the start of the image. [in,out] image Destination 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()
|
static |
Check that an image can fit the bounded RGB workspace.
- Parameters
-
width Pixel columns. height Pixel 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()
|
static |
Encode a bounded interleaved RGB image at the simulation quality setting.
- Parameters
-
output Open output stream, closed by the caller. image Populated 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
-
filename Destination JPEG path. cache_directory Local map tile cache root. shot Trigger containing position, attitude and AGL. width Output columns. height Output rows. horizontal_fov_deg Horizontal field of view in degrees. vertical_fov_deg Vertical 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()
|
static |
Render a simulated camera view from cached map tiles.
- Parameters
-
filename Destination JPEG path. cache_directory Root of the local map tile cache. shot Trigger containing the position, attitude, and height above ground. width Output width in pixels. height Output height in pixels. horizontal_fov_deg Horizontal field of view in degrees. vertical_fov_deg Vertical 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
-
filename Writable path to the JPEG to transform in place. shot Flight 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()
|
static |
Apply simulated attitude to the existing fixture JPEG.
- Parameters
-
filename Fixture JPEG to replace if a transform is applied. shot Trigger 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()
|
static |
Apply both axis-specific and combined near-horizon limits.
- Parameters
-
roll_rad Aircraft roll in radians. pitch_rad Aircraft 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()
|
static |
Intersect a camera ray with a local flat ground plane.
- Parameters
-
rotation Body-to-north/east/down rotation. forward Forward component of the body ray, with unit down component. right Rightward component of that ray. altitude_pixels Height above the plane at the local map scale. center_x World pixel column below the aircraft. center_y World pixel row below the aircraft. [out] map_x Projected world pixel column on success. [out] map_y Projected 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()
|
static |
Reflect a sample coordinate into the source image.
- Parameters
-
coordinate Finite source position, possibly outside the image. extent Axis 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()
|
static |
Map a destination pixel back into the fixture JPEG.
- Parameters
-
rotation Attitude rotation, applied here by its transpose. focal_length Pinhole focal length in pixels. center_x Principal point column. center_y Principal point row. ray_scale Field-of-view contraction applied before rotation. destination_x Output pixel column. destination_y Output pixel row. [out] source_x Projected source column on success. [out] source_y Projected 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()
|
static |
Check for a horizon crossing in the candidate projection.
- Parameters
-
source Image descriptor defining the candidate raster dimensions. rotation Attitude rotation. focal_length Focal length in pixels. center_x Principal point column. center_y Principal point row. ray_scale Candidate 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()
|
static |
Read bounded image dimensions without decoding pixels.
- Parameters
-
input Open JPEG stream positioned at the start of the image. [out] image Descriptor 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()
|
static |
Publish a complete simulated JPEG in place of its fixture.
- Parameters
-
filename Final JPEG path. image RGB 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()
|
static |
Redirect a fatal libjpeg error to the active codec operation.
- Parameters
-
jpeg_info Codec 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()
|
static |
Check marker bounds before forwarding a libjpeg diagnostic.
- Parameters
-
state Codec state with this module's installed error manager. level libjpeg 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()
|
static |
Resample a fixture into a camera view at the supplied attitude.
- Parameters
-
source Decoded fixture RGB raster. [out] destination Separate output raster with caller-provided storage. roll_rad Aircraft roll in radians. pitch_rad Aircraft pitch in radians. yaw_rad Aircraft yaw in radians. synthesize_terrain Initially allow mirrored terrain beyond the fixture.
- Returns
IMAGE_MOCK_TRANSFORM_APPLIEDon 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
|
static |
Definition at line 109 of file image_mock_transform.c.
◆ workspace_mutex
|
static |
Definition at line 110 of file image_mock_transform.c.