RAW to ACES Utility

Table of Contents

1. Introduction
2. Package Contents
3. Prerequisites
4. Installation
5. Usage
6. Known Issues
7. License

Introduction

The RAW to ACES Utility or rawtoaces, is a software package that converts digital camera RAW files to ACES container files containing image data encoded according to the Academy Color Encoding Specification (ACES) as specified in SMPTE 2065-1. This is accomplished through one of two methods.

1. CameraRAW RGB data (generated by libraw) is converted to ACES by calculating an Input Device Transform (IDT) based on the camera's sensitivity and a light source.

2. CameraRAW RGB data (generated by libraw) is converted to ACES by calculating an RGB to XYZ matrix using information included in libraw and metadata found in the RAW file.

The output image complies with the ACES Container specification (SMPTE S2065-4).

Package Contents

The source code contains the following:

• cmake/ - CMake modules for locating dependencies (e.g., libraw )
• config/ - CMake configuration files
• data/ - Data files containing camera sensitivity, light source, color matching function and 190 training patch data
• lib/ - IDT and math libraries
• src/ - AcesRender wrapper library and C++ header file containing rawtoaces usage information
• test/ - Sample testing materials such as a ".NEF" RAW image and a camera spectral sensitivity data file
• main.cpp - C++ source code file for call routines to process images

Prerequisites

CMake

CMake can be downloaded directly from https://cmake.org/ and/or installed using one of the commands below.

• Ubuntu

   $ sudo apt-get install cmake

• Redhat

   $ yum install cmake

• macOS

  Install homebrew if not already installed

   /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  Install cmake

   $ brew install cmake

IlmBase

The rawtoaces tool depends on an essential part of the IlmBase software package, which can be downloaded from http://www.openexr.com and/or installed using one of the commands below.

• Ubuntu

   $ sudo apt-get install libilmbase-dev

• Redhat

   $ yum install ilmbase-devel

• macOS

  Install homebrew if not already installed

   /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  Install ilmBase

   $ brew install ilmBase

ACES Container

ACES Container is the reference implementation for a file writer intended to be used with the Academy Color Encoding System (ACES). rawtoaces relies on it to produce images that comply with the ACES container specification (SMPTE S2065-4). ACES Container can be downloaded from https://github.com/ampas/aces_container or installed using one of the commands below.

• Ubuntu / Redhat / macOS

  NOTE : During the beta period please use the build of ACES Container specified below

  Install aces_container

   git clone https://github.com/miaoqi/aces_container.git
   cd aces_container
   git checkout windowBuildSupport
   
   mkdir build && cd build
   cmake ..
   make
   sudo make install	

LibRaw

LibRaw is a library that processes RAW files from digital cameras. It handles image pre-processing for rawtoaces. LibRaw can be downloaded from http://www.libraw.org/download or installed using one of the commands below.

• Ubuntu

   $ sudo apt-get install libraw-dev

• Redhat

   $ yum install libraw1394-devel

• macOS

  Install homebrew if not already installed

   /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  Install libraw

   $ brew install libraw

Boost

Boost has multiple C++ libraries that support tasks related to linear algebra, multithreading, image processing, unit testing, etc. It handles data loading and unit testing for rawtoaces. Boost can be downloaded from http://www.boost.org/ or installed using one of the commands below.

• Ubuntu

   $ sudo apt-get install libboost-all-dev

• Redhat

   $ yum install boost-devel

• macOS

  Install homebrew if not already installed

   /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  Install boost

   $ brew install boost

Ceres Solver

Ceres Solver is an open source library for solving Non-linear Least Squares problems with bounds constraints and unconstrained optimization problems. It processes non-linear regression for rawtoaces. Ceres Solver can be downloaded from http://ceres-solver.org/ or installed using one of the commands below.

• Linux (e.g. Ubuntu)

  Install google-glog + gflags

   sudo apt-get install libgoogle-glog-dev

  Install BLAS & LAPACK

   sudo apt-get install libatlas-base-dev

  Install Eigen3

   sudo apt-get install libeigen3-dev

  Install SuiteSparse and CXSparse (optional)

   sudo apt-get install libsuitesparse-dev
   sudo add-apt-repository ppa:bzindovic/suitesparse-bugfix-1319687
   sudo apt-get update
   sudo apt-get install libsuitesparse-dev

  Build, Test and Install Ceres

   tar zxf ceres-solver-version#.tar.gz
   mkdir ceres-bin
   cd ceres-bin
   cmake ../ceres-solver-version#
   make -j3
   make test
   sudo make install

