PsychColorCorrection

Psychtoolbox › PsychGLImageProcessing

varargout = PsychColorCorrection(cmd, varargin)

This function is used to setup and control the built-in color correction
and transformation mechanisms of PTB's imaging pipeline. It allows to choose
among different methods of color correction (for calibrated output of
stimuli) and to change parameters of the chosen method. This only works
when the imaging pipeline is enabled and with certain output devices.

This functions are mostly meant to provide fast color correction, e.g.,
gamma correction, when PTB is used with special high precision / HDR
output devices, e.g., CRS Bits++ in Mono++ or Color++ mode, or video
attenuators. When operating such devices, the standard gamma correction
mechanisms of your graphics card can't be used, so PTB must do it itself.

With a standard 8bpc framebuffer, you won't need this function for simple
gamma correction or color correction.
Instead you'd use the Screen('LoadNormalizedGammaTable') command to
perform gamma correction with the graphics cards built-in gamma tables.
Same applies to Bits++ box in Bits++ mode, using the built-in tables of
the Bits++ device, also controlled via Screen('LoadNormalizedGammaTable').

For more complex correction schemes than a lookup table transform you can
still use this function, even with a normal 8 bit framebuffer, as long as
the imaging pipeline is enabled. It's just important to note that you
don't need to use it for a standard framebuffer in the simple case -- the
gfx cards gamma tables are more efficient for the simple case.

How to use:

1. Before opening an onscreen window, you use the following
PsychImaging() setup call to specify the method of display color correction
to apply, and the view channel to apply it to (in case there are multiple
like in many stereo display setups):

PsychImaging('AddTask', whichChannel, 'DisplayColorCorrection', methodname);
- where whichChannel can be 'LeftView' or 'RightView' for the left- or
right display output channel/device of a stereo setup, or
'FinalFormatting' if you have a single display monoscopic setup or want
to apply the same color correction to both channels of a stereo setup.
The parameter 'methodname' is a name string with the name of one of the
supported methods - See overview below for supported methods.

CAUTION: The order of specifications matters! If you use multiple color
correction methods or other image processing operations simultaneously,
make sure to specify them in the order in which they should be executed.
The system tries to order operations in a reasonable way, but it is not
fool-proof!

2. Then, after you've specified all other window parameters via the
PsychImaging() subcommands, you open the onscreen window via the usual
win = PsychImaging('OpenWindow', ....); call, as always when you use the
imaging pipeline. This will open the window and apply the chosen color
correction method, choosing reasonable default parameters for the method
at hand.

3. At any time in your script you can change the operating parameters of
the chosen color correction method via the PsychColorCorrection()
subfunctions mentioned below. You'll have to specify the window handle
for the onscreen window whose parameters should be changed, and - in a
stereo display setup with separate color correction parameters for each
of the display channels - the name 'whichChannel' of the display channel
to change, e.g., 'LeftView'. Changes take effect at next Screen('Flip').



Supported display color correction methods:
===========================================

These are the method names that can be passed as 'methodname' parameter to
PsychImaging('DisplayColorCorrection', ....., methodname):

'methodname' is the name string of one of the supported methods:

* 'None': Don't do anything. Fastest, but not safest.

If your stimulus contains (by accident) color or luminance values outside
the displayable range, the corresponding pixels may show undefined output
color -- Likely not what you want. This mode is about 10% faster than
'ClampOnly'. This mode is the default if no method is selected, unless
you use Bits++ in Mono++ or Color++ mode, where 'ClampOnly' is the
default.


* 'ClampOnly': Do not apply any color transformation. Default for Bits++
in Mono++ or Color++ mode:

In this mode, values are clamped against the limits set via
'SetColorClampingRange' (see below) to always keep them in the
requested range set via PsychColorCorrection('SetColorClampingRange'),
nothing else.


* 'CheckOnly': Do not apply any color transformation.

In this mode, values are checked against the limits set via
PsychColorCorrection('SetColorClampingRange'). Values outside that
range are visually coded, so you should be able to see troublesome
areas via visual inspection: All values are first clamped, then
inverted, in the hope that this creates clearly detectable artifacts in
your stimulus. We may change the "marker" method in the future if we
happen to find a better visual marker. This mode is meant for debugging
your stimulation scripts, not for running them on your subjects!

* 'SimpleGamma' : Apply some power-law based gamma correction:

Simple gamma correction means: Apply a power-law to incoming
values: outcolor = incolor ^ EncodingGamma. incolor is the uncorrected
input color or intensity, outcolor the corrected one, EncodingGamma is
encoding gamma value to apply. See PsychColorCorrection('SetEncodingGamma')
for how to set the gamma values. After gamma correction, output values
are clamped against the range set via PsychColorCorrection('SetColorClampingRange').

See PsychColorCorrection('SetExtendedGammaParameters') on how to supply
additional parameters for use of a more complex gamma correction function.


* 'LookupTable' : Apply color correction by color table lookup, ie. a CLUT.

This will allow to pass in a color lookup table of selectable
granularity (ie., number of slots) and range, which is later on used to
lookup corresponding corrected color values for given framebuffer input
values.


* 'GainMatrix' : Apply color gain correction by 2D gain matrix lookup.

This allows to apply a 2D matrix G which stores luminance- or color gain
correction factors for each single output pixel of the display. For
each 2D display pixel location (x,y), the stimulus image I(x,y) will be
multiplied with the corresponding gain factor G(x,y) of the gain matrix
and the result O(x,y) used for further processing and display. G(x,y)
can be a single scalar for luminance correction, or - if G is a 3-layer
matrix - a RGB vector with individual gains for each color channel and
pixel location.

O(x,y) = I(x,y) * G(x,y).

If you want to combine this with one of the other correction methods,
e.g., gamma correction, you should issue this command first, because
the non-linear gamma correction should apply to the output of this
method for correct results.

After you've opened your onscreen 'window', you'll need to define the 2D
gain 'matrix' via a call to ...

PsychColorCorrection('SetGainMatrix', ...);

See below for description of 'SetGainMatrix'.



Supported runtime Subfunctions:
===============================

The following routines must be called *after* opening a window for which color
correction is enabled. They can be called anytime and changed settings
will apply at the next Screen('Flip'). If your 'window' is actually a
stereo display window, you may want or need to provide the optional
'viewId' parameter to tell PTB which of the two stereo view channels
shall be changed in its settings. If both stereo views are displayed on
the same physical display device, this is not needed. If the separate
views go to separate physical displays, you may need to calibrate them
separately. Allowable values for viewId are 'AllViews', 'LeftView' and
'RightView', corresponding to the 'whichChannel' setting that you used
when setting up the window with PsychImaging().

PsychColorCorrection('SetColorClampingRange', window, min, max [,viewId]);
- Set the range of allowable output color or luminance intensity values
to the interval [min; max] for onscreen window 'window'. Values outside
that range get either clamped to the 'min'imum or 'max'imum value, or -
in 'CheckOnly' mode - will be visually marked as out of range. The default
range is [0.0 ; 1.0] -- The range that your display device can really
display.


PsychColorCorrection('SetEncodingGamma', window, gamma [,viewId]);
- Set the gamma value to use for gamma correction on window 'window'.
'gamma' can be either a single scalar if the same gamma should apply to
all color channels (or single luminance channel), or it can be a
three-component [gammaRed, gammaGreen, gammaBlue] vector, if each color
channel should be gamma corrected with an individual gamma value.

How the value gets applied depends on the chosen method of color
correction (see above). The simplest method ('SimpleGamma') performs a
simple power-law mapping of input values to output values: out = in ^ gamma.
'in' must be greater than zero, and 'gamma' must be greater than zero,
otherwise results may be undefined, depending on your graphics hardware.
However, usually only encoding 'gamma' values in the range of about
0.33 - 1.0 are meaningful.

Example: If your monitor has a "decoding gamma" of 1.8, the proper
setting for 'gamma' would be gamma = 1/1.8. For a decoding gamma of 2.2,
you'd choose gamma = 1/2.2 ...


PsychColorCorrection('SetExtendedGammaParameters', window, minL, maxL, gain, bias [,viewId]);
- Set the additional (optional) parameters to fine-tune gamma correction on
window 'window'. All these parameters have reasonable defaults. All
parameters can be supplied as a scalar value if the same setting shall
apply to all color channels (or a single luminance channel), or you can
provide 3-component vectors with one component for each color channel:

After this function has been called at least once, the following formula
will be used to map input values to output values ['gamma' is as set by
the 'SetEncodingGamma' function, 'in' is input, 'out' is output value]:

out = bias + gain * ( ((in-minL) / (maxL-minL)) ^ gamma )

Required parameters:
'minL' Minimum expected input luminance/intensity value (Default is 0.0).
'maxL' Maximum expected input luminance/intensity value (Default is 1.0).
'gain' Gain factor to apply after power-law mapping (Default is 1.0).
'bias' Bias/Offset to apply to final result before output (Default is 0.0).


PsychColorCorrection('SetLookupTable', window, clut [, viewId][, maxinput=1][, scalefactor]);
- Assign color lookup table 'clut' for use with color correction method
'LookupTable'. 'clut' must be a 1 column vector for pure luminance lookup
tables, or a 3 column matrix for RGB color lookup tables with one column
per color channel, ie., [1,2,3] = [Red, Green, Blue]. clut must have at
least 1 row, but usually will have way more than 2 rows, typically almost
as many rows as n = 2^bpc for a given output device bitdepths bpc. For a
10 bit output device, n would be usually 2^10 = 1024 rows for a perfect
one-to-one mapping. At runtime, color correction will be performed by the
following formula: Be Rin, Gin, Bin the input red, green and blue color
components, and Rout, Gout, Bout the final output value for the
framebuffer. First Rin, Gin and Bin are clamped individually to the range
0.0 - 'maxinput' (maxinput is 1.0 by default), scalefactor is chosen by
default as scalefactor = [number of rows in clut - 1] / maxinput, ie., it
maps the possible input range 0 - maxinput to the full range of row
indices 1 - rowcount to cover the full range of entries stored in the
clut. This is the most reasonable default, but can be changed by the
optional 'scalefactor' and 'maxinput' arguments.

Then the output color for each component is looked up in the proper slot
(= row index) of the passed clut:

Rout = clut(Rin * scalefactor,1);
Gout = clut(Gin * scalefactor,2);
Bout = clut(Bin * scalefactor,3);

Color values for fractional indices inbetween reference values in the
clut are interpolated linearly between the two nearest neighbour
reference values --> linear interpolation.

Finally, Rout, Gout and Bout are clamped to the valid output range as set
by the function PsychColorCorrection('SetColorClampingRange', ...); by
default to the range 0.0 - 1.0.


PsychColorCorrection('SetGainMatrix', window, matrix [, viewId][, precision=2]);

- Set gain matrix for method 'GainMatrix'.
If matrix is a 2D matrix, the gain will be applied to all color
channels equally. If matrix is a 3D matrix, matrix(y,x,1) will define
the red channel gain, matrix(y,x,2) will define the green channel gain,
and matrix(y,x,3) will define the blue channel gain.

The optional 'precision' parameter defines the numerical precision with
which the gain factors are stored. The default setting of 2 stores with
32 bit floating point precision - about 6 digits behind the decimal
point. A Setting of 1 stores with 16 bit float precision, about 3 digits.
A Setting of 0 stores with 256 levels, about 2 digits. A lower precision
is less precise but allows for faster processing and higher redraw rates
if needed.



Internal commands, usually not meant for direct use by pure mortals:
====================================================================

All these methods are usually called from within PsychImaging() to do the
dirty setup work...

Call this *before* opening a window:

PsychColorCorrection('ChooseColorCorrection', methodname);
- Specify the method to be used for color correction for the next
onscreen window that will be opened. This needs to be called *before* the
window is opened, however its usually done automatically at the right
moment by routines like PsychImaging() or BitsPlusPlus() if you use these
to open windows.

Called after Screen('OpenWindow') during shader and pipeline setup:

[shader, idstring, configString, overrideMain] = PsychColorCorrection('GetCompiledShaders', window, debuglevel);
- Compile corresponding shaders for chosen color correction method,
return shaderhandles and idstring to calling routine. That routine will
link the returned shaders with other shader code to produce the final
GLSL program object for color conversion and output formatting. 'shader'
is the GLSL shader handle, idstring the name string for the shader,
configString the shader option string for the 'Hookfunction' call, e.g.,
to bind additional LUT textures, etc.


Called after linking and attaching the final processing GLSL program
objects and slots to the imaging pipelines hook chain(s):

PsychColorCorrection('ApplyPostGLSLLinkSetup', window, viewId);
- Perform whatever setup work is needed after final GLSL program object
has been created and attached to imaging pipeline.