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
-
input Original clean JPEG. output New derivative path. profile Validated profile. cache Optional 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
-
state Codec 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
-
state Codec state carrying the installed JpegError. level libjpeg 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
-
value JSON field. name Field name used in diagnostics. minimum Inclusive lower bound. maximum Inclusive 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
-
path Input path. maximum Maximum 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
-
path JPEG path. tile True for a cache tile (must be exactly 256x256); false for a source frame. budget Maximum permitted working bytes. header Optional destination for encoder facts used by –measure. decode_pixels False 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_pixelsis 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
-
path USHER_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
-
metadata EXIF from the clean input JPEG. [out] geometry MIMIC 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()
|
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
-
input Unmodified clean RGB source (may be empty when cache_pathis set andsource_sizesupplies the input dimensions).shot Validated flight pose. geometry Source-camera geometry. profile Validated lens/effect parameters. cache_path Optional offline tile-cache directory. resources Active worker resource policy. source_size Optional clean-input dimensions when inputwas 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
-
metadata EXIF object to update. ifd Destination directory. tag EXIF tag identifier. format EXIF storage format. components Number 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
-
valid Condition to enforce. message Diagnostic copied into the exception.
- Exceptions
-
std::runtime_error If validis 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
-
valid Condition to enforce. message Diagnostic copied into the exception.
- Exceptions
-
std::runtime_error If validis 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()
|
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()
|
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()
|
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
-
metadata EXIF object to update. tag EXIF measurement tag. value Measurement value. denominator Decimal scale used to preserve useful precision. signed_value Select 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
-
metadata EXIF object to update. ifd Destination directory. tag EXIF tag identifier. text Text bytes. undefined Use 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()
|
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
-
metadata Parsed EXIF object. ifd EXIF directory. tag Tag 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
-
field Reference-channel ray field. pose Shot motion, vibration and shutter model. width Output width. height Output height. maximum Profile 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
-
output Destination, which is never the clean input. image RGB derivative. quality Profile JPEG quality. metadata EXIF payload to retain and extend.
Definition at line 477 of file camera_lens.cpp.
Variable Documentation
◆ lens_inverse_iterations
|
constexpr |
OpenCV's iterative Brown inversion has a hard work ceiling.
Definition at line 98 of file camera_lens.cpp.
◆ lens_polish_passes
|
constexpr |
Forward-model correction passes and target after OpenCV inversion.
Definition at line 100 of file camera_lens.cpp.
◆ lens_polish_tolerance_px
|
constexpr |
Definition at line 101 of file camera_lens.cpp.
◆ maximum_exif_payload_bytes
|
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
|
constexpr |
Reject pathological dimensions before allocating decoder or OpenCV buffers.
Definition at line 89 of file camera_lens.cpp.
◆ maximum_mock_pixels
|
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
|
constexpr |
Fisheye/Brown inversion must round-trip within a tenth of one pixel.
Definition at line 96 of file camera_lens.cpp.
◆ mib
|
constexpr |
Binary-size unit used by file and memory bounds.
Definition at line 83 of file camera_lens.cpp.
◆ pi
|
constexpr |
Angle conversion shared by pose and calibration calculations.
Definition at line 81 of file camera_lens.cpp.
◆ ray_grid_initial_step
|
constexpr |
First exact-inverse node spacing; halved until interpolation is verified.
Definition at line 103 of file camera_lens.cpp.
◆ ray_interpolation_tolerance_px
|
constexpr |
Maximum verified ray interpolation error, in output pixels.
Definition at line 105 of file camera_lens.cpp.
◆ temporal_sample_spacing_px
|
constexpr |
Maximum ground motion between neighbouring exposure samples, in pixels.
Definition at line 107 of file camera_lens.cpp.
◆ tile_cache_entries
|
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.