Reference

The WhyCon code is actually implemented as a reusable C++ shared library, which can be included in any C++ project. The API documentation will be available soon.

The WhyCon localization system is implemented in a single command-line executable. If you run it without parameters you will see the accepted parameters.

Note: some parameters may change across versions, although the main parameters will stay mostly as presented here. Please see the currently accepted parameters (by running the executable) for details.

Localization System Overview

There are three main parameters that are required:

1. working mode: tracking (--track) or axis setting (--set-axis)
2. input source: camera (--cam), video file (--video) or image sequence (--img).
3. calibration file input, either in MATLAB format (--mat) or own XML-based format (--xml) from calibrator executable

Note: when video is used as input, it always requires the user to click on the image to start (this allows the camera to stabilize white balance and exposure). For video and image input, the processing starts right away without user intervection. This also implies that when the GUI is disabled, on all three input types, no user intervention is required. To stop processing the input of the camera (or any other input type), you can interrupt the process (CTRL+C).

Furthermore, on tracking mode, you should either specify:

1. if axis file should be loaded (--axis) or not (--no-axis)
2. output prefix name (--output)

Other possible parameters:

1. GUI disable (--no-gui)

Examples

Axis-setting

./localization-system --set-axis axis.xml --cam 0 --mat Calib_Results.m

In this case, the first detected camera will be used as input. The GUI window will appear and will display the camera view. The axis will be set after the user clicks on the image. The computed axis and transformation will be saved in axis.xml.

./localization-system --set-axis axis.xml --video 1.avi --xml calibration.xml

Here, the input is video file 1.avi. Also, in this case, the XML-based camera calibration file is used.

./localization-system --set-axis axis.xml --img img/%1d.png --xml calibration.xml

This last example shows how to use an image sequence as input. Images inside the img directory named as 0.png to 9.png will be loaded. A single image can also be loaded by using a fixed name instead of a pattern (this is useful when you have a picture of the circles used for defining the axis).

Tracking

./localization-system --track 5 --no-axis --video 1.avi --xml calibration.xml --output out

This shows the case of tracking mode where 5 targets are expected. Here, no axis definition is used, hence the output pose will be in camera-centered coordinates. The output information (pose per frame per target) will be saved as out.log and a video file will be saved as out.avi.

./localization-system --track 5 --axis axis.xml --video 1.avi --xml calibration.xml --output out --no-gui

In contrast to previous example, an axis file definition (axis.xml) is loaded and will be processed without opening any windows (since --no-gui is used).

Camera calibrator

While it is possible to use the widely known MATLAB calibration toolbox to obtain intrinsic camera parameters, you can use the provided camera_calibrator executable to make things easier.

This program will read live camera images while attempting to detect a standard chessboard pattern without user intervention. When the pattern is visible in the image it will be drawn. Whenever you choose to take a picture of the current chessboard pose, simply left-click the window image. The frame counter should increase. Repeat this process until enough images are taken (a minimum of three, which is generally enough is recommended). To end the process right-click the image. This will perform camera calibration and generate an output XML file containing camera parameters.

If you run the executable without any parameters it will display the usage guide.

Example

./camera_calibrator 640 480 13 13 30 30 0

Here, the first camera camera is used (ID 0) and a resolution of 640x480 pixels is requested. The chessboard contains 13x13 squares along X and Y direction respectively. The sizes on X,Y of each square in mm is 30 in this case.