| Customize Help
| Save Settings

McalList



Function Map
Synopsis
Calibrate your camera setup using a list of coordinates.
Syntax
void McalList(
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
)
Description

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 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 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_DIRECTION to ensure that the orientation of the Y-axis 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 3D-based 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 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 camera calibration improves the accuracy of your camera 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 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 3D-based 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 3D-based 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 pinhole-camera 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 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 camera calibration, see the Steps to performing a camera calibration section of Chapter 26: Calibrating your camera setup.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
CalibrationId

Specifies the identifier of the camera calibration context.

PixCoordXArrayPtr INQ
Accepts the address of one of the following:
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] (and a maximum array rank for C# of 1)
    Required array size:(NumPoint)

Specifies the address of the array containing the X-pixel coordinates.

When performing a M_FULL_CALIBRATION operation in M_3D_ROBOTICS camera calibration mode, set this parameter to M_NULL.

PixCoordYArrayPtr INQ
Accepts the address of one of the following:
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] (and a maximum array rank for C# of 1)
    Required array size:(NumPoint)

Specifies the address of the array containing the Y-pixel coordinates.

When performing a M_FULL_CALIBRATION operation in M_3D_ROBOTICS camera calibration mode, set this parameter to M_NULL.

WorldCoordXArrayPtr INQ
Accepts the address of one of the following:
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] (and a maximum array rank for C# of 1)
    Required array size:(NumPoint)

Specifies the address of the array containing the X-world coordinates in the camera calibration-plane coordinate system.

When performing a M_FULL_CALIBRATION operation in M_3D_ROBOTICS camera calibration mode, set this parameter to M_NULL.

WorldCoordYArrayPtr INQ
Accepts the address of one of the following:
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] (and a maximum array rank for C# of 1)
    Required array size:(NumPoint)

Specifies the address of the array containing the Y-world coordinates in the camera calibration-plane coordinate system.

When performing a M_FULL_CALIBRATION operation in M_3D_ROBOTICS camera calibration mode, set this parameter to M_NULL.

WorldCoordZArrayPtr INQ
Accepts the address of one of the following:
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] (and a maximum array rank for C# of 1)
    Required array size:(NumPoint)

Specifies the address of the array containing the Z-world coordinates.

For 2D-based 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 non-planar, it is possible to provide the Z-coordinates 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 Z-world coordinates when using McalList() with M_DISPLACE_RELATIVE_COORD or M_DISPLACE_CAMERA_COORD.

NumPoint INQ

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 Z-coordinates, the minimum number of coordinates is 5.

For M_TSAI_BASED camera calibrations, using Z-coordinates, the minimum number of coordinates is 7.

For 3D-based 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 real-world 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.

Operation

Specifies the camera calibration operation to perform. This parameter must be set to one of the following values:

function map For specifying the camera calibration operation
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_FULL_CALIBRATION.

Click to summarize M_ACCUMULATE

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

At least three calls to McalList() should be made with this operation before performing full camera calibration with M_FULL_CALIBRATION. This operation is only supported for M_3D_ROBOTICS camera calibration mode.

(summarize)
Click to summarize 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. Note that besides the camera coordinate system, this also displaces the tool coordinate system (if still linked with M_LINK_TOOL_AND_CAMERA); no other coordinate system is affected. This camera calibration operation is only supported for 3D-based camera calibration contexts that are fully calibrated with M_FULL_CALIBRATION.

If the camera is moved to a new position but its internal attributes are already known by a previous full camera calibration, you can use this operation to allow for a faster camera calibration.

(summarize)
Click to summarize M_DISPLACE_RELATIVE_COORD

Calculates only the relative coordinate system position in space. This camera calibration operation is only supported for 3D-based camera calibration contexts that are fully calibrated with M_FULL_CALIBRATION.

You can use this operation to move the relative coordinate system only and remain calibrated. This operation keeps the camera fixed with respect to the absolute coordinate system, and its intrinsic attributes unmodified. You can then obtain the position and orientation of the relative coordinate system with respect to any other coordinate system using McalGetCoordinateSystem(), and calculate the unknown position of an object in space.

When using this operation, the camera calibration plane is considered to be the relative coordinate system regardless of the M_CALIBRATION_PLANE setting.

(summarize)
Click to summarize M_FULL_CALIBRATION

Performs a full camera calibration. For 3D-based camera calibration contexts, this operation calculates the camera's internal attributes and the difference in position and orientation between the camera and the camera calibration plane. It then sets the camera coordinate system accordingly.

When working in M_TSAI_BASED camera calibration mode, the camera's optical axis should be at least 30 degrees away from the axis perpendicular to the camera calibration plane (also known as, angle of incidence). Otherwise, the camera calibration might fail.

(summarize)
ControlFlag

Reserved for future expansion. This parameter must be set to M_DEFAULT.

Compilation information
Header Include mil.h.
Library Use mil.lib; milcal.lib.
DLL Requires mil.dll; milcal.dll.
3D ROBOTICS TSAI BASED DEFAULT DEFAULT 3D ROBOTICS TSAI BASED NULL NULL NULL NULL NULL NULL DEFAULT ACCUMULATE DISPLACE CAMERA COORD DISPLACE RELATIVE COORD FULL CALIBRATION NULL UNIFORM TRANSFORMATION LINEAR INTERPOLATION PERSPECTIVE TRANSFORMATION 3D ROBOTICS TSAI BASED CALIBRATED DEFAULT DEFAULT TSAI BASED 3D ROBOTICS CALIBRATED 3D ROBOTICS CALIBRATED FULL CALIBRATION DEFAULT 3D ROBOTICS