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
camera_lens_detail Namespace Reference

Data Structures

struct  FileCloser
struct  JpegError
struct  Decoder
 Own decoder state across libjpeg's nonlocal error return. More...
struct  JpegHeader
 Encoder facts of a decoded JPEG, used to calibrate profiles. More...
struct  Encoder
 Own encoder state independently of the output stream. More...
struct  TemporaryOutput
 Own an unpublished derivative and its temporary sibling path. More...
struct  Resources
struct  Bounds
class  TileCache
struct  Lens
class  RayField
struct  Pose
struct  Rendered
struct  TemporalSampling
struct  Development
struct  RowSamplePose
struct  SourcePinhole

Typedefs

using Json = usher_cv_json::Value
using File = std::unique_ptr<FILE, FileCloser>

Functions

void require (bool valid, const char *message)
 Route a failed precondition to the CLI's diagnostic handler.
void require (bool valid, const std::string &message)
 Route a failed precondition to the CLI's diagnostic handler.
double number (const Json &value, const std::string &name, double minimum, double maximum)
File open_regular (const std::string &path, size_t maximum)
Json read_profile (const char *path)
void jpeg_failure (j_common_ptr state)
 Return a fatal libjpeg error to the active codec recovery point.
void jpeg_message (j_common_ptr state, int level)
 Enforce JPEG marker bounds before normal message handling.
cv::Mat read_jpeg (const std::string &path, bool tile, size_t budget, JpegHeader *header=nullptr, bool decode_pixels=true)
void write_jpeg (const std::string &output, const cv::Mat &image, int quality, const exif_document *metadata)
std::string tag_text (const exif_document *metadata, exif_directory ifd, uint16_t tag)
unsigned char * replace_tag (exif_document *metadata, exif_directory ifd, uint16_t tag, exif_format format, size_t components)
void set_text (exif_document *metadata, exif_directory ifd, uint16_t tag, const std::string &text, bool undefined=false)
void set_rational (exif_document *metadata, uint16_t tag, double value, unsigned denominator, bool signed_value=false)
Json read_shot (const exif_document *metadata, Json &geometry)
const std::array< float, 256 > & srgb_decoding ()
 8-bit sRGB to linear-light lookup, built once.
TemporalSampling temporal_sampling (const RayField &field, const Pose &pose, int width, int height, int maximum)
 Choose the fewest odd exposure samples that resolve motion blur.
const std::array< unsigned char, 65536 > & srgb_encoding ()
 Linear-light to 8-bit sRGB lookup, built once.
int reflect_101 (int index, int size)
 Reflect-101 index clamp matching OpenCV's BORDER_REFLECT_101.
CAMERA_LENS_SIMD void blur_linear_rgb (cv::Mat &frame, double sigma)
 Parallel separable Gaussian blur on a contiguous CV_32FC3 frame.
float stateless_normal (uint64_t row_seed, int index)
 Stateless zero-mean, unit-variance Irwin-Hall normal sample.
CAMERA_LENS_SIMD void encode_sensor_rows (const cv::Mat &linear, cv::Mat &output, int start_row, int end_row, float well, float read_variance, uint64_t seed, const unsigned char *encode)
 Parallel shot/read noise + sRGB encoding for a row range.
CAMERA_LENS_SIMD void sharpen_luma_rgb (cv::Mat &output, double sharpen)
 Parallel luma-only unsharp mask (sigma = 1 px) preserving chroma.
float sample_tile_channel (const float *const *tile_ptrs, int grid_width, int max_x, int max_y, float map_x, float map_y, int channel)
 Bilinearly sample one channel from a 2D pointer grid of 256x256 linear float32 RGB tiles without assembling a strip mosaic.
void sample_tile_rgb (const float *const *tile_ptrs, int grid_width, int max_x, int max_y, float map_x, float map_y, float &red, float &green, float &blue)
 Bilinearly sample all 3 RGB channels at identical coordinates from a 2D pointer grid of 256x256 linear float32 tiles.
float sample_pinhole_channel (const cv::Mat &source, float map_x, float map_y, int channel)
 Bilinearly sample a linear CV_32FC3 pinhole source image matching OpenCV INTER_LINEAR + BORDER_CONSTANT(0).
CAMERA_LENS_SIMD void compute_strip_bounds_rows (const std::vector< std::unique_ptr< RayField > > &fields, int channels, const RowSamplePose *poses, int samples, int first, int start_row, int end_row, double *min_e, double *max_e, double *min_n, double *max_n, std::atomic< bool > &horizon, std::atomic< bool > &non_finite)
 SIMD-friendly strip ground-bounds and horizon check.
