First you need to have a photometer. Moncalib works with three different brands of photometers.

Photometer name	Image	Manual	Comments
Photo Research SpectraScan 650			Can make a full set of measurements (including full spectrum measurements) and is considered the gold standard. Our software may work with other models from PhotoResearch, but this is the one we have typically used
Topcon SR-3A-L1 Spectroradiomter		English manual	Similar to the PR650 in capabilities
Minolta LS100			Measures only luminance. Need to also buy LSA-15 Cable which adapts the output to serial.
Minolta CS100a		Instruction manual Communication manual	Measures luminance and chrominance. Need to also buy LSA-15 Cable which adapts the output to serial.

Our code may work with different models, but we have only tested the above listed models. If you want to use another photometer you can input the readings manually or consider writing a few lines of code in moncalib to support your photometer type.

Note that there are some commercially available devices to calibrate monitor screens which create color profiling information. We have tested one of these called Spyder2Pro which allows you to linearize the monitor output but found that is not yet suitable for psychophysics purposes. The calibration program crashes when you use the default settings to linearize the monitor (an email to the tech support confirmed this is a bug in their software). Using advanced settings it worked but it could only test luminance at 5 output levels. The linearization that it achieved was not accurate enough when tested with the PR650 (it looked like they are doing some sort of spline fit of the points and the luminance as a function of monitor output level looked like a wavy line around the ideal).

You will also need an adaptor to connect the USB on your computer to the photometer. Make sure you have a good device - cause this is typically the reason why you might have a problem connecting to your photometer. Some work, some don't. Some break when you upgrade your OS. Why? Because they rely on driver software that the developers don't really spend so much time making sure works perfectly. That is, they are buggy. So, if things don't work, it is very likely that you don't have a good USB/Serial device driver. Here is what we know has worked for us and what has not.

USB/Serial device	Image	Driver version	Comments
Plugable USB to RS-232 DB9 Serial Adapter		Prolific driver 1.5.1 Prolific driver, compatible with Sonoma	Update: works with Minolta CS100a as well, with the right driver. Works with the Topcon
Keyspan High-Speed USB to Serial Adapter USA-19HS		Mac OS X 10.9.x to 10.11.x Version 2.6 Try this if that link is broken or look for 'USA-19HS' here	Works with Minolta CS100a. We used to use other versions of this device Keyspan USA-28 which worked with PR650 and a white translucent Keyspan USA-28X B which did not work. The Keyspan USA website does not yet have support for OS Sonoma.

Typically you can just connect the USB/Serial device to the Serial cable of the photometer, but for the Topcon you will need a nullmodem connector between the two (this swaps the read/write lines for communication). It looks like this (remember this should only be necessary for Topcon).

Most display cards typically have 10 bit gamma tables - we test this by incrementing the output values by 1/1024 and making sure that this increments the luminance and making sure that this increases the luminance (an 8 bit card will show ladder steps because it will only change the luminance as you increase by 1/256). This can be tested using moncalib('bitTest=1');

The NVIDIA GeForce series of video cards have 10 bit gamma tables (these are the only ones we have tested):

