Color correction with matrix transformation

With the 2.0 SDK version, we added a gpu_pipeline support. With this mode enabled, you can use a powerful instrument to change the brightness or color levels of the video in MPlatform and MFormats.

Important! This feature works only with the GPU-pipeline mode enabled.

What is a color transformation matrix?

In its most common form, color correction takes a form of 3x3 matrix operation, where each line is multiplied to some constant parameter (level), so we can imagine it as 4x3 matrix:

 and the color correction calculation looks like:

Rcc = Lr*(Rr*Ro + Rg*Go + Rb*Bo),
Gcc = Lg*(Gr*Ro + Gg*Go + Gb*Bo),
Bcc = Lb*(Br*Ro + Bg*Go + Bb*Bo),

Where Rcc, Gcc, and Bcc are the color-corrected output signals, Rr – Bb are the matrix coefficients for the color correction matrix, and Ro, Go, and Bo are the original signals.

How to set the matrix?

The matrix is set like a string of 12 coefficients separated by commas. The coefficients are in this order:

Rr, Rg, Rb, Lr, Gr, Gg, Gb, Lg, Br, Bg, Bb, Lb

For example, a matrix that doesn't transform colors - uses original signals - is "1,0,0,0,0,1,0,0,0,0,1,0"

To enable a color conversion you can specify the "gpu.rgb_transform_matrix" property in the system registry for MPlatform:

//MPlatform
HKEY_CURRENT_USER\Software\Medialooks\MPlatform\MFile
HKEY_CURRENT_USER\Software\Medialooks\MPlatform\MPlaylist
HKEY_CURRENT_USER\Software\Medialooks\MPlatform\MPreview
HKEY_CURRENT_USER\Software\Medialooks\MPlatform\MRenderer
gpu.rgb_transform_matrix = 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0

or in a source code with PropsSet method.

MPlatform

string BT2020_BT709 =@"
1.6605, -0.5876, -0.0728, 0.0,
-0.1246, 1.1329, -0.0083, 0.0,
-0.0182, -0.1006, 1.1187, 0.0";

m_objMFile.PropsSet("object::gpu.rgb_transform_matrix", BT2020_BT709 );

MFormats

Here you transform each and every frame separately:

pFrame.MFStrSet("gpu.rgb_transform_matrix", "1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0");

Shorten matrix values

You can set a full-sized matrix every time you use it - with all 12 parameters specified. But there are shorten version of the matrix:

Example value	Parameters	Explanation
"0.5"	Specifies only the main diagonal color elements keeping the level unchanged ("0"): Rr = Gg = Bb, the rest parameters are 0.
"0.5, 0.5"	Specifies the main diagonal color elements (with the same value) and the same level for all colors. Rr = Gg = Bb, Lr = Lg = Lb, the rest parameters are 0.
"0.7,0.5,0.9, 0.1,1.5,-0.2"	Specifies the main diagonal color elements with individual values (Rr, Gg, Bb), and the level values for each color (Lr, Lg, Lb). Other parameters are 0.

Predefined matrixes

There are a few predefined matrixes in SDK - for common color conversion scenarios like conversion of BT.709 colors into BT.2020.

You can specify such matrices by its shorten names with the PropsSet method:

Examples

There is a sample application attached to this article where the functionality of matrix color correction is illustrated.

Here is a sample of how it looks:

Original video with the original matrix value of "1,0,0,0,0,1,0,0,0,0,1,0" (doesn't change anything):

And a transformed one (with defined in the sample grayscale transformation) with the matrix value of "1,0,0,0,1,0,0,0,1,0,0,0":