API Overview

Use the user guide to convert files from the command line. This page chooses a programming API: convert a whole RAW file, run the OpenImageIO buffer steps yourself, or solve a transform from metadata or spectral data.

The table names the entry point. The sections below say what you pass in, what comes back, which data the call needs, how failure is reported, and where the worked example and signatures live. C++ and Python cover the same tasks where both languages have the API. Helpers that exist only in C++ are listed at the end.

Task

Main API

Where it is available

Convert a RAW file to an ACES EXR

ImageConverter and Settings, through process_image

C++ and every Python build

Run the pipeline on OpenImageIO buffers

configure, load_image, process_buffer, save_image, and the apply_* steps

C++. Python when the extension is built with OpenImageIO 3.2 or later

Solve from extracted camera metadata

Metadata and MetadataSolver

C++ and Python

Solve from measured spectral data

SpectralData and SpectralSolver

C++ and Python

Generate an illuminant spectrum directly, or adapt D65 XYZ

calculate_daylight_SPD, calculate_blackbody_SPD, and XYZD65Solver

C++. Python can load the built-in named illuminants through SpectralSolver.find_illuminant

Task examples repeats each of these tasks with the same settings in Shell, C++, and Python.

OpenImageIO 3.2

Calling the buffer methods from Python requires an extension built against OpenImageIO 3.2 or later, with ImageBuf, ParamValueList, and ImageSpec registered for nanobind. Importing that extension also imports the OpenImageIO Python module. An earlier OpenImageIO build still provides process_image and configure(input_filename), and omits the buffer methods. After a successful import, hasattr(rawtoaces.ImageConverter, "load_image") reports whether they are present. The capability table lists each method.

The C++ methods are members of rta::util::ImageConverter in rawtoaces_util, which links OpenImageIO.

Convert a RAW file

Pass a filesystem path to rta::util::ImageConverter::process_image() or rawtoaces.ImageConverter.process_image(). Set ImageConverter::Settings first when the defaults are not the conversion you want. process_image configures the transform from the file, decodes it, applies lens correction (off unless requested), the colour matrix, exposure scaling, and crop, then writes an ACES EXR.

The output name is <stem>_aces.exr. It is written beside the input, or under output_dir when that is set. create_dirs defaults to false, so the output directory must already exist unless you enable it. overwrite defaults to false. Pixel values are multiplied by headroom * scale; headroom is a linear factor and defaults to 6.0. The API crop default is hard: only the crop region is written. The command-line crop default is described in the user guide.

White balance defaults to metadata from the file. DNG is the format that carries the calibration this method uses. A named illuminant, or the spectral matrix method, needs camera sensitivity data. Auto selects the spectral matrix when that data is available and otherwise uses metadata. An Adobe matrix comes from LibRaw through OpenImageIO. A custom matrix is a complete camera RGB to ACES AP0 matrix and is applied as given. database_directories selects the spectral data directory; when it is empty the search uses RAWTOACES_DATA_PATH, then the legacy AMPAS_DATA_PATH, then the platform default. Setup is in Getting Started. Lens correction is opt-in and uses the Lensfun database; see Lens Correction.

A failed call returns false. Read status and last_error_message. status distinguishes a missing input, an existing output, a missing spectral database, and a failure in configuration, reading, lens correction, the matrix, scale, crop, or writing.

Convert a single image shows this call in Shell, C++, and Python. Convert a batch, white balance and matrix, crop and scale, and errors continue from it. The C++ and Python guides expand on the same class. Signatures: C++ Reference and Python Reference. rta::util::collect_image_files() and rawtoaces.collect_image_files() group file and directory arguments into batches. rta::util::ImageConverter::make_output_path(), init_parser, and parse_parameters are C++ only; Python sets settings directly.

OpenImageIO buffers

Use this layer when the surrounding application already owns the image or needs to run load, colour, scale, crop, and save separately.

In C++, and in the Python overload that accepts options, pass the current settings plus either a RAW path or an OIIO::ImageSpec / OpenImageIO.ImageSpec into configure. The file overload fills an OpenImageIO parameter list with decoding hints. The ImageSpec overload uses metadata you already have. Then pass that parameter list to load_image to fill an ImageBuf. process_buffer runs lens correction, the matrix, scale, and crop. The same four steps are apply_lens_correction, apply_matrix, apply_scale, and apply_crop. save_image writes an ACES container; the default stored sample type is half-float. get_WB_multipliers and get_transform_matrix are valid after a successful configure.

Python file conversion can call configure(input_filename) in every build. The overloads that take ParamValueList or ImageSpec, and load_image, save_image, process_buffer, and the apply_* methods, require OpenImageIO 3.2 or later as described in OpenImageIO 3.2.

Each step returns false and sets status and last_error_message when it fails. Call configure again after changing settings that affect the transform.

OpenImageIO buffers shows the sequence in C++ and Python. The C++ signatures are on rta::util::ImageConverter in the C++ Reference. The Python signatures are on rawtoaces.ImageConverter in the Python Reference.

Solve from camera metadata

Use rta::core::MetadataSolver or rawtoaces.MetadataSolver when you already have DNG calibration metadata and want the transform without decoding a file.

Pass a rta::core::Metadata / rawtoaces.Metadata value: neutral_RGB, baseline_exposure, and two calibration sets. Each calibration set carries an illuminant tag and an XYZ-to-camera-RGB matrix. calculate_transform returns a boolean and, on success, writes a 3×3 matrix to transform_matrix. That matrix includes chromatic adaptation and takes camera RGB to ACES. The solver copies the metadata it is given; it does not read a spectral database.

A false return leaves the explanation in last_error_message. Python raises ValueError when a required vector has the wrong length.

Solve from metadata shows the same calibration in C++ and Python. The Python core guide explains the data model. Signatures are in the C++ Reference and the Python Reference.

Solve from spectral data

Use rta::core::SpectralSolver or rawtoaces.SpectralSolver when the transform should come from measured spectra.

Pass search directories to the constructor, or assign camera, illuminant, observer, and training_data yourself. find_camera and find_illuminant load those two from the search path. Built-in illuminant names such as d55 and 3200k are generated; any other name must exist in the data directory. Before calculate_transform, the camera needs three channels, the illuminant one, the observer three, and the training set must be non-empty. Calculate white balance with calculate_WB, or with the three-multiplier form of find_illuminant. The name form only loads the illuminant.

On success, get_WB_multipliers holds the RGB multipliers and transform_matrix holds the 3×3 transform. A missing camera, illuminant, observer, or training set makes calculate_transform return false and sets last_error_message. Leaving white balance unset keeps the multipliers at [1.0, 1.0, 1.0] and is not reported as an error. Python raises ValueError for an invalid argument shape.

The dataset layout and schema are documented with the rawtoaces-data repository. Solve from spectra shows the same database lookup in C++ and Python. The Python core guide explains the containers. C++ types are introduced in rawtoaces Core and Spectral Data, with signatures in the C++ Reference and the Python Reference.

C++-only helpers

These C++ entry points have no matching Python function. Python reaches the built-in illuminants through SpectralSolver.find_illuminant instead of the two spectrum generators.

Signatures are in the C++ Reference.