• macOS

  Install homebrew if not already installed

   /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  Install ceres-solver

   $ brew tap homebrew/homebrew-science
   $ brew install ceres-solver --HEAD

  If there are errors with regard to a version mis-match of the Eigen library, please consider brew-installing required libraries first and then buiding Ceres from source (see above).

  In case of any linking errors you should take ownership of CMAKE then run linker:

   sudo chown -R $USER:admin /usr/local/lib/cmake
   $ brew link ceres-solver

  In case of any GFlag errors AFTER running the next step (rawtoaces installation) you should repeat the install of ceres and follow the instructions shown in terminal to switch the version.

   $ brew install ceres-solver --HEAD

  This should present something like:

  homebrew/science/ceres-solver-HEAD-97cefd4_4 already installed, however linked version is 1.12.0_4 You can use brew switch ceres-solver HEAD-97cefd4_4 to link to this version.

  Therefore you would enter:

   $ brew switch ceres-solver HEAD-97cefd4_4

  And then repeat installation of rawtoaces in the next step.

Installation

• macOS

  Install homebrew if not already installed

   /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  Install rawtoaces

   $ brew install rawtoaces

• From Source

  From the root source directory:

   $ git clone https://github.com/ampas/rawtoaces
   $ mkdir build && cd build
   $ cmake ..
   $ make
   $ sudo make install

The default process will install librawtoaces_idt_${rawtoaces_version}.dylib and librawtoaces_util_${rawtoaces_version}.dylib to /usr/local/lib, a few header files to /usr/local/include/rawtoaces/include and a number of data files into /usr/local/include/rawtoaces/data.

Usage

Overview

rawtoaces uses one of three methods to convert RAW image files to ACES.

1. Camera spectral sensitivities and illuminant spectral power distributions
2. Camera file metadata
3. Camera data included in the libraw software

The preferred, and most accurate, method of converting RAW image files to ACES is to use camera spectral sensitivities and illuminant spectral power distributions, if available. If spectral sensitivity data is available for the camera, rawtoaces uses the method described in Academy document P-2013-001 (.pdf download).

While preferred, camera spectral sensitivity data is not commonly known to general users. When that is the case, rawtoaces can use either the metadata embedded in the camera file or camera data included in libraw to approximate a conversion to ACES.

Help message

A help message with a description of all command line options can be obtained by typing the following command:

$ rawtoaces --help
rawtoaces - convert RAW digital camera files to ACES

Usage:
  rawtoaces file ...
  rawtoaces [options] file
  rawtoaces --help
  rawtoaces --version

IDT options:
  --help                  Show this screen
  --version               Show version
  --wb-method [0-4]       White balance factor calculation method
                            0=white balance using file metadata 
                            1=white balance using user specified illuminant [str] 
                            2=Average the whole image for white balance
                            3=Average a grey box for white balance <x y w h>
                            4=Use custom white balance  <r g b g>
                            (default = 0)
  --mat-method [0-2]      IDT matrix calculation method
                            0=Calculate matrix from camera spec sens
                            1=Use file metadata color matrix
                            2=Use adobe coeffs included in libraw
                            (default = 0)
                            (default = /usr/local/include/rawtoaces/data/camera)
  --headroom float        Set highlight headroom factor (default = 6.0)
  --cameras               Show a list of supported cameras/models by LibRaw
  --valid-illums          Show a list of illuminants
  --valid-cameras         Show a list of cameras/models with available
                          spectral sensitivity datasets

Raw conversion options:
  -c float                Set adjust maximum threshold (default = 0.75)
  -C <r b>                Correct chromatic aberration
  -P <file>               Fix the dead pixels listed in this file
  -K <file>               Subtract dark frame (16-bit raw PGM)
  -k <num>                Set the darkness level
  -S <num>                Set the saturation level
  -n <num>                Set threshold for wavelet denoising
  -H [0-9]                Highlight mode (0=clip, 1=unclip, 2=blend, 3+=rebuild) (default = 0)
  -t [0-7]                Flip image (0=none, 3=180, 5=90CCW, 6=90CW)
  -j                      Don't stretch or rotate raw pixels
  -W                      Don't automatically brighten the image
  -b <num>                Adjust brightness (default = 1.0)
  -q [0-3]                Set the interpolation quality
  -h                      Half-size color image (twice as fast as "-q 0")
  -f                      Interpolate RGGB as four colors
  -m <num>                Apply a 3x3 median filter to R-G and B-G
  -s [0..N-1]             Select one raw image from input file
  -G                      Use green_matching() filter
  -B <x y w h>            Use cropbox

