User Guide

Command Line Interface

The rawtoaces command-line tool provides a comprehensive interface for converting RAW images to ACES format.

Basic Syntax

rawtoaces [options] <input_files_or_directories>

White Balance Options

--wb-method <method>

Specify the white balance method:

  • metadata (default): Use white balance from file metadata

  • illuminant: White balance to a specific illuminant

  • box: Calculate white balance from a region of the image

  • custom: Use custom white balance multipliers

--illuminant <name>

Specify the illuminant for white balancing. Can be:

  • A blackbody color temperature below 4000K (e.g., 2800K, 3200K)

  • A D-series illuminant (e.g., D50, D55, D65)

  • Any illuminant name present in the data folder

--wb-box <x,y,w,h>

Define a region for box white balance calculation.

--custom-wb <r,g,b,g2>

Provide custom white balance multipliers.

Matrix Options

--mat-method <method>

Specify the color matrix method:

  • auto (default): Use spectral if available, otherwise metadata

  • spectral: Use camera spectral sensitivity curves

  • metadata: Use matrix from file metadata (DNG)

  • adobe: Use Adobe color matrix from LibRaw

  • custom: Use a custom 3x3 matrix

--custom-matrix <m00,m01,...,m22>

Provide a custom 3x3 color transformation matrix.

Output Options

--output-dir <path>

Specify output directory for converted files.

--overwrite

Allow overwriting existing output files.

--create-dirs

Create output directories if they don’t exist.

--headroom <value>

Set the highlight headroom (default: 6.0 stops).

Cropping Options

--crop <mode>

Specify cropping mode:

  • off: Write full sensor area

  • soft: Full sensor area with crop marked as display window

  • hard (default): Write only the crop area

Camera Override Options

--custom-camera-make <name>

Override camera manufacturer name.

--custom-camera-model <name>

Override camera model name.

These options are useful when metadata is missing or incorrect.

Lens Correction Options

See Lens Correction for more information on lens correction.

--lens-correction <types>

Lens correction types to be applied to the images. Specify a string containing the following symbols in any order:

  • c: chromatic abberation

  • d: geometric distortion

  • v: vignetting

  • a: all of the above

--require-lens-correction

Lens correction is treated as optional by default, i.e. the correction will only be applied if there is sufficient information about the camera/lens and the shot conditions (aperture, focal length, focus distance) is available for the image. Setting this flag will make lens correction mandatory, the conversion will fail if lens correction can’t be applied.

--custom-lens-make <name>

Override lens manufacturer name.

--custom-lens-model <name>

Override lens model name.

--custom-aperture <value>

Override aperture (F-number) value.

--custom-focal-length <value>

Override focal length value (in millimetres).

--custom-focus-distance <value>

Override focus distance value (in metres).

Verbosity Options

--verbose or -v

Enable verbose output.

--timing

Show timing information for each processing step.

Examples

Convert a single file with default settings:

rawtoaces photo.dng

Convert using a specific illuminant:

rawtoaces --wb-method illuminant --illuminant D55 photo.cr2

Batch convert a directory:

rawtoaces --output-dir ./converted --overwrite /path/to/raw/files/

Use custom white balance:

rawtoaces --wb-method custom --custom-wb 2.1,1.0,1.5,1.0 photo.nef