====== Overview ====== Moncalib is the program in MGL that we use to calibrate monitors. It is used to measure with a photometer (PhotoResearch, Minolta or Topcon) the monitor luminance values and then store them in a table that can be used by the initScreen function to make sure you always use a calibrated output. Moncalib talks through a serial interface to these photometers so that you don't have to sit and take each measurement. Depending on settings (how many repeats of each measurement and how finely you sample the output) it can take several hours to run. We typically recommend running the calibration every few months as the output of displays can change over time (very important for projectors with light bulbs that can get darker over time). ====== Monitor calibration basics ====== Why do we need to calibrate a monitor? There are many reasons. For example, we may want to be able to specify actually units for the luminance that we present in a stimulus (the brightest white on different monitors can have vastly different physical luminance values). We may want to know the spectrum produced by each color channel of a monitor. We may have specific needs for testing color vision. But, here we will concentrate on the issue of **linearizing** the monitor's gamma. What is gamma? Well, when you set the color of your output display you typically set values that are between 0 and 255 (sometimes normalized to 0 and 1 - like for OpenGL and MGL functions). Changing the level from 0 to 255 does not linearly increase the intensity of light coming from the monitor. The relationship is typically a non-linear relationship that is approximated as a exponential function like in the graph here:
>> 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
- 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
- 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
- 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
=================================================================================================
===== Serial Mode Setup =====
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.
==== Topcon ====
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
==== Minolta CS100a and LS100 ====
Hold down F while turning on and make sure that the screen displays a small C.
==== PhotoResearch PR650 ====
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.
==== Notes on PR650 ====
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).
===== Actual calibration =====
* 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 [[#initial_setup|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 [[:mgl:taskreferencefunctionreference#mgleditscreenparams|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
^Parameter ^ Default ^ Comments ^
| numRepeats | 4 | How many times to repeat measurements - the more the longer, but more accurate |
| stepsize | 1/256 | Steps of values to take in testing. To test all 256 values you would do 1/256 (values in MGL are specified from 0 to 1 and not 0 to 256 |
| initWaitTime | 0 | How long to wait before starting, you can set this to something long enough in seconds to let you run out of the room |
| spectrum | 0 | Collect a spectrum measurement - works only with Topcon |
| bitTest | 0 | Tests the resolution of the gamma table by stepping through and seeing whether you get an increase in luminance - also might want to set bitTestBits, bitEstNumRepeats, bitTestN, bitTestBase - see the help |
| tableTest | 1 | After getting calibration, tests that calibration by putting the inverse table into the gamma table and running through values. Should give a nice linear relationship between input and output |
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.
===== Debugging =====
- 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.