PXLab Manual

[Home]    [Content]    [Previous Chapter]    [Next Chapter]

Colors and Color Calibration

Colors in PXLab

All colors in PXLab are specified in device independent color coordinates. PXLab uses the CIE 1931 XYZ System as its internal system for color coordinates. All design file color specifications are given with three coordinates: [Lxy], with
  1. L the luminance in candela per square meter [cd/m2],
  2. x the CIE 1931 x-chromaticity, and
  3. y the CIE 1931 y-chromaticity.

Thus an example for defining a color is

   Color = [60.0, 0.3127, 0.3291];
which assigns an array to the experimental parameter 'Color' and the color has a luminance of 60.0 cd/m2 and has the chromaticity (0.3127, 0.3291), which corresponds to D65 white.

In many experiments it may not be necessary to have device independent colors and exact color specifications. For those cases we have a set of color functions which default to the basic device colors and may be used to assign color values to parameters like

   Color = white(); 
which assigns a white color to the parameter 'Color'. Note, however, that the colors defined by these functions are not device independent.

In some cases it may also be desirable to use color coordinates which differ from the CIE 1931 XYZ-System. These cases can be handled by using built in color transformations. The chapter on parameter values contains a list of all available transformations. Using these one may, as an example, use CIELab-Coordinates for color definition:

   Color = fromCIELab([40, 0, 0]);
This defines a color which has a CIELab Lightness L*-value of 40, and the chromaticity (a*,b*) of (0, 0).

The internal PXLab color objects are instances of class PxlColor. These store color coordinates as CIE 1931 XYZ-coordinates. This class also contains many static transformations into different color systems: CIE L*a*b* 1976, CIE L'u'v' 1976, CIEL*u*v* 1976, CIECAM 1997, the Smith & Pokorny Fundamental Cone Excitation codes, the MacLeod & Boynton Relative Cone Excitation codes, linear device RGB, and gamma dependent device RGB.

The CIE L*a*b* related systems need a white point for defining their transformation. This white point is defined by the global experimental parameter CIEWhitePoint. By default this parameter is undefined and the system uses the current color device's white point as its reference. In order to define a 80 cd/m2 white point for a D65 illuminant we may set

   CIEWhitePoint = [80.0, 0.3127, 0.3291];

Color transformations related to RGB-Systems need to know the current color device primaries. The following sections describe how these may be defined and how the necessary color calibration may be achieved.

Color Calibration

Color calibration of CRT devices can be rather complicated. Brainard, Pelli, and Robson (2002) give a detailed discussion of all problems involved. The PXLab software package provides simple calibration tools which will satisfy most applications. The basic assumptions are:

In order to use the PXLab color calibration tools the Yxy-coordinates of the display's color primaries at maximum luminance must be known. Here the Y-coordinate refers to the maximum luminance which can be achived by the respective color channel and the xy-chromaticities describe the device's phosphor chromaticities. These coordinates may be set by defining the experimental parameters RedPrimary, GreenPrimary, and BluePrimary. Here is an example for defining the primaries of a Sony Trinitron monitor which creates a maximum luminance of 100 cd/qm at full white:

   RedPrimary = [21.26, 0.621, 0.340];
   GreenPrimary = [71.52, 0.281, 0.606];
   BluePrimary = [7.22, 0.152, 0.067];

Colors are controlled by writing integer values into certain video memory slots. The relation of actual luminance at each screen position and for each color channel to these integer values is nonlinear. This function is usually called 'gamma function'. It relates video digital-to-analog converter entries to output luminance. Berns, Motta, and Gorzynski (1993) have suggested a gamma function of the following form:

   L = (a*E - s)^g
which is widely accepted in color vision laboratories. Brainard, Pelli, and Robson (2002) propose a different formula, which, however, is equivalent. This function has three parameters: the gain parameter a, the offset parameter s and the gamma parameter g. The offset parameter is not independent of the gain but is s = (1-a), such that it is sufficient to define g and a. These parameters may be set in PXLab by defining the experimental parameters RedGamma, GreenGamma, and BlueGamma. Here is an example which uses the default settings of PXLab which correspond to the sRGB color space:
   RedGamma = [2.4, 1.0];
   GreenGamma = [2.4, 1.0];
   BlueGamma = [2.4, 1.0];