• NVIDIA GeForce FX 6600 (In the G5 in the magnet room)
• NVIDIA GeForce FX 7300 GT (brownie Mike Landy's psychophysics room)
• NVIDIA GeForce FX ????? (Jackson the G5 in the psychophysics room)

ATI 10 bit cards:

• any Randeon card for desktop computers above series 7000 has 10-bits DAC resolution (laptop cards don't have it necessarely or drivers do not access it)
• some more information about this can be found on Denis Pelli webpage [3] and on the Psychtoolbox.org discussion group [4].

It is always the best to use the bit test in moncalib because some drivers do not allow 10-bit control on 10-bit DAC cards. You can also query the display card to see if it says that it supports a 10 bit gamma:

displayInfo = mglDescribeDisplays

Check the field gammaTableWidth to see if it is 10.

First, you will want to test the USB/Serial connection. You can do that with the following steps:

1. Make sure the device driver for your particular usb/serial device is installed. Also, make sure that mgl is updated. After the installation is complete you need to restart the computer.
2. Connect the USB/Serial device to your computer
3. Connect the Serial cable of the Photometer to the USB/Serial Device (Topcon will need the null modem connector described above)
4. Turn on the photometer, making sure it is in the correct mode. This procedure is different for different photometers and is described below.
5. Run moncalib in the commTest mode. Run and choose your photometer (the below demonstrates with Minolta and the Keyspan USA-19HS USB/Serial device)

   >> moncalib('commTest=1')
   (moncalib) PhotometerTest using serial port. Make sure your device is connected and ready to go
   Which photometer are you using?
     0=quit
     1-Photo Research [PR650]
     2-Minolta [LS-100]
     3-Minolta [CS-100a]
     4-Topcon [SR-3A])
   ==================
   3

6. Next you will need to choose what serial port to work with - this is the device name that was installed with your driver (sometimes you just have to guess a few times to get it right). Here the 4th device is the correct one

   1: cu.Bluetooth-Incoming-Port
   2: cu.Bluetooth-Modem
   3: cu.KeySerial1
   4: cu.USA19H2421P1.1
   Choose a serial device (0 to quit)4

7. You will be asked to turn on your photometer and make sure it is in the correct mode (you should have already done this):

   Please turn on the LS100 and press the white F key at the same time.
   
   The LCD panel on the LS100 should end with a "C"
   
   Is there a "C" at the end (y/n)? y

8. It will try to make a measurement. If all is good, it should report no errors and give you a luminance value that looks reasonable (make sure you are pointing at something reasonably bright). Looks like this

   (moncalib:photometerTest) Trying to make a measurement from your photometer.
   If the code hangs here, there is probably a communication problem. A few things to try:
   1) Unplug your serial adaptor from the computer and plug it back in again.
   2) Restart Matlab
   3) Reboot the computer (sometimes the serial adaptor needs a good kick in the pants)
   4) Check to make sure you have the correct cable (For example, the Topcon needs a null-modem cable that crosses read/write lines, while other photometers may need a simple pass through cable).
   5) Make sure that your communication mode on the device is setup correctly. Minolta can only use 4800/even/7 bits/2 stop bits. Other photometers have different settings, but should be set to 9600/none/8/1
   6) Power cycle your photometer and try again.
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) 0 bytes available
   (moncalib:readSerialPortUsingComm) Reading 28 bytes
   (moncalib:readSerialPortUsingComm) Received OK13,  33.40, .3729, .4013
   
   (moncalib:readSerialPortUsingComm) 0 bytes available
    Luminance=33.400000 cd/m^-2 
   ============================ Photometer measurement has been made ===============================
   (moncalib:photometerTest) Measured luminace=33.400000 x=0.372900 y=0.401300
   =================================================================================================

Each photometer is a bit different in how you get it setup for serial mode. The section below describes the procedure for each of the photometers we have worked with.

First make sure that the topcon has the correct serial port settings, by pushing the [MODE] key for about 2 seconds to enter the function mode. Then push the [ENTER] key four times to set the RS-232C Parameters. The settings should be Baud rate: 9600, Length=8, parity=NONE, Stop bit=1. Use the [CHANGE],[ROTATION] & [ENTER] keys accordingly.

Then make sure that the data communication method is set to Normal Type. From the function mode (see above) hit [ENTER] five times. It should say:

• CS900 ON/OFF *
• Normal Type

Hold down F while turning on and make sure that the screen displays a small C.

There are a few points that you should pay special attention to:

• When using the automated calibration via the serial port, the program will ask you to turn on the PR650 and then press 'return' within 5 secs. You might not want to press 'return' right away, or you may get something like this on the photometer:

PR650 REMOTE MODE 
(XFER) s/w ver 1.02 
CMD 51 NAK

This indicates that you pressed the return while the photometer is waiting for a transfer signal (not sure what it is), and hence entered the XFER mode. If you wait another 2 secs or so it will enter the control mode, now press 'return' you should see this:

PR650 REMOTE MODE 
(CTRL) s/w ver 1.19 
CMD B

Basically there is about 2-3 secs time window you should press 'return' to get to this state.

