How to create a 3D LUT to perform a colour transformation?

[jfitch12]

Hello,
newbie here, just learning what this great lib can do!

I have searched but not found a result, so I'm not sure if colour-science can currently achieve this.

How can I create a 3D LUT .cube that executes a color space transform, for example from P3 with Gamma 2.6 to Rec 709 with Gamma 2.4 ?
Is this possible ?

Thanks!

[KelSolaar]

Hello,

Yes this should be possible although this would be probably better expressed as a 2 1D LUTS + matrix but this should do:

import colour

lut3D = colour.LUT3D(size=33)
lut3D.table = colour.gamma_function(lut3D.table, 2.6)
lut3D.table = colour.RGB_to_RGB(lut3D.table, "DCI-P3", "sRGB")
lut3D.table = colour.cctf_encoding(lut3D.table,"ITU-R BT.1886")

colour.write_LUT(lut3D, "my_lut.cube")

[jfitch12]

does not seem to work, it writes an invalid LUT file:

TITLE "Unity 33"
LUT_3D_SIZE 33
0.0000000 0.0000000 0.0000000
0.0247919 nan nan
0.0525321 nan nan
0.0815062 nan nan
0.1113117 nan nan
0.1417512 nan nan

[KelSolaar]

Oh, of course! This is because we are going from a larger space , i.e., DCI-P3, to a smaller one, i.e., sRGB. Try this instead:

import colour
import numpy as np

lut3D = colour.LUT3D(size=33)
lut3D.table = colour.gamma_function(lut3D.table, 2.6)
lut3D.table = colour.RGB_to_RGB(lut3D.table, "DCI-P3", "sRGB")
lut3D.table = np.clip(lut3D.table, 0, np.inf)
lut3D.table = colour.cctf_encoding(lut3D.table,"ITU-R BT.1886")

colour.write_LUT(lut3D, "my_lut.cube")

[jfitch12]

same result, the LUT contains nan values.

[KelSolaar]

Try to clip before the second encoding, (I updated the snippet)

[KelSolaar]

Alternatively, if you are using the develop branch directly, you should be able to pull down the latest and get rid of the clip! I ensured that the BT 1886 function handles negative numbers, note that it will generate negative values in the LUT now.

[jfitch12]

clipping before the 2nd encoding did help that the LUT now contains numbers.
but the generated LUT is not correct.

[KelSolaar]

How is it not correct?

[KelSolaar]

This for example produce almost exactly the same output:

import colour
import numpy as np

def f(x):
    x = colour.gamma_function(x, 2.6)
    x = colour.RGB_to_RGB(x, "DCI-P3", "sRGB")
    return colour.cctf_encoding(x, "ITU-R BT.1886")


lut3D = colour.LUT3D(size=33)
lut3D.table = f(lut3D.table)

v = [
    [0.0, 0.0, 0.0],
    [0.2, 0.2, 0.2],
    [0.5, 0.5, 0.5],
    [0.75, 0.75, 0.75],
    [1.0, 1.0, 1.0],
]

print(f(v))
print(np.nan_to_num(lut3D.apply(v)))

[[ 0.          0.          0.        ]
 [ 0.17488563  0.17490428  0.17490248]
 [ 0.47190634  0.47195665  0.47195179]
 [ 0.73218587  0.73226393  0.73225639]
 [ 0.9999347   1.00004131  1.00003102]]
[[ 0.          0.          0.        ]
 [ 0.17464554  0.17487668  0.17479104]
 [ 0.47190634  0.47195665  0.47195179]
 [ 0.73218587  0.73226393  0.73225639]
 [ 0.9999347   1.00004131  1.00003102]]

[jfitch12]

How is it not correct?

1 - in order to get a LUT that maps from DCI-P3 to Rec 709, the order of operations has to be switched like this:

lut3D = colour.LUT3D(size=33)
lut3D.table = colour.gamma_function(lut3D.table, 2.6)
lut3D.table = colour.RGB_to_RGB(lut3D.table, "sRGB", "DCI-P3")
lut3D.table = colour.cctf_encoding(lut3D.table,"Gamma 2.4")

2 - but even with that, the resulting cube is higher than what I get from Lattice (commercial app). other than that, cube shape looks very similar.

Any idea why the colour-science cube is higher?

[KelSolaar]

Conversion from DCI-P3 to sRGB must be done by using colour.RGB_to_RGB(x, "DCI-P3", "sRGB") not the reverse which maps from sRGB to DCI-P3.

Then I'm assuming that you are going from a cinema-like display to HDTV one, hence the BT.1886 transfer function used which has a gamma of 2.4 and typically encodes sRGB/Rec.709 signals.

What do you mean by higher? Values going slightly over one? This is because of the whitepoint change, so depending your processing chain, you might need to either normalise the LUT or normalise post LUT application.

[jfitch12]

thank you, I will do that!

[KelSolaar]