Benchmarking options:
  -v                      Verbose: print progress messages (repeated -v will add verbosity)
  -F                      Use FILE I/O instead of streambuf API
  -d                      Detailed timing report
  -E                      Use mmap()-ed buffer instead of plain FILE I/O

RAW conversion options

In most cases the default values for all "RAW conversion options" should be sufficient. Please see the help menu for details of the RAW conversion options.

Conversion using spectral sensitivities

If spectral sensitivity data for your camera is included with rawtoaces then the following command will convert your RAW file to ACES using that information.

$ rawtoaces input.raw

This command is equivalent to :

$ rawtoaces --wb-method 0 --mat-method 0 input.raw

To process mutiple raw files, you can try:

$ rawtoaces input1.raw input2.raw

To batch-process raw files in a directory, you can try:

$ rawtoaces input_dir

To batch-process raw files from multiple directories, you can try:

$ rawtoaces input_dir1 input_dir2

This is the preferred method as camera white balance gain factors and the RGB to ACES conversion matrix will be calculated using the spectral sensitivity data from your camera. This provides the most accurate conversion to ACES.

By default, rawtoaces will determine the adopted white by finding the set of white balance gain factors calculated from spectral sensitivities closest to the "As Shot" (aka Camera Multiplier) white balance gain factors included in the RAW file metadata. This default behavior can be overridden by including the desired adopted white name after the white balance method. The following example will use the white balance gain factors calculated from spectral sensitivities for D60.

$ rawtoaces --wb-method 1 D60 --mat-method 0 input.raw

If you have spectral sensitivity data for your camera but it is not included with rawtoaces you may place that data in /usr/local/include/RAWTOACES/data/camera or set the evironment variable AMPAS_CAMERA_SENSITIVITIES_PATH to the path of your camera's data.

If you have spectral data for an illuminant but it is not included with rawtoaces you may place that data in /usr/local/include/RAWTOACES/data/illuminant or set the evironment variable AMPAS_ILLUMINANT_PATH to the path of your data.

An example of the use of the custom spectral data directories would be

$ export AMPAS_CAMERA_SENSITIVITIES_PATH=/usr/local/include/rawtoaces/data/camera
$ export AMPAS_ILLUMINANT_PATH=/usr/local/include/rawtoaces/data/illuminant"
$ rawtoaces input.raw

JSON Schema for Spectral Datasets

The schema takes its roots in IES TM-27-14 but implements support for multiple spectral datasets while adopting JSON over XML for the simplicity of its grammar.

rawtoaces expects the spectral dataset to have the following shape: (380, 780, 5), i.e. starting from 380nm and ending at 780nm with a 5nm interval/bin size.

The attributes are defined as follows:

• header
  • schema_version
    • description: Required, schema version of the current document.
    • type: "string"
  • catalog_number
    • description: Optional,
    • type: ["string", "null"]
  • comments
    • description: Optional, additional information for the spectral dataset.
    • type: ["string", "null"]
  • description
    • description: Required, description of the spectral dataset.
    • type: "string"
  • document_creation_date
    • description: Required, document creation date expressed as per RFC 3339 - Date and Time on the Internet: Timestamps, e.g. 2017-01-01T12:00:00Z.
    • type: "string"
    • format: "date-time"
  • document_creator
    • description: Required, creator of the document, e.g. company, individual, laboratory, etc.
    • type: "string"
  • laboratory
    • description: Optional, laboratory or company that performed the measurements.
    • type: ["string", "null"]
  • license
    • description: Required, usage license of the document, e.g. "CC-BY-NC-ND".
    • type: ["string", "null"]
  • manufacturer
    • description: Optional, manufacturer of the device being tested.
    • type: ["string", "null"]
  • measurement_equipment
    • description: Optional, measurement equipment used to test the device.
    • type: ["string", "null"]
  • model
    • description: Optional, model of the device being tested.
    • type: ["string", "null"]
  • unique_identifier
    • description: Optional, generated unique identifier for the document, e.g. SHA256.
    • type: ["string", "null"]