CAMERA_LENS_SIMD void sample_cache_rows (const std::vector< std::unique_ptr< RayField > > &fields, int channels, const RowSamplePose *poses, int samples, int first, int start_row, int end_row, int width, float inv_map_scale, float base_offset_x, float base_offset_y, const float *const *tile_ptrs, int grid_width, int grid_height, float gain, float vignette_scale, cv::Mat &linear)
 Fused parallel strip kernel for map-cache rendering.
Rendered render (const cv::Mat &input, const Json &shot, const Json &geometry, const Json &profile, const std::string &cache_path, const Resources &resources, cv::Size source_size={})
Json emulate (const std::string &input, const std::string &output, const Json &profile, const std::string &cache)

Variables

constexpr double pi = 3.14159265358979323846
constexpr size_t mib = 1024 * 1024
constexpr size_t maximum_exif_payload_bytes = 65533
constexpr unsigned int maximum_image_dimension = 4096
constexpr uint64_t maximum_mock_pixels = 8388608
constexpr size_t tile_cache_entries = 48
constexpr double maximum_reprojection_error_pixels = 0.1
constexpr int lens_inverse_iterations = 30
constexpr int lens_polish_passes = 8
constexpr double lens_polish_tolerance_px = 0.001
constexpr int ray_grid_initial_step = 16
constexpr double ray_interpolation_tolerance_px = 0.02
constexpr double temporal_sample_spacing_px = 0.5

Detailed Description

Internal camera/lens implementation, kept together so the projection path is navigable.

Typedef Documentation

◆ File

using camera_lens_detail::File = std::unique_ptr<FILE, FileCloser>

Definition at line 115 of file camera_lens.cpp.

◆ Json

Definition at line 79 of file camera_lens.cpp.

Function Documentation

◆ blur_linear_rgb()

CAMERA_LENS_SIMD void camera_lens_detail::blur_linear_rgb ( cv::Mat & frame,
double sigma )

Parallel separable Gaussian blur on a contiguous CV_32FC3 frame.

Definition at line 1311 of file camera_lens.cpp.

◆ compute_strip_bounds_rows()

CAMERA_LENS_SIMD void camera_lens_detail::compute_strip_bounds_rows ( const std::vector< std::unique_ptr< RayField > > & fields,
int channels,
const RowSamplePose * poses,
int samples,
int first,
int start_row,
int end_row,
double * min_e,
double * max_e,
double * min_n,
double * max_n,
std::atomic< bool > & horizon,
std::atomic< bool > & non_finite )

SIMD-friendly strip ground-bounds and horizon check.

Definition at line 1695 of file camera_lens.cpp.

◆ emulate()

Json camera_lens_detail::emulate ( const std::string & input,
const std::string & output,
const Json & profile,
const std::string & cache )

Apply one profile and preserve the clean source while writing a tagged derivative.

Parameters
inputOriginal clean JPEG.
outputNew derivative path.
profileValidated profile.
cacheOptional tile-cache directory.
Returns
EXIF evidence plus run-time/resource measurements.

Definition at line 2254 of file camera_lens.cpp.

◆ encode_sensor_rows()

CAMERA_LENS_SIMD void camera_lens_detail::encode_sensor_rows ( const cv::Mat & linear,
cv::Mat & output,
int start_row,
int end_row,
float well,
float read_variance,
uint64_t seed,
const unsigned char * encode )

Parallel shot/read noise + sRGB encoding for a row range.

Definition at line 1417 of file camera_lens.cpp.

◆ jpeg_failure()

void camera_lens_detail::jpeg_failure ( j_common_ptr state)

Return a fatal libjpeg error to the active codec recovery point.

Parameters
stateCodec state carrying the installed JpegError.

The recovery branch converts the failure to an exception; this C callback itself never unwinds the C++ stack.

Definition at line 322 of file camera_lens.cpp.

◆ jpeg_message()

void camera_lens_detail::jpeg_message ( j_common_ptr state,
int level )

Enforce JPEG marker bounds before normal message handling.

Parameters
stateCodec state carrying the installed JpegError.
levellibjpeg diagnostic level.

Forward accepted messages to the saved handler so warning accounting remains available to the decoder.

Definition at line 331 of file camera_lens.cpp.

◆ number()

double camera_lens_detail::number ( const Json & value,
const std::string & name,
double minimum,
double maximum )

