CAMERA CALIBRATION TOOLBOX FOR MATLAB (v2.1b)


Installation
------------

Simply copy all the .m files into a directory 'calibr' and add it to your
MATLABPATH. Matlab version 4.0 or later is required.

Things to do
------------

If you have a 3-D calibration object, you can cope with a single image. In 
order to obtain satisfactory calibration result, the object should cover the
entire image as well as possible. Also, multiple images are supported. Then,
the images should be captured from different viewpoints changing the camera
orientation and distance. In case of a coplanar calibration target a single
image is not adequate and a set of images (2-6) is needed to solve all
the camera parameters. The coordinates of the coplanar control points should 
be selected so that the z coordinates become zero. The 3-D coordinate unit is
millimeter and image coordinate unit is pixel. The calibration coordinate 
system is right-handed. The origin of the image coordinate system is in the
top left corner, x axis is to the right and y axis downwards.

The input data to CACAL-routine is following:

First parameter is a string that defines the camera type. The valid camera
types are listed in CONFIGC.M that is a function where the user can add his
own configuration data. The data consists of the following information:
  NDX   number of pixels in horizontal direction
  NDY   number of pixels in vertical direction
  Sx    effective CCD chip size in horizontal direction [mm]
  Sy    effective CCD chip size in vertical direction [mm]
  f0    nominal focal length (needed in case of coplanar targets)
  rad   radius of the control points [mm] (needed in circal)
  name  name of the setup

The calibration data is given in separate matrices for each image. The maximum
number of images is currently six. The data matrix structure is following:
Columns 1 to 3: x, y, and z coordinates of the control points. In case of a
                a coplanar target the z-coordinates must be zero.
Columns 4 to 5: corresponding x- and y- image coordinates.
Columns 6 to 8: normal vector [nx ny nz] of the target surface around 
                the control point given in the world coordinate frame.

The output data is following:

- Eight intrinsic camera parameters:
            par(1)=scale factor ~1
            par(2)=effective focal length
            par(3:4)=principal point
            par(5:6)=radial distortion coefficients
            par(7:8)=tangential distortion coefficients

- The position and orientation of the camera for each image:
            pos(1:3)=x, y, z -coordinates (actually, the position
                     of the calibration coordinate frame origin with
                     respect to the camera coordinate frame)
            pos(4:6)=w, p, r euler rotation angles around x, y, z axes.
- Number of iterations required
- Sum of squared error terms
- The remaining error in pixels. This error gives a guideline to detect
  the accuracy of the calibration. The error should be non-systematic with
  the standard deviation less than 0.2 pixels. If the error is larger, 
  something goes wrong. 
- Covariance matrix of the estimated parameters. The diagonal elements gives
  the variance of the estimates.
  
  
For more information, see:
    Heikkila, J. & Silven O. (1996) Calibration procedure for short focal
    length off-the-shelf CCD cameras. In: Proc of The 13th International
    Conference on Pattern Recognition. Vienna, Austria. pp. 166-170.
    
    Heikkil, J. & Silvn, O. (1997) A Four-step Camera Calibration 
    Procedure with Implicit Image Correction. To appear in: IEEE Computer
    Society Conference on Computer Vision and Pattern Recognition (CVPR'97), 
    San Juan, Puerto Rico. 
  

Version History
---------------

Version 1.0:

* calibration with 3-D and coplanar targets
* multiple images
* two-step procedure with the direct linear transformation (DLT) in
  the first step, and nonlinear optimization in the second step

Version 2.0:

* faster implementation of the nonlinear optimization step
* three-step procedure for computing the intrinsic and extrinsic
  camera parameters with circular control points
* fourth step for correcting image coordinates

Version 2.1b:

* computation of the extrinsic camera parameters from 3D - 2D correspondences


Questions and comments are welcome to:

Janne Heikkila
University of Oulu
Department of Electrical Engineering
FIN-90570 Oulu, Finland

email: jth@ee.oulu.fi
web:   http://ee.oulu.fi/~jth
