# Copyright Contributors to the rawtoaces Project.
# SPDX-License-Identifier: Apache-2.0
# Generated from compiled bindings by nanobind.stubgen.
# Edit src/cpp/bindings/*.cpp docstrings, rebuild and regenerate; do not edit prose here.
# Forward annotations, enum aliases and public OpenImageIO names are normalized.
"""
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
:ref:`python-oiio-availability` for the capability table.
"""
from __future__ import annotations
from collections.abc import Sequence
import enum
from typing import Final, overload
import OpenImageIO
[docs]
class Spectrum:
"""
A regularly sampled spectral curve.
Corresponds to :cpp:struct:`rta::core::Spectrum`. Per-element
arithmetic requires both curves to share a shape and sample count.
"""
@overload
def __init__(self, value: float = 0.0, shape: Spectrum.Shape = ...) -> None:
"""
Create a curve and fill every sample with ``value``.
:param value: Initial value of every sample.
:param shape: Sampling of the new curve. Defaults to
``Spectrum.ReferenceShape``. Pass ``Spectrum.EmptyShape`` to
allocate no samples.
:raises ValueError: If ``step`` is positive and the wavelengths are
non-finite or ``last`` is less than ``first``.
"""
@overload
def __init__(self, other: Spectrum) -> None:
"""Copy constructor."""
[docs]
class Shape:
"""
Regular wavelength sampling, in nanometers.
``first`` and ``last`` are the endpoint wavelengths and ``step`` is
the spacing. Shapes compare equal when all three values match.
"""
@overload
def __init__(self, first: float = 0.0, last: float = 0.0, step: float = 0.0) -> None:
"""
Create a sampling description.
:param first: Wavelength of the first sample, in nanometers.
:param last: Wavelength of the last sample, in nanometers.
:param step: Spacing between samples, in nanometers. A zero step
describes an empty curve.
"""
@overload
def __init__(self, other: Spectrum.Shape) -> None:
"""Copy constructor."""
@property
def first(self) -> float:
"""Wavelength of the first sample, in nanometers."""
@first.setter
def first(self, arg: float, /) -> None: ...
@property
def last(self) -> float:
"""Wavelength of the last sample, in nanometers."""
@last.setter
def last(self, arg: float, /) -> None: ...
@property
def step(self) -> float:
"""Spacing between samples, in nanometers."""
@step.setter
def step(self, arg: float, /) -> None: ...
def __eq__(self, arg: Spectrum.Shape, /) -> bool:
"""Return whether ``first``, ``last``, and ``step`` all match."""
__hash__: None = None
ReferenceShape: Final[Spectrum.Shape] = ...
"""
Built-in sampling used by rawtoaces, from 380 nm through 780 nm in
5 nm steps. Each access returns a new copy.
"""
EmptyShape: Final[Spectrum.Shape] = ...
"""
Empty sampling (zero step) used to construct a curve with no samples.
Each access returns a new copy.
"""
@property
def shape(self) -> Spectrum.Shape:
"""
Wavelength sampling of this curve, in nanometers. Assigning a shape
records that sampling and leaves ``values`` unchanged, so the sample
count can disagree with the shape. ``reshape()`` resamples onto
``ReferenceShape`` from the current samples and does not check that
the sample count matches the shape.
"""
@shape.setter
def shape(self, arg: Spectrum.Shape, /) -> None: ...
@property
def values(self) -> list[float]:
"""
Spectral samples. Reading returns a new list, so assigning to an
index of that list leaves the curve unchanged. Assign a sequence to
replace the samples.
"""
@values.setter
def values(self, arg: Sequence[float], /) -> None: ...
[docs]
def reshape(self) -> None:
"""
Resample this curve onto ``ReferenceShape`` with linear interpolation.
Wavelengths outside the current range are filled from the nearest
endpoint sample. A curve whose shape already equals
``ReferenceShape`` is left unchanged, including when its sample count
does not match that shape.
:raises ValueError: If the curve has no samples.
"""
[docs]
def integrate(self) -> float:
"""
Sum every sample.
:return: The sum of ``values``, or ``0`` when the curve is empty.
"""
[docs]
def max(self) -> float:
"""Return the largest sample, or ``0`` when ``values`` is empty."""
def __add__(self, arg: Spectrum, /) -> Spectrum:
"""
Per-element addition.
:param other: Curve with the same shape and sample count.
:return: A new curve.
:raises ValueError: If the operands differ in shape or sample count.
"""
def __sub__(self, arg: Spectrum, /) -> Spectrum:
"""
Per-element subtraction.
:param other: Curve with the same shape and sample count.
:return: A new curve.
:raises ValueError: If the operands differ in shape or sample count.
"""
def __mul__(self, arg: Spectrum, /) -> Spectrum:
"""
Per-element multiplication.
:param other: Curve with the same shape and sample count.
:return: A new curve.
:raises ValueError: If the operands differ in shape or sample count.
"""
def __truediv__(self, arg: Spectrum, /) -> Spectrum:
"""
Per-element division.
:param other: Curve with the same shape and sample count.
:return: A new curve.
:raises ValueError: If the operands differ in shape or sample count.
"""
def __iadd__(self, arg: Spectrum, /) -> Spectrum:
"""
Per-element addition in place.
:param other: Curve with the same shape and sample count.
:return: This curve.
:raises ValueError: If the operands differ in shape or sample count.
"""
def __isub__(self, arg: Spectrum, /) -> Spectrum:
"""
Per-element subtraction in place.
:param other: Curve with the same shape and sample count.
:return: This curve.
:raises ValueError: If the operands differ in shape or sample count.
"""
def __imul__(self, arg: Spectrum, /) -> Spectrum:
"""
Per-element multiplication in place.
:param other: Curve with the same shape and sample count.
:return: This curve.
:raises ValueError: If the operands differ in shape or sample count.
"""
def __itruediv__(self, arg: Spectrum, /) -> Spectrum:
"""
Per-element division in place.
:param other: Curve with the same shape and sample count.
:return: This curve.
:raises ValueError: If the operands differ in shape or sample count.
"""
[docs]
class SpectralData:
"""
A data-class for storing spectral data, based on the file format used in
[rawtoaces-data](https://github.com/AcademySoftwareFoundation/rawtoaces-data).
"""
def __init__(self) -> None:
"""Default constructor"""
@property
def manufacturer(self) -> str:
"""Manufacturer of the device being tested."""
@manufacturer.setter
def manufacturer(self, arg: str, /) -> None: ...
@property
def model(self) -> str:
"""Model of the device being tested."""
@model.setter
def model(self, arg: str, /) -> None: ...
@property
def type(self) -> str:
"""Type of the spectral dataset."""
@type.setter
def type(self, arg: str, /) -> None: ...
@property
def units(self) -> str:
"""Unit or quantity of measurement for the spectral dataset."""
@units.setter
def units(self, arg: str, /) -> None: ...
[docs]
def load(self, path: str, reshape: bool = True) -> bool:
"""
Load spectral data from a given path
:param path: path a path to the file to load data from
:type path: str
:param reshape: if set to ``True``, the data will be reshaped to
:py:attr:`rawtoaces.Spectrum.ReferenceShape`
:type reshape: bool
:return: ``True`` if loaded successfully.
"""
def __getitem__(self, name: str) -> Spectrum:
"""
Return a copy of the named channel in the ``main`` data set.
:param name: Channel name in the ``main`` set.
:return: A copy of that channel's spectrum.
:raises ValueError: If the ``main`` set or the channel is absent.
"""
def __setitem__(self, name: str, curve: Spectrum) -> None:
"""
Replace the named channel in the ``main`` data set.
:param name: Channel name in the ``main`` set.
:param curve: Spectrum to store. The channel must already exist.
:raises ValueError: If the ``main`` set or the channel is absent.
"""
def __contains__(self, name: str) -> bool:
"""
Return whether ``name`` is a channel in the ``main`` data set.
:param name: Channel name to look up.
:return: ``True`` when that channel exists. An empty container and a
missing ``main`` set return ``False``.
"""
__iter__: None = None
[docs]
def get(self, set_name: str, channel_name: str) -> Spectrum:
"""
Return a copy of one channel from a named data set.
:param set_name: Spectral set name, usually ``"main"``.
:param channel_name: Channel name within that set.
:return: A copy of the matching spectrum.
:raises ValueError: If the set or channel is absent.
"""
class TransformSolver:
"""Base class for a colour space transform solver."""
def calculate_transform(self) -> bool:
"""
Calculate the transform matrix. The solved matrix can be accessed via
``transform_matrix``.
Call this method on :py:class:`rawtoaces.MetadataSolver` or
:py:class:`rawtoaces.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 with :py:meth:`rawtoaces.SpectralSolver.calculate_WB`
or the multiplier form of
:py:meth:`rawtoaces.SpectralSolver.find_illuminant`.
:return: ``True`` if calculated successfully, ``False`` otherwise.
Inspect ``last_error_message`` on failure. Read
``transform_matrix`` only after a successful solve.
"""
@property
def transform_matrix(self) -> list[list[float]]:
"""
A 3×3 colour transform matrix populated by `calculate_transform()`
(initially the identity matrix).
"""
@transform_matrix.setter
def transform_matrix(self, arg: Sequence[Sequence[float]], /) -> None: ...
@property
def last_error_message(self) -> str:
"""
Error message from the most recent method call that returned ``False``.
"""
@last_error_message.setter
def last_error_message(self, arg: str, /) -> None: ...
@property
def verbosity(self) -> int:
"""Verbosity level."""
@verbosity.setter
def verbosity(self, arg: int, /) -> None: ...
[docs]
class SpectralSolver(TransformSolver):
"""
Solve an input transform using spectral sensitivity curves of a camera.
The inherited ``calculate_transform``, ``transform_matrix``,
``last_error_message``, and ``verbosity`` members are available on this
class.
"""
def __init__(self, search_directories: Sequence[str] = []) -> None:
"""
Initialize SpectralSolver with database search path.
Sets white balance multipliers to neutral (1, 1, 1),
``transform_matrix`` to identity, and ``verbosity`` to zero. Takes the
database search path as an optional parameter for finding spectral data
files.
:param search_directories: optional database search path for spectral
data files
"""
[docs]
def collect_data_files(self, type: str) -> list[str]:
"""
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.
:param type: data type of the files to search for (e.g., ``camera``,
``illuminant``, ``cmf``)
:type type: str
:return: a collection of file paths found in the database
"""
[docs]
def find_camera(self, make: str, model: str) -> bool:
"""
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.
:param make: the camera make to search for
:type make: str
:param model: the camera model to search for
:type model: str
:return: ``True`` if loaded successfully, ``False`` otherwise
"""
@overload
def find_illuminant(self, type: str) -> bool:
"""
Load 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; call ``calculate_WB()``
after loading the camera.
:param type: Non-empty standard or database illuminant name.
:return: ``True`` on success, ``False`` on failure. A failed database lookup
may leave ``last_error_message`` empty or unchanged.
:raises ValueError: If ``type`` is empty.
"""
@overload
def find_illuminant(self, wb_multipliers: Sequence[float]) -> bool:
"""
Choose 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()``.
:param wb_multipliers: Exactly three white-balance multipliers, [R, G, B].
:return: ``True`` on success, ``False`` on failure. State-validation failures
populate ``last_error_message``; a failed database lookup may leave it
empty or unchanged.
:raises ValueError: If ``wb_multipliers`` does not contain exactly three values.
"""
[docs]
def calculate_WB(self) -> bool:
"""
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: ``True`` if calculated successfully, ``False`` otherwise
:pre: camera and illuminant data must be properly loaded
"""
[docs]
def load_spectral_data(self, file_path: str, out_data: SpectralData) -> bool:
"""
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.
:param file_path: the path to the file to load. If the path is relative,
all locations in the search path will be searched in.
:type file_path: str
:param out_data: the `SpectralData` object to be filled with the loaded
data.
:type out_data: rawtoaces.SpectralData
:return: ``True`` if loaded successfully, ``False`` otherwise
"""
[docs]
def get_WB_multipliers(self) -> list[float]:
"""
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.
:return: a 3-element white balance multiplier list [R, G, B]
:pre: white balance calculation must have been performed successfully
"""
@property
def camera(self) -> SpectralData:
"""
The camera spectral data. Can be either assigned directly, loaded
in place via ``solver.camera.load()``, or found via
``solver.find_camera()``.
"""
@camera.setter
def camera(self, arg: SpectralData, /) -> None: ...
@property
def illuminant(self) -> SpectralData:
"""
The illuminant spectral data. Can be either assigned directly, loaded
in place via ``solver.illuminant.load()``, or found via
``solver.find_illuminant()``.
"""
@illuminant.setter
def illuminant(self, arg: SpectralData, /) -> None: ...
@property
def observer(self) -> SpectralData:
"""
The observer spectral data. Can be either assigned directly, or loaded
in place via ``solver.observer.load()``.
"""
@observer.setter
def observer(self, arg: SpectralData, /) -> None: ...
@property
def training_data(self) -> SpectralData:
"""
The training set spectral data. Can be either assigned directly, or loaded
in place via ``solver.training_data.load()``.
"""
@training_data.setter
def training_data(self, arg: SpectralData, /) -> None: ...
[docs]
def calculate_IDT_matrix(self) -> bool:
"""
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.
:return: ``True`` if calculated successfully, ``False`` otherwise
:pre: camera, illuminant, observer, and training_data must be properly
loaded
.. deprecated:: 2.2.0
Will be removed in v3. Use ``calculate_transform()``.
"""
[docs]
def get_IDT_matrix(self) -> list[list[float]]:
"""
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: a 3×3 IDT transformation matrix
:pre: ``calculate_transform()`` or deprecated ``calculate_IDT_matrix()``
completed successfully
.. deprecated:: 2.2.0
Will be removed in v3. Read ``transform_matrix`` after a successful
``calculate_transform()`` call.
"""
[docs]
def collect_image_files(path: Sequence[str]) -> list[list[str]]:
"""
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.
:param path: paths vector of paths to files or directories to process.
:type path: list[str]
:return: list of batches, where each batch contains files from one input
path.
"""
[docs]
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.
"""
def __init__(self) -> None:
"""Default constructor."""
@property
def settings(self) -> ImageConverter.Settings:
"""The conversion settings."""
@settings.setter
def settings(self, arg: ImageConverter.Settings, /) -> None: ...
@property
def status(self) -> ImageConverter.Status:
"""
This property holds the error code from the most recent method call
that returns a bool.
"""
@property
def last_error_message(self) -> str:
"""
Error message from the most recent method call that returned ``False``.
"""
@last_error_message.setter
def last_error_message(self, arg: str, /) -> None: ...
[docs]
def process_image(self, input_filename: str) -> bool:
"""
A convenience single-call method to process an image.
:param input_filename: Full path to the file to be converted.
:type input_filename: str
:return: ``True`` if processed successfully.
"""
[docs]
def get_WB_multipliers(self) -> list[float]:
"""
Get the solved white balance multipliers of the currently processed
image. The multipliers become available after calling the ``configure``
method.
:return: a list containing 3 multiplier values.
"""
[docs]
def get_IDT_matrix(self) -> list[list[float]]:
"""
Get the solved input transform matrix of the currently processed image.
The matrix becomes available after calling the ``configure`` method.
:return: a list containing a 3x3 matrix.
.. deprecated:: 2.2.0
Will be removed in v3. Use ``get_transform_matrix()``.
"""
[docs]
def get_CAT_matrix(self) -> list[list[float]]:
"""
Get the solved chromatic adaptation transform matrix of the currently
processed image. The matrix becomes available after calling the
``configure`` method.
:return: a list containing a 3x3 matrix.
.. deprecated:: 2.2.0
Will be removed in v3. Use ``get_transform_matrix()``.
"""
@overload
def configure(self, input_filename: str) -> bool:
"""
Configure white balance, the colour transform and decoding options from a file.
Uses the current ``settings`` and reads metadata from ``input_filename``.
This overload is available in every Python build and does not expose the
OpenImageIO decoding options to Python.
:param input_filename: Path to the RAW image whose metadata will be read.
:return: ``True`` on success, ``False`` on failure. On failure, inspect
``last_error_message`` and ``status``.
"""
@overload
def configure(self, input_filename: str, options: OpenImageIO.ParamValueList) -> bool:
"""
Configure white balance, the colour transform and decoding options from a file.
Uses the current ``settings`` and reads metadata from ``input_filename``.
``options`` may 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
:ref:`python-oiio-availability`.
:param input_filename: Path to the RAW image whose metadata will be read.
:param options: OpenImageIO input options; this object may be modified.
:return: ``True`` on success, ``False`` on failure. On failure, inspect
``last_error_message`` and ``status``.
"""
@overload
def configure(self, image_spec: OpenImageIO.ImageSpec, options: OpenImageIO.ParamValueList) -> bool:
"""
Configure white balance, the colour transform and decoding options from metadata.
Uses the current ``settings`` and fills or modifies ``options`` in place with
OpenImageIO decoding hints. Requires compatible OpenImageIO 3.2+ bindings;
see :ref:`python-oiio-availability`.
:param image_spec: Image specification containing the source metadata.
:param options: OpenImageIO input options; this object may be modified.
:return: ``True`` on success, ``False`` on failure. On failure, inspect
``last_error_message`` and ``status``.
"""
[docs]
def get_supported_illuminants(self) -> list[str]:
"""
Collects all illuminants supported by this version.
:return: List of all supported illuminants.
"""
[docs]
def get_supported_cameras(self) -> list[str]:
"""
Collects all camera models for which spectral sensitivity data is
available in the database.
:return: List containing camera model names.
"""
[docs]
def apply_lens_correction(self, dst: OpenImageIO.ImageBuf, src: OpenImageIO.ImageBuf) -> bool:
"""
Apply the lens correction to the image buffer.
Available only with compatible OpenImageIO 3.2+ bindings; see
:ref:`python-oiio-availability`.
:param dst: Destination image buffer
:type dst: OpenImageIO.ImageBuf
:param src: Source image buffer, can be the same as ``dst`` for in-place conversion.
:type src: OpenImageIO.ImageBuf
:return: ``True`` if applied successfully.
"""
[docs]
def apply_matrix(self, dst: OpenImageIO.ImageBuf, src: OpenImageIO.ImageBuf) -> bool:
"""
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
:ref:`python-oiio-availability`.
:param dst: Destination image buffer.
:type dst: OpenImageIO.ImageBuf
:param src: Source image buffer, can be the same as ``dst`` for in-place conversion.
:type src: OpenImageIO.ImageBuf
:return: ``True`` if applied successfully.
"""
[docs]
def apply_scale(self, dst: OpenImageIO.ImageBuf, src: OpenImageIO.ImageBuf) -> bool:
"""
Multiply image buffer pixel values by ``settings.headroom * settings.scale``.
Available only with compatible OpenImageIO 3.2+ bindings; see
:ref:`python-oiio-availability`.
:param dst: Destination image buffer
:type dst: OpenImageIO.ImageBuf
:param src: Source image buffer, can be the same as ``dst`` for in-place conversion.
:type src: OpenImageIO.ImageBuf
:return: ``True`` if applied successfully.
"""
[docs]
def apply_crop(self, dst: OpenImageIO.ImageBuf, src: OpenImageIO.ImageBuf) -> bool:
"""
Apply the cropping mode as specified in crop_mode.
Available only with compatible OpenImageIO 3.2+ bindings; see
:ref:`python-oiio-availability`.
:param dst: Destination image buffer.
:type dst: OpenImageIO.ImageBuf
:param src: Source image buffer, can be the same as ``dst`` for in-place conversion.
:type src: OpenImageIO.ImageBuf
:return: ``True`` if applied successfully.
"""
[docs]
def process_buffer(self, dst: OpenImageIO.ImageBuf, src: OpenImageIO.ImageBuf) -> bool:
"""
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.
Available only with compatible OpenImageIO 3.2+ bindings; see
:ref:`python-oiio-availability`.
:param dst: Destination image buffer.
:type dst: OpenImageIO.ImageBuf
:param src: Source image buffer, can be the same as ``dst`` for in-place conversion.
:type src: OpenImageIO.ImageBuf
:return: ``True`` if processed successfully.
"""
[docs]
def load_image(self, path: str, hints: OpenImageIO.ParamValueList, buffer: OpenImageIO.ImageBuf, data_type: OpenImageIO.TypeDesc = OpenImageIO.BASETYPE.FLOAT) -> bool:
"""
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.
Available only with compatible OpenImageIO 3.2+ bindings; see
:ref:`python-oiio-availability`.
:param path: Path to where the image from.
:type path: str
:param hints: Conversion hints to be passed to OIIO when reading an image file.
:type hints: OpenImageIO.ParamValueList
:param buffer: Destination buffer where the image loaded into.
:type buffer: OpenImageIO.ImageBuf
:param data_type: Sample type in the destination buffer (default:
``OpenImageIO.FLOAT``).
:type data_type: OpenImageIO.TypeDesc
:return: ``True`` if image load successfully.
"""
[docs]
def save_image(self, output_filename: str, buf: OpenImageIO.ImageBuf, data_type: OpenImageIO.TypeDesc = OpenImageIO.BASETYPE.HALF) -> bool:
"""
Save an image into an ACES container.
Available only with compatible OpenImageIO 3.2+ bindings; see
:ref:`python-oiio-availability`.
:param output_filename: Full path to the output file.
:type output_filename: str
:param buf: Image buffer to save.
:type buf: OpenImageIO.ImageBuf
:param data_type: Sample type written to the file (default:
``OpenImageIO.HALF``).
:type data_type: OpenImageIO.TypeDesc
:return: ``True`` if saved successfully.
"""
[docs]
class Settings:
"""
The structure containing all parameters needed to configure image
conversion.
"""
def __init__(self) -> None: ...
@property
def WB_method(self) -> ImageConverter.Settings.WBMethod:
"""The selected white-balancing method to use for conversion."""
@WB_method.setter
def WB_method(self, arg: ImageConverter.Settings.WBMethod, /) -> None: ...
@property
def matrix_method(self) -> ImageConverter.Settings.MatrixMethod:
"""
The selected colour transform matrix calculation method to use for
conversion.
"""
@matrix_method.setter
def matrix_method(self, arg: ImageConverter.Settings.MatrixMethod, /) -> None: ...
@property
def crop_mode(self) -> ImageConverter.Settings.CropMode:
"""The selected cropping mode to use for conversion."""
@crop_mode.setter
def crop_mode(self, arg: ImageConverter.Settings.CropMode, /) -> None: ...
@property
def illuminant(self) -> str:
"""
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.
"""
@illuminant.setter
def illuminant(self, arg: str, /) -> None: ...
@property
def headroom(self) -> float:
"""
Linear highlight headroom factor (default 6.0). Pixel scaling uses
``headroom * scale``.
"""
@headroom.setter
def headroom(self, arg: float, /) -> None: ...
@property
def custom_camera_make(self) -> str:
"""
Camera manufacturer name to be used for spectral sensitivity
curves lookup.
"""
@custom_camera_make.setter
def custom_camera_make(self, arg: str, /) -> None: ...
@property
def custom_camera_model(self) -> str:
"""Camera model name to be used for spectral sensitivity curves lookup."""
@custom_camera_model.setter
def custom_camera_model(self, arg: str, /) -> None: ...
@property
def auto_bright(self) -> bool:
"""Enable automatic exposure adjustment."""
@auto_bright.setter
def auto_bright(self, arg: bool, /) -> None: ...
@property
def adjust_maximum_threshold(self) -> float:
"""
Automatically lower the linearity threshold provided in the metadata by
this scaling factor.
"""
@adjust_maximum_threshold.setter
def adjust_maximum_threshold(self, arg: float, /) -> None: ...
@property
def black_level(self) -> int:
"""If >= 0, override the black level specified in the file metadata."""
@black_level.setter
def black_level(self, arg: int, /) -> None: ...
@property
def saturation_level(self) -> int:
"""If >= 0, override the saturation level specified in the file metadata."""
@saturation_level.setter
def saturation_level(self, arg: int, /) -> None: ...
@property
def half_size(self) -> bool:
"""Decode the image at half size resolution."""
@half_size.setter
def half_size(self, arg: bool, /) -> None: ...
@property
def highlight_mode(self) -> int:
"""
Highlight recovery mode, as supported by OpenImageIO/Libraw:
0 = clip, 1 = unclip, 2 = blend, 3..9 = rebuild.
"""
@highlight_mode.setter
def highlight_mode(self, arg: int, /) -> None: ...
@property
def flip(self) -> 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.)
"""
@flip.setter
def flip(self, arg: int, /) -> None: ...
@property
def denoise_threshold(self) -> float:
"""Wavelet denoising threshold."""
@denoise_threshold.setter
def denoise_threshold(self, arg: float, /) -> None: ...
@property
def scale(self) -> float:
"""Additional scaling factor to apply to the pixel values."""
@scale.setter
def scale(self, arg: float, /) -> None: ...
@property
def demosaic_algorithm(self) -> str:
"""
Demosaicing algorithm.
Supported options: ``linear``, ``VNG``, ``PPG``, ``AHD``, ``DCB``,
``DHT``, ``AAHD``.
"""
@demosaic_algorithm.setter
def demosaic_algorithm(self, arg: str, /) -> None: ...
@property
def bad_pixels_path(self) -> 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.
"""
@bad_pixels_path.setter
def bad_pixels_path(self, arg: str, /) -> None: ...
@property
def database_directories(self) -> list[str]:
"""
Directory containing rawtoaces spectral sensitivity and illuminant
data files. Overrides the default search path and the
``RAWTOACES_DATA_PATH`` environment variable.
"""
@database_directories.setter
def database_directories(self, arg: Sequence[str], /) -> None: ...
@property
def overwrite(self) -> bool:
"""Allows overwriting existing files."""
@overwrite.setter
def overwrite(self, arg: bool, /) -> None: ...
@property
def create_dirs(self) -> bool:
"""Create output directories if they don't exist."""
@create_dirs.setter
def create_dirs(self, arg: bool, /) -> None: ...
@property
def compression(self) -> 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``.
"""
@compression.setter
def compression(self, arg: str, /) -> None: ...
@property
def output_dir(self) -> str:
"""The directory to write the output files to."""
@output_dir.setter
def output_dir(self, arg: str, /) -> None: ...
@property
def use_timing(self) -> bool:
"""Log the execution time of each step of image processing."""
@use_timing.setter
def use_timing(self, arg: bool, /) -> None: ...
@property
def disable_cache(self) -> bool:
"""Disable caching."""
@disable_cache.setter
def disable_cache(self, arg: bool, /) -> None: ...
@property
def disable_exiftool(self) -> bool:
"""Disable calling exiftool to fetch missing metadata."""
@disable_exiftool.setter
def disable_exiftool(self, arg: bool, /) -> None: ...
@property
def keep_diagnostic_attributes(self) -> 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 ``rta`` prefix.
"""
@keep_diagnostic_attributes.setter
def keep_diagnostic_attributes(self, arg: bool, /) -> None: ...
@property
def verbosity(self) -> int:
"""Verbosity level."""
@verbosity.setter
def verbosity(self, arg: int, /) -> None: ...
@property
def lens_correction_types(self) -> ImageConverter.Settings.LensCorrectionType:
"""
The requested lens correction types.
No correction is requested by default. Combine LensCorrectionType
values to enable it.
"""
@lens_correction_types.setter
def lens_correction_types(self, arg: ImageConverter.Settings.LensCorrectionType, /) -> None: ...
@property
def require_lens_correction(self) -> 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.
"""
@require_lens_correction.setter
def require_lens_correction(self, arg: bool, /) -> None: ...
@property
def custom_lens_make(self) -> str:
"""Lens manufacturer name to be used for lens correction data lookup."""
@custom_lens_make.setter
def custom_lens_make(self, arg: str, /) -> None: ...
@property
def custom_lens_model(self) -> str:
"""Lens model name to be used for lens correction data lookup."""
@custom_lens_model.setter
def custom_lens_model(self, arg: str, /) -> None: ...
@property
def custom_aperture(self) -> float:
"""Aperture (f-number) to be used for lens correction."""
@custom_aperture.setter
def custom_aperture(self, arg: float, /) -> None: ...
@property
def custom_focal_length(self) -> float:
"""Focal length to be used for lens correction."""
@custom_focal_length.setter
def custom_focal_length(self, arg: float, /) -> None: ...
@property
def custom_focus_distance(self) -> float:
"""Focus distance to be used for lens correction."""
@custom_focus_distance.setter
def custom_focus_distance(self, arg: float, /) -> None: ...
@property
def WB_box(self) -> list[int]:
"""
Box to use for white balancing when ``WB_method`` == ``WBMethod::Box``.
(default = (0,0,0,0) - full image)
"""
@WB_box.setter
def WB_box(self, arg: Sequence[int], /) -> None: ...
@property
def custom_WB(self) -> list[float]:
"""
Custom white balance multipliers to be used when
``WB_method`` == ``WBMethod::Custom``.
"""
@custom_WB.setter
def custom_WB(self, arg: Sequence[float], /) -> None: ...
@property
def custom_matrix(self) -> 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.
"""
@custom_matrix.setter
def custom_matrix(self, arg: Sequence[Sequence[float]], /) -> None: ...
@property
def crop_box(self) -> 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.
"""
@crop_box.setter
def crop_box(self, arg: Sequence[int], /) -> None: ...
@property
def chromatic_aberration(self) -> list[float]:
"""Red and blue scale factors for chromatic aberration correction."""
@chromatic_aberration.setter
def chromatic_aberration(self, arg: Sequence[float], /) -> None: ...
[docs]
class WBMethod(enum.Enum):
"""The enumerator containing all supported white-balancing methods."""
Metadata = 0
"""
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.
"""
Illuminant = 1
"""
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.
"""
Box = 2
"""
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.
"""
Custom = 3
"""
Use custom white balancing multipliers. This mode is useful if
the white balancing coefficients are calculated by an external tool.
"""
[docs]
class MatrixMethod(enum.Enum):
"""
The enumerator containing all supported colour transform matrix
calculation methods.
"""
Auto = 0
"""
Automatically choose the best available matrix method.
- If spectral sensitivity data for the camera is available, use ``Spectral``.
- Otherwise, fall back to ``Metadata``.
"""
Spectral = 1
"""
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.
"""
Metadata = 2
"""
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.
"""
Adobe = 3
"""Use the Adobe colour matrix for the camera supplied in LibRaw."""
Custom = 4
"""
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.
"""
[docs]
class CropMode(enum.Enum):
"""The enumerator containing all supported cropping modes."""
Off = 0
"""Write out full sensor area."""
Soft = 1
"""
Write out full sensor area, mark the crop area as the display
window.
"""
Hard = 2
"""Write out only the crop area."""
[docs]
class LensCorrectionType(enum.Flag):
"""The enumerator containing all supported lens correction types."""
Aberration = 1
"""Chromatic aberration"""
Distortion = 2
"""Geometric distortion"""
Vignetting = 4
"""Vignetting"""
Metadata: ImageConverter.Settings.MatrixMethod = MatrixMethod.Metadata
Illuminant: ImageConverter.Settings.WBMethod = WBMethod.Illuminant
Box: ImageConverter.Settings.WBMethod = WBMethod.Box
Custom: ImageConverter.Settings.MatrixMethod = MatrixMethod.Custom
Auto: ImageConverter.Settings.MatrixMethod = MatrixMethod.Auto
Spectral: ImageConverter.Settings.MatrixMethod = MatrixMethod.Spectral
Adobe: ImageConverter.Settings.MatrixMethod = MatrixMethod.Adobe
Off: ImageConverter.Settings.CropMode = CropMode.Off
Soft: ImageConverter.Settings.CropMode = CropMode.Soft
Hard: ImageConverter.Settings.CropMode = CropMode.Hard
Aberration: ImageConverter.Settings.LensCorrectionType = LensCorrectionType.Aberration
Distortion: ImageConverter.Settings.LensCorrectionType = LensCorrectionType.Distortion
Vignetting: ImageConverter.Settings.LensCorrectionType = LensCorrectionType.Vignetting
[docs]
class Status(enum.Enum):
"""Status codes for operation results."""
Success = 0
""""Operation completed successfully."""
DatabaseNotFound = 14
"""Failed to locate spectral measurements database."""
FileExists = 1
"""Output file already exists and overwrite is not enabled."""
InputFileNotFound = 2
"""Input file does not exist."""
EmptyInputFilename = 3
"""Empty input filename provided."""
FilesystemError = 4
"""Filesystem error occurred."""
OutputDirectoryError = 5
"""Output directory does not exist and cannot be created."""
InvalidPath = 6
"""Invalid path format."""
ConfigurationError = 7
"""Failed to configure the image reader."""
ReadError = 8
"""Failed to read the image file."""
LensCorrectionError = 9
"""Failed to apply lens correction."""
MatrixApplicationError = 10
"""Failed to apply colour space conversion."""
ScaleApplicationError = 11
"""Failed to apply scale."""
CropApplicationError = 12
"""Failed to apply crop."""
WriteError = 13
"""Failed to save the output file."""
UnknownError = 15
"""Unknown error."""
Success: ImageConverter.Status = Status.Success
DatabaseNotFound: ImageConverter.Status = Status.DatabaseNotFound
FileExists: ImageConverter.Status = Status.FileExists
InputFileNotFound: ImageConverter.Status = Status.InputFileNotFound
EmptyInputFilename: ImageConverter.Status = Status.EmptyInputFilename
FilesystemError: ImageConverter.Status = Status.FilesystemError
OutputDirectoryError: ImageConverter.Status = Status.OutputDirectoryError
InvalidPath: ImageConverter.Status = Status.InvalidPath
ConfigurationError: ImageConverter.Status = Status.ConfigurationError
ReadError: ImageConverter.Status = Status.ReadError
LensCorrectionError: ImageConverter.Status = Status.LensCorrectionError
MatrixApplicationError: ImageConverter.Status = Status.MatrixApplicationError
ScaleApplicationError: ImageConverter.Status = Status.ScaleApplicationError
CropApplicationError: ImageConverter.Status = Status.CropApplicationError
WriteError: ImageConverter.Status = Status.WriteError
UnknownError: ImageConverter.Status = Status.UnknownError