You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 2_Configuration/config_camera_calibration.md
+78-62Lines changed: 78 additions & 62 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,31 +1,49 @@
1
1
#Calibrating Your Camera
2
-
In the ARToolKit software, default camera properties are contained in the camera parameter file camera_para.dat, that is read in each time an application is started. These parameters are sufficient for basic tracking for a wide range of different cameras. However, to get best tracking accuracy, particularly when looking directly onto a flat marker, it is important to calibrate your camera. As well as helping tracking accuracy and reducing jitter, in a video-see through AR interface, the video image can be warped to remove the camera's lens distortion.
2
+
In the ARToolKit software, default camera properties are contained in the camera parameter file camera_para.dat, that is read in each time an application is started. These parameters are sufficient for basic tracking for a wide range of different cameras. However, to get best tracking accuracy, particularly when looking directly onto a flat marker, it is important to calibrate your camera. Using a calibrated camera improves tracking accuracy and reduces jitter. In the case of video see-through AR devices (goggles that are not optically see through that usually utilize stereo cameras), having calibrated cameras can help remove lens distortion in the displayed video image.
3
3
4
4
![Beginning calibration with the chessboard][Beginning_calibration_with_the_chessboard]
5
5
6
6
Using a very simple camera calibration technique it is possible to generate a separate parameter file for the specific camera(s) that are being used. This page presents how to use the utility programs included with ARToolKit to calibrate your video camera.
7
7
8
-
##Set-Up
9
-
Calibration works by capturing images of the pre-prepared calibration pattern with the camera. The calibration pattern is in the file "Calibration chessboard.pdf" contained in the `doc/patterns` directory inside your ARToolKit distribution. This PDF is designed to be printed on A4 paper. If printing on US Letter paper, you should choose to crop the PDF rather than scale it to fit the smaller paper size.
8
+
###Set-Up
9
+
Calibration works by capturing images of the pre-prepared calibration pattern with the camera. Two calibration pattern image files are provided by the ARToolKit SDK (path: [downloaded ARToolKit SDK root directory]/doc/patterns):
10
+
11
+
"Calibration chessboard (US Letter).pdf"
12
+
"Calibration chessboard (A4).pdf"
13
+
14
+
Print the PDF file using a media size respective to the labeled PDF filename.
10
15
11
16
![Chessboard pattern affixed to board ready for calibration][Chessboard_ready_for_calibration]
12
17
13
18
Once printed, the pattern must be affixed to a flat surface. The easiest means of doing this is to use a piece of thin very flat board (as might be obtained from a hardware store) and a dry glue. Using a millimeter rule, measure the size of the edges of the squares. If printed without scaling, this distance will be exactly 30 mm. Other sizes can be used, as long as they are accurately known.
14
19
15
20
Finally, set up your camera. A calibration file is only valid for one focus setting of the camera (although it will still work at other focal lengths), so choose in advance the focus setting for the camera which will be used most often. *This is especially important when your camera supports multiple aspect ratios. While the resolution need not be 1:1 with your camera calibration, the aspect ratio is extremely important.*
16
21
17
-
##How it Works
22
+
###How it Works
18
23
The ["Calibration pattern.pdf"][2] image consists of a grid of black and white squares surrounded by a white border. When viewed through the camera lens, lens distortion causes the straight lines at the edges of the squares to appear curved. The calib_camera program uses the OpenCV library to locate the corners of the squares and then measures the spacing between the corners and uses this information to calculate the lens distortion. The more images captured, and the more angles they are captured from, the lower the error in the distortion measurement.
19
24
20
-
## Running calib_camera
21
-
Open a command prompt (on Mac OS X / Linux, open a Terminal window, or on Windows choose "Run" from the Start menu, type "cmd"). Run the calib_camera program from the command prompt.
25
+
####Executing the calib_camera Application
26
+
Open a command prompt:
27
+
28
+
Mac OS X or Linux: open a Terminal window
29
+
or
30
+
31
+
Windows: open the "Run" prompt from the Start menu, in the "Open:" textbox, type "cmd"<return>
32
+
33
+
---
34
+
35
+
For the Android or iOS version of calib_camera, build and deploy the Android Studio, Eclipse or XCode project available in the respective platform project directory found directly under the root directory of the download ARToolKit SDK specific for the platform.
36
+
37
+
---
22
38
23
-
On OS X / Linux, type:
39
+
Run the calib_camera application executable from the command prompt. Change the directory to the path: [downloaded ARToolKit SDK root directory]/bin.
40
+
41
+
OS X or Linux command-line, type:
24
42
<pre>
25
43
./calib_camera
26
44
</pre>
27
45
28
-
On Windows, type:
46
+
Windows command-line, type:
29
47
<pre>
30
48
calib_camera.exe
31
49
</pre>
@@ -43,95 +61,93 @@ You will see output similar to this in your terminal:
43
61
44
62
At this point, you should see the image from the camera appear.
45
63
46
-
###Optional - Changing the Default Calibration Pattern Settings
64
+
#####Optional - Changing the Default Calibration Pattern Settings
47
65
If you need to, the size of the calibration squares, the number of intermediate corners in horizontal and vertical directions (i.e. the number of rows minus 1 and the number of columns minus 1), and the number of calibration images captured can all be adjusted from the command line. Running the utility with the `--help` option will show the various command-line options for adjusting the default calibration settings.
48
66
49
-
On OS X / Linux, type:
50
-
<pre>
51
-
./calib_camera --help
52
-
</pre>
67
+
OS X or Linux command-line, type:
53
68
54
-
On Windows, type:
55
-
<pre>
56
-
calib_camera.exe --help
57
-
</pre>
69
+
./calib_camera --help
70
+
71
+
Windows command-line, type:
72
+
73
+
calib_camera.exe --help
58
74
59
75
The help text is reproduced here:
60
-
<pre>
76
+
61
77
Usage: ./calib_camera [options]
62
78
Options:
63
-
--vconf <videoparameterforthecamera>
64
-
-cornerx=n: specify the number of corners on chessboard in X direction.
65
-
-cornery=n: specify the number of corners on chessboard in Y direction.
66
-
-imagenum=n: specify the number of images captured for calibration.
67
-
-pattwidth=n: specify the square width in the chessbaord.
68
-
-h -help --help: show this message
69
-
</pre>
70
-
71
-
###Optional - Specifying Options for Video Configuration
79
+
-vconf <video parameter for the camera>
80
+
-cornerx=n: specify the number of corners on chessboard in
81
+
X direction.
82
+
-cornery=n: specify the number of corners on chessboard in
83
+
Y direction.
84
+
-imagenum=n: specify the number of images captured for calibration.
85
+
-pattwidth=n: specify the square width in the chessbaord.
86
+
-h or -help or --help: show this message
87
+
88
+
#####Optional - Specifying Options for Video Configuration
72
89
In addition to command-line options for controlling the calibration pattern settings, a video configuration can also be specified on the command line using the `--vconf` parameter (followed by the actual video config, in quotes if it includes spaces), allowing you to choose a video format and/or image size, if your camera supports those options.
73
90
74
91
For example, this invocation on Mac OS X requests the image from the camera be scaled to 640x480:
75
-
<pre>
76
-
./calib_camera --vconf "-width=640 -height=480"
77
-
</pre>
92
+
93
+
./calib_camera --vconf "-width=640 -height=480"
78
94
79
95
If you use the video configuration to select a video size different from that which will be used later, be sure to maintain the same proportions between the width and the height. For example, a 4:3 image of 1600x1200 pixels can be scaled to 800x600 or 640x480, whereas a 16:9 image of 1920x1080 image can be scaled to 860x540. *A camera calibration is only valid per aspect ratio.*
80
96
81
-
##Capturing Calibration Images
82
-
Calibration requires the capturing of a series of images. In the top-left corner of the capture window is displayed the number of images captured so far. Point the camera at the chessboard grid, and the inner corners of the squares will be highlighted with "X" marks and numbered.
97
+
####Capturing Calibration Images
98
+
Calibration requires the capturing of a series of images. In the top-left corner of the capture window is displayed the number of images captured so far. Point the camera at the chessboard grid, and the inner corners of the squares will be highlighted with 'X' marks and numbered.
83
99
84
-
When the camera can clearly see all the intermediate corners, the X marks turn RED, and a calibration image can be captured:
100
+
When the camera can clearly see all the intermediate corners, the 'X' marks turn RED, and a calibration image can be captured:
85
101
![A good view of the calibration board, ready to capture.][Calibration_example_OK_1]
86
102
87
-
If some of the corners are obscured by the edges of the camera frame, or poor lighting or reflection, the crosses will be GREEN, and no calibration image can be captured until the optical conditions are changed.
103
+
If some of the corners are obscured by the edges of the camera frame, or poor lighting or reflection, the 'X' will be GREEN, and no calibration image can be captured until the optical conditions are changed.
88
104
![A poor view of the calibration board, NOT ready to capture.][Calibration_example_not_OK]
89
105
90
-
Once you have an image with all red crosses, you can press the space bar on the keyboard. The image will be captured, and the locations of the X points will be printed to the terminal window, and the counter will increment.
106
+
Once you have an image with all red 'X's, you can press the keyboard spacebar. The spacebar tab captures the video frame augmented with red 'X' characters. The relative positions of the 'X' indicators on the captured frame are calculated, recorded, written to standard out of the command-line window and the capture counter is incremented.
91
107
92
-
In order to obtain a good calibration for the camera, it is important to obtain images of the calibration board at a variety of angles to the camera lens. The images below give examples of the configurations of the calibration board you should try to obtain. Note that these involve holding the camera at different angles to the board, including upside-down:
108
+
In order to obtain a good calibration for the camera, it is important to obtain images of the calibration board at a variety of angles to the camera lens. The images below give examples of the configurations of the calibration board you should try to obtain. Note that these involve holding the calibration board at different angles relative to the camera, including upside-down:
93
109
![Calibration example OK 1][example OK 1]
94
110
![Calibration example OK 2][example OK 2]
95
111
![Calibration example OK 3][example OK 3]
96
112
![Calibration example OK 4][example OK 4]
97
113
![Calibration example OK 5][example OK 5]
98
114
![Calibration example OK 6][example OK 6]
99
115
100
-
Once all the calibration images have been captured (10 by default), the calibration data will be output to the terminal window, and you will be prompted for a file name for the calibration data:
Once all the calibration images have been captured, that is, ten (ten is the default) presses of the spacebar, the calibration data is tabulated and a distortion factor associated to the camera device is calculated. The tabulated calibration data is written to standard out of the command-line window. At this point, the application prompts for a filename to write the calibration data to.
117
+
118
+
--------------------------------------
119
+
SIZE = 640, 480
120
+
Distortion factor: k1=-0.064153, k2=0.000674,
121
+
p1=-0.003693, p2=-0.011219,
122
+
fx=6819.694824, fy=4906.716797,
123
+
x0=-13355.703125, y0=1494.664429,
124
+
s=-0.891334
125
+
-7651.11364 -0.00000 -13355.70312 0.00000
126
+
-0.00000 -5504.91609 1494.66443 0.00000
127
+
0.00000 0.00000 1.00000 0.00000
128
+
--------------------------------------
129
+
Err[ 1]: 0.384557[pixel]
130
+
Err[ 2]: 0.637637[pixel]
131
+
Err[ 3]: 0.605374[pixel]
132
+
Err[ 4]: 0.517292[pixel]
133
+
Err[ 5]: 0.730103[pixel]
134
+
Err[ 6]: 0.560028[pixel]
135
+
Err[ 7]: 0.586818[pixel]
136
+
Err[ 8]: 0.501263[pixel]
137
+
Err[ 9]: 0.437201[pixel]
138
+
Err[10]: 0.385920[pixel]
139
+
Filename[camera_para.dat]:
124
140
125
141
If the calibration data is good, there should be very low estimated error in each image: hopefully, less than 1 pixel. *Error greater than 2 pixels indicates a poor calibration, and it should be abandoned and restarted.*
126
142
127
143
At this point, you can press return or enter on the keyboard to save the data in a file named "camera_para.dat".
128
144
129
145
That's all there is to it. This new calibration procedure takes only a minute, and should be fast enough that you can recalibrate your camera any time you change its focus or zoom. With good calibration, you'll see much improved tracking in ARToolKit.
130
146
131
-
##Using the Calibration Data
147
+
###Using the Calibration Data
132
148
To use your new calibration file, just replace the default camera_para.dat file in ARToolKit's `bin/Data` directory with your newly saved data. It can be helpful to keep a collection of camera_para.dat files for cameras you commonly use.
133
149
134
-
##Further Reading - Stereo Camera Calibration
150
+
###Further Reading - Stereo Camera Calibration
135
151
If calibrating a stereo camera, calibrate each eye separately first, saving the parameters, then run the program calib_stereo to perform the final step of [inter-ocular calibration][3].
0 commit comments