M3dmapTriangulate

const MIL_ID *ContextCalOrImageBufIdArrayPtr,	//in
const MIL_DOUBLE *PixelCoordXArrayPtr,	//in
const MIL_DOUBLE *PixelCoordYArrayPtr,	//in
MIL_DOUBLE *WorldCoordXArrayPtr,	//out
MIL_DOUBLE *WorldCoordYArrayPtr,	//out
MIL_DOUBLE *WorldCoordZArrayPtr,	//out
MIL_DOUBLE *RMSErrorArrayPtr,	//out
MIL_INT NumCalibrations,	//in
MIL_INT NumPoints,	//in
MIL_INT64 CoordinateSystem,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function uses triangulation to calculate the X-, Y-, and Z-world coordinates of points (features) that can be seen by two or more cameras. You must identify the pixel location of the points in the image plane of the different cameras. Each of the camera setups must be calibrated in 3D mode so that the position of the cameras in the world is known. To calculate each point's location in the world, the point's location in each camera's image plane and the camera's location in the world are used.

With a single call to M3dmapTriangulate(), you can calculate the world coordinates of multiple points, even if a point does not appear in the image plane of all cameras. Each point must be seen by at least two cameras. To indicate that a point is not seen by a camera, use M_INVALID_POINT. For example, to determine the world coordinates of the following two points on an object that is seen by three cameras, you would pass the following arguments to M3dmapTriangulate():

The calibration contexts of the camera setups must have been allocated in 3D mode using McalAlloc() with M_TSAI_BASED or M_3D_ROBOTICS and they must share a common world coordinate system. For more information about camera calibration, see Chapter 25: Calibrating your camera setup.

Although results can be obtained with only two cameras, rounding and extraction errors can affect the accuracy of the calculations. Using more than two cameras will increase the robustness of the function.

For points that could not be computed, their corresponding entries in the coordinate output arrays will be set to M_INVALID_POINT and their corresponding entries in the RMSErrorArrayPtr array will be set to 0.0. This can occur when all projection lines from the image planes to the point are perfectly parallel and therefore do not intersect.

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 if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

ContextCalOrImageBufIdArrayPtr

Specifies the address of an array containing the identifiers of the camera calibration contexts for each of the camera setups. Alternatively, the array can contain the identifiers of calibrated or corrected images; the operation uses the camera calibration contexts associated with the images.

PixelCoordXArrayPtr

Specifies the address of the array containing the X-pixel coordinates of the common points in the image plane of each camera. This array must have a size equal to (NumCalibrations x NumPoints).

Specify the location of the points in the image plane of a given camera, before specifying them for another camera; list them in the same order for each camera. If more than two cameras are used and a point is seen by only a subset of all the cameras, indicate that the point is not seen by a camera by setting the corresponding entry in the array to M_INVALID_POINT. Order the groups of points according to order of their camera's calibration context in the specified list of camera calibration contexts (ContextCalOrImageBufIdArrayPtr).

PixelCoordYArrayPtr

Specifies the address of the array containing the Y-pixel coordinates of the common points in the image plane of each camera. This array must have a size equal to (NumCalibrations x NumPoints).

WorldCoordXArrayPtr

Specifies the address of an array in which to write the calculated X-world coordinates. This array must have a size equal to NumPoints.

WorldCoordYArrayPtr

Specifies the address of the array in which to write the calculated Y-world coordinates. This array must have a size equal to NumPoints.

WorldCoordZArrayPtr

Specifies the address of the array in which to write the calculated Z-world coordinates. This array must have a size equal to NumPoints.

RMSErrorArrayPtr

Specifies the address of the array in which to write the root mean square (RMS) error for the calculated world coordinates of each point. This array must have a size equal to NumPoints.

If the RMS error is not needed, set this parameter to M_NULL.

NumCalibrations

Specifies the number of calibration contexts. This should correspond to the number of cameras. This parameter must be greater or equal to 2.

NumPoints

Specifies the number of points to compute using triangulation. This parameter must be greater or equal to 1.

CoordinateSystem

Specifies the world coordinate system that is common to all the specified camera calibration contexts.

For specifying the common coordinate system
Value	Description
M_ABSOLUTE_COORDINATE_SYSTEM	Specifies that the calibration contexts have the absolute coordinate system in common.
M_RELATIVE_COORDINATE_SYSTEM	Specifies that the calibration contexts have the relative coordinate system in common.
M_ROBOT_BASE_COORDINATE_SYSTEM	Specifies that the calibration contexts have the robot-base coordinate system in common.
M_TOOL_COORDINATE_SYSTEM	Specifies that the calibration contexts have the tool coordinate system in common.

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; mil3dmap.lib.
DLL	Requires mil.dll; mil3dmap.dll.