C++ Reference
Image Converter
Class Reference
-
class ImageConverter
The ImageConverter class is the main interface for converting RAW images to ACES format. It provides a high-level API that handles the entire conversion pipeline.
Public Types
-
enum class Status
Status codes for operation results.
Values:
-
enumerator Success
Operation completed successfully.
-
enumerator FileExists
Output file already exists and overwrite is not enabled.
-
enumerator InputFileNotFound
Input file does not exist.
-
enumerator EmptyInputFilename
Empty input filename provided.
-
enumerator FilesystemError
Filesystem error occurred.
-
enumerator OutputDirectoryError
Output directory does not exist and cannot be created.
-
enumerator InvalidPath
Invalid path format.
-
enumerator ConfigurationError
Failed to configure the image reader.
-
enumerator ReadError
Failed to read the image file.
-
enumerator LensCorrectionError
Failed to apply lens correction.
-
enumerator MatrixApplicationError
Failed to apply colour space conversion.
-
enumerator ScaleApplicationError
Failed to apply scale.
-
enumerator CropApplicationError
Failed to apply crop.
-
enumerator WriteError
Failed to save the output file.
-
enumerator DatabaseNotFound
Failed to locate spectral measurements database.
-
enumerator UnknownError
Unknown error.
-
enumerator Success
Public Functions
-
bool apply_crop(OIIO::ImageBuf &dst, const OIIO::ImageBuf &src)
Apply the cropping mode as specified in crop_mode.
- Parameters:
dst – Destination image buffer.
src – Source image buffer, can be the same as
dstfor in-place conversion.
- Returns:
trueif applied successfully.
-
bool apply_crop(OIIO::ImageBuf &dst, const OIIO::ImageBuf &src, OIIO::ROI roi)
Apply the cropping mode as specified in crop_mode.
- Parameters:
dst – Destination image buffer.
src – Source image buffer, can be the same as
dstfor in-place conversion.roi – Ignored. This overload processes the whole image and will be removed in v3.
- Returns:
trueif applied successfully.
-
bool apply_lens_correction(OIIO::ImageBuf &dst, const OIIO::ImageBuf &src)
Apply the lens correction to the image buffer.
- Parameters:
dst – Destination image buffer.
src – Source image buffer, can be the same as
dstfor in-place conversion.
- Returns:
trueif applied successfully.
-
bool apply_matrix(OIIO::ImageBuf &dst, const OIIO::ImageBuf &src)
Apply the colour space conversion matrix (or matrices) to convert the image buffer from the raw camera colour space to ACES.
- Parameters:
dst – Destination image buffer.
src – Source image buffer, can be the same as
dstfor in-place conversion.
- Returns:
trueif applied successfully.
-
bool apply_matrix(OIIO::ImageBuf &dst, const OIIO::ImageBuf &src, OIIO::ROI roi)
Apply the colour space conversion matrix (or matrices) to convert the image buffer from the raw camera colour space to ACES.
- Parameters:
dst – Destination image buffer.
src – Source image buffer, can be the same as
dstfor in-place conversion.roi – Ignored. This overload processes the whole image and will be removed in v3.
- Returns:
trueif applied successfully.
-
bool apply_scale(OIIO::ImageBuf &dst, const OIIO::ImageBuf &src)
Apply the headroom scale to image buffer.
- Parameters:
dst – Destination image buffer.
src – Source image buffer, can be the same as
dstfor in-place conversion.
- Returns:
trueif applied successfully.
-
bool apply_scale(OIIO::ImageBuf &dst, const OIIO::ImageBuf &src, OIIO::ROI roi)
Multiply image buffer pixel values by
settings.headroom * settings.scale.- Parameters:
dst – Destination image buffer.
src – Source image buffer, can be the same as
dstfor in-place conversion.roi – Ignored. This overload processes the whole image and will be removed in v3.
- Returns:
trueif applied successfully.
-
bool configure(const OIIO::ImageSpec &imageSpec, OIIO::ParamValueList &options)
Configures the converter using the requested white balance and colour matrix method, and the metadata of the given OIIO::ImageSpec object. Use this method if you already have an image read from file to save on disk operations.
- Parameters:
imageSpec – An image spec obtained from OIIO::ImageInput or OIIO::ImageBuf.
options – Conversion hints to be passed to OIIO when reading an image file. The list can be pre- or post- updated with other hints, unrelated to the rawtoaces conversion.
- Returns:
trueif configured successfully.
-
bool configure(const std::string &input_filename, OIIO::ParamValueList &options)
Configures the converter using the requested white balance and colour matrix method, and the metadata of the file provided in
input_file. This method loads the metadata from the given image file and initialises the options to give the OIIO raw image reader to decode the pixels.- Parameters:
input_filename – A file name of the raw image file to read the metadata from.
options – Conversion hints to be passed to OIIO when reading an image file. The list can be pre- or post- updated with other hints, unrelated to the rawtoaces conversion.
- Returns:
trueif configured successfully.
-
const std::vector<std::vector<double>> &get_CAT_matrix() const
Get the solved chromatic adaptation transform matrix of the currently processed image. The matrix becomes available after calling either of the two
configuremethods.- Returns:
a reference to the matrix.
-
const std::vector<std::vector<double>> &get_IDT_matrix() const
Get the solved input transform matrix of the currently processed image. The matrix becomes available after calling either of the two
configuremethods.- Returns:
a reference to the matrix.
-
std::vector<std::string> get_supported_cameras() const
Collects all camera models for which spectral sensitivity data is available in the database.
-
std::vector<std::string> get_supported_formats() const
Collects all camera raw formats supported by this version.
-
std::vector<std::string> get_supported_illuminants() const
Collects all illuminants supported by this version.
-
const std::vector<std::vector<double>> &get_transform_matrix() const
Get the solved colour transform matrix applied by
apply_matrixto the current image. The matrix becomes available after calling either of the twoconfiguremethods.- Returns:
a reference to the matrix.
-
const std::vector<double> &get_WB_multipliers() const
Get the solved white balance multipliers of the currently processed image. The multipliers become available after calling either of the two
configuremethods.- Returns:
a reference to the multipliers vector.
-
void init_parser(OIIO::ArgParse &arg_parser)
Initialise the parser object with all the command line parameters used by this tool. The method also sets the help and usage strings. The parser object can be amended by the calling code afterwards if needed. This method is optional, all of the settings above can be modified directly.
- Parameters:
arg_parser – The command line parser object to be updated.
-
bool load_image(const std::string &path, const OIIO::ParamValueList &hints, OIIO::ImageBuf &buffer, OIIO::TypeDesc data_type = OIIO::TypeDesc::FLOAT)
Load an image from a given
pathinto abufferusing thehintscalculated by theconfiguremethod. The hints can be manually modified prior to invoking this method.- Parameters:
path – Path to where the image from.
hints – Conversion hints to be passed to OIIO when reading an image file.
buffer – Destination buffer where the image loaded into.
data_type – Data type of the samples in the destination buffer.
- Returns:
trueif image loaded successfully.
-
bool make_output_path(std::string &path, const std::string &suffix = "_aces")
Make output file path and check if it is writable.
- Parameters:
path – A reference to a variable containing the input file path. The output file path gets generated in-place.
suffix – A suffix to add to the file name.
- Returns:
trueif the file can be written, e.g. the output directory exists, or creating directories is allowed; the file does not exist or overwriting is allowed.
-
bool parse_parameters(const OIIO::ArgParse &arg_parser)
Initialise the converter settings from the command line parser object. Prior to calling this, first initialise the object via
ImageConverter::init_parser(), and callOIIO::ArgParse::parse_args(). This method is optional, all of the settings above can be modified directly.- Parameters:
arg_parser – the command line parser object
- Returns:
trueif parsed successfully
-
bool process_buffer(OIIO::ImageBuf &dst, const OIIO::ImageBuf &src)
A convenience single-call method to process an image buffer. Equivalent to calling
apply_lens_correction,apply_matrix,apply_scale, andapply_cropin sequence.- Parameters:
dst – Destination image buffer.
src – Source image buffer, can be the same as
dstfor in-place conversion.
- Returns:
trueif processed successfully.
-
bool process_image(const std::string &input_filename)
A convenience single-call method to process an image. Equivalent to
make_output_path,configure,load_image,process_buffer, andsave_imagein sequence.- Parameters:
input_filename – Full path to the file to be converted.
- Returns:
trueif processed successfully.
-
bool save_image(const std::string &output_filename, const OIIO::ImageBuf &buf, OIIO::TypeDesc data_type = OIIO::TypeDesc::HALF)
Saves the image into ACES Container.
- Parameters:
output_filename – Full path to the file to be saved.
buf – Image buffer to be saved.
data_type – Data type of the samples to be written out.
- Returns:
trueif saved successfully.
Public Members
-
std::string last_error_message
Error message from the most recent method call that returned false.
-
struct Settings
The structure containing all parameters needed to configure image conversion.
Unnamed Group
-
friend LensCorrectionType operator&(const LensCorrectionType &lhs, const LensCorrectionType &rhs)
Bit-wise operators on lens correction types
-
friend LensCorrectionType operator|(const LensCorrectionType &lhs, const LensCorrectionType &rhs)
-
friend LensCorrectionType &operator|=(LensCorrectionType &lhs, const LensCorrectionType &rhs)
Public Types
-
enum class CropMode
The enumerator containing all supported cropping modes.
Values:
-
enumerator Off
Write out full sensor area.
-
enumerator Soft
Write out full sensor area, mark the crop area as the display window.
-
enumerator Hard
Write out only the crop area.
-
enumerator Off
-
enum class LensCorrectionType
The enumerator containing all supported lens correction types.
Values:
-
enumerator None
-
enumerator Aberration
-
enumerator Distortion
-
enumerator Vignetting
-
enumerator None
-
enum class MatrixMethod
The enumerator containing all supported colour transform matrix calculation methods.
Values:
-
enumerator Auto
Automatically choose the best available matrix method.
If spectral sensitivity data for the camera is available, use
Spectral.Otherwise, fall back to
Metadata.
-
enumerator Spectral
Use the camera spectral sensitivity curves to solve for the colour conversion matrix. In this mode the illuminant is either provided directly in
illuminantifWB_method==WBMethod::Illuminant, or the best illuminant is derived from the white balancing multipliers.
-
enumerator Metadata
Use the metadata provided in the image file. This mode is mostly usable with DNG files, as the information needed for conversion is mandatory in the DNG format.
-
enumerator Adobe
Use the Adobe colour matrix for the camera supplied in LibRaw.
-
enumerator Custom
Specify a full camera RGB to ACES AP0 matrix in
custom_matrix. The matrix is applied directly, without an additional XYZ to ACES conversion. It can be calculated by an external tool.
-
enumerator Auto
-
enum class WBMethod
The enumerator containing all supported white-balancing methods.
Values:
-
enumerator Metadata
Use the metadata provided in the image file. This mode is mostly usable with DNG files, as the information needed for conversion is mandatory in the DNG format.
-
enumerator Illuminant
White balance to a specified illuminant. See the
illuminantproperty for more information on the supported illuminants. This mode can only be used if spectral sensitivities are available for the camera.
-
enumerator Box
Calculate white balance by averaging over a specified region of the image. See
WB_box. In this mode if an empty box is provided, white balancing is done by averaging over the whole image.
-
enumerator Custom
Use custom white balancing multipliers. This mode is useful if the white balancing coefficients are calculated by an external tool.
-
enumerator Metadata
Public Members
-
float adjust_maximum_threshold = 0.75
Automatically lower the linearity threshold provided in the metadata by this scaling factor.
-
bool auto_bright = false
Enable automatic exposure adjustment.
-
std::string bad_pixels_path
A path to the file containing a list of bad bixels in libraw format: a plain text where each line describes a single bad pixel using three numbers separated by whitespace for the column, row and UNIX timestamp.
-
int black_level = -1
If >= 0, override the black level specified in the file metadata.
-
float chromatic_aberration[2] = {1.0f, 1.0f}
Red and blue scale factors for chromatic aberration correction.
-
std::string compression
Output file compression type. Supported options include none, rle, zip, zips, piz, pxr24, b44, b44a, dwaa, dwab, htj2k256, htj2k32. An empty string (the default) writes uncompressed output, as does
none.
-
bool create_dirs = false
Create output directories if they don’t exist.
-
int crop_box[4] = {0, 0, 0, 0}
Apply custom crop. If not specified (all values are zeroes), the default crop is applied, which should match the crop of the in-camera JPEG.
-
float custom_aperture = 0.0f
Aperture (f-number) to be used for lens correction.
-
std::string custom_camera_make
Camera manufacturer name to be used for spectral sensitivity curves lookup.
-
std::string custom_camera_model
Camera model name to be used for spectral sensitivity curves lookup.
-
float custom_focal_length = 0.0f
Focal length to be used for lens correction.
-
float custom_focus_distance = 0.0f
Focus distance to be used for lens correction.
-
std::string custom_lens_make
Lens manufacturer name to be used for lens correction data lookup.
-
std::string custom_lens_model
Lens model name to be used for lens correction data lookup.
-
float custom_matrix[3][3] = {{1, 0, 0}, {0, 1, 0}, {0, 0, 1}}
Custom camera RGB to ACES AP0 matrix to be used when
matrix_method==MatrixMethod::Custom. Applied directly; it must include the complete colour-space transform to ACES AP0. No additional XYZ to ACES conversion is composed.
-
float custom_WB[4] = {1.0, 1.0, 1.0, 1.0}
Custom white balance multipliers to be used when
WB_method==WBMethod::Custom.
-
std::vector<std::string> database_directories
Directory containing rawtoaces spectral sensitivity and illuminant data files. Overrides the default search path and the RAWTOACES_DATA_PATH environment variable.
-
std::string demosaic_algorithm = "AHD"
Demosaicing algorithm. Supported options: ‘linear’, ‘VNG’, ‘PPG’, ‘AHD’, ‘DCB’, ‘DHT’, ‘AAHD.
-
float denoise_threshold = 0
Wavelet denoising threshold.
-
bool disable_cache = false
Disable caching.
-
bool disable_exiftool = false
Disable calling exiftool to fetch missing metadata.
-
int flip = -1
If not -1, override the orientation specified in the metadata. 1..8 correspond to EXIF orientation codes (0 = none, 3 = 180 deg, 6 = 90 deg CCW, 8 = 90 deg CW.)
-
bool half_size = false
Decode the image at half size resolution.
-
int highlight_mode = 0
Highlight recovery mode, as supported by OpenImageIO/Libraw 0 = clip, 1 = unclip, 2 = blend, 3..9 = rebuild.
-
std::string illuminant
An illuminant to use for white balancing and/or colour matrix calculation. Only used when
WB_method==WBMethod::Illuminantandmatrix_method==MatrixMethod::Spectral.An illuminant can be provided as a black body correlated colour temperature, like
3200K; or a D-series illuminant, likeD56; or any other illuminant, in such case it must be present in the data folder.
-
bool keep_diagnostic_attributes = false
Keep the diagnostic attributes in the output exr file. The attributes contain the information about the transforms being applied to the image and start with the prefix
"rta".
-
LensCorrectionType lens_correction_types = LensCorrectionType::None
The requested lens correction types. No correction is requested by default. Combine LensCorrectionType values to enable it.
-
MatrixMethod matrix_method = MatrixMethod::Auto
The selected colour transform matrix calculation method to use for conversion.
-
std::string output_dir
The directory to write the output files to.
-
bool overwrite = false
Allows overwriting existing files.
-
bool require_lens_correction = false
If true, treat lens correction as mandatory. The conversion will fail if any of the correction types above is requested, but rawtoaces is unable to obtain a suitable lens model.
-
int saturation_level = -1
If >= 0, override the saturation level specified in the file metadata.
-
float scale = 1.0f
Additional scaling factor to apply to the pixel values.
-
bool use_timing = false
Log the execution time of each step of image processing.
-
int verbosity = 0
Verbosity level.
-
int WB_box[4] = {0, 0, 0, 0}
Box to use for white balancing when
WB_method==WBMethod::Box. (default = (0,0,0,0) - full image)
Friends
-
friend bool operator&&(const LensCorrectionType &lhs, const LensCorrectionType &rhs)
Convenience operator to simplify testing for enabled flags. Performs
bit-wise andand returns true if not zero.
-
friend LensCorrectionType operator&(const LensCorrectionType &lhs, const LensCorrectionType &rhs)
-
enum class Status
Utility Functions
-
std::vector<std::vector<std::string>> rta::util::collect_image_files(const std::vector<std::string> &paths)
Collect all files from given
pathsinto batches. For each path that is a directory, a batch is created in the returned vector and filled with the file names. Invalid paths are skipped with an error message.First batch is reserved for all paths that are individual files. If no such paths are provided, the first batch will be empty.
- Parameters:
paths – vector of paths to files or directories to process.
- Returns:
vector of batches, where each batch contains files from one input path.
rawtoaces Core
Class Reference
-
struct Spectrum
A data class for storing a spectral curve. Implements a few arithmetic operations and simple reshaping via linear interpolation.
Public Functions
-
Spectrum(double value = 0, const Shape &shape = ReferenceShape)
The
Spectrumobject constructor. Allocates as many spectral samples as required for theshapeparameter, and initialises them withvalue.- Parameters:
value – the value to initialise the spectral samples with.
shape – the shape of the spectral data to create. Pass a shape with zero step, like
rta::core::Spectrum::EmptyShapeto avoid allocating any samples.
-
void reshape()
Reshape the
Spectrumobject to the reference shape (rta::core::Spectrum::ReferenceShape).
Public Members
-
std::vector<double> values
The spectral samples storage.
Public Static Attributes
Friends
-
struct Shape
The spectral data sampling information. Only regular step data sets are currently supported. All values are wavelength in nanometers.
Public Functions
-
Spectrum(double value = 0, const Shape &shape = ReferenceShape)
-
struct SpectralData
A data-class for storing spectral data, based on the file format used in rawtoaces-data.
Public Types
-
typedef std::pair<std::string, Spectrum> SpectralChannel
A spectral channel, contains a channel name and the corresponding
Spectrumobject. Can represent a single curve in an RGB or XYZ triplet.
-
typedef std::vector<SpectralChannel> SpectralSet
A spectral set, may contain one or multiple spectral channels, like an RGB or XYZ triplet.
Public Functions
-
Spectrum &get(std::string set_name, std::string channel_name)
A convenience method returning the
Spectrumof a given channel name in the given data set.- Parameters:
set_name – the set name to search for.
channel_name – the channel name to search for.
- Throws:
std::invalid_argument – if the set or channel is not found (non-const overload).
- Returns:
the
Spectrumobject reference if found.
-
bool load(const std::string &path, bool reshape = true, std::string *error_message = nullptr)
Loads spectral data from a given file path.
- Parameters:
path – a path to the file to load data from
reshape – if set to
true, the data will be reshaped to the reference shape (rta::core::Spectrum::ReferenceShape).error_message – an optional destination for any error message that occurred during loading.
- Returns:
trueif loaded successfully.
-
Spectrum &operator[](std::string name)
A convenience operator returning the
Spectrumof a given channel name in the “main” data set.- Parameters:
name – the channel name in the “main” data set to return.
- Throws:
std::invalid_argument – if the requested channel is not found (non-const overload; the const overload requires the channel to exist).
- Returns:
the
Spectrumobject corresponding to the given channel name.
Public Members
-
std::string bandwidth_corrected
Whether bandwidth correction has been applied to the spectral data.
-
std::string bandwidth_FWHM
Spectro-radiometer full-width at half-maximum bandwidth in nm.
-
std::string comments
Additional information for the spectral dataset.
-
std::string creation_date
Document creation date expressed as per RFC 3339 - Date and Time on the Internet: Timestamps, e.g.
2017-01-01T12:00:00Z.
-
std::map<std::string, SpectralSet> data
The spectral data storage.
-
std::string description
Description of the spectral dataset.
-
std::string document_creator
Creator of the document, e.g. company, individual, laboratory, etc.
-
std::string laboratory
Laboratory or company that performed the measurements.
-
std::string license
Usage license of the document, e.g. “CC-BY-NC-ND”.
-
std::string manufacturer
Manufacturer of the device being tested.
-
std::string measurement_equipment
Measurement equipment used to test the device.
-
std::string model
Model of the device being tested.
-
std::string reflection_geometry
Reflection geometry attributes as per CIE 15:2004. Required if units is reflectance.
-
std::string transmission_geometry
Transmission geometry attributes as per CIE 15:2004. Required if units is transmittance.
-
std::string type
Type of the spectral dataset.
-
std::string unique_identifier
Generated unique identifier for the document, e.g. SHA256.
-
std::string units
Unit or quantity of measurement for the spectral dataset.
-
typedef std::pair<std::string, Spectrum> SpectralChannel
-
struct Metadata
DNG metadata required to calculate an input transform.
Public Members
-
double baseline_exposure = 0.0
Exposure calibration multiplier.
-
struct Calibration calibration[2]
Calibration datasets. Currently two sets are supported.
-
std::vector<double> neutral_RGB
Neutral RGB values. The colour channels in the camera RGB colour space representing a neutral colour.
-
struct Calibration
A calibration data set structure. Contains calibration matrices for a given light source.
Public Members
-
std::vector<double> camera_calibration_matrix
Camera calibration matrix.
-
unsigned short illuminant = 0
EXIF light source tag. The values [0..22] encode predefined light sources, the extended values (≥32768) can be used to encode an arbitrary CCT.
-
std::vector<double> XYZ_to_RGB_matrix
XYZ to camera RGB colour transform matrix.
-
std::vector<double> camera_calibration_matrix
-
double baseline_exposure = 0.0
-
class TransformSolver
Base class for a colour space transform solver.
Subclassed by rta::core::MetadataSolver, rta::core::SpectralSolver, rta::core::XYZD65Solver
Public Functions
-
TransformSolver()
Initialise the initial state of the solver. Sets the
transform_matrixto an identity matrix and verbosity level to zero for silent operation.
-
virtual ~TransformSolver() = default
-
virtual bool calculate_transform() = 0
Calculate the transform matrix. Each subclass must implement this method.
- Returns:
trueon success.
Public Members
-
std::string last_error_message
Error message from the most recent method call that returned false.
-
std::vector<std::vector<double>> transform_matrix
3×3 colour transform matrix populated by
calculate_transform()(starts as identity from the baseTransformSolverconstructor).
-
int verbosity
Verbosity level.
-
TransformSolver()
-
class SpectralSolver : public rta::core::TransformSolver
Solve an input transform using spectral sensitivity curves of a camera.
Public Functions
-
SpectralSolver(const std::vector<std::string> &search_directories = {})
Initialize SpectralSolver with database search path. Sets white balance multipliers to neutral (1, 1, 1) and relies on the base
TransformSolverconstructor for an identitytransform_matrixand zero verbosity. Takes the database search path as an optional parameter for finding spectral data files.- Parameters:
search_directories – optional database search path for spectral data files
-
bool calculate_IDT_matrix()
Calculate an input transform matrix using curve fitting optimization. This function computes the optimal IDT matrix by comparing camera RGB responses with target XYZ values across all training patches. The
camera,illuminant,observerandtraining_datahave to be configured prior to this call.- Returns:
trueif calculated successfully,falseotherwise- Pre:
camera, illuminant, observer, and training_data must be properly loaded
-
virtual bool calculate_transform() override
Solve the spectral IDT via curve fitting and store the 3×3 matrix in
transform_matrix. Compares camera RGB responses with target XYZ values across training patches. Requirescamera,illuminant,observer, andtraining_datato be configured prior to this call.- Returns:
trueif calculated successfully,falseotherwise- Pre:
camera, illuminant, observer, and training_data must be properly loaded
-
bool calculate_WB()
Calculate the white-balance multipliers for the given configuration. This function computes RGB white balance multipliers by integrating camera spectral sensitivity with illuminant power spectrum. The multipliers normalize the camera response to achieve proper white balance under the specified illuminant conditions. The
cameraandilluminantdata have to be configured prior to this call.- Returns:
trueif calculated successfully,falseotherwise- Pre:
camera and illuminant data must be properly loaded
-
bool collect_aliases(const std::string &type, std::map<std::string, std::string> &make_aliases, std::map<std::string, std::map<std::string, std::pair<std::string, std::string>>> &model_aliases) const
A helper method collecting aliases of a given type from the database. This function searches through the configured search directories to find all make/model aliases of the specified type (“camera” is the only currently supported type).
- Parameters:
type – type of the aliases to search for (e.g., “camera”)
make_aliases – output parameter referencing the map to be filled with the found make aliases.
model_aliases – output parameter referencing the map to be filled with the found model aliases.
- Returns:
trueon success.
-
std::vector<std::string> collect_data_files(const std::string &type) const
A helper method collecting spectral data files of a given type from the database. This function searches through the configured search directories to find all spectral data files matching the specified type (e.g., “camera”, “illuminant”). It searches for type subdirectories at the top level of each directory and returns JSON files matching the type.
- Parameters:
type – data type of the files to search for (e.g., “camera”, “illuminant”, “cmf”)
- Returns:
a collection of file paths found in the database
-
bool find_camera(const std::string &make, const std::string &model)
Load spectral sensitivity data for a camera by searching the database. This function searches through camera data files in the database to find a match for the specified camera manufacturer and model. It loads the spectral sensitivity data into the camera member variable.
- Parameters:
make – the camera make to search for
model – the camera model to search for
- Returns:
trueif loaded successfully,falseotherwise
-
bool find_illuminant(const std::string &type)
Find spectral power distribution data of an illuminant of the given type. This function can handle both built-in illuminant types (e.g., “d55”, “3200k”) and custom illuminants stored in the database. For built-in types, it generates the spectral data using standard formulas.
- Parameters:
type – illuminant type. Can be one of the built-in types, e.g.
d55,3200k, or a custom illuminant stored in the database.- Returns:
trueif loaded successfully,falseotherwise
-
bool find_illuminant(const std::vector<double> &wb_multipliers)
Find the illuminant best matching the given white-balancing multipliers. This function analyzes all available illuminants and selects the one that best matches the white balance coefficients. It uses Sum of Squared Errors (SSE) to find the optimal match and automatically scales the white balance multipliers.
- Parameters:
wb_multipliers – white-balancing multipliers to match
- Returns:
trueif loaded successfully,falseotherwise
-
const std::vector<std::vector<double>> &get_IDT_matrix() const
Get the matrix from the last successful spectral solve (same data as
transform_matrix). This function returns a reference to the 3×3 IDT matrix that transforms camera RGB values to standardized color space. The matrix is computed by curve fitting optimization and represents the optimal color transformation for the camera under the specified illuminant conditions.- Returns:
a reference to the 3×3 IDT transformation matrix
- Pre:
calculate_transform()or deprecatedcalculate_IDT_matrix()completed successfully
-
const std::vector<double> &get_WB_multipliers() const
Get the white-balance multipliers calculated using
find_illuminant()orcalculate_WB(). This function returns a reference to the 3-element vector containing RGB white balance multipliers. These multipliers scale the camera response to achieve proper white balance under the specified illuminant conditions.- Returns:
a reference to the 3-element white balance multiplier vector [R, G, B]
- Pre:
white balance calculation must have been performed successfully
-
bool load_spectral_data(const std::string &file_path, SpectralData &out_data)
A helper method loading the spectral data for a file at the given path. This function loads spectral data from a file, handling both absolute and relative paths. For relative paths, it searches through all configured search directories.
- Parameters:
file_path – the path to the file to load. If the path is relative, all locations in the search path will be searched in.
out_data – the
SpectralDataobject to be filled with the loaded data.
- Returns:
trueif loaded successfully,falseotherwise
Public Members
-
SpectralData camera
The camera spectral data. Can be either assigned directly, loaded in place via
solver.camera.load(), or found viasolver.find_camera().
-
SpectralData illuminant
The illuminant spectral data. Can be either assigned directly, loaded in place via
solver.illuminant.load(), or found viasolver.find_illuminant().
-
SpectralData observer
The observer spectral data. Can be either assigned directly, or loaded in place via
solver.observer.load().
-
SpectralData training_data
The training set spectral data. Can be either assigned directly, or loaded in place via
solver.training_data.load().
-
SpectralSolver(const std::vector<std::string> &search_directories = {})
-
class MetadataSolver : public rta::core::TransformSolver
Solve an input transform using the metadata stored in DNG files.
Public Functions
-
MetadataSolver(const core::Metadata &metadata)
Initialize the solver using DNG metadata. Creates a MetadataSolver instance with the provided camera metadata for calculating IDT and CAT matrices.
- Parameters:
metadata – DNG metadata containing camera calibration and exposure information
-
std::vector<std::vector<double>> calculate_CAT_matrix()
Calculate the Color Adaptation Transform (CAT) matrix for color space conversion. This function computes the CAT matrix needed to transform colors from the camera’s white point to the target ACES RGB white point. It first obtains the camera’s XYZ transformation matrix and white point, then creates the target ACES RGB to XYZ matrix, and finally calculates the color adaptation transform between the two white points using the Bradford or CAT02 method.
The CAT matrix is essential for maintaining color appearance when converting between different illuminant conditions, ensuring that colors look consistent across different lighting environments. Strictly speaking, this matrix is not required for image processing, as it is embedded in the IDT; see
calculate_transform()or deprecatedcalculate_IDT_matrix().- Returns:
3×3 Color Adaptation Transform matrix
- Pre:
_metadata must contain valid camera calibration and neutral RGB data
-
std::vector<std::vector<double>> calculate_IDT_matrix()
Calculate the Input Device Transform (IDT) matrix for DNG color space conversion. This function computes the final IDT matrix that transforms camera RGB values to ACES RGB color space. It combines the Color Adaptation Transform (CAT) matrix with the D65 ACES RGB to XYZ transformation matrix to create a complete camera-to-ACES transformation pipeline.
Note
CAT is computed internally;
calculate_CAT_matrix()does not need to be called first.- Returns:
3×3 Input Device Transform matrix for DNG to ACES conversion
- Pre:
_metadata must contain valid camera calibration data
-
virtual bool calculate_transform() override
Calculate the Input Device Transform (IDT) matrix for DNG color space conversion. This function computes the final IDT matrix that transforms camera RGB values to ACES RGB color space. It combines the Color Adaptation Transform (CAT) matrix with the D65 ACES RGB to XYZ transformation matrix to create a complete camera-to-ACES transformation pipeline.
On success, writes the same 3×3 matrix as deprecated
calculate_IDT_matrix()intotransform_matrixand returnstrue.- Returns:
trueon success- Pre:
_metadata must contain valid camera calibration data
-
MetadataSolver(const core::Metadata &metadata)
-
class XYZD65Solver : public rta::core::TransformSolver
Fixed transform for XYZ data with a D65 white point: chromatic adaptation from D65 toward the ACES white point, combined with XYZ D60 to ACES.
Public Functions
-
virtual bool calculate_transform() override
Sets
transform_matrixto the built-in D65 adaptation × XYZ D60→ACES product. Always succeeds if invoked.- Returns:
true
-
virtual bool calculate_transform() override
Utility Functions
-
void rta::core::calculate_daylight_SPD(const int &cct, Spectrum &spectrum)
Calculate spectral power distribution (SPD) of CIE standard daylight. The function generates the spectral power distribution for a daylight illuminant based on the requested correlated color temperature using CIE standard formulas.
- Parameters:
cct – Correlated colour temperature of the requested illuminant either in Kelvin (in range of 4000-25000), or in short form from an illuminant name, e.g. 55 for D55 (in range of 40-250).
spectrum – Reference to a
Spectrumobject to fill with the calculated values
- Pre:
cct is in valid range for daylight calculations
-
void rta::core::calculate_blackbody_SPD(const int &kelvin, Spectrum &spectrum)
Calculate spectral power distribution (SPD) of blackbody radiation at given temperature. Generates a blackbody curve using Planck’s law for the specified correlated color temperature. The function calculates spectral power distribution across wavelengths defined by Spectrum object.
- Parameters:
kelvin – Correlated colour temperature of the requested illuminant (1500-3999 Kelvin)
spectrum – Reference to a
Spectrumobject to fill with the calculated values
- Pre:
kelvin is in valid range for blackbody calculations (1500-3999)
Namespaces
-
namespace rta
-
namespace util
-
namespace core