1 @page dwx_calibration_cli_tool Command Line Calibration Tool
3 The DriveWorks command line calibration tool takes a configuration file input and image data (in
4 the form of static files or through cameras), along with a rig calibration xml file, containing
5 intrinsics calibration data for the cameras and vehicle definition, and performs the extrinsic
6 calibration of the system.
8 ## Overview and Options
11 The command line calibration tool performs the following operations:
15 Images are acquired through live cameras or loaded from disk, depending
16 on the contents of the configuration file.
17 When images are loaded from files, the expected format is :
19 imagePrefix + index + imageSuffix
21 where `imagePrefix` and `imageSuffix` are specified in the configuration file
22 and `index` is the index of the camera, ranging from 0 to 3 (inclusive).
23 For example, if the default values are used, the files must be of the form
27 2. Calibration Markers detection
29 The Markers are detected from the images, with a parameter set defined in the
32 3. Extrinsics Calibration
34 The extrinsics parameters of the system are computed and optimized, according
35 to the parameter set defined in the configuration file.
38 4. Export of the output calibration file
40 The final results are exported in an XML calibraiton file that contains the
41 intrinsics provided as input and the computed extrinsics.
43 #### Invocation and Options
45 This tool is invoked as follows :
47 ./calibration-cli --configuration=/path/to/configuration/file.cfg [--verbose=1]
49 With the following options:
51 - `--configuration`: Must reference a valid configuration file, such as described below.
52 - `--verbose` : Specifies reporting level. For verbose mode, set this option
53 to a non-void value. Verbose mode generates more logs and debug images.
59 * `input.rig` : path to the input rig file, containing intrinsics calibration information.
60 Default value : `./rig.xml`
61 * `input.mode` : specified whether to load images from disk (`Files`) or to open cameras to take live snapshots
62 (`Cameras`). Default value : `Files`.
63 * `input.imageFolder` : folder in which the images are located, ignored if live cameras are used. Default value : `.`
64 * `input.imagePrefix` : prefix of the image files. Default : `camera_`
65 * `input.imageSuffix` : suffix of the image files. Default : `.png`
66 * `input.cameraType` : Camera type to use, ignored if static files are used. Default: `ar0231`. For more informatino,
67 report to the DriveWorks sensor documentation.
68 * `input.csiPort` : CSI port the cameras are plugged into. Default : `ab`.
69 * `input.cameraCount` : Number of cameras plugged into the CSI port. Default value : `4`.
73 * `output.rig` : Path to the output calibration xml file. Default : `./output-rig.xml`
74 * `output.snapshotFolder` = Folder in which snapshots wil be saved, ignored when using static files. Default : `.`
77 #### Marker Definition
79 * `detector.unitSize` : Unit sized of the markers, in mm. Default: `33.0`
80 * `detector.markerRadius` : Size of the markers, in unit. Default : `3.5`
81 * `detector.patternRadius` : Size of the full pattern, in unit. Default : `7.0`
83 #### Advanced Marker Detection Parameters
84 These are a set of parameters for the internal marker detection algoorithms. These can be tweaked in order to
85 improve detection performance in bad conditions (e.g. bad illumination, low contrast, etc.).
87 * `detector.findPatternRansacIterations` : Numbder of ransac iterations used during the marker detection.
89 * `detector.clusterMeanDistanceFactor` : Numerical coefficient applied to distance between clusters during marker detection. Default : `1.5`
90 * `detector.minNumberOfContourPointsInMarker` : Minimum number of contour points a marker should contain. Default: `30`
91 * `detector.minMarkerContourSolidity` : Minimum solidity of a marker contour for it to be registered. Default: `0.8`
92 * `detector.minAreaInPixelsOfMarker` : Minimum area of a marker for to be registered, in pixel. Default : `40`
93 * `detector.edgeSubpixelSearchRadius` : Search radius of the subpixel edge refinement. Default : `2.0`
94 * `detector.circleFittingErrorInitial` : Initial numerical error of the circle fitting procedure. Default : `0.04`
95 * `detector.circleFittingErrorPrediction` : Predicted numerical error of the circle fitting procedure. Default : `0.06`
98 #### Extrinsics computation
99 The following 6 parameters indicate whether to optimize or not individual components of the transformation
100 between the vehicle and the master camera. A value of `0` indicates that this components should not
101 be optimized, any other numerical value indicates that this component should be optimized.
103 * `extrinsics.optimize.Tx` = 0
104 * `extrinsics.optimize.Ty` = 0
105 * `extrinsics.optimize.Tz` = 1
106 * `extrinsics.optimize.Rx` = 1
107 * `extrinsics.optimize.Ry` = 1
108 * `extrinsics.optimize.Rz` = 0
110 #### Master camera position
111 These 3 parameters are the components of the translation between the center of the rear axle and the
112 master camera. Those are expressed in meters.
114 * `extrinsics.RearAxle.Tx` = 3.470
115 * `extrinsics.RearAxle.Ty` = 0
116 * `extrinsics.RearAxle.Tz` = 0
118 ## Known Limitations ##
120 This sections highlights the main differences between the GUI version of the tool and
121 this command line interface.
125 Only the newer `4-circles` markers are supported. Legacy calibration markers are not supported by this tool.
129 It is expected that the camera sequence is overall preserved. For example, if in the input calibration file, the cameras
130 are presented in the order Front, Rear, Right, Left. It will be expected that, in the case of static files,
131 the file with index 0 corresponds to the front camera, 1 to the rear camera and so on. Similarly, in the case of live cameras,
132 it is expected that the front camera is plugged on the port `0` of the port group specified in the configuration file,
133 the rear camera is plugged in the port `1` and so on.
135 ### Lack of Intrinsics Calibration Estimation
136 This tool is not intended for intrinsics calibration, as such, it has no support for this operation.
137 It is expected that the tool will be presented with a valid input rig xml file containing the required
138 intrinsics calibration information.
141 This tool has no encoding support. It is expected that it will not be presented with paths or any other
142 text data that cannot be represented in the ASCII charset.
144 ### Calibration Modes
146 Contrary to the GUI tool, this cli calibration tool only supports the `SurroundView` calibration mode.
147 More specifically, this mode expects 4 cameras to be around a vehicle. It is expected that 4 image sources
148 will be present at runtime (either cameras or image files).
150 ### Master Camera Selection
152 This tool does not support choosing the master camera. It will always be assumed that the amster camera is the
153 camera with index `0`. It is also expected that this camera is forward facing.
155 ### Alignement Options
157 This tool does not support advanced alignement options of the master camera. As such, it will always
158 account for the transformation between the master camera and the rig, and compensate it, in order to
159 have the `x` axis of the rig's frame of reference aligned with the optical axis of the master camera.
161 ### Inplace Processing
162 This tool does not support inplace processing. It is expected that the absolute apth to the input rig file
163 and the absolute path to the output file are different.