Over the years, we've run into a few issues calibrating with the PR650. While it's the best photometer we have, it can be quite finicky and frustrating. Here are some things to keep in mind and to try when things go wrong.

• Before each test measurement, or a run of the calibration, you probably need to unplug/replug the photometer and power cycle it. Otherwise, the “CMD B” interface might not pop up. If you are having trouble getting CMD B, unplug, replug, and power cycle.
• Weak light signal error: For some reason, the PR650, crown jewel of the photometer world, doesn't do a very good job making measurements in low light conditions. When the luminance is very low (e.g. at the beginning of the calibration when the screen starts off as black), it will give you an error that reads “Weak light signal” followed by a luminance value. That luminance value is a lie: it is made up, and when running moncalib, the program will treat it as an error and be unable to continue iterating through different luminances. If you are running into this issue, run moncalib with the flag “fastSearch=1”. At the beginning of the calibration, this will find the lowest luminance at which the photometer is able to make a legitimate measurement, and then calibrate with that as the lowest point. This may or may not be a problem for running stimuli with very low contrast - unclear at this point (12/2023).

• When doing the automated calibration, turn off screensavers and energysaver, otherwise the screen will go blank after a while and you'll be measuring luminance of blank sreens.
• Make sure that the photometer is close to the screen and properly focused (preferably on a tripod).
• Make sure that you will have enough time to leave the room and close the door so that you won't introduce stray light into the room.
• If you cannot install the serial port interface or don't want to automatically calibrate using the USB cable you can also use the program to run manually with any photometer by typing in the luminance measurements yourself.
• Once you have checked the serial connection with the instructions above, you are ready to go.
• You can just run as follows (the directions are similar to when you tested the comm port above) Note that we also set initWaitTime so that you have 60 seconds before the calibration starts to turn off the lights and leave the room.

  moncalib('initWaitTime=60');

• When you have run the calibration, try running mglEditScreenParams, select “Find latest calibration” for the calibType and click the displayCalib button to see your calibration. If your calibration does not show up there, then it will not be used when you run your stimulus programs, so it is important to confirm. You will also see text that will describe your calibration, like the following

  (moncalib) Displaying data for calibration file /Users/steeve/proj/mgl/task/displays/0001_sr14-3fa8fef553_141110
  (moncalib) Calibration took 00:57:57
  (moncalib) Calibration measured on 10-Nov-2014 13:42:13
  (moncalib) Measured gamma with stepsize: 0.003906 (1/256), numRepeats: 4
  (moncalib) Measured table correction with stepsize: 0.003906 (1/256), numRepeats: 4

There are a number of parameters to set, check help moncalib for a full description, but some things of interest are

The program moncalib will save a calibration file in the local directory. For you to use this calibration file, you can store it in one of two places. Either in your own program directory under a directory called displays:

./displays

Or you can store it in the general displays directory

mgl/task/displays

InitScreen should automatically find the correct table by checking your computer name and looking for the file in these two places. If you do not use the standard filename, or have multiple calibrations for the same computer (like if you have multiple monitors calibrated), you can use a specific file by setting myscreen.calibFilename

myscreen.calibFilename = 'mycalibrationfile.mat';
myscreen = initScreen(myscreen);

Note that the calibFilename can be a literal filename as in the above, or you can specify a portion of the name that will get matched in a file from the displays directory (e.g. computername_displayname would matcha any file in the displays directory that looks like *computername_displayname*.mat).

The name of the file usually created by moncalib will be:

xxxx_computername_yymmdd.mat

Where xxxx is a sequential number starting at 0001 and yymmdd is the date of the calibration. This stores a variable called calib which contains all the information about the calibration. You can quickly plot the data in calib by doing:

load 0001_stimulus-g5_LCD_061004
moncalib(calib);

The most important field of calib is the table field which holds the inverse lookup table to linearize the monitor.

1. For some reason, there are runs in which the gamma table doesn't change during the gamma measurement. I have found that rerunning moncalib, or waiting longer between the gammatable change and the photometer measurement (moncalib around L248) seems to alleviate this problem.