Where can one get the gamma parameters from? The best way to get the gamma parameters is to measure luminance output for sufficiently many digital-to-analog converter entries and compute estimates for the gamma function parameters. This is done by the PXlab application ColorCalibrationTool. It requires that one has a photometer available and the device chromaticities are known.

Experimental Parameters for Color Calibration

PXlab can access multiple display screens simultanously. Thus the color calibration parameters must be screen specific. Currently there are two screen classes: PrimaryScreen and SecondaryScreen These classes contain the following experimental parameters for defining the screen color properties:
A code for identifying the color display device. If this code is 0 then the color device properties are initialized from the experimental parameters below. If the code is non-zero then it should identify one of the known standard devices. In this case the device's primaries are read from an internal table.
Gives the upper limit of the range of values available to the respective color device's digital-to-analog conversion unit. Most devices have 8 bit DACs and thus have a range from 0 to 255. Some special devices may have more than 8 bits available.
Parameters of the gamma function for the red channel. The text for the meaning of the parameters.
Parameters of the gamma function for the green channel. The text for the meaning of the parameters.
Parameters of the gamma function for the blue channel. The text for the meaning of the parameters.
Yxy-coordinates of the red color device primary at maximum luminance.
Yxy-coordinates of the green color device primary at maximum luminance.
Yxy-coordinates of the blue color device primary at maximum luminance.
Contains the full access path of a device color table. This will be explained later in this chapter.

Screen calibration should not be done in a design file directly but should be done in a startup file. If the screen calibration data are contained in the design file then the design file is not portable. And screen calibration should be done such that every experiment which is run on a certain display device should use the same screen calibration data. This can be achieved by using the PXLab startup file mechanism. A file named screen.pxd should be put into the PXLab installation design file directory and this file should contain the calibration parameter setting. Here is an example of such a file:

	// Date: Tue Nov 30 14:21:16 CET 2004
	PrimaryScreen.ColorDeviceDACRange = 255;
	PrimaryScreen.RedGamma = [2.2927118766973535, 1.0941907385275362];
	PrimaryScreen.GreenGamma = [2.136562108023064, 1.2236609745347005];
	PrimaryScreen.BlueGamma = [2.12673917562787, 1.1853268525118388];
	PrimaryScreen.RedPrimary = [21.11, 0.634, 0.34];
	PrimaryScreen.GreenPrimary = [53.12, 0.297, 0.598];
	PrimaryScreen.BluePrimary = [9.337, 0.148, 0.064];
This file has been created by ColorCalibrationTool and contains the settings for a primary screen. PXLab will automatically load this file at startup and set the calibration parameters accordingly. See section 'Initialization' in chapter 'Running an Experiment' for more details on startup files.

Color Tables

In some cases the calibration precision achievable with gamma function estimates will not be enough. PXLab can use a color table in those cases. A color table is a text file which contains a single color description on every line. The color description contains at least 6 entries: the first three of these 6 entries are the CIE XYZ-coordinates of a target color and the last three are the device intensity levels for each output channel. Here is an example for such a table which also contains the CIE Yxy-coordinates of the target colors in the first three columns:

 21.26 0.511 0.299 36.334 21.26 13.5097 189 53 82
 92.78 0.364 0.423 79.8391 92.78 46.719 209 207 129
 7.22 0.198 0.188 7.604 7.22 23.5802 43 68 112
 71.52 0.318 0.502 45.3055 71.52 25.6446 133 202 87
 53.564 0.309 0.329 50.3078 53.564 58.9367 169 164 163
The first three entries in each line are the CIE Yxy-coordinates of the respective target color. The next three entries are the CIE XYZ-coordinates and the last three entries are the device RGB-values. PXLab uses only the last 6 entries of each line. These must be the CIE XYZ-coordinates and the device RGB-values.

