McalList

This function uses a specified list of calibration points to calibrate your camera setup. Calibration points are pixel coordinates and their associated real-world coordinates. The mapping is stored with the specified calibration context. The specified calibration context determines the calibration mode used.

Unlike when using McalGrid(), McalList() does not use a default orientation for the Y-axis of the absolute coordinate system. It establishes the orientation based on the specified calibration points. It arbitrarily selects three of the specified points (for example, point A, B, and C). It then establishes the direction that a line between point A and B would rotate to meet a line between point A and C while using the smallest angle of rotation. It finally selects the Y-axis orientation for the absolute coordinate system so that the rotation direction in the pixel coordinate system and in the absolute coordinate system are the same. You can use M_Y_AXIS_UP to ensure that the orientation of the Y-axis was set correctly. For more information, see the List of coordinates subsection of the Calibrating using calibration points from a grid or a list section of Chapter 25: Calibrating your camera setup.

Typically, you specify the list of calibration points in the absolute coordinate system. However, for 3D-based calibration modes (M_TSAI_BASED or M_3D_ROBOTICS), it is possible to use a list of calibration points that are not in the Z=0 plane of the absolute coordinate system. In this case, it is possible to describe the points in the relative coordinate system instead, using McalControl() with M_CALIBRATION_PLANE set to M_RELATIVE_COORDINATE_SYSTEM. You can then use McalSetCoordinateSystem() to move the relative coordinate system. Both of these calls must be made before calling McalList().

When working in M_3D_ROBOTICS calibration mode, you must perform at least three calls to McalList() with M_ACCUMULATE before performing a full calibration. Before each 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. Using McalList() with M_ACCUMULATE more than three times before performing a full calibration improves the accuracy of your calibration.

You can inquire about the pixel coordinates and associated real-world coordinates of each calibration point of one particular call using McalInquireSingle().

For 3D-based calibration modes, McalList() 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 McalList() recalculate only the orientation and distance between them. In this case, depending on what you moved, you can specify that McalList() 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 relative coordinate system regardless of the M_CALIBRATION_PLANE setting.

For 3D-based calibrations, it is also mandatory to set the image coordinates of the principal point prior to calibrating using McalControl() with M_PRINCIPAL_POINT_X, and M_PRINCIPAL_POINT_Y. If the aspect ratio of the CCD element is different than 1, specify it using McalControl() with M_CCD_ASPECT_RATIO before calling McalList().

Also, for 3D-based calibration modes, a successful call to McalList() 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 systems will affect both. This link can be broken using McalControl() with M_LINK_TOOL_AND_CAMERA.

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.

After calling McalList(), you can inquire about the success of the calibration using McalInquire() with M_CALIBRATION_STATUS. Also, you can inquire about the pixel coordinates and associated real-world coordinates of each calibration point using McalInquire() with M_CALIBRATION_IMAGE_POINTS_X, M_CALIBRATION_IMAGE_POINTS_Y, M_CALIBRATION_WORLD_POINTS_X and M_CALIBRATION_WORLD_POINTS_Y. These coordinates correspond to the center of circles in a circle grid or to points connecting four corners in a chessboard grid.

For more information on performing calibration, see the Steps to performing a calibration section of Chapter 25: Calibrating your camera setup.