maintained by James Davis
|
maintained by James Davis |
What is included
This tool is really a collection of a bunch of smaller tools all wrapped up together in order to make internal camera calibration easy. In theory external pose is solved as well, but I only use it for internal myself. In particular there are these parts:
- hough - A compiled C executable to find circles in an image
- match2ideal - A perl script to convert the output of hough into the input for match2fin
- match2fin - Compiled matlab for camera calibration given world XYZ and image UV coordinates
- tclcalib - A compiled tcl wrapper around everything
- xyzuvcal_both - A compiled matlab function to to calibrate a single camera
- xyzuvcal_extonly - Function to calibrate external parameters given internal
- sample C++ code for reading the calibration files
At the core is Janne Heikkila's calibration toolbox. However everything has been compiled and integrated so that it is hopefully easier to use.
Download
tclcalib_v2.zip - A large 18MB zip archive of everything, plus maybe some stuff you don't need.
Platforms
Irix
This was originally a bunch of individual tools under IRIX, with a tcl/tk wrapper that called everything so that I didn't have to remember the exact recipe to follow. I think it should be possible to make it work under other unix flavors but I haven't tried. Also you'll need to have all the right support applications installed.
Win2K
In order to make it more usable by other people I have munged it all into a distribution that includes everything you need to run under Win2K. I've compiled both the matlab and tcl into executables for Win2K so that you don't need to have either installed.
Other calibration tools
Janne Heikkila's Camera Calibration Toolbox (on which this tool is based)
Rather than list them all myself, I refer interested parties to an annotated list maintained by Jean-Yves Bouget. He has a fine matlab calibration toolbox himself, as well as C implementation available.
http://www.vision.caltech.edu/bouguetj/calib_doc/htmls/links.html
Installation
Only the Win2K installation is described, for IRIX all the parts are included but no instructions.
Easy installation
- If SGIs IFL library has not been installed on your machine, then install the libraries in IFL1_3_1.exe. Unfortunately, just copying DLLs around does not seem to work, you must actually install the libraries using their installer, as Administrator on your machine. This is freely available from the SGI web site, but I've included it for convenience, and to insure that the same version is used.
- Make sure the directory 'pc_tclcalib_complete' is in your path. You don't need any of the other directories to run under Win2K, they contain source for the various tools that make up the package. You can delete them if you want to.
More detailed installation
The directory pc_tclcalib_complete has a relatively small amount of stuff that is actually part of this package. The rest of the mess is all the support executables and surrounding DLLs. Its all been included in the easy installation above to make it easy for people to get this running. If you already had a machine set up for development you might be able to keep just the smaller set, since everything else may be installed elsewhere on your machine anyway. Except matlab, all the external tools are free on the net.
The following executables are included in pc_tclcalib and must be in your path:
- calib.exe
- hough.exe
- match2fin.exe
- match2ideal [perl script]
These scripts make use of the following external things, all of which need to be in your path:
- SGIs IFL library
- Available from their web site and included in this package. Their installation gets it all set in your path.
- Matlab
- match2fin is compiled matlab code. Its a windows executable, but requires a bunch of DLLs from matlab. I think you have these already whenever matlab is installed.
- Cygwin
- The following executables from cygwin are used:
- cat, cygpath, echo, gawk, rm, sh, which
- ImageMagick
- The 'convert' utility from the ImageMagick toolbox is used. Unfortunately windows already has its own 'convert', so you need a copy of the executable named 'iconvert' in your path in order to prevent the name conflict.
Usage
Easy Usage
- You should see something like this (but with no image yet)
- Select the image to start with - (click on image1.tif)
- Click on 'Find Dots' (now the image should appear)
- Repeat for image2.tif and image3.tif
- Highlight the desired images to use for calibration (select all of the images)
- Click 'Calibrate'
- Note in the console information about the quality of calibration
- Click 'Quit'
- Calibration results are in 'camera.fin'
GUI Components
- Num Rows Slider - Set the number of rows of circles you want to find
- Num Cols Slider - Set the number of columns of circles you want to find
- R, dR pixels Slider - Something about the expected image size of circles that I admit I don't understand.
- Threshold Slider - The image intensity (0,255) to threshold at to find circles, adjust depending on lighting conditions.
- Spacing Slider - Set the physical spacing between circles, if you want your calibration to correspond to correct world scale.
- Image Pane (near the top of the window) - Shows the image only after you click 'Find Dots'. If some circles were found then shows these highlighted in green.
- Find Dots Button - Essentially runs 'hough' and 'match2ideal' on the selected image, leaving the results in the current directory. These locate dots and arrange the results
- Calibrate Button - Runs'match2fin' on all of the selected images, or more precisely on the image.match files that were left around the directory by Find Dots. Produces camera.fin which is the final calibration data.
Command Line Usage To Calibrate Internal Parameters
We can calibrate camera internal parameters using the above gui or with the following command line routines.
% hough 6 6 10 10 100 image1.tif % match2ideal image1.tif_points 65 6 > image1.match % hough 6 6 10 10 100 image2.tif % match2ideal image2.tif_points 65 6 > image2.match % match2fin camera . image1.match image2.match
- calib <imagefile1.tif> [imagefile2.tif] [imagefile3.tif] ...
- This tool basically acts as a gui wrapper around the commands above. It was originally tcl, and FreeWrap was used to wrap it up so that tcl does not need to be installed. pc_tclcalib/calib.tcl is the tcl source.
- hough <rows> <cols> <R> <dR> <threshold> <imagefile.tif>
- This tool finds black circles on a white background in an image and writes out a file with the image plane location of the points. Its a C++ executable, that needs IFL to compile, I've done it on SGI and Win2K.
- match2ideal <points_file_from_hough> <spacing_between_dots> <cols>
- This perl script converts the points from hough into the format expected by match2fin.
- match2fin <outputfilename> <directory> <file1.match> [file2.match] ...
- This is basically Heikkila's calibration toolbox. A few wrapper functions were written and the matlab code was compiled using mcc. Thus it is now runable from the command line, rather than requiring matlab. This takes a bunch of match files and generates a meaningful internal calibration file. Since we used images of a plane from several viewpoints the external corresponds to one of them. I never worried about which one.
Command Line Usage To Calibrate External Parameters
Suppose we have a set of xyzuv data. That is image plane observations (uv) related to actual world 3D coordinates (xyz). The *.match files generated by the above procedure have this information, but you may also have obtained it via some other method. You may or may not have bothered to obtain a set of internal calibration parameters. You can use one of the following two commands to obtain a camera calibration file with both internal and external calibration.
- xyzuvcal_both <xyzuvfilename> <outputfilename>
- This tool will calculate both internal and external calibration parameters. This will work fine, but more stable internal parameters will be obtained by first calibrating the camera internals using the above procedure and then using the routine below. Note that this routine applies only to a single camera. 'match2fin' above does something similar, but it takes multiple match files and generates a single estimate of camera internal parameters.
- xyzuvcal_extonly <in.xyzuv> <internal.fin> <output.fin>
- Calibrates only the external pose of a single camera. You give it the correct internal parameters on the command line, and get an output *.fin file that has these same internal parameters and the best external parameters for the supplied xyzuv info.
Interpreting the calibration data
The produced file camera.fin has the following numbers in it.
640.000000 # NDX - [pix] number of pixels in x direction 480.000000 # NDY 6.384000 # Sx - effective CCD chip size in horizontal direction 4.804800 # Sy - 0.963191 # Asp - aspect ratio 5.939386 # Effective focal length 353.051566 # Cx - [pix] principal point 245.274074 # Cy -0.006705 # Rad1 - lens distortion parameters 0.000157 # Rad2 0.000786 # Tan1 -0.005542 # Tan2 -0.032590 # Inverse lens distortion parameters 0.001763 -0.000759 0.005345 0.001896 -0.000100 0.000001 -0.039093 -505.7523 # Tx - [mm] Extrinsic parameters 109.213337 # Ty 995.917779 # Tz -170.885852 # Rx [rad] -2.951705 # Ry -6.014927 # Rz
What is in all these directories?
- C++_Examples - some C++ code which can read the resulting calibration files
- docs - this documentation
- heikkila - the matlab camera calibration toolbox that I got from Heikkila's web site, plus a few wrapper routines. Compiled via mcc to to match2fin under Win2K, but just called via matlab on unix.
- hough - a C++ application for finding circles in images. Relies on IFL to load image. Compiles via VisualStudio on Win2K and Makefile on Irix.
- pc_tclcalib - the tcl/tk wrapper that just presents a graphic interface and calls all the right things. This is the Win2K version in this directory. Compiled to calib using Freewrap so that tcl doesn't need to be installed on the machine. This directory also has copies of all precompiled executables for Win2K, so that only this one directory needs to be in the system path.
- pc_tclcalib_complete - This is an alternate directory to pc_tclcalib. The same stuff plus a zillion support applications and DLLs. A big ugly mess, but should make it easier to get this running on a fresh machine.
- targets - A perl script that produces postscript that produces targets with circles.
- tclcalib - the Irix version of the wrapper tcl script, also a shell script that sets up environment variables.
- testdata - some test images to try this out on
- util - the match2ideal perl script
- IFL1_3_1.exe - installation for IFL
Acknowledgements
Heikkila and Silva - The main calibration code is from their toolbox.
Szymon Rusinkiewicz, Kari Pulli, and Alex Roetter - The hough code was at one point touched by each of these guys. smr also wrote some of the perl munging stuff.
Xing Chen - The C++ classes that can read these calibration files, as well as some of the matlab wrapper code was written by Cindy.
Matt Pharr, Maneesh Agrawala, Chris Stolte - The C++ code uses a matrix library called sgl that was written by Matt, and then made to work under visual studio by either Maneesh or Chris.
Dennis R. LaBelle - Wrote FreeWrap, which is a nice way to wrap up tcl so that there doesn't need to be an actual full tcl installation on the target machine.
Bits and pieces from SGI, Mathworks, ImageMagick, and Cygwin.
(I don't think I've included anything any of these people are trying to sell.)
