McalGrid

This function uses an image of a grid of circles or squares and the world description of this grid to establish calibration points, calibrate your camera setup, and create an absolute world coordinate system. If using a circle grid, the center of each circle in the real-world grid is used as a calibration point; if using a chessboard grid, the intersection of four squares/rectangles is used as a calibration point. McalGrid() automatically determines the pixel coordinates of the calibration points in the image using feature extraction algorithms, and calculates the world coordinates of the calibration points using the world description of the grid (number of rows/columns and the space between rows/columns). From these calibration points and the specified calibration mode, McalGrid() establishes a pixel-to-world and world-to-pixel mapping function. The mapping is stored in the specified calibration context.

McalGrid() can also extract calibration points from a special type of chessboard grid which contains a fiducial; this is referred to as a fiducial grid. The fiducial supported in a fiducial grid is a Data Matrix code that encodes the world description of the grid itself. This information includes the grid spacing, the units in which the spacing is measured, the position of the grid's reference calibration point, and the grid's orientation.

MIL is distributed with five different camera calibration grids that you can print and use: ChessboardCalibrationGrid_15x16_Letter.pdf, ChessboardCalibrationGrid_18x22_Letter.pdf, CircleCalibrationGrid_15x16_Letter.pdf, CircleCalibrationGrid_18x22_Letter.pdf, and FiducialCalibrationGrid_Letter.pdf. These files are located in the Matrox Imaging\Images directory. Each file includes the world description of the grid. For guidelines when printing the grid, see the Printing the grid subsection of the Generating a grid for calibration section of Chapter 27: Calibrating your camera setup.

After calling McalGrid(), you can inquire about the success of the camera calibration using McalInquire() with M_CALIBRATION_STATUS. You can inquire about the accuracy of the mapping function (camera calibration error) using McalInquire() with M_AVERAGE_PIXEL_ERROR, M_MAXIMUM_PIXEL_ERROR, M_AVERAGE_WORLD_ERROR, or M_MAXIMUM_WORLD_ERROR. In addition, you can visualize the calibration points that were used, using McalDraw() with M_DRAW_IMAGE_POINTS; this visualization can be especially effective when overlaid on the image of the original grid. It is important that the extracted calibration points are directly in the middle of each circle, for a circle grid, and at the intersection of the grid squares/rectangles, for a chessboard grid. Any extra points, missing points, or imprecisely positioned points will result in calibration inaccuracy. For more information, see the Inquiring about your camera calibration section of Chapter 27: Calibrating your camera setup.

In the default calibration mode, M_LINEAR_INTERPOLATION mode, a mapping function is created so that comparing transformed coordinates (either pixel-to-world or world-to-pixel) of the calibration points results in virtually no measured calibration error. This produces increased calibration accuracy for areas of the image inside the grid and reduced accuracy for areas outside the grid. For all other calibration modes, the mapping function applies the calibration error equally to all areas in the image, regardless of where the grid was in the image. If there are any problems with the mapping function, the calibration error is averaged out over the entire image.

For 3D-based camera calibration modes (M_TSAI_BASED or M_3D_ROBOTICS), it is possible to use a grid that is not in the XY-plane (Z=0) of the absolute coordinate system. This allows you to account for two XY-planes in the working area of the camera or even for the thickness of the calibration grid itself. For both cases, you can use the GridOffsetZ parameter to specify the height or thickness of the grid being used.

When working in M_3D_ROBOTICS camera calibration mode, you must first call this function with M_ACCUMULATE at least three times to accumulate data with different images and orientations. Calling this function with M_ACCUMULATE more than 3 times improves the accuracy of the camera calibration. Before each data accumulation call, you must change the position and orientation of the tool holding the camera with respect to the robot base. More specifically, you must rotate the tool along at least two non-parallel axes. You must also use McalSetCoordinateSystem() to set the position of the tool coordinate system with respect to the robot base coordinate system before each of these calls. When you are done accumulating data, you must call this function with M_FULL_CALIBRATION and no image to perform the full camera calibration. Once you perform a full camera calibration, you can no longer accumulate camera calibration poses.

For 3D-based camera calibration modes, McalGrid() performs two types of calculations. It calculates the camera's internal attributes, and it calculates the orientation and distance between the camera and camera calibration plane. Initially, the latter is used to set the camera coordinate system. If you move the camera or the grid (not both), you can have McalGrid() recalculate only the orientation and distance between them. In this case, depending on what you moved, you can specify that McalGrid() displace either the camera coordinate system or the relative coordinate system, using M_DISPLACE_CAMERA_COORD or M_DISPLACE_RELATIVE_COORD, respectively. When using M_DISPLACE_RELATIVE_COORD, the camera calibration plane is considered to be the XY-plane of the relative coordinate system, regardless of how McalControl() with M_CALIBRATION_PLANE is set.

Note that the internal attributes calculated for the camera are not those of the physical camera, but those of the ideal pinhole-camera used to model the physical camera.

Also, for 3D-based camera calibration modes, a successful call to McalGrid() with M_FULL_CALIBRATION creates a rigid link between the camera coordinate system and the tool coordinate system. This link ensures that moving either the tool or the camera coordinate system will affect both. This link can be broken using McalControl() with M_LINK_TOOL_AND_CAMERA.

Note that for an M_3D_ROBOTICS calibration context, which requires multiple calls to McalGrid(), you can inquire about any particular call using McalInquireSingle().

Depending on the type of calibration grid and the orientation of the camera and grid in your setup, you might have to specify a hint pixel to indicate the grid's reference calibration point, used to determine the origin of the absolute coordinate system. You can do this using McalControl() set to M_GRID_HINT_PIXEL_X and M_GRID_HINT_PIXEL_Y. Note that the default position of the reference calibration point for complete grids (grids that are unobstructed and show all specified rows and columns) is the calibration point in the corner of the grid closest to the top-left corner of the image. For chessboard grids that are partially obscured and for all fiducial grids, the default reference calibration point is the calibration point closest to the center of the image.

For more information on performing camera calibration using a chessboard or circle grid, see the Calibrating using calibration points from a grid section of Chapter 27: Calibrating your camera setup. For information on camera calibration using a fiducial grid, see the Calibrating using a fiducial grid section of Chapter 27: Calibrating your camera setup.