Validate one finite numeric profile/geometry field and return its value.

Parameters
valueJSON field.
nameField name used in diagnostics.
minimumInclusive lower bound.
maximumInclusive upper bound.
Returns
Validated number.

Definition at line 137 of file camera_lens.cpp.

◆ open_regular()

File camera_lens_detail::open_regular ( const std::string & path,
size_t maximum )

Open only a bounded regular file; O_NONBLOCK prevents special-file stalls.

Parameters
pathInput path.
maximumMaximum permitted size in bytes.
Returns
Owning stream, or throws a descriptive error.

Definition at line 150 of file camera_lens.cpp.

◆ read_jpeg()

cv::Mat camera_lens_detail::read_jpeg ( const std::string & path,
bool tile,
size_t budget,
JpegHeader * header = nullptr,
bool decode_pixels = true )

Decode one regular JPEG after applying source/tile dimensions and memory checks.

Parameters
pathJPEG path.
tileTrue for a cache tile (must be exactly 256x256); false for a source frame.
budgetMaximum permitted working bytes.
headerOptional destination for encoder facts used by –measure.
decode_pixelsFalse to validate header/dimensions/budget only (used when rendering from a map cache without pinhole source sampling).
Returns
Contiguous RGB pixels, or empty when decode_pixels is false.

Definition at line 367 of file camera_lens.cpp.

◆ read_profile()

Json camera_lens_detail::read_profile ( const char * path)

Fill profile defaults, then validate schema, known keys, types and ranges.

Parameters
pathUSHER_LENS_PROFILE_V1 JSON file.
Returns
Validated profile with all optional defaults materialized.

Definition at line 170 of file camera_lens.cpp.

◆ read_shot()

Json camera_lens_detail::read_shot ( const exif_document * metadata,
Json & geometry )

Validate USHER shot tags and extract the source pose and camera geometry.

Parameters
metadataEXIF from the clean input JPEG.
[out]geometryMIMIC source geometry, or null for an explicit real-camera profile.
Returns
Validated pose values in JSON form.

Definition at line 596 of file camera_lens.cpp.

◆ reflect_101()

int camera_lens_detail::reflect_101 ( int index,
int size )
inline

Reflect-101 index clamp matching OpenCV's BORDER_REFLECT_101.

Definition at line 1303 of file camera_lens.cpp.

◆ render()

Rendered camera_lens_detail::render ( const cv::Mat & input,
const Json & shot,
const Json & geometry,
const Json & profile,
const std::string & cache_path,
const Resources & resources,
cv::Size source_size = {} )

Render bounded image strips and return the assumptions/resource evidence used.

Parameters
inputUnmodified clean RGB source (may be empty when cache_path is set and source_size supplies the input dimensions).
shotValidated flight pose.
geometrySource-camera geometry.
profileValidated lens/effect parameters.
cache_pathOptional offline tile-cache directory.
resourcesActive worker resource policy.
source_sizeOptional clean-input dimensions when input was header-probed without scanline decompression.
Returns
Corrected pixels and quantitative provenance fields.

Definition at line 1850 of file camera_lens.cpp.

◆ replace_tag()

unsigned char * camera_lens_detail::replace_tag ( exif_document * metadata,
exif_directory ifd,
uint16_t tag,
exif_format format,
size_t components )

Replace or create an EXIF entry with zero-initialized storage.

Parameters
metadataEXIF object to update.
ifdDestination directory.
tagEXIF tag identifier.
formatEXIF storage format.
componentsNumber of values.
Returns
Borrowed entry owned by metadata; throws if bounded allocation fails.

Definition at line 541 of file camera_lens.cpp.

◆ require() [1/2]

void camera_lens_detail::require ( bool valid,
const char * message )

Route a failed precondition to the CLI's diagnostic handler.

Parameters
validCondition to enforce.
messageDiagnostic copied into the exception.
Exceptions
std::runtime_errorIf valid is false.

Use exceptions so the job's scoped resources unwind on failure.

Definition at line 122 of file camera_lens.cpp.

◆ require() [2/2]

void camera_lens_detail::require ( bool valid,
const std::string & message )

Route a failed precondition to the CLI's diagnostic handler.

Parameters
validCondition to enforce.
messageDiagnostic copied into the exception.
Exceptions
std::runtime_errorIf valid is false.

Use exceptions so the job's scoped resources unwind on failure.

Definition at line 127 of file camera_lens.cpp.

