Trying to get some very basic marker detection working for an indoor localisation project. After days of searching the web I still had to call on Jayson to help me out. After so many failures, it was a surprise and a relief that the solution below just worked. It’s a shame most of these AR projects seem to be out of date or undocumented.

Compiling ARToolKitPlus

Get ARToolKitPlus from Launchpad. As I write this in May 2011, the latest version is 2.2.1 released on 2011-02-05. Download the tar.bz2 archive.

tar xvjf ARToolKitPlus-2.2.1.tar.bz2
cd ARToolKitPlus-2.2.1
mkdir build
cd build
cmake ..
make
sudo make install

cmake-gui is a useful alternative to cmake if you need to change the configuration.

Sample code

There is a very simple example in sample/simple. Compile it with g++ main.cpp -o main -lARToolKitPlus. Run it from the sample directory so it can find its sample image.

Apparently the simple tracking locates markers individually, but can still locate multiple markers in each frame, and the multi tracking locates several markers that are assumed to be on the same plane and computes the equation of that plane.

Camera calibration

Calibrating the camera (to compensate for distortion) is important if you want to estimate accurate positions of the markers relative to the camera.

For camera calibration, follow the instructions from the bottom of the Studierstube website. Here are some instructions on how to use the toolbox.

1. Download the Matlab calibration toolbox by Jean-Yves Bouguet.
2. Take about 10 pictures of a chequerboard with the camera you wish to calibrate. Store them in the toolbox_calib directory along with the Matlab code you just downloaded. File names must end with an incrementing number (before the file format extension). Format can be ras, bmp, tif, pgm, jpg or ppm.
3. Run the calib script.
4. Choose the standard method.
5. Image names or Read images seem to do the same thing. If your files are called 0.bmp, 1.bmp, 2.bmp… then hit return for the basename and enter ‘b’ for the format.
6. Extract grid corners.
7. Hit return without entering anything to process all images.
8. Depending on the pixel size of your screen, the resolution of your camera and how accurately you can click, you may need to increase the wintx and winty parameters. These are half the size in pixels of the box within which the toolbox looks for grid corners. 20 was a good value for my 5×7 chequerboard with 40mm squares and a 640×480 camera.
9. Hit return again to use the automatic square counting mechanism or enter your own values. Count the number of squares in each direction on your calibration board and subtract 2 from each (in other words, don’t count the outer squares).
10. Click the four corners of the board, starting at the top left, and going clockwise.
11. Enter the size of the squares on the board in millimetres. You only get asked this for the first image. If you get it wrong you need to close the toolbox and restart (maybe clear the workspace too).
12. If your camera and lens distort the image a lot, the other corners in the image will not be detected properly because they aren’t spaced at predictable intervals. By entering a value between -1 and 1 for the initial distortion you can get the initial corner estimates to be closer to the real corners. I had no idea what a good value was so just tried a few until the red crosses were more or less in the right positions. Note that whether you enter an initial estimate for the distortion factor or not, the window you need to look at may be hidden behind another figure.
13. The toolbox will ask you to select the four outer corners and then attempt to detect the others for all images in succession.
    It shouldn’t matter too much if some of the corners aren’t detected properly. I expect they are ignored as outliers at the end.
14. When you’ve detected the corners on all images, click Calibration.
15. Visually check that the computed parameters make sense by clicking Undistort image. Enter 1, then the name (including number) of the image without the extension. The image should very clearly be undistorted, ie. the lines on the chequerboard should be parallel.
16. Click Show calib results and use the numbers given to create a camera calibration file to use in ARToolKitPlus. The format is given on the Studierstube page:
    [line1]: ARToolKitPlus_CamCal_Rev02
    [line2]: xsize ysize cc_x cc_y fc_x fc_y kc1 kc2 kc3 kc3 kc5 kc6 iter