The lut3d module is introduced in dt-2.7 and is designed to apply a 3D LUT (LookUp Table) to an image.
3D LUT
A 3D LUT is a tridimensional table which allows to transform any RGB value into another RGB value. The most common applications of LUTs are film simulation and color grading. But they can be used for any other technical transforms like LOG to REC.709, which are used in video edition for example.
The module accepts cube files, haldclut files and compressed LUT files.
Cube files
Cube files are used by video editors and colorists. They are text files with the cube extension. You can find such files through these links:
Haldclut files
Haldclut files are used in Rawtherapee and PhotoFlow. The are usually coded as a png image. Smaller than cube files, they are also more accurate (see LUT dimension below). Here are some places to find them:
Compressed LUT files
Compressed LUT files have been created by the G’MIC team (see Pixls.us - CLUT compression).
They are also png files but actually 100 times smaller than haldclut files. Decompression time is mitigated using cache files (which can be shared with G’MIC). This small size allows dt to save the image transformation in its database and/or in the image xmp file. See below some useful G’MIC scripts to created your compressed LUT library.
Note: except for compressed LUT, due to the size of the LUT file, LUT data are not saved with the parameters of the image. Instead the file path (inside the root folder) is saved. Then you need to backup properly the LUT files (+ folders) you have used.
CAUTION: dt understands Compressed LUT file only if G’MIC library is installed on your machine.
The module itself
Before using the module you must define the folder where you have stored the LUTs you like. This folder can have sub-folders. This is done selecting the correct 3D lut root folder in Configuration/Core options/Miscellaneous.
Lut3d has three parameters:
- LUT file
- application color space
- interpolation
LUT file
The different types of source file are described above.
The important point to remember is the difference between compressed and not compressed files. If compressed, the LUT itself is saved (compressed) with the parameters of the image, and in the xmp file if activated as well.
Otherwise the parameters only hold the file name and path (relative to 3D lut root folder). As a consequence the module cannot recalculate the image without original LUT file.
Color space
Each 3D LUT is built to be applied on a given color space. The module lut3d lets you select the appropriated one. Usually cube files are built for REC.709 and haldclut for sRGB.
Note: The color space selection is effective when lut3d module is placed between input color profile and output color profile modules. Otherwise the selected color profile is ignored, and the LUT is applied on the current profile in the pipeline.
Interpolation
The interpolation method defines the way to calculate colors which are not exactly on a node of the RGB cube (described by the LUT).
There are three interpolation methods available: tetrahedral (the default one), trilinear and pyramid. Usually you don’t see the difference between the interpolation method except sometimes with small size LUTs.
Cube dimension: The RGB cube is characterized by its dimensions. It’s always below 256. The larger it is, the more accurate the transform is. It seems that above 48x48x48 one cannot see the difference any more.
Usually haldclut cubes (64x64x64 is common) are larger than cube cubes (33x33x33 is common).
G’MIC commands.
G’MIC offers some useful commands to manipulate LUT files. To be able to run these commands you must have G’MIC installed on your machine.
See https://gmic.eu/.
Cube to Haldclut
Be careful, as an haldclut file is an image, the square of the image width must be equal to the cube of the cube size. The below command first resizes the input cube and then transforms the result into a flat image.
gmic -input_cube <filename1>.cube -r 64,64,64,3,3 -r 512,512,1,3,-1 -o <filename2>.png
Compression
Compression is a process which takes time. The compression commands are different for color or black & white transforms.
gmic -i <filename1>.png -compress_clut 8,2,2048 split c,2 append x permute yxzc -o <filename2>.png
- Color to black & white haldclut:
gmic -i <filename1>.png -compress_clut 8,2,2048 split c -r[3] 100%,100%,100%,3,1 append c split c,2 append x permute yxzc -o <filename2>.png
gmic -input_cube <filename1>.cube -compress_clut 8,2,2048 split c,2 append x permute yxzc -o <filename2>.png
About this article
This article is licensed under the terms of the Attribution 2.0 Generic (CC BY 2.0), or, at your option, the Creative Commons BY-NC-SA 3.0 License.
This is a companion discussion topic for the original entry at https://www.darktable.org/2019/05/New module-lut3d/