◆ sample_cache_rows()

CAMERA_LENS_SIMD void camera_lens_detail::sample_cache_rows ( const std::vector< std::unique_ptr< RayField > > & fields,
int channels,
const RowSamplePose * poses,
int samples,
int first,
int start_row,
int end_row,
int width,
float inv_map_scale,
float base_offset_x,
float base_offset_y,
const float *const * tile_ptrs,
int grid_width,
int grid_height,
float gain,
float vignette_scale,
cv::Mat & linear )

Fused parallel strip kernel for map-cache rendering.

Definition at line 1760 of file camera_lens.cpp.

◆ sample_pinhole_channel()

float camera_lens_detail::sample_pinhole_channel ( const cv::Mat & source,
float map_x,
float map_y,
int channel )
inline

Bilinearly sample a linear CV_32FC3 pinhole source image matching OpenCV INTER_LINEAR + BORDER_CONSTANT(0).

Definition at line 1667 of file camera_lens.cpp.

◆ sample_tile_channel()

float camera_lens_detail::sample_tile_channel ( const float *const * tile_ptrs,
int grid_width,
int max_x,
int max_y,
float map_x,
float map_y,
int channel )
inline

Bilinearly sample one channel from a 2D pointer grid of 256x256 linear float32 RGB tiles without assembling a strip mosaic.

Definition at line 1581 of file camera_lens.cpp.

◆ sample_tile_rgb()

void camera_lens_detail::sample_tile_rgb ( const float *const * tile_ptrs,
int grid_width,
int max_x,
int max_y,
float map_x,
float map_y,
float & red,
float & green,
float & blue )
inline

Bilinearly sample all 3 RGB channels at identical coordinates from a 2D pointer grid of 256x256 linear float32 tiles.

Definition at line 1616 of file camera_lens.cpp.

◆ set_rational()

void camera_lens_detail::set_rational ( exif_document * metadata,
uint16_t tag,
double value,
unsigned denominator,
bool signed_value = false )

Store a floating measurement as a bounded EXIF rational.

Parameters
metadataEXIF object to update.
tagEXIF measurement tag.
valueMeasurement value.
denominatorDecimal scale used to preserve useful precision.
signed_valueSelect signed rational format for exposure compensation.

Definition at line 573 of file camera_lens.cpp.

◆ set_text()

void camera_lens_detail::set_text ( exif_document * metadata,
exif_directory ifd,
uint16_t tag,
const std::string & text,
bool undefined = false )

Replace an ASCII or UNDEFINED EXIF text tag and include its terminating byte.

Parameters
metadataEXIF object to update.
ifdDestination directory.
tagEXIF tag identifier.
textText bytes.
undefinedUse EXIF_FORMAT_UNDEFINED (needed for UserComment).

Definition at line 557 of file camera_lens.cpp.

◆ sharpen_luma_rgb()

CAMERA_LENS_SIMD void camera_lens_detail::sharpen_luma_rgb ( cv::Mat & output,
double sharpen )

Parallel luma-only unsharp mask (sigma = 1 px) preserving chroma.

Adding the luma high-pass delta equally to R, G, and B shifts Y while leaving YCrCb chroma differences (R - Y, B - Y) unchanged, avoiding full-frame colour-space splits and merges.

Definition at line 1452 of file camera_lens.cpp.

◆ srgb_decoding()

const std::array< float, 256 > & camera_lens_detail::srgb_decoding ( )

8-bit sRGB to linear-light lookup, built once.

Definition at line 722 of file camera_lens.cpp.

◆ srgb_encoding()

const std::array< unsigned char, 65536 > & camera_lens_detail::srgb_encoding ( )

Linear-light to 8-bit sRGB lookup, built once.

65,536 linear levels keep every round-trip of an 8-bit sRGB code exact while replacing a per-pixel pow() call.

Definition at line 1270 of file camera_lens.cpp.

◆ stateless_normal()

float camera_lens_detail::stateless_normal ( uint64_t row_seed,
int index )
inline

Stateless zero-mean, unit-variance Irwin-Hall normal sample.

Keyed directly by (row_seed, channel_index) so noise is strictly deterministic, unbiased, and bit-identical across any thread count.

Definition at line 1392 of file camera_lens.cpp.

◆ tag_text()

std::string camera_lens_detail::tag_text ( const exif_document * metadata,
exif_directory ifd,
uint16_t tag )

Read EXIF text while preserving the eight-byte UserComment encoding prefix.

