Python Reference
This reference describes the superset of Python bindings available across supported builds. Methods accepting OpenImageIO objects require an extension built with compatible OpenImageIO 3.2+ bindings. Check the capability table before using those methods.
Python bindings for RAW image conversion and metadata/spectral solving.
Methods accepting OpenImageIO objects require a compatible OpenImageIO 3.2+ build. Those methods are absent from earlier builds; see OpenImageIO interoperability for the capability table.
Classes
- class rawtoaces.ImageConverter[source]
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.
- class Settings[source]
The structure containing all parameters needed to configure image conversion.
- enum CropMode(value)[source]
The enumerator containing all supported cropping modes.
Valid values are as follows:
- Off = <CropMode.Off: 0>
- Soft = <CropMode.Soft: 1>
- Hard = <CropMode.Hard: 2>
- flag LensCorrectionType(value)[source]
The enumerator containing all supported lens correction types.
Valid values are as follows:
- Aberration = <LensCorrectionType.Aberration: 1>
- Distortion = <LensCorrectionType.Distortion: 2>
- Vignetting = <LensCorrectionType.Vignetting: 4>
- enum MatrixMethod(value)[source]
The enumerator containing all supported colour transform matrix calculation methods.
Valid values are as follows:
- Auto = <MatrixMethod.Auto: 0>
- Spectral = <MatrixMethod.Spectral: 1>
- Metadata = <MatrixMethod.Metadata: 2>
- Adobe = <MatrixMethod.Adobe: 3>
- Custom = <MatrixMethod.Custom: 4>
- enum WBMethod(value)[source]
The enumerator containing all supported white-balancing methods.
Valid values are as follows:
- Metadata = <WBMethod.Metadata: 0>
- Illuminant = <WBMethod.Illuminant: 1>
- Box = <WBMethod.Box: 2>
- Custom = <WBMethod.Custom: 3>
- property WB_box: list[int]
Box to use for white balancing when
WB_method==WBMethod::Box. (default = (0,0,0,0) - full image)
- property adjust_maximum_threshold: float
Automatically lower the linearity threshold provided in the metadata by this scaling factor.
- property bad_pixels_path: str
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.
- property chromatic_aberration: list[float]
Red and blue scale factors for chromatic aberration correction.
- property compression: str
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.
- property crop_box: list[int]
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.
- property custom_WB: list[float]
Custom white balance multipliers to be used when
WB_method==WBMethod::Custom.
- property custom_camera_make: str
Camera manufacturer name to be used for spectral sensitivity curves lookup.
- property custom_camera_model: str
Camera model name to be used for spectral sensitivity curves lookup.
- property custom_matrix: list[list[float]]
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.
- property database_directories: list[str]
Directory containing rawtoaces spectral sensitivity and illuminant data files. Overrides the default search path and the
RAWTOACES_DATA_PATHenvironment variable.
- property demosaic_algorithm: str
Demosaicing algorithm. Supported options:
linear,VNG,PPG,AHD,DCB,DHT,AAHD.
- property flip: int
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.)
- property headroom: float
Linear highlight headroom factor (default 6.0). Pixel scaling uses
headroom * scale.
- property highlight_mode: int
Highlight recovery mode, as supported by OpenImageIO/Libraw: 0 = clip, 1 = unclip, 2 = blend, 3..9 = rebuild.
- property illuminant: str
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.
- property keep_diagnostic_attributes: bool
Keep the diagnostic attributes in the output EXR file.
The attributes contain information about the transforms applied to the image and start with the
rtaprefix.
- property lens_correction_types: LensCorrectionType
The requested lens correction types. No correction is requested by default. Combine LensCorrectionType values to enable it.
- property matrix_method: MatrixMethod
The selected colour transform matrix calculation method to use for conversion.
- property require_lens_correction: bool
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.
- enum Status(value)[source]
Status codes for operation results.
Valid values are as follows:
- Success = <Status.Success: 0>
- DatabaseNotFound = <Status.DatabaseNotFound: 14>
- FileExists = <Status.FileExists: 1>
- InputFileNotFound = <Status.InputFileNotFound: 2>
- EmptyInputFilename = <Status.EmptyInputFilename: 3>
- FilesystemError = <Status.FilesystemError: 4>
- OutputDirectoryError = <Status.OutputDirectoryError: 5>
- InvalidPath = <Status.InvalidPath: 6>
- ConfigurationError = <Status.ConfigurationError: 7>
- ReadError = <Status.ReadError: 8>
- LensCorrectionError = <Status.LensCorrectionError: 9>
- MatrixApplicationError = <Status.MatrixApplicationError: 10>
- ScaleApplicationError = <Status.ScaleApplicationError: 11>
- CropApplicationError = <Status.CropApplicationError: 12>
- WriteError = <Status.WriteError: 13>
- UnknownError = <Status.UnknownError: 15>
- apply_crop(dst, src)[source]
Apply the cropping mode as specified in crop_mode.
Available only with compatible OpenImageIO 3.2+ bindings; see OpenImageIO interoperability.
- Parameters:
dst (OpenImageIO.ImageBuf) – Destination image buffer.
src (OpenImageIO.ImageBuf) – Source image buffer, can be the same as
dstfor in-place conversion.
- Return type:
- Returns:
Trueif applied successfully.
- apply_lens_correction(dst, src)[source]
Apply the lens correction to the image buffer.
Available only with compatible OpenImageIO 3.2+ bindings; see OpenImageIO interoperability.
- Parameters:
dst (OpenImageIO.ImageBuf) – Destination image buffer
src (OpenImageIO.ImageBuf) – Source image buffer, can be the same as
dstfor in-place conversion.
- Return type:
- Returns:
Trueif applied successfully.
- apply_matrix(dst, src)[source]
Apply the colour space conversion matrix (or matrices) to convert the image buffer from the raw camera colour space to ACES.
Available only with compatible OpenImageIO 3.2+ bindings; see OpenImageIO interoperability.
- Parameters:
dst (OpenImageIO.ImageBuf) – Destination image buffer.
src (OpenImageIO.ImageBuf) – Source image buffer, can be the same as
dstfor in-place conversion.
- Return type:
- Returns:
Trueif applied successfully.
- apply_scale(dst, src)[source]
Multiply image buffer pixel values by
settings.headroom * settings.scale.Available only with compatible OpenImageIO 3.2+ bindings; see OpenImageIO interoperability.
- Parameters:
dst (OpenImageIO.ImageBuf) – Destination image buffer
src (OpenImageIO.ImageBuf) – Source image buffer, can be the same as
dstfor in-place conversion.
- Return type:
- Returns:
Trueif applied successfully.
- configure(input_filename: str) bool
- configure(input_filename: str, options: OpenImageIO.ParamValueList) bool
- configure(image_spec: OpenImageIO.ImageSpec, options: OpenImageIO.ParamValueList) bool
configure(input_filename: str) -> boolConfigure white balance, the colour transform and decoding options from a file.
Uses the current
settingsand reads metadata frominput_filename. This overload is available in every Python build and does not expose the OpenImageIO decoding options to Python.- Parameters:
input_filename – Path to the RAW image whose metadata will be read.
- Returns:
Trueon success,Falseon failure. On failure, inspectlast_error_messageandstatus.
configure(input_filename: str, options: OpenImageIO.ParamValueList) -> boolConfigure white balance, the colour transform and decoding options from a file.
Uses the current
settingsand reads metadata frominput_filename.optionsmay be pre-populated with additional OpenImageIO decoding hints and is modified in place with the hints calculated for the rawtoaces conversion. Requires compatible OpenImageIO 3.2+ bindings; see OpenImageIO interoperability.- Parameters:
input_filename – Path to the RAW image whose metadata will be read.
options – OpenImageIO input options; this object may be modified.
- Returns:
Trueon success,Falseon failure. On failure, inspectlast_error_messageandstatus.
configure(image_spec: OpenImageIO.ImageSpec, options: OpenImageIO.ParamValueList) -> boolConfigure white balance, the colour transform and decoding options from metadata.
Uses the current
settingsand fills or modifiesoptionsin place with OpenImageIO decoding hints. Requires compatible OpenImageIO 3.2+ bindings; see OpenImageIO interoperability.- Parameters:
image_spec – Image specification containing the source metadata.
options – OpenImageIO input options; this object may be modified.
- Returns:
Trueon success,Falseon failure. On failure, inspectlast_error_messageandstatus.
- get_CAT_matrix()[source]
Get the solved chromatic adaptation transform matrix of the currently processed image. The matrix becomes available after calling the
configuremethod.Deprecated since version 2.2.0: Will be removed in v3. Use
get_transform_matrix().
- get_IDT_matrix()[source]
Get the solved input transform matrix of the currently processed image. The matrix becomes available after calling the
configuremethod.Deprecated since version 2.2.0: Will be removed in v3. Use
get_transform_matrix().
- get_WB_multipliers()[source]
Get the solved white balance multipliers of the currently processed image. The multipliers become available after calling the
configuremethod.
- get_supported_cameras()[source]
Collects all camera models for which spectral sensitivity data is available in the database.
- get_transform_matrix()[source]
Get the solved colour transform matrix to be applied by
process_image. The matrix becomes available after calling theconfiguremethod.
- property last_error_message: str
Error message from the most recent method call that returned
False.
- load_image(path, hints, buffer, data_type=OpenImageIO.BASETYPE.FLOAT)[source]
Load an image from a given
pathinto abufferusing thehintscalculated by theconfiguremethod. The hints can be manually modified prior to invoking this method.Available only with compatible OpenImageIO 3.2+ bindings; see OpenImageIO interoperability.
- Parameters:
path (str) – Path to where the image from.
hints (OpenImageIO.ParamValueList) – Conversion hints to be passed to OIIO when reading an image file.
buffer (OpenImageIO.ImageBuf) – Destination buffer where the image loaded into.
data_type (OpenImageIO.TypeDesc) – Sample type in the destination buffer (default:
OpenImageIO.FLOAT).
- Return type:
- Returns:
Trueif image load successfully.
- process_buffer(dst, src)[source]
A convenience single-call method to process an image buffer. Equivalent to calling
apply_lens_correction,apply_matrix,apply_scale, andapply_cropin sequence.Available only with compatible OpenImageIO 3.2+ bindings; see OpenImageIO interoperability.
- Parameters:
dst (OpenImageIO.ImageBuf) – Destination image buffer.
src (OpenImageIO.ImageBuf) – Source image buffer, can be the same as
dstfor in-place conversion.
- Return type:
- Returns:
Trueif processed successfully.
- save_image(output_filename, buf, data_type=OpenImageIO.BASETYPE.HALF)[source]
Save an image into an ACES container.
Available only with compatible OpenImageIO 3.2+ bindings; see OpenImageIO interoperability.
- class rawtoaces.Spectrum(value: float = 0.0, shape: Spectrum.Shape = ...)[source]
- class rawtoaces.Spectrum(other: Spectrum)
A regularly sampled spectral curve.
Corresponds to
rta::core::Spectrum. Per-element arithmetic requires both curves to share a shape and sample count.-
EmptyShape:
Final[Shape] = Ellipsis Empty sampling (zero step) used to construct a curve with no samples. Each access returns a new copy.
-
ReferenceShape:
Final[Shape] = Ellipsis Built-in sampling used by rawtoaces, from 380 nm through 780 nm in 5 nm steps. Each access returns a new copy.
- class Shape(first: float = 0.0, last: float = 0.0, step: float = 0.0)[source]
- class Shape(other: Spectrum.Shape)
Regular wavelength sampling, in nanometers.
firstandlastare the endpoint wavelengths andstepis the spacing. Shapes compare equal when all three values match.
- integrate()[source]
Sum every sample.
- Return type:
- Returns:
The sum of
values, or0when the curve is empty.
- reshape()[source]
Resample this curve onto
ReferenceShapewith linear interpolation.Wavelengths outside the current range are filled from the nearest endpoint sample. A curve whose shape already equals
ReferenceShapeis left unchanged, including when its sample count does not match that shape.- Raises:
ValueError – If the curve has no samples.
- Return type:
- property shape: Shape
Wavelength sampling of this curve, in nanometers. Assigning a shape records that sampling and leaves
valuesunchanged, so the sample count can disagree with the shape.reshape()resamples ontoReferenceShapefrom the current samples and does not check that the sample count matches the shape.
-
EmptyShape:
- class rawtoaces.SpectralData[source]
A data-class for storing spectral data, based on the file format used in [rawtoaces-data](https://github.com/AcademySoftwareFoundation/rawtoaces-data).
- get(set_name, channel_name)[source]
Return a copy of one channel from a named data set.
- Parameters:
- Return type:
- Returns:
A copy of the matching spectrum.
- Raises:
ValueError – If the set or channel is absent.
- load(path, reshape=True)[source]
Load spectral data from a given path
- Parameters:
path (str) – path a path to the file to load data from
reshape (bool) – if set to
True, the data will be reshaped torawtoaces.Spectrum.ReferenceShape
- Return type:
- Returns:
Trueif loaded successfully.
- class rawtoaces.SpectralSolver(search_directories=[])[source]
Solve an input transform using spectral sensitivity curves of a camera.
The inherited
calculate_transform,transform_matrix,last_error_message, andverbositymembers are available on this class.- calculate_IDT_matrix()[source]
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.- Return type:
- Returns:
Trueif calculated successfully,Falseotherwise- Pre:
camera, illuminant, observer, and training_data must be properly loaded
Deprecated since version 2.2.0: Will be removed in v3. Use
calculate_transform().
- calculate_WB()[source]
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.
- Return type:
- Returns:
Trueif calculated successfully,Falseotherwise- Pre:
camera and illuminant data must be properly loaded
- calculate_transform()
Calculate the transform matrix. The solved matrix can be accessed via
transform_matrix.Call this method on
rawtoaces.MetadataSolverorrawtoaces.SpectralSolver; the base class cannot be constructed directly in Python. The derived solver’s inputs must be configured before solving. For spectral solving, calculate white balance first withrawtoaces.SpectralSolver.calculate_WB()or the multiplier form ofrawtoaces.SpectralSolver.find_illuminant().- Return type:
- Returns:
Trueif calculated successfully,Falseotherwise. Inspectlast_error_messageon failure. Readtransform_matrixonly after a successful solve.
- property camera: SpectralData
The camera spectral data. Can be either assigned directly, loaded in place via
solver.camera.load(), or found viasolver.find_camera().
- collect_data_files(type)[source]
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.
- find_camera(make, model)[source]
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.
- find_illuminant(type: str) bool
- find_illuminant(wb_multipliers: Sequence[float]) bool
find_illuminant(type: str) -> boolLoad an illuminant by its non-empty standard or database name.
Generates daylight spectra such as
"d55"and blackbody spectra such as"3200k"; other names are searched in the configured spectral database paths. Camera data is not required for this form. This overload loads the illuminant but does not calculate white balance; callcalculate_WB()after loading the camera.- Parameters:
type – Non-empty standard or database illuminant name.
- Returns:
Trueon success,Falseon failure. A failed database lookup may leavelast_error_messageempty or unchanged.- Raises:
ValueError – If
typeis empty.
find_illuminant(wb_multipliers: Sequence[float]) -> boolChoose the illuminant best matching three white-balance multipliers.
Requires camera data with three channels (R, G, B) to be loaded first. Searches generated daylight/blackbody spectra and database illuminants. On success this overload also calculates white-balance multipliers, available from
get_WB_multipliers().- Parameters:
wb_multipliers – Exactly three white-balance multipliers, [R, G, B].
- Returns:
Trueon success,Falseon failure. State-validation failures populatelast_error_message; a failed database lookup may leave it empty or unchanged.- Raises:
ValueError – If
wb_multipliersdoes not contain exactly three values.
- get_IDT_matrix()[source]
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.- Return type:
- Returns:
a 3×3 IDT transformation matrix
- Pre:
calculate_transform()or deprecatedcalculate_IDT_matrix()completed successfully
Deprecated since version 2.2.0: Will be removed in v3. Read
transform_matrixafter a successfulcalculate_transform()call.
- get_WB_multipliers()[source]
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.
- property illuminant: SpectralData
The illuminant spectral data. Can be either assigned directly, loaded in place via
solver.illuminant.load(), or found viasolver.find_illuminant().
- property last_error_message: str
Error message from the most recent method call that returned
False.
- load_spectral_data(file_path, out_data)[source]
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 (str) – the path to the file to load. If the path is relative, all locations in the search path will be searched in.
out_data (rawtoaces.SpectralData) – the SpectralData object to be filled with the loaded data.
- Return type:
- Returns:
Trueif loaded successfully,Falseotherwise
- property observer: SpectralData
The observer spectral data. Can be either assigned directly, or loaded in place via
solver.observer.load().
- property training_data: SpectralData
The training set spectral data. Can be either assigned directly, or loaded in place via
solver.training_data.load().
- class rawtoaces.Metadata[source]
DNG metadata required to calculate an input transform.
- class Calibration[source]
A calibration data set structure. Contains calibration matrices for a given light source.
- property calibration: list[Calibration]
Calibration datasets. Currently two sets are supported.
- class rawtoaces.MetadataSolver(metadata)[source]
Solve an input transform using the metadata stored in DNG files.
The inherited
calculate_transform,transform_matrix,last_error_message, andverbositymembers are available on this class.- calculate_CAT_matrix()[source]
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().
Deprecated since version 2.2.0: Will be removed in v3. Use
calculate_transform().
- calculate_IDT_matrix()[source]
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.
- Return type:
- Returns:
3×3 Input Device Transform matrix for DNG to ACES conversion
- Note:
CAT is computed internally;
calculate_CAT_matrix()does not need to be called first.
Deprecated since version 2.2.0: Will be removed in v3. Use
calculate_transform().
- calculate_transform()
Calculate the transform matrix. The solved matrix can be accessed via
transform_matrix.Call this method on
rawtoaces.MetadataSolverorrawtoaces.SpectralSolver; the base class cannot be constructed directly in Python. The derived solver’s inputs must be configured before solving. For spectral solving, calculate white balance first withrawtoaces.SpectralSolver.calculate_WB()or the multiplier form ofrawtoaces.SpectralSolver.find_illuminant().- Return type:
- Returns:
Trueif calculated successfully,Falseotherwise. Inspectlast_error_messageon failure. Readtransform_matrixonly after a successful solve.
- property last_error_message: str
Error message from the most recent method call that returned
False.
Utility Functions
- rawtoaces.collect_image_files(path)[source]
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.