Jump to: navigation, search



The display measurement toolbox (dmToolBox) is a collection of Matlab utilities, along with a GUI, that help you systematically calibrate the spatial, spectral and intensity properties of a display.

The toolbox was written by Greg Ng (gregng-atsign-stanfordalumni . org).

To start the toolbox, go to the dmToolBox root directory and type

dmSetPath       % to set your path
dmRun           % to start the GUI



The dmToolBox lives in the repository PDC/Applications/dmToolBox.

It requires

  • Matlab 7 or higher
  • Nikon Capture software (for display PSFs; see Joyce Farrell.)
  • PDC/Applications/Devices
  • PDC/utilities

We have not found a way to run the PR-650 on MacOSX, so at this point Windows is required. This is believed to be a limitation of OSX, since it does not seem to have serial port support. We hear rumors from Bob Dougherty of new serial support on MacOSX.


  • PR-650 SpectraScan. This device measures spectral power distribution (SPD) and intensity (gamma curve). It connects to the PC via a serial cable. Currently, we connect the DB25 serial cable to a DB25 to DB9 adapter; this in turn connects to a serial<->USB bridge. Windows drivers for the serial<->USB bridge are located in the ext/guc232a subfolder of the dmToolBox.
  • A compatible Nikon digital camera and appropriate lens. These are used for PSF measurements. Suggestions about setup are included in the sections Spatial Calibration and Camera Hardware.

Spectral calibration (SPD and Gamma)

Connect the PR-650 to the PC and focus it on the center of the display. Then, go to the Measure Display window and select Measure SPD and Gamma. See Display Measurement Options.

After verifying your options you will be asked where to save the output data.

Once you select the output file, dmToolBox begins the automated calibration procedure. The calibration procedure takes about 15 minutes with the default settings (reduced to 6 minutes when averaging once per sample). The SPD is measured first, then the gamma curve.