Parameters
metadataParsed EXIF object.
ifdEXIF directory.
tagTag identifier.
Returns
Bounded text, or empty when absent.

Definition at line 521 of file camera_lens.cpp.

◆ temporal_sampling()

TemporalSampling camera_lens_detail::temporal_sampling ( const RayField & field,
const Pose & pose,
int width,
int height,
int maximum )

Choose the fewest odd exposure samples that resolve motion blur.

Parameters
fieldReference-channel ray field.
poseShot motion, vibration and shutter model.
widthOutput width.
heightOutput height.
maximumProfile sample ceiling (odd).
Returns
Sample count whose neighbouring-sample ground spacing is at most temporal_sample_spacing_px at every probe, plus the largest blur path.

Probe the corners, edge centres and centre of the frame, follow each ray's ground intersection across the exposure (including vibration reversals) and convert path length to pixels with the local ground sampling distance. Sub-pixel blur therefore costs few samples, while long exposures keep every sample the profile allows.

Definition at line 1225 of file camera_lens.cpp.

◆ write_jpeg()

void camera_lens_detail::write_jpeg ( const std::string & output,
const cv::Mat & image,
int quality,
const exif_document * metadata )

Write a JPEG derivative with EXIF into a same-directory temporary then rename it.

Parameters
outputDestination, which is never the clean input.
imageRGB derivative.
qualityProfile JPEG quality.
metadataEXIF payload to retain and extend.

Definition at line 477 of file camera_lens.cpp.

Variable Documentation

◆ lens_inverse_iterations

int camera_lens_detail::lens_inverse_iterations = 30
constexpr

OpenCV's iterative Brown inversion has a hard work ceiling.

Definition at line 98 of file camera_lens.cpp.

◆ lens_polish_passes

int camera_lens_detail::lens_polish_passes = 8
constexpr

Forward-model correction passes and target after OpenCV inversion.

Definition at line 100 of file camera_lens.cpp.

◆ lens_polish_tolerance_px

double camera_lens_detail::lens_polish_tolerance_px = 0.001
constexpr

Definition at line 101 of file camera_lens.cpp.

◆ maximum_exif_payload_bytes

size_t camera_lens_detail::maximum_exif_payload_bytes = 65533
constexpr

JPEG APP1 segment data maximum (the 16-bit marker length reserves two bytes).

Definition at line 86 of file camera_lens.cpp.

◆ maximum_image_dimension

unsigned int camera_lens_detail::maximum_image_dimension = 4096
constexpr

Reject pathological dimensions before allocating decoder or OpenCV buffers.

Definition at line 89 of file camera_lens.cpp.

◆ maximum_mock_pixels

uint64_t camera_lens_detail::maximum_mock_pixels = 8388608
constexpr

MIMIC fixture guard: 8 megapixels bounds the full-frame software path.

Definition at line 91 of file camera_lens.cpp.

◆ maximum_reprojection_error_pixels

double camera_lens_detail::maximum_reprojection_error_pixels = 0.1
constexpr

Fisheye/Brown inversion must round-trip within a tenth of one pixel.

Definition at line 96 of file camera_lens.cpp.

◆ mib

size_t camera_lens_detail::mib = 1024 * 1024
constexpr

Binary-size unit used by file and memory bounds.

Definition at line 83 of file camera_lens.cpp.

◆ pi

double camera_lens_detail::pi = 3.14159265358979323846
constexpr

Angle conversion shared by pose and calibration calculations.

Definition at line 81 of file camera_lens.cpp.

◆ ray_grid_initial_step

int camera_lens_detail::ray_grid_initial_step = 16
constexpr

First exact-inverse node spacing; halved until interpolation is verified.

Definition at line 103 of file camera_lens.cpp.

◆ ray_interpolation_tolerance_px

double camera_lens_detail::ray_interpolation_tolerance_px = 0.02
constexpr

Maximum verified ray interpolation error, in output pixels.

Definition at line 105 of file camera_lens.cpp.

◆ temporal_sample_spacing_px

double camera_lens_detail::temporal_sample_spacing_px = 0.5
constexpr

Maximum ground motion between neighbouring exposure samples, in pixels.

Definition at line 107 of file camera_lens.cpp.

◆ tile_cache_entries

size_t camera_lens_detail::tile_cache_entries = 48
constexpr

Fixed cache residency avoids turning tile access order into unbounded RAM growth while keeping wide fisheye strip working sets (~35 tiles) resident.

Definition at line 94 of file camera_lens.cpp.