MIL_ID CalibrationId,  //in 
const MIL_DOUBLE *PixCoordXArrayPtr,  //in 
const MIL_DOUBLE *PixCoordYArrayPtr,  //in 
const MIL_DOUBLE *WorldCoordXArrayPtr,  //in 
const MIL_DOUBLE *WorldCoordYArrayPtr,  //in 
const MIL_DOUBLE *WorldCoordZArrayPtr,  //in 
MIL_INT NumPoint,  //in 
MIL_INT64 Operation,  //in 
MIL_INT64 ControlFlag  //in 
This function uses a specified list of calibration points to calibrate your camera setup. Calibration points are pixel coordinates and their associated realworld coordinates. The mapping is stored with the specified camera calibration context. The specified camera calibration context determines the camera calibration mode used.
Unlike when using McalGrid(), McalList() does not use a default orientation for the Yaxis 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 Yaxis 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_DIRECTION to ensure that the orientation of the Yaxis was set correctly. For more information, see the Calibrating using calibration points from a list section of Chapter 26: Calibrating your camera setup.
Typically, you specify the list of calibration points in the absolute coordinate system. However, for 3Dbased camera 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 camera calibration mode, you must perform at least three calls to McalList() with M_ACCUMULATE before performing a full camera 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 nonparallel 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 camera calibration improves the accuracy of your camera calibration.
You can inquire about the pixel coordinates and associated realworld coordinates of each calibration point of one particular call using McalInquireSingle().
For 3Dbased camera 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 3Dbased camera 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 3Dbased camera 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 pinholecamera used to model the physical camera.
After calling McalList(), you can inquire about the success of the camera calibration using McalInquire() with M_CALIBRATION_STATUS. Also, you can inquire about the pixel coordinates and associated realworld 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 camera calibration, see the Steps to performing a camera calibration section of Chapter 26: Calibrating your camera setup.
Specifies the address of the array containing the Xpixel coordinates.
When performing a M_FULL_CALIBRATION operation in M_3D_ROBOTICS camera calibration mode, set this parameter to M_NULL.
Specifies the address of the array containing the Ypixel coordinates.
When performing a M_FULL_CALIBRATION operation in M_3D_ROBOTICS camera calibration mode, set this parameter to M_NULL.
Specifies the address of the array containing the Xworld coordinates in the camera calibrationplane coordinate system.
When performing a M_FULL_CALIBRATION operation in M_3D_ROBOTICS camera calibration mode, set this parameter to M_NULL.
Specifies the address of the array containing the Yworld coordinates in the camera calibrationplane coordinate system.
When performing a M_FULL_CALIBRATION operation in M_3D_ROBOTICS camera calibration mode, set this parameter to M_NULL.
Specifies the address of the array containing the Zworld coordinates.
For 2Dbased camera calibration modes (M_UNIFORM_TRANSFORMATION, M_LINEAR_INTERPOLATION or M_PERSPECTIVE_TRANSFORMATION), this parameter must be set to M_NULL.
For a M_TSAI_BASED camera calibration mode, if the object you are imaging is planar (has all its points on a single plane), this parameter must be set to M_NULL. However, if the object is nonplanar, it is possible to provide the Zcoordinates and the minimum camera angle is not required.
For a M_3D_ROBOTICS camera calibration mode, the parameter must be set to M_NULL if the context is not yet calibrated. However, you can provide Zworld coordinates when using McalList() with M_DISPLACE_RELATIVE_COORD or M_DISPLACE_CAMERA_COORD.
Specifies the number of coordinates in the supplied arrays.
For M_UNIFORM_TRANSFORMATION and M_LINEAR_INTERPOLATION camera calibration modes, the minimum number of coordinates is 3. For M_PERSPECTIVE_TRANSFORMATION camera calibration mode, the minimum number of coordinates is 4.
For M_TSAI_BASED and M_3D_ROBOTICS camera calibrations, using no Zcoordinates, the minimum number of coordinates is 5.
For M_TSAI_BASED camera calibrations, using Zcoordinates, the minimum number of coordinates is 7.
For 3Dbased camera calibration contexts (M_TSAI_BASED and M_3D_ROBOTICS camera calibrations), using Operation with M_DISPLACE_CAMERA_COORD or M_DISPLACE_RELATIVE_COORD, the minimum number of calibration points required is 4.
Note, the specified pixel coordinates should cover the area of the image from which you want realworld coordinates (the working area). When performing a M_FULL_CALIBRATION operation in M_3D_ROBOTICS camera calibration mode, set this parameter to M_NULL.
When using a standard vector (std::vector) overload function in C++, you can pass M_DEFAULT to this parameter and MIL will automatically determine the size based on the number of items in the vector passed to the PixCoordXArrayPtr, PixCoordYArrayPtr, WorldCoordXArrayPtr, WorldCoordYArrayPtr, or WorldCoordZArrayPtr parameter.
Specifies the camera calibration operation to perform. This parameter must be set to one of the following values:
For specifying the camera calibration
operation


Value  Description  
M_DEFAULT 
Same as M_FULL_CALIBRATION. 

M_ACCUMULATE 
Specifies to receive only the position of the calibration points and stores them in the camera calibration context. 

M_DISPLACE_CAMERA_COORD 
Calculates only the position and orientation between the camera and the camera calibration plane, and displaces the camera coordinate system accordingly. 

M_DISPLACE_RELATIVE_COORD 
Calculates only the relative coordinate system position in space. 

M_FULL_CALIBRATION 
Performs a full camera calibration. 
Header  Include mil.h. 
Library  Use mil.lib; milcal.lib. 
DLL  Requires mil.dll; milcal.dll. 