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.

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 dst for in-place conversion.

Returns:

true if 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 dst for in-place conversion.

  • roi – Ignored. This overload processes the whole image and will be removed in v3.

Returns:

true if 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 dst for in-place conversion.

Returns:

true if 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 dst for in-place conversion.

Returns:

true if 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 dst for in-place conversion.

  • roi – Ignored. This overload processes the whole image and will be removed in v3.

Returns:

true if 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 dst for in-place conversion.

Returns:

true if 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 dst for in-place conversion.

  • roi – Ignored. This overload processes the whole image and will be removed in v3.

Returns:

true if 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:

true if 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:

true if 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 configure methods.

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 configure methods.

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_matrix to the current image. The matrix becomes available after calling either of the two configure methods.

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 configure methods.

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 path into a buffer using the hints calculated by the configure method. 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:

true if 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:

true if 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 call OIIO::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:

true if 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, and apply_crop in sequence.

Parameters:
  • dst – Destination image buffer.

  • src – Source image buffer, can be the same as dst for in-place conversion.

Returns:

true if 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, and save_image in sequence.

Parameters:

input_filename – Full path to the file to be converted.

Returns:

true if 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:

true if saved successfully.

Public Members

std::string last_error_message

Error message from the most recent method call that returned false.

Settings settings

The conversion settings.

Status status = Status::Success

This property holds the error code from the most recent method call that returns a bool.

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.

enum class LensCorrectionType

The enumerator containing all supported lens correction types.

Values:

enumerator None
enumerator Aberration
enumerator Distortion
enumerator Vignetting
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 illuminant if WB_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.

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 illuminant property 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.

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.

CropMode crop_mode = CropMode::Hard

The selected cropping mode to use for conversion.

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.

float headroom = 6.0

Linear highlight headroom factor. Pixel scaling uses headroom * scale.

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::Illuminant and matrix_method == MatrixMethod::Spectral.

An illuminant can be provided as a black body correlated colour temperature, like 3200K; or a D-series illuminant, like D56; 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)

WBMethod WB_method = WBMethod::Metadata

The selected white-balancing method to use for conversion.

Friends

friend bool operator&&(const LensCorrectionType &lhs, const LensCorrectionType &rhs)

Convenience operator to simplify testing for enabled flags. Performs bit-wise and and returns true if not zero.

Utility Functions

std::vector<std::vector<std::string>> rta::util::collect_image_files(const std::vector<std::string> &paths)

Collect all files from given paths into 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 Spectrum object constructor. Allocates as many spectral samples as required for the shape parameter, and initialises them with value.

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::EmptyShape to avoid allocating any samples.

double integrate() const

Integrate the spectral curve.

Returns:

the sum of all elements in values.

double max() const

Find the maximum element in values

Returns:

the maximum element in values.

Spectrum &operator*=(const Spectrum &rhs)

Per-element multiplication operator.

Spectrum &operator+=(const Spectrum &rhs)

Per-element addition operator.

Spectrum &operator-=(const Spectrum &rhs)

Per-element subtraction operator.

Spectrum &operator/=(const Spectrum &rhs)

Per-element division operator.

void reshape()

Reshape the Spectrum object to the reference shape (rta::core::Spectrum::ReferenceShape).

Public Members

struct rta::core::Spectrum::Shape shape
std::vector<double> values

The spectral samples storage.

Public Static Attributes

static Shape EmptyShape = {0, 0, 0}

An empty shape. Useful for creating Spectrum objects without allocating any samples.

static Shape ReferenceShape = {380, 780, 5}

The reference shape to use with all Spectrum objects by default. These are the values used by rawtoaces internally.

Friends

friend Spectrum operator*(Spectrum lhs, const Spectrum &rhs)

Per-element multiplication operator.

friend Spectrum operator+(Spectrum lhs, const Spectrum &rhs)

Per-element addition operator.

friend Spectrum operator-(Spectrum lhs, const Spectrum &rhs)

Per-element subtraction operator.

friend Spectrum operator/(Spectrum lhs, const Spectrum &rhs)

Per-element division operator.

struct Shape

The spectral data sampling information. Only regular step data sets are currently supported. All values are wavelength in nanometers.

Public Functions

bool operator==(const Shape &shape) const

Comparison operator, mostly required for storing the Spectrum data in containers.

Parameters:

shape – another Shape object to compare this with.

Returns:

true if the objects are equal.

Public Members

float first = 0

The leftmost sample’s wavelength in nanometers.

float last = 0

The rightmost sample’s wavelength in nanometers.

float step = 0

The sampling step in nanometers.

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 Spectrum object. 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 Spectrum of 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 Spectrum object reference if found.

const Spectrum &get(std::string set_name, std::string channel_name) const
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:

true if loaded successfully.

Spectrum &operator[](std::string name)

A convenience operator returning the Spectrum of 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 Spectrum object corresponding to the given channel name.

const Spectrum &operator[](std::string name) const

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.

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.

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_matrix to 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:

true on 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 base TransformSolver constructor).

int verbosity

Verbosity level.

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 TransformSolver constructor for an identity transform_matrix and 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, observer and training_data have to be configured prior to this call.

Returns:

true if calculated successfully, false otherwise

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. Requires camera, illuminant, observer, and training_data to be configured prior to this call.

Returns:

true if calculated successfully, false otherwise

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 camera and illuminant data have to be configured prior to this call.

Returns:

true if calculated successfully, false otherwise

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:

true on 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:

true if loaded successfully, false otherwise

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:

true if loaded successfully, false otherwise

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:

true if loaded successfully, false otherwise

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 deprecated calculate_IDT_matrix() completed successfully

const std::vector<double> &get_WB_multipliers() const

Get the white-balance multipliers calculated using find_illuminant() or calculate_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 SpectralData object to be filled with the loaded data.

Returns:

true if loaded successfully, false otherwise

Public Members

SpectralData camera

The camera spectral data. Can be either assigned directly, loaded in place via solver.camera.load(), or found via solver.find_camera().

SpectralData illuminant

The illuminant spectral data. Can be either assigned directly, loaded in place via solver.illuminant.load(), or found via solver.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().

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 deprecated calculate_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() into transform_matrix and returns true.

Returns:

true on success

Pre:

_metadata must contain valid camera calibration data

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_matrix to the built-in D65 adaptation × XYZ D60→ACES product. Always succeeds if invoked.

Returns:

true

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 Spectrum object 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 Spectrum object to fill with the calculated values

Pre:

kelvin is in valid range for blackbody calculations (1500-3999)

Namespaces

namespace rta
namespace util
namespace core