ObjectOrientedCalibration
The calibration process consists of several measurements of the spectral power distribution (SPD) or the chroma/luma of a target square which is placed at an arbitrary position on the screen against a uniform field background. The chromaticity/luminance of the target and the background are varied in order to order to conduct the following:
- Basic linearity tests (first pass)
- Gamma curve measurements
- Basic linearity tests (second pass)
- Background-dependence tests
- Ambient light measurements
In the basic linearity tests, the background is held constant and the settings of the Red, Green, and Blue primaries of the target region are varied jointly. The purpose of these measurements is to characterize the degree to which the three primaries add linearly within the target region. For a display that adheres to primary (or channel) independence, there should be minimal deviations of the measured SPD for a multi-component stimulus from the SPD computed by adding the component SPDs.
In the gamma curve measurements, the background is held constant and the settings of the Red, Green, and Blue primaries of the target region are varied in isolation. The purpose of these measurements is to characterize the gamma function that maps settings (or gamma in) values to primary (or gamma out) values.
In the background-dependence tests, the background and the target are varied jointly. The purpose of these measurements is to characterize the spectral stability of the target region with respect to modulations of the background. For a display that adheres to spatial independence there should be minimal dependencies.
Finally, the ambient light measurements, measure the SPD of the target when both the target and the background are set to zero.
The OOCalibrationToolbox is a collection of Matlab classes and executive scripts for measuring and analyzing radiometric data from different display systems (such as an LCD panel driven by the MGL-graphics library) obtained using different measurement devices (such as the PR-650 spectro-radiometer).
The measurement code consists of two abstract classes.
- the
@Radiometerclass, which defines the basic behavior of an object that communicates with a radiometric measurement device - the
@Calibratorclass, which defines the basic behavior of an object that conducts a calibration procedure, by presenting an ensemble of calibration stimuli on a display, obtaining measurements from a radiometric device, and storing the obtained data in a format that can be subsequently used by a variety of experimental programs
To program a calibration procedure using a specific device, e.g., the PR-650 spectro-radiometer, and a specific graphics library, e.g., the MGL graphics library, device/graphics-specific classes are used, in this case, the @PR650dev subclass, derived from the @Radiometer class, and the @MGLCalibrator subclass, derived from @Calibrator class. These subclasses, inherit their basic functionality from their parent classes, and have additional functionality, that is specific to the PR650 spectra-radiometer and the MGL graphics library, specifically. Additional device-specific classes are in our development path, specifically classes for interfacing to the PR-670 radiometer and the Klein K10A colorimeter. A PsychToolbox-3 specific subclass of @Calibrator is also planned.
To analyze a calibration file generated by a calibration procedure, we use the @CalibratorAnalyzer class.
Customizing the calibration script
The OOC_calibrateMonitor.m script is the only script one needs to run to conduct the standard BrainardLab calibration. Various settings, specific to the display being calibrated and calibration options can be set in the generateConfigurationForDisplayAtHand()function.
This function is a skeleton function. Copy it and adapt it according to your needs.
Calibrating
After a calibration configuration is setup in the OOC_calibrateMonitor.m, connect the radiometer to the host computer via a USB cable. In Matlab's command window type
OOC_calibrateMonitorIf the radiometric device is not detected, you will see something like the following in red.
> No devices found. Make sure that your radiometer is plugged in.If you do get this message, make sure that your device is connected and turned ON, and that the Keyspan USB drivers have been installed on your system. The driver is located in the /Users/Shared/Matlab/BrainardLabToolbox/OOCalibrationToolbox/KeySpanUSBSerialDriver folder. After installing the driver, make sure you reboot you computer.
If your radiometer device is detected you will see the following:
* Ports found:
* [1]: cu.KeySerial1
* Will attempt to open /dev/cu.KeySerial1.
* Established communication during attempt 1.Next, you will be prompted to enter your name and email (for notification of when the procedure is finished). After this stage, the script will go in auto-pilot mode and conduct the calibration procedure, as specified by the various options set in the calibration script.
Note: The calibration files produced by the object-oriented calibration code are compatible with the old PTB code. See '/Users/Shared/Matlab/Toolboxes/Psychtoolbox-3/Pychtoolbox/PsychDemos/CalDemo.m' script for an example of how to do this.
The OOC_analyzeCal.m script demonstrates how to use a @CalibratorAnalyzer object to analyze and visualize calibration files generated by the OOC_calibrateMonitor.m script.
In Matlab's command window type
OOC_analyzeCalYou will be prompted to enter a calibration file. A default calibration file will be shown between the square brackets. For illustration purposes, hit enter to select this default file. Otherwise, enter a different calibration file.
A calibration file may contain a number of calibrations, each corresponding to a different calibration date. Select one of them to import. A summary of the imported calibration will be displayed in Matlab's window, as shown below.
Calibration:
* Computer: nicolas's Manta, 10.9.3
* Screen: 2
* Monitor: NicolasViewSonic
* Video driver: object-oriented calibration
* Dac size: 8
* Frame rate: 60 hz
* Calibration performed by: NPC
* Calibration performed on 06-Jun-2014 3:51:37 PM
* Calibration program: OOC_calibrateMonitor
* Comment: Nicolas Office ViewSonic (via new method)
* Calibrated device has 3 primaries
* Gamma fit type crtPolyLinearNext, you will be prompted, whether you want to refit the data. Hit enter to continue with the data as they were fitted during the calibration phase, or enter 1 to refit the data. In the latter case, you will be prompted to enter different data fitting parameters. Next, the calibration data will are displayed in three multi-panel figure groups.
======== 1. Essential data figure group
The first figure group contains a basic characterization of the examined display. Data are displayed according to the following 3x3 panel configuration:
- (1,1): Gamma functions for the display's primaries
- (1,2): Spectral power distributions (SPDs) of the display's primaries
- (1,3): SPD of the ambient light
- (2,1): Stability of the SPD of the display's red primary at different intensity levels
- (2,2): Stability of the SPD of the display's green primary at different intensity levels
- (2,3): Stability of the SPD of the display's blue primary at different intensity levels
- (3,1): CIE chromaticity coordinates of the display's primaries
- (3,2): Stability of the CIE chromaticity coordinates at different intensity levels
- (3,3): Repeatability of the measurements
======== 2. Linearity checks figure group
The second figure group contains assessments of linearity of summation of the primaries in the examined display. Data are displayed according to the following 3x2 panel configuration:
- (1,1): Correspondence between nominal and measured xy (chromaticity) and Y (luminance) for the set of examinedRGB stimuli
- (1,2): Deviation b/n measured & nominal xyY values, as a function of the nominal Y value for the set of examined RGB stimuli
- (2,1): Comparison of measured and predicted SPDs for the RGB = (1.0 1.0 1.0) stimulus
- (2,2): Comparison of measured and predicted SPDs for the RGB = (.75 .75 .75) stimulus
- (3,1): Comparison of measured and predicted SPDs for the RGB = (.50 .50 .50) stimulus
- (3,2): Comparison of measured and predicted SPDs for the RGB = (.25 .25 .25) stimulus
======== 3. Background effects figure group
The third figure group contains assessments of the effects of a background stimulus on the spectral composition of a centrally located stimulus. Data are displayed according to the following 3x2 panel configuration:
- (1,1): SPDs of an RGB = (1.0 1.0 1.0) center stimulus obtained with different background RGB stimuli (background RGB values shown in the legend)
- (1,2): SPDs of an RGB = (0.5 0.5 0.5) center stimulus obtained with different background RGB stimuli (background RGB values shown in the legend)
- (2,1): SPDs of an RGB = (0.5 0.0 0.0) center stimulus obtained with different background RGB stimuli (background RGB values shown in the legend)
- (2,2): SPDs of an RGB = (0.0 0.5 0.0) center stimulus obtained with different background RGB stimuli (background RGB values shown in the legend)
- (3,1): SPDs of an RGB = (0.0 0.0 0.5) center stimulus obtained with different background RGB stimuli (background RGB values shown in the legend)
- (3,2): SPDs of an RGB = (0.0 0.0 0.0) center stimulus obtained with different background RGB stimuli (background RGB values shown in the legend)
=======
You can save any of the displayed figures by pressing the corresponding Export button, located in the lower-left corner. A PNG version of the figure will be saved in a subdirectory within the directory containing the imported calibration file. The exact location of the file will be shown in a message box that pops-up after the figure is saved. An example of an exported figure is shown below.
A short tutorial on how to use calibration files in order to present linearized stimuli is [here] (https://davidbrainard.github.io/BrainardLabToolbox/Tutorials/Calibration/Linearization/LinearizationTutorial.html)