SwisTrack/Examples/Calibration/SemiAutomatic

The present example shows how to calibrate your setup in a semi-automatic fashion by taking a picture of markers at known real-world positions. This procedure is preferred if the blobs cannot be detected reliably with the automatic calibration.

In this procedure, you will determine a set of points of which you know their real-world position and their position on the image taken by the camera. The calibration component used in SwisTrack will fit a function which best describes the mapping between the real-world and the image coordinates.

Setup and Marker Placement

Setup your experimental arena as if you would run an experiment. Make sure that the camera is mounted properly at its final position. It is furthermore advisable to do the calibration under the same light conditions as the final experiment.

Place 6 to 50 markers in your arena. More markers will generally result in better calibration on heavily distorted images, but take more time to place. If your are working with low distortion, a 4-by-4 pattern (16 markers) will probably yield good enough results.

If you are using simple markers in your experiment later on, reuse the very same markers to do the calibration. Otherwise, simply use circles printed on paper. Make sure that the markers can be well-distinguished from the background (at least locally), such as black filled circles on white paper, for instance. The markers should have a size of at least 5 by 5 pixels on the image. A size of about 10 by 10 pixels is preferred, though.

Place these markers in your arena and carefully measure the center position (x, y) of each of them. You may use one of your markers or the arena boundary as reference point. Note that you can place the markers at positions of your choice. It is not necessary to place them in a specific pattern, although placing them in a systematic fashion usually makes it easier to determine their real-world position.

Note that the calibration markers should be placed at the same height as the final marker (or object) to track during your experiment. Placing them on the ground will result in significant offsets at the image border.

Taking a Picture

Switch on the camera and launch SwisTrack. If you have a SwisTrack configuration for your experiment already, use that one to take a picture. Otherwise, start with a new (empty) configuration and add the component corresponding to your camera, as well as a Conversion to Grayscale (or Conversion to Color) component.

Click on the Conversion to Grayscale (or Conversion to Color) component and press the Step button in the toolbar. SwisTrack will acquire and image and display it on the screen. Make sure that your blobs are well visible on the image and adjust the camera acquisition parameters if necessary. This is also the last moment you could move the camera or adjust the focus if needed.

Once you are happy with the image, right-click on the displayed image and choose Save original image as .... Save the image as calibration.bmp.

Extracting the Markers

Launch Matlab and load the saved image with

image = imread('calibration.bmp');

To display the image on the screen (for verification purposes), type

imagesc(image)
axis equal

Switch to the calibrationFileTools folder of SwisTrack and type

image_positions = FindBlobs(image, N, THRESHOLD_LEVEL);

where N stands for the number of markers visible on your picture and THRESHOLD_LEVEL for the value (0..1) at which the image should be thresholded. You will have to find a suitable threshold value for your image by modifying this value until the markers are (at least locally) well distinguished from the surroundings. A good value to start with is 0.5.

Once you have found a suitable threshold value, click on each marker. The script will automatically calculate the center of the marker by taking into account nearby pixels of the same color. When you are done, the script returns an N-by-2 matrix with the image positions of the markers.

Creating an XML Calibration File

In addition to the image positions, you'll need the world positions of these markers. Create an N-by-2 with the world positions of your markers in the same order as they appear in the image_positions matrix (i.e. in the same order as you clicked them).

world_positions = [2.0, 1.0
                   2.0, 1.5
                   ...
                   ];

Then, write the XML file by calling

writeSwisTrackCalibXMLFile(worldPoints,imagePoints,'calibration_points.xml')

The file calibration_points.xml can subsequently be used with the calibrations components available in SwisTrack.