• spectral_data
  • bandwidth_FWHM
    • description: Optional, spectro-radiometer full-width at half-maximum bandwidth in nm.
    • type: ["number", "null"]
  • bandwidth_corrected
    • description: Optional, whether bandwidth correction has been applied to the spectral data.
    • type: ["boolean", "null"]
  • data
    • description: Required, defines the spectral dataset, requiring at least one key from index whose value is an object containing wavelength/value pairs.
    • type: "object"
  • index
    • description: Required, indexes the spectral dataset.
    • type: "object"
  • reflection_geometry
    • description: Required if units is reflectance, reflection geometry attributes as per CIE 15:2004.
    • type: ["string", "null"]
    • enum: ["di:8", "de:8", "8:di", "8:de", "d:d", "d:0", "45a:0", "45c:0", "0:45a", "45x:0", "0:45x", "other", null]
  • transmission_geometry
    • description: Required if units is transmittance, transmission geometry attributes as per CIE 15:2004.
    • type: ["string", "null"]
    • enum: ["0:0", "di:0", "de:0", "0:di", "0:de", "d:d", "other", null]
  • units
    • description: Required, unit or quantity of measurement for the spectral dataset.
    • type: "string"
    • enum: ["flux", "absorptance", "transmittance", "reflectance", "intensity", "irradiance", "radiance", "exitance", "R-Factor", "T-Factor", "relative", "other"]

The full JSON schema for spectral datasets can be used to validate a new user file using a validator and is defined as follows:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "definitions": {
    },
    "id": "#",
    "properties": {
        "header": {
            "id": "/properties/header",
            "properties": {
                "schema_version": {
                    "description": "Required, schema version of the current document.",
                    "id": "/properties/header/properties/api_version",
                    "type": "string"
                },
                "catalog_number": {
                    "description": "Optional, ",
                    "id": "/properties/header/properties/catalog_number",
                    "type": ["string", "null"]
                },
                "comments": {
                    "description": "Optional, additional information for the spectral dataset.",
                    "id": "/properties/header/properties/comments",
                    "type": ["string", "null"]
                },
                "description": {
                    "description": "Required, description of the spectral dataset.",
                    "id": "/properties/header/properties/description",
                    "type": "string"
                },
                "document_creation_date": {
                    "description": "Required, document creation date expressed as per RFC 3339 - Date and Time on the Internet: Timestamps, e.g. 2017-01-01T12:00:00Z.",
                    "id": "/properties/header/properties/document_creation_date",
                    "type": "string",
                    "format": "date-time"
                },
                "document_creator": {
                    "description": "Required, creator of the document, e.g. company, individual, laboratory, etc.",
                    "id": "/properties/header/properties/document_creator",
                    "type": "string"
                },
                "laboratory": {
                    "description": "Optional, laboratory or company that performed the measurements.",
                    "id": "/properties/header/properties/laboratory",
                    "type": ["string", "null"]
                },
                "license": {
                    "description": "Required, usage license of the document, e.g. CC-BY-NC-ND",
                    "id": "/properties/header/properties/license",
                    "type": "string"
                },
                "manufacturer": {
                    "description": "Optional, manufacturer of the device being tested.",
                    "id": "/properties/header/properties/manufacturer",
                    "type": ["string", "null"]
                },
                "measurement_equipment": {
                    "description": "Optional, measurement equipment used to test the device.",
                    "id": "/properties/header/properties/measurement_equipment",
                    "type": ["string", "null"]
                },
                "model": {
                    "description": "Optional, model of the device being tested.",
                    "id": "/properties/header/properties/model",
                    "type": ["string", "null"]
                },
                "unique_identifier": {
                    "description": "Optional, generated unique identifier for the document, e.g. SHA256.",
                    "id": "/properties/header/properties/unique_identifier",
                    "type": ["string", "null"]
                }
            },
            "required": [
                "description",
                "document_creation_date",
                "document_creator",
                "license"
            ],
            "type": "object"
        },
        "spectral_data": {
            "id": "/properties/spectral_data",
            "properties": {
                "bandwidth_FWHM": {
                    "description": "Optional, spectro-radiometer full-width at half-maximum bandwidth in nm.",
                    "id": "/properties/spectral_data/properties/bandwidth_FWHM",
                    "type": ["number", "null"]
                },
                "bandwidth_corrected": {
                    "description": "Optional, whether bandwidth correction has been applied to the spectral data.",
                    "id": "/properties/spectral_data/properties/bandwidth_corrected",
                    "type": ["boolean", "null"]
                },
                "data": {
                    "description": "Required, defines the spectral dataset, requiring at least one *key* from `index` whose *value* is an *object* containing wavelength/value pairs.",
                    "id": "/properties/spectral_data/properties/data",
                    "patternProperties": {
                    	"^.*$": { "type": "object" }
                    },
                    "additionalProperties": false,
                    "type": "object"
                },
                "index": {
                    "description": "Required, indexes the spectral dataset.",
                    "id": "/properties/spectral_data/properties/index",
                    "patternProperties": {
                        	"^.*$": { "type": "array" }
                    },
                    "additionalProperties": false,
                    "type": "object"
                },
                "reflection_geometry": {
                    "description": "Required if `units` is *reflectance*, reflection geometry attributes as per CIE 15:2004.",
                    "id": "/properties/spectral_data/properties/reflection_geometry",
                    "type": ["string", "null"],
                    "enum": ["di:8", "de:8", "8:di", "8:de", "d:d", "d:0", "45a:0", "45c:0", "0:45a", "45x:0", "0:45x", "other", null]
                },
                "transmission_geometry": {
                    "description": "Required if `units` is *transmittance*, transmission geometry attributes as per CIE 15:2004.",
                    "id": "/properties/spectral_data/properties/transmission_geometry",
                    "type": ["string", "null"],
                    "enum": ["0:0", "di:0", "de:0", "0:di", "0:de", "d:d", "other", null]
                },
                "units": {
                    "description": "Required, unit or quantity of measurement for the spectral dataset.",
                    "id": "/properties/spectral_data/properties/units",
                    "type": "string",
                    "enum": ["flux", "absorptance", "transmittance", "reflectance", "intensity", "irradiance", "radiance", "exitance", "R-Factor", "T-Factor", "relative", "other"]
                }
            },
            "required": [
                "data",
                "index",
                "units"
            ],
            "type": "object"
        }
    },
    "required": [
        "header",
        "spectral_data"
    ],
    "type": "object"
}