Let us know how it goes!

[jfitch12]

Let us know how it goes!

it worked 👍 😄

Then I'm assuming that you are going from a cinema-like display to HDTV one, hence the BT.1886 transfer function used which has a gamma of 2.4 and typically encodes sRGB/Rec.709 signals.

yes, this is exactly what I did, but the projector is not very uniform in it's signal range.

question: if I take a table of measurements, for example 9x9x9, is it possible to create a 3D LUT from the measurement data with the colour package that calibrates the signal to for example standard Rec.709 gamma 2.4?

[KelSolaar]

Quite coincidentally, I made an example yesterday for someone else on how to do something very close to that and involving LUT inversion:

https://colab.research.google.com/drive/18CnW2TZTgl6xa_nR3NDBOHqoh0km2uPR

[jfitch12]

@KelSolaar

I made an example involving LUT inversion

Thanks for sharing, much appreciated! 🙏
Very interesting, I would have never thought of approaching it like this.
I tested this:
1 - first, using the random data in the example. keeping the inversed LUT at size 33. The resulting correction LUT when saved and analyzed in Lattice shows banding and artifacts. This may be due to the random data.
2 - Second, I then replaced the random test data with real profile data: 10x10x10 XYZ normalized. The resulting LUT is unusable. Visually already in Lattice, the cube is scattered instead of in the correct shape, heavy banding and posterization when applied to a color ramp.
When inserting the LUT into the signal chain and measuring a few patches, the R,G,B gamut primaries and W are not too far off, but everything inside the gamut has very high dE.
I then upped the correction LUT size to 330. Took a few minutes to complete. This LUT is slightly better, but still unusable.

Am I supplying the profile data incorrectly?

[KelSolaar]

Can you try to set query_size=9 or larger when calling the .invert method and see if it helps?

[jfitch12]

@KelSolaar
tried this in various ways in the .invert method:
1 - cube size 33, query size 9: shape is bit better but points still scattered - unusable
2 - cube size 33, query size up to 600: shape gets more and more deformed but less scattering of points, unusable and not accurate
3 - cube size 128, query size 600 (took a while to finish): shape seems to have improved, but the cube is now very small - unusable
4 - cube size 64, query size 120: same as 3, the trend seems to be that combining these two parameter together above a cube size of 33 compresses the cube - unusable

could you elaborate on the logic of inverting the cube measurements to derive the delta for LUT correction?

[KelSolaar]

The logic is simple, you when you measure, you map via a LUT $L$ a set of reference values $x$ to another set of measured values $y$, i.e., $y = L(x)$. Now you want to correct your measurements, which is finding $x$ for a given $y$, thus $L^{-1}$ must be applied, i.e., the inverse LUT.

[jfitch12]

The logic is simple, you when you measure, you map via a LUT L a set of reference values $x$to another set of measured values y , i.e., y = L ( x ) . Now you want to correct your measurements, which is finding x for a given y , thus L − 1 must be applied, i.e., the inverse LUT.

Wouldn't it rather be that we're mapping the measured values x via the LUT to the reference values?
i.e., the signal (which the measurements refer to) is corrected by the LUT to map to the reference target.
Either way, it's a little bit hard for me to follow the invert logic, as it:
1 - takes linear XYZ
2 - converts to linear sRGB - which will introduce a lot of negative values for displays that have much larger gamut than target/destination, those are obviously out of gamut points in terms of saturation, but that's to be expected, I have no idea how these are handled during inverting?
3 - then inverts the linear RGB cube to a much larger cube by brute force estimation
is this the final result correction LUT? or are we missing gamma encoding?
or do I need to run reference RGB values through that inverted cube to get the final correction LUT?
I'm confused 😄 I feel gamma encoding is missing and that this result is not accurate by estimating which is what the results show, but maybe this is user error on my part?

For example, my current approach outlined here, attempts to directly calculate the needed correction delta and then apply that to the LUT.
While the end result is unfortunately not as accurate as it needs to be (measurements are much closer but still too far off), the resulting cube is absolutely usable - there are no deformities or banding/posterization/artifacts introduced.
By the way, I attached the full profile data set here.
Can you comment on what is potentially missing in my outlined approach?

🙏, appreciate the conversation!

[KelSolaar]

Wouldn't it rather be that we're mapping the measured values x via the LUT to the reference values?

This is what you want to achieve indeed, but the measurements you took are from reference value to measured. So the function you define is going from reference to measured but you want to correct the measured values to the reference, thus the invert function is required, hence the LUT inversion.

I haven't spent too much time with your data as I'm busy working on other stuff but it is interlaced in a really odd way:

I would expect something along those lines to work with our code:

Blue increases faster, here is the linear table for a 4x4x4 Cube:

array([[[[ 0.        ,  0.        ,  0.        ],
         [ 0.        ,  0.        ,  0.33333333],
         [ 0.        ,  0.        ,  0.66666667],
         [ 0.        ,  0.        ,  1.        ]],

        [[ 0.        ,  0.33333333,  0.        ],
         [ 0.        ,  0.33333333,  0.33333333],
         [ 0.        ,  0.33333333,  0.66666667],
         [ 0.        ,  0.33333333,  1.        ]],

        [[ 0.        ,  0.66666667,  0.        ],
         [ 0.        ,  0.66666667,  0.33333333],
         [ 0.        ,  0.66666667,  0.66666667],
         [ 0.        ,  0.66666667,  1.        ]],

        [[ 0.        ,  1.        ,  0.        ],
         [ 0.        ,  1.        ,  0.33333333],
         [ 0.        ,  1.        ,  0.66666667],
         [ 0.        ,  1.        ,  1.        ]]],


       [[[ 0.33333333,  0.        ,  0.        ],
         [ 0.33333333,  0.        ,  0.33333333],
         [ 0.33333333,  0.        ,  0.66666667],
         [ 0.33333333,  0.        ,  1.        ]],

        [[ 0.33333333,  0.33333333,  0.        ],
         [ 0.33333333,  0.33333333,  0.33333333],
         [ 0.33333333,  0.33333333,  0.66666667],
         [ 0.33333333,  0.33333333,  1.        ]],

        [[ 0.33333333,  0.66666667,  0.        ],
         [ 0.33333333,  0.66666667,  0.33333333],
         [ 0.33333333,  0.66666667,  0.66666667],
         [ 0.33333333,  0.66666667,  1.        ]],

        [[ 0.33333333,  1.        ,  0.        ],
         [ 0.33333333,  1.        ,  0.33333333],
         [ 0.33333333,  1.        ,  0.66666667],
         [ 0.33333333,  1.        ,  1.        ]]],


       [[[ 0.66666667,  0.        ,  0.        ],
         [ 0.66666667,  0.        ,  0.33333333],
         [ 0.66666667,  0.        ,  0.66666667],
         [ 0.66666667,  0.        ,  1.        ]],

        [[ 0.66666667,  0.33333333,  0.        ],
         [ 0.66666667,  0.33333333,  0.33333333],
         [ 0.66666667,  0.33333333,  0.66666667],
         [ 0.66666667,  0.33333333,  1.        ]],

        [[ 0.66666667,  0.66666667,  0.        ],
         [ 0.66666667,  0.66666667,  0.33333333],
         [ 0.66666667,  0.66666667,  0.66666667],
         [ 0.66666667,  0.66666667,  1.        ]],

        [[ 0.66666667,  1.        ,  0.        ],
         [ 0.66666667,  1.        ,  0.33333333],
         [ 0.66666667,  1.        ,  0.66666667],
         [ 0.66666667,  1.        ,  1.        ]]],


       [[[ 1.        ,  0.        ,  0.        ],
         [ 1.        ,  0.        ,  0.33333333],
         [ 1.        ,  0.        ,  0.66666667],
         [ 1.        ,  0.        ,  1.        ]],

        [[ 1.        ,  0.33333333,  0.        ],
         [ 1.        ,  0.33333333,  0.33333333],
         [ 1.        ,  0.33333333,  0.66666667],
         [ 1.        ,  0.33333333,  1.        ]],

        [[ 1.        ,  0.66666667,  0.        ],
         [ 1.        ,  0.66666667,  0.33333333],
         [ 1.        ,  0.66666667,  0.66666667],
         [ 1.        ,  0.66666667,  1.        ]],

        [[ 1.        ,  1.        ,  0.        ],
         [ 1.        ,  1.        ,  0.33333333],
         [ 1.        ,  1.        ,  0.66666667],
         [ 1.        ,  1.        ,  1.        ]]]])

[jfitch12]

but it is interlaced in a really odd way

I assume by "interlaced" you mean the order of the patches?
If so, that is done on purpose to keep the display from heating up, and that's not an issue at all, as you can simply arrange the measurements as you like.
The measurement data used in my tests of the .invert method was arranged in a 10x10x10 LUT with blue fastest order.

Here is the measurement data as csv file, arranged with blue fastest channel.
Dell_10x10x10_LUT_order.csv

[KelSolaar]

Thanks, I did not have too much time to look into this but there is nothing I can do at this point to improve the inversion. You might have better luck with a LUT 3x1D + 3x3 matrix. Alternatively, you could try OpenColorIO inversion and see if it fares better.

[jfitch12]

okay, thanks for looking at it!
Would you happen to have a link to the OpenColorIO inversion function (they don't seem to have a discussion forum) and does OCIO have a Python version?

Thx!

[KelSolaar]

That would be ociobakelut: https://opencolorio.readthedocs.io/en/stable/guides/using_ocio/using_ocio.html#ociobakelut

[KelSolaar]

BTW, as we support OCIO to a degree in Colour, I had some plans to try having inversion via OCIO as a method.