Note: There is a functional framework to allow you to present the stimulus using one computer, and to measure it using the PR-650 on another computer. This would be useful for controlling the display using a Mac, and using the PR-650 on a PC (since it doesn't work with OSX). In the routine dmMeasureSPDData/dmMeasureGammaData, you would also need to pass a parameter 'measuremode' with value 'measureonly' on the PC controlling the PR-650, and a parameter 'measuremode' with value 'stimulusonly' on the computer controlling the display.


There are two common ways the calibration can fail, both associated with COM ports. COM ports are the source of most evil problems with calibration.

  • dmToolBox will tell you if you select an invalid COM port. It will also tell you which valid ones are available. If you select an invalid number, Matlab cannot communicate with the PR-650.
  • If you select a valid COM port, but not the one connected the PR-650, there will be other errors. The PR-650 will appear to start responding, but then it will stop and Matlab will hang. The COM port may change if you unplug and replug the PR-650 into the computer.

Command Line Usage

It is also possible to use dmToolBox functions from the Matlab command line:

% Perform with default options:
spdData = dmMeasureSPDData
gammaStructures = dmMeasureGammaData

% Or specify some options.  This set lets you calibrate the primary display if it's 1024x768.
% See function help for more options.
nComPort = 4;
px = 1;    %Monitor Pos X
py = 1;    %Monitor Pos Y
sx = 1024; %Monitor Size X
sy = 768;  %Monitor Size Y

sy1 = 1024; % Height of Primary display
screenPos(1) = px;
screenPos(2) = (sy1-sy) + py;
screenPos(3) = screenPos(1) + sx;
screenPos(4) = screenPos(2) + sy;
spdData = dmMeasureSPDData('nComPort', nComPort, 'scrpos', screenPos);
gammaStructures = dmMeasureGammaData('nComPort', nComPort, 'scrpos', screenPos);

% Save the data to an output file.
save('myspdgamma.mat', 'spdData', 'gammaStructures');

Note that the screen position parameter in dmToolBox calls the upper left (1,1).

Interpreting the SPD data

After the SPD calibration finishes, data are saved into the MAT file that you specified before the procedure. The following section describes how to interpret this mat file and shows examples of how to perform some analysis operations.

DmToolBox stores the SPD calibration data as a cell array of each of the stimuli measured. Each cell in the array contains several fields:

  • vColor - m x 1 vector of the color displayed on the monitor, where m is the number of color channels for this display. The values of the entries of vColor are scaled between 0 and 1, where 1 indicates the channel to be at full intensity, and 0 indicates the channel to be completely off. Usually m = 3 and the entries are RGB.
  • waves - n x 1 vector of the wavelengths (nm) at which this SPD was measured.
  • spd - n x 1 vector with the spectral power distribution values (watts/steradian/m2/nm).

To plot the spectral power distribution of three channels in the image:

sg = load('myspdgamma.mat');
for ii = 1:3
    plot(sg.spdData{ii}.waves, sg.spdData{ii}.spd, 'Color', sg.spdData{ii}.vColor);
    hold on;
hold off;

Interpreting Plots from Analyze SPD

  • Gamut of Display Primaries - This is a standard plot of the chromaticities of the display primaries. The gray polygon with starred vertices represents the gamut of the display when the display primaries are at maximum intensity. The polygons with dashed lines and circled vertices represent the gamut at lower intensities (DV = 0.25, 0.5, and 0.75). The black stars and circles in the middle represent the chromaticity of gray at the corresponding DV levels.
  • Additivity of Pixel at 100% Display Brightness - This plot compares the sum of the individual primary SPDs (100% intensity) with the SPD when all of the primaries are on (100%). If the primaries are independent, the sum of the individual SPDs should equal the white SPD.
  • Gamma Curve Derived from SPD Measurements - In this plot, we compare the intensity of SPDs from DV = (0.25, 0.5, and 0.75) to the SPD of a DV=1.0 stimulus. We then use this scale factor to construct a mapping from digital value to relative display intensity (a gamma curve). If available, gamma data collected by the Measure Gamma is overlayed on the plot. This plot serves as a check that the spectrophotometer is operating consistently in both the luminance measurement mode and the SPD measurement mode.
  • Spectral Power Distribution at Varying Intensities - This is a plot of the SPD at DV = (0, 0.25, 0.5, 0.75, and 1.00).

You can use the Analyze SPD interface to plot from the command line:

plotOutputFmts= {'png'};
plotOutputDir = '.';
spdstructs = dmmAnalyzeSPD('myspdgamma.mat', plotOutputDir, plotOutputFmts );

Interpreting Gamma data

Gamma Curve

The gamma calibration routine stores the raw measured luminance of each channel intensity value. You can use the Analyze Gamma functionality to estimate the gamma exponent and offset level (black level) of this display.

The spd/gamma MAT file contains a variable called gammaStructures, which is a cell array where each cell element represents the data for one color channel. The cell structure has the following fields:

  • vColor - a vector representing what color this channel is (same as in SPD).
  • vRawData - this element has sub-elements x and y. x represents the intensity presented to the display. You can compute what color vector was presented to the display by computing vColor*vRawData.x . vRawData.y contains the luminance values measured by the photometer for each corresponding x level.

If you wanted to plot the gamma data yourself:

sg = load('myspdgamma.mat');
for ii = 1:3
    plot(sg.gammaStructures{ii}.vRawData.x, sg.gammaStructures{ii}.vRawData.y, ...
         'Color', sg.gammaStructures{ii}.vColor);
    hold on;
hold off;

You can use the Analyze Gamma interface to get a quick estimate of how well the gamma data fits to a power law (i.e., <math>y=x^\gamma+offset</math> ). An approximate fitted function will appear in the Matlab command window. To do your own more detailed analysis, you can use the function dmmAnalyzeGamma:

plotOutputFmts= {'png'};
plotOutputDir = '.';
gammastructs = dmmAnalyzeGamma('myspdgamma.mat', plotOutputDir, plotOutputFmts );

The code above will read the gamma data in myspdgamma.mat, fit the raw gamma data in myspdgamma.mat to a power law equation, and return the gamma structure with fitting data in gammastructs. gammastructs has an element fitCoefs which contains fitting coefficients (described in dmmAnalyzeGamma.m), as well as a fitted curve in the element vFitLUT. You can use the values in vFitLUT to perform functional interpolation of your gamma curve.

Using the Nikon D100 for spatial calibration

PSF Measurement Window
This section describes the software-related process for measuring a pxdisplay's pixel's spatial properties. We assume that you have already set up the camera hardware and the display.

From the Measure Display window, you can choose "Measure PSF" to begin the automated PSF capture process. The software will try to guide you through some of the non-obvious parts of the PSF capture process. The entire process is described in detail below:

Step 1: Start Nikon Capture Control

Start Nikon Capture Control, then set the following options:

  1. Under the Storage tab, select RAW (NEF) as the image capture format.
  2. Select the Exposure 1 tab so that the controls for exposure time are visible.
  3. Select a Download directory to save images to. This directory should be empty, as dmToolBox will delete all files in this directory before beginning the automated PSF capture.

Step 2: Position the pixel target in the camera viewfinder

dmToolBox will display a black window with cross-hairs on the target display. Position this target so that it is fully visible in the camera viewfinder. You can double-click the mouse in any location to reposition the pixel target. You can also use the arrow keys to fine-tune the pixel target's position. Be sure that all of the subpixels are visible in the camera viewfinder (especially the pixels that will be adjacent to the left and below the primary pixel). Press a and s to increase and decrease the magnification of the target. You may also press h at any time to get help on other keys that may help you adjust your target.

Step 3: Press Y to begin the measurement

After the target has been positioned in a satisfactory manner for PSF capture, press Y. (To quit the without measuring, you may press 'Q'.) dmToolBox will now ask you where the PSF images will be downloaded to. Find and select the same folder that you chose in Step 1. During the capture process, dmToolBox will monitor this folder to watch that the images are being correctly saved. It will also save a log of what images were captured (as a .mat file).

The capture process has two steps: The first step is automatic exposure (AE) finding, and the second is to capture the necessary stimuli. AE attempts to capture an image where the highest digital value recorded is [90%], and then reduces the exposure time by 1/3EV.

The capture software then displays the necessary stimulus subpixels in succession and capture images of them to be analyzed later. The amount of time required for the measurement may vary according to your display, but will probably not take more than 30 minutes.

Analyzing Spatial (PSF) Data

single pixel

To analyze the data, you will need the NEF images captured. Note that the first few images will be thrown away (these are "dummy images" to make sure that capture is working properly). You will need to delete these images and find the first image that is of only a single "white" pixel, such as the one at right. During the PSF analysis, DmToolbox creates a log in psflog.mat describing which NEF images correspond to which stimulus.

To begin analysis, go to the Measure Display window and press Analyze PSF. Then select the NEF image described above. Many plots will be generated; see below for descriptions:

Dell LCD
Dell LCD
  • PSF Images - The top row of images are PSF Images, which are images of display pixels. In the examples above, two horizontally-adjacent pixels were compared for additivity. Actual Image is an image of two horizontally-adjacent pixels both set to "white." Predicted Image is the composite of two images: one image of the left pixel set to white and the right pixel set to black, and an image of the left pixel black and the right pixel white. The Difference Image is the difference of these two images. Ideally, the difference image will be completely black, showing complete additivity.
  • Additivity Plots - The bottom row of graphs are Additivity plots, which correlate pixels in the actual image with pixels in the predicted image. Ideally, all pixels will lie along the black line, indicating that each pixel value in the predicted image is equal to the pixel value in the actual image. There are two common deviations from the ideal case:
    • A "bulge" near the center of the intensity range - This may indicate that there was some camera shake between the predicted and actual images. Check the edges of the display pixel on the difference image to confirm this.
    • Multiple linear trends - Rather than all pixels falling along the one-to-one black line, some pixels may fall near this line, along with a secondary mode, as shown for the NEC LCD and the CRT. This may indicate crosstalk between display pixels. In the case of the horizontally-adjacent pixels on a CRT, this crosstalk results from the slew time of the electron gun. For the NEC LCD, the cause is not definitively known. On LCDs, this additivity failure will occur if the display is not operated at its native resolution (i.e., if the display performs any image interpolation or if the display controller uses "overdrive technology").
  • Gamma from PSFs
    Gamma curve derived from PSFs - This is a curve of display intensity based on the images captured of the PSFs. The idea is similar to the Gamma Curve Derived from SPD Measurements plot. However, here, we consider the sum of all the image pixels in a PSF image and compute the scale factor relative to the max-intensity pixel. One can view this as integrating the light output of the entire pixel to determine its brightness. Ideally, this curve should match with the gamma curve produced by the spectrophotometer. (Note: The image at the right was produced with the Analyze SPD, PSF, and Gamma Jointly command, not the Analyze PSF command.)

Display Measurement Options

COM port where photometer is located - This is the serial port where the PR-650 is connected. Be aware that the appropriate port number may change if you unplug the PR-650 or if you restart the computer.

Configuring extended desktop in Windows XP
Which monitor are you measuring (1 or 2)? - If you are trying to measure the properties of the primary display or you are using a "cloned" display mode, then use 1. If you are using extended desktop mode to measure a secondary display, then use "2", and configure the next two items, which are properties for the 2nd monitor.

x-position and y-position of top-left corner of 2nd monitor (pixels) - These options allow you to configure the virtual position of your secondary display. Windows' desktop properties can help you figure out what settings should go here:

Here, the secondary display has been configured to be just to the right of the primary display. Because the primary display has a resolution of 1280 x 1024 pixels, the secondary display is located at the position (1280,0).

Horizontal size and vertical size of the 2nd monitor (pixels) - In the above dual display example, the secondary monitor has a resolution of 1024 x 768 pixels, so you would enter 1024 and 768, respectively into these two fields.

Number of data samples to average - Number of times to repeat measurements. Measurements will be averaged for more reliable results. In general, measurements with the PR-650 are relatively stable and shouldn't need to be averaged more than three times.

Number of sample points on gamma curve - Number of evenly-spaced points along the display's intensity range to measure. For example, if the number of sample points on the gamma curve

Pause time before measurement starts (sec) - Number of seconds to wait before beginning to present the calibration stimuli. This pause may be useful if you need time to leave the room before the measurement begins.

Gray levels of the display - I think this option is actually irrelevant. ctToolBox had this option all over the place, but it doesn't really do anything AFAIK since we're really just showing an image in a matlab figure, which takes a double-precision floating-point image with values from 0.0 to 1.0 as input. But I think the idea is that you might need to know how many levels at which your display will quantize. (gregng)

Camera Hardware


  • You will need to choose the correct lens for good magnification of the display pixels. Here is an example setup that was used for a 17-inch laptop display: The Nikon D100 is mounted onto a fixed platform. We attach the Nikon bellows unit to that, and to the other end of the bellows unit, we attach a 20mm Nikon lens in reverse (sometimes called reverse macro). Reverse macro changes the intuition of focal length vs. magnification. In reverse macro mode, a longer focal length will result in less magnification of pixels. Therefore, when calibrating a display with larger pixels (such as a 30-inch non-HD plasma display), you might want to replace the 20mm lens with a 50mm lens.
  • You might try enabling the Mirror Anti Shock option in Nikon Capture Control for better image sharpness. Normally, there should be no downside to enabling this option, but I've found that for some reason, in our setup, the Nikon becomes unreliable.

Known Issues

  • The command dial on the Nikon D100 in Packard 070 is a bit flaky. Sometimes, the camera may be connected to the PC but refuse to take pictures remotely. If this is the case, try wiggling the command dial until the software and camera respond.


This toolbox is based on ctToolBox code by Xiaowei Ding.

Related Pages

Stimulus:Display calibration

Personal tools