Conversion using camera file metadata

In lieu of spectral sensitivity data, camera metadata can be used to convert RAW files to ACES. This includes the camera multiplier white balance gains and any RGB to XYZ matrix included. The RGB to XYZ matrix included in the metadata will be used to calculate the final RGB to ACES matrix used for conversion. The accuracy of this method is dependent on the camera manufacturer writing correct metadata into their RAW files.

The following commands will convert RAW to ACES using the camera file metadata for both white balance and the RGB to XYZ matrix.

$ rawtoaces --wb-method 0 --mat-method 1 input.raw

Conversion using camera data included in LibRaw

libraw includes matrices for a wide range of cameras which may provide a reasonable basis for conversion from RGB to ACES. These matrices were calculated by Adobe and are often referred to as the Adobe coefficients. To use these built-in matrices the following command may be used.

$ rawtoaces --mat-method 2

libraw also provides a few other methods for calculating white balance, including averaging the entire image, averaging a specified box within the image, or explicitly specifying the white balance gain factors to be used. These options can be utilized by using --wb-method [2-4] as desired.

Known Issues

For a list of currently known issues see the issues list in github. Please add any issue found to the github list.

License

For 3rd party license details see LICENSES.md

The RAW to ACES Utility Reference Implementation is provided by the Academy under the following terms and conditions:

Copyright © 2017 Academy of Motion Picture Arts and Sciences ("A.M.P.A.S."). Portions contributed by others as indicated. All rights reserved.

A worldwide, royalty-free, non-exclusive right to copy, modify, create derivatives, and use, in source and binary forms, is hereby granted, subject to acceptance of this license. Performance of any of the aforementioned acts indicates acceptance to be bound by the following terms and conditions:

Copies of source code, in whole or in part, must retain the above copyright notice, this list of conditions and the Disclaimer of Warranty.

Use in binary form must retain the above copyright notice, this list of conditions and the Disclaimer of Warranty in the documentation and/or other materials provided with the distribution.

Nothing in this license shall be deemed to grant any rights to trademarks, copyrights, patents, trade secrets or any other intellectual property of A.M.P.A.S. or any contributors, except as expressly stated herein.

Neither the name "A.M.P.A.S." nor the name of any other contributors to this software may be used to endorse or promote products derivative of or based on this software without express prior written permission of A.M.P.A.S. or the contributors, as appropriate.

This license shall be construed pursuant to the laws of the State of California, and any disputes related thereto shall be subject to the jurisdiction of the courts therein.

Disclaimer of Warranty: THIS SOFTWARE IS PROVIDED BY A.M.P.A.S. AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE DISCLAIMED. IN NO EVENT SHALL A.M.P.A.S., OR ANY CONTRIBUTORS OR DISTRIBUTORS, BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, RESITUTIONARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE ACADEMY SPECIFICALLY DISCLAIMS ANY REPRESENTATIONS OR WARRANTIES WHATSOEVER RELATED TO PATENT OR OTHER INTELLECTUAL PROPERTY RIGHTS IN THE RAW TO ACES UTILITY REFERENCE IMPLEMENTATION, OR APPLICATIONS THEREOF, HELD BY PARTIES OTHER THAN A.M.P.A.S., WHETHER DISCLOSED OR UNDISCLOSED.