- Introduction
- Package Contents
- Prerequisites
- Installation
- Usage
- Known Issues
- Installation for Redhat
- License
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.
-
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.
-
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).
The source code contains the following:
cmake/
- CMake modules for locating dependencies (e.g.,libraw
)config/
- CMake configuration filesdata/
- Data files containing camera sensitivity, light source, color matching function and 190 training patch datalib/
- IDT and math librariessrc/
- AcesRender wrapper library and C++ header file containingrawtoaces
usage informationtest/
- Sample testing materials such as a ".NEF" RAW image and a camera spectral sensitivity data filemain.cpp
- C++ source code file for call routines to process images
To build rawtoaces
you would need to sutisfy these dependencies:
Library | Min Version | Purpose | Link to installation instruction |
---|---|---|---|
cmake |
3.10 |
CMake download | |
ceres |
1.12.0 |
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 installation |
imath |
3.1.8 |
Provides the half data type used for representing 16-bit floating-point values. It's used by rawtoaces for storing high dynamic range (HDR) data in a compact format. | Imath installation |
libraw |
0.19.4 |
LibRaw is a library that processes RAW files from digital cameras. It handles image pre-processing for rawtoaces. | LibRaw download |
boost |
1.76.0 |
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 download |
aces_container |
latest |
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 installation |
Install homebrew if not already installed
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install cmake ceres-solver imath libraw boost aces_container
$ sudo apt-get -f cmake
$ build_scripts/install_aces_container.bash
$ sudo apt-get -f install \
libimath-dev \
libboost-dev libboost-filesystem-dev \
libboost-test-dev \
libraw-dev libceres-dev
$ sudo yum install cmake
$ build_scripts/install_aces_container.bash
$ sudo yum install eigen3-devel ceres-solver-devel LibRaw-devel boost-devel imath
Install cmake first via installer or with Chocolatey:
$ choco install cmake
$ build_scripts/install_aces_container.bash
$ vcpkg install \
libraw:x64-windows \
ceres:x64-windows \
imath:x64-windows \
boost-system:x64-windows \
boost-foreach:x64-windows \
boost-filesystem:x64-windows \
boost-test:x64-windows \
boost-property-tree:x64-windows
From the root source directory:
$ git clone https://github.com/ampas/rawtoaces
$ cd rawtoaces
$ cmake -S . -B build
$ cmake --build build
$ sudo cmake --install build # Optional if you want it to be accessible system wide
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
.
Assuming you have Docker installed, installing and running rawtoaces is relatively straightforward except for the compilation of ceres-solver that requires a significant amount of memory, well over the 2Go that Docker allocates by default. Thus you will need to increase the memory in Docker preferences: Preferences --> Resources --> Advanced, 8Go should be enough.
-
From the root source directory, build the container:
$ docker build -f "Dockerfile" -t rawtoaces:latest "."
-
Then to run it from a directory with images:
$ docker run -it --rm -v $PWD:/tmp -w /tmp rawtoaces:latest rawtoaces IMG_1234.CR2
rawtoaces
uses one of three methods to convert RAW image files to ACES.
- Camera spectral sensitivities and illuminant spectral power distributions
- Camera file metadata
- 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.
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)
--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
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.
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
You can use the environment varilable of AMPAS_DATA_PATH
to specify the repository for your own datasets. 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 place the data in the folder pointed by AMPAS_DATA_PATH
.
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"
- description: Required, defines the spectral dataset, requiring at least one key from
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]
- description: Required if
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]
- description: Required if
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"
}
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
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.
For a list of currently known issues see the issues list in github. Please add any issue found to the github list.
Please follow the steps given in the docx files RAWtoACES_CentOS7.docx and RAWtoACES_CentOS7_noyum.docx with yum and without yum respectively.