If a color table is loaded into the system then PXLab will always use it for those target colors defined in the table. If a color table is loaded and a target color is needed which is not contained in the color table then the previously described conversion method via the current gamma table is used. In order to identify the target color in the color table only the first 3 decimal digits after the decimal point are used.

A color table may be loaded into the system by defining its file name in the monitor description file. The color table file must always be located in the same directory as the design file. This may be done by adding the following line to the previous example for a monitor desription file:

	PrimaryScreen.DeviceColorTableFile = "coltab.dat";
This adds a color table to the device color conversion package for the primary screen. The color table file named 'coltab.dat' must be contained in the same directory as the design file.

The PXlab application ColorCalibrationTool can be used to create a color table file. This is described in a later section.

Here is a short review on PXLab's initialization mechanism as described in more detail in the chapter named 'Running an Experiment': On startup the program searches for the file named 'pxlab.properties' which should be contained in the user's home directory or in the classpath. It contains the definitions of 'pxlab.home' and 'pxlab.local'. These are directory path names where PXLab might search for further initialization files. One of these directories should contain the file 'system.pxd' which can be used to initialize global experimental parameters. One of these parameters may be ScreenParameterFile which should evaluate to a string containing the screen parameter file name or a string array if there are two screens to handle. The screen parameter file name might define parameter PrimaryScreen.DeviceColorTableFile and SecondaryScreen.DeviceColorTableFile which give the file names of color table files. Screen device transforms are installed only immediately before the experiment is started. Thus the color table files will be read only after the screens have been initialized since only then will PXLab know which type of screen is to be used. In order to watch the color table initialization the debugging options 'files' and 'coldev' might be useful. Use the following command line to set these options:

  java de.pxlab.pxl.run.ExRun -D files -D coldev 

Color Calibration Devices

The GretagMacbeth Eye-One Color Pro Spectral Photometer

Using the Eye-One requires that its drivers are installed. The most simple way to make sure that this is the case is to make sure that the software coming with the Eye-One has been installed and is working properly.

GretagMacbeth provides a software development kit (SDK) for communicating with the Eye-One via software. You should get the Eye-One SDK for the C programming language. This package includes Java bindings for using Java to communicate with the Eye-One. The package also includes a driver which may be installed without installing the Eye-One application programs. The SDK documentation describes how to do that.

[Driver installation can simply be done by plugging the Eye-One into the USB port and then tell the Windows Device Manager where the drivers are. In the SDK tree the drivers are contained in directory 'driver'. Windows does the rest.]

The major part of the communication software is contained in the dynamic link library EyeOne.dll. The Java bindings are contained in the library JEyeOne.dll whose source code is part of the SDK. Both dynamic link libraries should be copied to the System32 subdirectory of the Windows system directory or any other path contained in the Windows search path..

This is all that is to do. The PXlab application ColorCalibrationTool is now able to communicate with the Eye-One device. Here is a screenshot where the Eye-One has measured gamma functions.

The Tektronix Lumacolor II with J1810 Colorimeter Head

In order to use the Tektronix Lumacolor II with J1810 Colorimeter Head the only thing which has to be done is to install the Java Communications API software. This is described in the chapter 'Connecting External Devices'. The PXlab application ColorCalibrationTool is then able to communicate with the Tektronix device via its serial line interface. This device, however, is not able to do spectral measurements but only measure color coordinates. To work properly the device has to be set up such that it shows CIE 1931 Yxy-chromaticity coordinates.

The Tektronix Lumacolor II may also be used as an input device in ordinary design files. This makes it possible to write a design file which runs luminance measurement from the Tektronix Lumacolor. Here is an example for such a design file:

Experiment() {
  Context() {
    AssignmentGroup() {
      SubjectCode = "pxlab";
      RandomizeTrials = 0;
    Session() {
      SessionStartMessage() {
        Text = "Press any key to start!";
	FontSize = 60;
        Timer = de.pxlab.pxl.TimerCodes.RELEASE_RESPONSE_TIMER;
      DeviceControl() {
	DeviceType = de.pxlab.pxl.DeviceCodes.SERIAL_LINE;
	Port = "COM1";
	CommandCode = de.pxlab.pxl.DeviceControlCodes.OPEN_DEVICE;
	Timer = de.pxlab.pxl.TimerCodes.NO_TIMER;
    SessionEnd() {
      DeviceControl() {
	DeviceType = de.pxlab.pxl.DeviceCodes.SERIAL_LINE;
	CommandCode = de.pxlab.pxl.DeviceControlCodes.CLOSE_DEVICE;
	Timer = de.pxlab.pxl.TimerCodes.NO_TIMER;
	Overlay = 0;
      SessionEndMessage() {
        Text = "E N D";
        Duration = 2000;
	DeviceControl.ResponseCode) {
      DeviceColorBar:A() {
        Timer = de.pxlab.pxl.TimerCodes.CLOCK_TIMER;
        Duration = 500;
      DeviceColorBar:B() {
        Timer = de.pxlab.pxl.TimerCodes.NO_TIMER;
	RedValue = Trial.DeviceColorBar:A.RedValue;
	GreenValue = Trial.DeviceColorBar:A.GreenValue;
	BlueValue = Trial.DeviceColorBar:A.BlueValue;
      DeviceControl() {
	DeviceType = de.pxlab.pxl.DeviceCodes.SERIAL_LINE;
	CommandCode = de.pxlab.pxl.DeviceControlCodes.SEND_DATA;
	Command = "!NEW\n";
        Timer = de.pxlab.pxl.TimerCodes.SERIAL_LINE_INPUT_TIMER;
	Overlay = de.pxlab.pxl.OverlayCodes.JOIN;
      Feedback() {
	ResponseParameter = "Trial.DeviceControl.ResponseCode";
	Evaluation = de.pxlab.pxl.EvaluationCodes.STRING_TO_COLOR;
	Text = "%Trial.Feedback.Response@b%";
	// Text = "%Trial.DeviceControl.ResponseCode%";
        Timer = de.pxlab.pxl.TimerCodes.CLOCK_TIMER;
        Duration = 3000;
	LocationY = 200;
  Procedure() {
    Session() {
      Block() {
        Trial(?, <0, 255>, <0, 255>, <0, 255>, ?);

This design file uses the following special features:

How to Create a Color Table File

The application ColorCalibrationTool can be used to create a color table file. In order to create a color table file we first have to create a color target file. A color target file is a text file which contains a single line for each color target. The last three entries on each line must be the CIE Yxy-coordinates of the target color. All other entries on the line are ignored by the ColorCalibrationTool. Here is an example for such a color target file:


Note that square brackets and semicolons are allowed but are not needed. Here are the steps for creating the color table:

  1. The color target file has to be loaded into the ColorCalibrationTool using Menu 'File' and selecting 'Open Color Table'.
  2. The ColorCalibrationTool has to be set to create a color table by using menu 'Task' and select entry 'Create Color Table'.
  3. Make sure that the proper measurement device has been selected from menu 'Measurement Device'.
  4. Now the calibration process can be started. ColorCalibrationTool will search for the best RGB device values for each entry in the table. This will take some time, depending on how fast the measurement device is.
  5. After calibration is finished the data should be saved to a file using menu 'File' and selecting entry 'Save Color Table Data'.
The final step is to enter the color table file path into the respective screen parameter file as described previously.


Berns, R. S., Motta, R. J., & Gorzynski, M. E. (1993). CRT Colorimetry. Part I: Theory and Practice. Colour Research and Application, 18, 299--314.

Brainard, D. H., Pelli, D.G., and Robson, T. (2002). Display characterization. In the Encyclopedia of Imaging Science and Technology. J. Hornak (ed.), Wiley. 172-188. (PDF)

[This file was last updated on July 15, 2010, 12:07:01.]

[Home]    [Content]    [Previous Chapter]    [Next Chapter]