Getting Started
Installation
Dependencies
The default CMake configuration builds the CLI, C++ libraries, Python bindings, and tests, with Eigen, Ceres, Lensfun, and the spectral database enabled. Install development headers and libraries as well as command line tools:
Dependency |
Requirement |
|---|---|
CMake and compiler |
CMake 3.15 or later and a C++17 compatible compiler. |
OpenImageIO |
OpenImageIO 3.0 or later, including a RAW input plugin built with LibRaw support. |
nlohmann-json |
Required JSON headers and CMake package configuration. |
Eigen3 and Ceres Solver |
Enabled by default. Ceres may also require Eigen and other dependencies from the package it was built against. |
Lensfun and pkg-config |
Lensfun 0.3.2 or later, discoverable through pkg-config. |
Python and nanobind |
Python 3.10 or later, its development headers, and nanobind’s CMake package. Required when |
pytest |
Needed to run Python tests when both bindings and tests are enabled. |
ExifTool is an optional runtime tool for fetching missing image metadata. Lens correction also needs Lensfun’s profile database; that database is separate from the rawtoaces spectral database.
On macOS, the native dependencies can be obtained from Homebrew:
brew install cmake eigen ceres-solver nlohmann-json openimageio lensfun pkgconf
export CMAKE_PREFIX_PATH="$(brew --prefix):$(brew --prefix eigen)"
The source-build and conversion steps below were checked with these dependencies already installed on macOS. Distribution packages on Linux and Windows differ in their versions and optional OpenImageIO plugins. This guide does not claim that an untested package-manager recipe supplies a compatible default build. Install the dependencies listed above through your package manager or from source, then use the same CMake build steps. The old CentOS 7 Word documents in the repository describe historical installations.
If CMake cannot find a dependency, add its installation prefix to CMAKE_PREFIX_PATH or provide its package directory, such as -DEigen3_DIR=/path/to/eigen/share/eigen3/cmake. For Lensfun, ensure pkg-config --modversion lensfun succeeds. That check fails when glib-2.0 is missing, because lensfun.pc requires it. Set PKG_CONFIG_PATH to the directory containing lensfun.pc for a custom installation. A Ceres package must find the Eigen version it was compiled against.
From Source
This example builds the CLI and C++ libraries while disabling the Python bindings and tests, so it does not require Python or nanobind:
git clone https://github.com/AcademySoftwareFoundation/rawtoaces.git
cd rawtoaces
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX="$PWD/install" \
-DRTA_BUILD_PYTHON_BINDINGS=OFF -DRTA_BUILD_TESTS=OFF
cmake --build build --config Release
cmake --install build --config Release
./install/bin/rawtoaces --version
./install/bin/rawtoaces --list-formats
--config Release selects the configuration for generators such as Visual Studio and Xcode; CMAKE_BUILD_TYPE selects it for single-configuration generators. Set the install prefix during configuration: this project resolves some installation directories to absolute paths at that point.
The install layout under the configured prefix is:
Default location |
Contents |
|---|---|
|
|
|
|
|
Public C++ headers. |
|
CMake package configuration and exported library targets. |
|
Spectral data and its license on macOS and Unix when |
Library and executable locations can be changed with INSTALL_LIB_DIR and INSTALL_BIN_DIR. The Python extension installs into the configured library directory, rather than automatically into Python’s site-packages.
Build Options
Option |
Default |
Effect |
|---|---|---|
|
|
Build the Python extension; requires Python development files and nanobind. |
|
|
Build the C++ tests and register Python tests when bindings are enabled. |
|
|
Fetch the pinned spectral data repository during configuration and install its data on macOS and Unix. Requires network access to fetch it. |
|
|
Enable lens corrections; requires Lensfun and pkg-config. |
|
|
Use Eigen/Ceres for numerical operations. Disabling either selects experimental alternatives. Disabling Eigen alone does not remove a Ceres package’s own Eigen dependency. |
|
|
Build shared C++ libraries. |
To build the Python extension, select the interpreter before configuring. For example, prepare a virtual environment and install its build and test packages:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install nanobind pytest
cmake -S . -B build-python -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX="$PWD/install-python" \
-DPython_EXECUTABLE="$VIRTUAL_ENV/bin/python"
cmake --build build-python --config Release
cmake --install build-python --config Release
Use the platform’s virtual-environment activation command on Windows. RTA_PYTHON_VERSION can additionally constrain CMake to an exact Python version. The interpreter must have matching development headers. Use that same interpreter to import the compiled extension. On macOS and Unix, for example:
PYTHONPATH="$PWD/install-python/lib" python -c \
"import rawtoaces; print(rawtoaces.ImageConverter)"
For builds against OpenImageIO 3.2 or later, rawtoaces also imports the OpenImageIO Python extension and checks its nanobind type registrations. Install a compatible OpenImageIO Python extension for the selected interpreter, with its native dependencies available to the runtime loader. Merely installing nanobind or satisfying the OpenImageIO version number is not sufficient. See API Overview for when to use the buffer methods and Python API for setup details.
Docker
With Docker installed, build the repository’s Dockerfile from the root source directory:
docker build -f Dockerfile -t rawtoaces:latest .
The Dockerfile compiles Ceres Solver, which needs substantial memory. The existing Dockerfile recommends allocating about 8 GB to Docker; increase the memory allocation in Docker Desktop’s resource settings if needed.
From a directory containing RAW images, mount that directory into the container and run the converter:
docker run -it --rm -v "$PWD:/tmp" -w /tmp rawtoaces:latest \
rawtoaces IMG_1234.CR2
Replace IMG_1234.CR2 with an existing RAW file. The mounted directory makes both the input image and the converted output available on the host. The container is removed when the command exits; files in the mounted directory remain.
Environment Setup
With RTA_INSTALL_DATABASE=ON, CMake fetches the spectral data into build/_deps/rawtoaces_data-src/data and installs it to <CMAKE_INSTALL_PREFIX>/share/rawtoaces/data on macOS and Unix. The library does not derive its runtime search path from a custom install prefix, so pass that data directory explicitly when using the local installation above.
On Windows, the data is fetched but not installed automatically. Keep the fetched data directory or obtain the rawtoaces-data repository and pass its data directory. That repository also describes dataset usage and the schema.
The CLI selects its data search paths in this order:
--data-diroverrides the other locations.RAWTOACES_DATA_PATHsupplies the primary environment override.AMPAS_DATA_PATHis a deprecated fallback whenRAWTOACES_DATA_PATHis unset.Platform defaults, including
/usr/local/share/rawtoaces/dataon macOS and Unix and/opt/homebrew/share/rawtoaces/dataon macOS. Windows defaults to the current directory. The old/usr/local/include/rawtoaces/datapath is retained only as a compatibility search location.
Separate multiple data directories with : on macOS and Unix, or ; on Windows. The path must identify the directory containing camera, illuminant, and the other spectral datasets, rather than the camera subdirectory alone.
Basic Usage
Replace input.dng with an existing RAW file:
./install/bin/rawtoaces --data-dir "$PWD/install/share/rawtoaces/data" \
--output-dir "$PWD/output" --create-dirs --crop-mode soft input.dng
This uses metadata white balance and the auto matrix method, which selects spectral solving if camera sensitivities are available and otherwise selects the metadata matrix method. It writes input_aces.exr into output. Existing output files are preserved unless --overwrite is supplied.
The CLI’s crop default is soft: it retains the sensor area and records the crop as the EXR display window. C++ and Python ImageConverter.Settings default to hard cropping. Choose the mode explicitly when comparing interfaces. For the full sensor area without a crop display window, use --crop-mode off. To write only the crop area, use --crop-mode hard.
To use the Adobe camera coefficients supplied by LibRaw:
./install/bin/rawtoaces --mat-method Adobe --crop-mode soft input.dng
Illuminant white balance and the spectral matrix method require measured camera sensitivities in the spectral database. For example, with rawtoaces on the command search path and a configured data path:
rawtoaces --wb-method illuminant --illuminant D60 \
--mat-method spectral --crop-mode soft input.dng
Use rawtoaces --help for the options supported by the installed build. For batch conversion and other options, see User Guide.
Migrating from v1.x
The v2 CLI uses named methods and long options. The tables below translate option fragments; append an input path to a complete conversion command. X Y W H and multiplier/matrix names are placeholders for separate numeric arguments, without commas or angle brackets.
White Balance and Matrix Methods
v1 option fragment |
Current option fragment |
Meaning |
|---|---|---|
|
|
Metadata multipliers. |
|
|
Spectral illuminant white balance. |
|
|
Whole-image neutral average. |
|
|
Neutral average of a region. |
|
|
Four custom multipliers. |
|
|
Spectral transform. |
|
|
Metadata matrices. |
|
|
LibRaw’s Adobe coefficients; case-sensitive name. |
|
|
Complete camera RGB to ACES AP0 transform, in row order. |
Supply a complete camera RGB to ACES AP0 transform. Both v1 and v2 custom matrix modes apply the supplied matrix directly to decoded camera RGB pixels before headroom and scale, without adding chromatic adaptation or an XYZ to ACES conversion. Older help and documentation incorrectly described this as camera RGB to XYZ.
RAW and Diagnostic Options
v1 option fragment |
Current option fragment |
Migration note |
|---|---|---|
|
|
Adjust the maximum threshold. |
|
|
Red and blue correction factors. |
|
|
Override the black level. |
|
|
Override the saturation level. |
|
|
Wavelet threshold. The current CLI parses this as an integer; do not assume a fractional v1 threshold is preserved. |
|
|
Highlight recovery mode. |
|
Omit |
Automatic brightening is already disabled by default. Supplying |
|
|
This is a different processing stage: v1 adjusted LibRaw’s decoder brightness, while |
|
|
Linear multiplier, not a number of exposure stops. |
|
|
Select AHD by name. |
|
|
Disable rotation. Other orientations use the current EXIF codes; v1’s numeric orientation codes must not be copied unchanged. |
|
No equivalent option. |
v1’s four-color interpolation flag was not an orientation flag. |
|
|
Decode at half-size resolution. |
|
|
Explicitly request cropped pixels; the CLI default |
|
|
LibRaw-format bad-pixel file. |
|
|
Print processing timings. |
|
|
List spectral illuminants. |
|
|
List cameras with spectral data, not every LibRaw-supported camera. |
Output files are no longer overwritten automatically. Use --overwrite only when replacement is intended. --output-dir accepts an absolute directory or a directory relative to each input’s directory; --create-dirs creates missing output directories.