McalTransformCoordinate3dList

MIL_ID CalibrationOrImageId,	//in
MIL_INT64 SrcCoordinateSystem,	//in
MIL_INT64 DstCoordinateSystem,	//in
MIL_INT NumPoints,	//in
const MIL_DOUBLE *SrcCoordXArrayPtr,	//in
const MIL_DOUBLE *SrcCoordYArrayPtr,	//in
const MIL_DOUBLE *SrcCoordZArrayPtr,	//in
MIL_DOUBLE *DstCoordXArrayPtr,	//out
MIL_DOUBLE *DstCoordYArrayPtr,	//out
MIL_DOUBLE *DstCoordZArrayPtr,	//out
MIL_INT64 ModeFlag	//in

)

Description

This function converts a list of coordinates from a source coordinate system to a destination coordinate system, where coordinates of unit direction vectors and of depth maps are also accepted as inputs or outputs.

Using this function, you can convert between the following:

Pixel coordinate system and world coordinate system.
World coordinate system and any other world coordinate system.
Fully corrected depth maps and world coordinate system.
Pixel coordinate system and unit direction vectors in any world coordinate system.

Note that conversion between unit direction vectors and the pixel coordinate system is supported, but conversion of direction vectors to depth maps or world coordinate systems is not. Also, if you pass a corrected image to McalTransformCoordinate3dList(), and you specify that the source points are expressed in the pixel coordinate system (M_PIXEL_COORDINATE_SYSTEM), the function assumes that the source points are expressed in the corrected pixel coordinate system.

To convert a point from the pixel coordinate system to its corresponding point in the specified world coordinate system, this function creates a line (simulating a light ray) from the effective pinhole of the camera through the specified point in the image plane, and then to the specified relative coordinate system (DstCoordinateSystem). Since all points along a given light ray project onto the same point in the image plane, every point along the ray is theoretically a solution. Therefore, to produce a unique solution, the point of intersection between the line and the XY-plane (Z=0) of the relative coordinate system is transformed to the specified world coordinate system. Then, the corresponding world point is returned. Alternatively, McalTransformCoordinate3dList() can return the X, Y, and Z-components of the unit direction vector corresponding to the direction of the calculated light ray as it intersects the source point (using M_UNIT_DIRECTION_VECTOR).

If the image plane is not parallel to the XY-plane (Z=0) of the relative coordinate system, due to the camera setup or a displacement of the relative coordinate system, not every point in the image plane will have a valid real-world equivalent. Three types of intersections can occur when transforming from the image plane to the world plane. If the specified point in the image plane corresponds to a point in front of the camera in the relative coordinate system, its corresponding position in the destination world coordinate system is returned. However, if the line traced through the specified point in the image plane does not intersect the XY-plane of the relative coordinate system, M_INVALID_POINT is returned. If the projected line's intersection with the XY-plane of the relative coordinate system is behind the camera, the mathematically computed value of this point of intersection is returned. Because this point of intersection is located behind the camera, its location in the relative coordinate system is considered as incorrect.

However, using M_NO_POINTS_BEHIND_CAMERA with McalTransformCoordinate3dList() returns M_INVALID_POINT if the returned point is behind the camera.

To convert a point specified in a world coordinate system to its corresponding point in the pixel coordinate system, the function transforms the specified point to the relative coordinate system and a line is formed (simulating a light ray) from the point to the effective pinhole of the camera. The function then returns the point of intersection of this line with the image plane. If the point given is behind the camera, the function will return the mathematically computed value. However, using M_NO_POINTS_BEHIND_CAMERA with McalTransformCoordinate3dList() will return M_INVALID_POINT instead of the mathematically computed value.

This function also supports the conversion of coordinates from a depth map to a specified world coordinate system and vice versa. To convert from a depth map to a world coordinate system, you must provide the depth map's X and Y coordinates and, optionally, the intensity value of the pixel. You can choose to omit the intensity value, in which case the function will obtain the value from the specified location in the depth map. If you choose to omit the intensity values, set SrcCoordZArrayPtr to M_NULL. The intensity value of the depth map point is linearly mapped to a corresponding Z-coordinate for the world coordinate system. Note, source pixel coordinates that are outside the depth map image will generate M_INVALID_POINT.

If the intensity of a depth map pixel is equal to the buffer's maximum intensity value, it is interpreted as missing data and cannot be converted. M_INVALID_POINT will be returned. Note, that this applies whether you choose to omit the intensity values or not.

To convert a point from a specified world coordinate system to a depth map, you must provide the X-, Y-, and Z-coordinates of the point. The function converts the X-, Y-, and Z-coordinates of the world coordinate system to X, Y and intensity values, respectively. The Z-coordinate of the world coordinate system is linearly mapped to a corresponding intensity value where the maximum Z-coordinate in the list is given the highest possible depth value and the minimum Z-coordinate is give the lowest possible depth value.

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

CalibrationOrImageId

Specifies the identifier of a camera calibration context, 3D reconstruction context, calibrated image, corrected image, or 3d reconstruction result buffer of type M_POINT_CLOUD_RESULT. When an identifier of an image buffer is specified, the transformation uses the camera calibration information associated with this image.

If you are transforming coordinates obtained from an image, pass the identifier of that image. For example, for coordinates originating from a child buffer, pass the child buffer's identifier.

When the identifier is set to a 3D reconstruction context or an M_POINT_CLOUD_RESULT 3D reconstruction result buffer, only world-to-world coordinate system conversions are supported. Specifically, for a 3D reconstruction context, you can only convert absolute coordinates to laser coordinates, or vice versa. For an M_POINT_CLOUD_RESULT 3D reconstruction result buffer, you can only convert absolute coordinates to relative coordinates, or vice versa.

SrcCoordinateSystem

Specifies the coordinate system of the source coordinates. This parameter must be set to one of the following values:

For specifying the type of the source coordinate system
Value	Description
M_ABSOLUTE_COORDINATE_SYSTEM	Specifies an implicit and fixed coordinate system from which all other world coordinate systems are defined. Note that for a 3D reconstruction context, you can only convert absolute coordinates to laser coordinates, and vice versa. For an M_POINT_CLOUD_RESULT 3D reconstruction result buffer identifier, you can only convert absolute coordinates to relative coordinates, and vice versa. (summarize) Specifies an implicit and fixed coordinate system from which all other world coordinate systems are defined. (more details...)
M_CAMERA_COORDINATE_SYSTEM	Specifies the coordinate system whose origin corresponds to the effective pinhole of the camera and whose Z-axis points in the direction that the camera is facing. This coordinate system is only defined after a successful camera calibration in M_TSAI_BASED or M_3D_ROBOTICS mode. Alternatively, you can define this coordinate system using McalSetCoordinateSystem() with M_ASSIGN. (summarize) Specifies the coordinate system whose origin corresponds to the effective pinhole of the camera and whose Z-axis points in the direction that the camera is facing. (more details...)
M_LASER_LINE_COORDINATE_SYSTEM	Specifies the coordinate system whose origin is on the first laser line at the point closest to the origin of the absolute coordinate system. Note that for a 3D reconstruction context, you can only convert laser coordinates to absolute coordinates, and vice versa. (summarize) Specifies the coordinate system whose origin is on the first laser line at the point closest to the origin of the absolute coordinate system. (more details...)
M_PIXEL_COORDINATE_SYSTEM	Specifies the pixel coordinate system of the image passed to CalibrationOrImageId (corrected or uncorrected); if a camera calibration context is passed instead, the pixel coordinate system is of any image that has the same pixel-to-world mapping as the specified camera calibration context. The origin of this coordinate system, (0, 0), is at the center of the image's top-left pixel. This is a 2D coordinate system. (summarize) Specifies the pixel coordinate system of the image passed to CalibrationOrImageId (corrected or uncorrected); if a camera calibration context is passed instead, the pixel coordinate system is of any image that has the same pixel-to-world mapping as the specified camera calibration context. (more details...)
M_RELATIVE_COORDINATE_SYSTEM	Specifies the relative coordinate system. The XY-plane (Z=0) of the relative coordinate system defines the world plane in which results are measured. By default, it is positioned at the absolute coordinate system. Note that for an M_POINT_CLOUD_RESULT 3D reconstruction result buffer, you can only convert relative coordinates to absolute coordinates, and vice versa. (summarize) Specifies the relative coordinate system. (more details...)
M_ROBOT_BASE_COORDINATE_SYSTEM	Specifies the coordinate system whose origin is positioned at the base of the robot holding the camera. This coordinate system is only available for an M_3D_ROBOTICS camera calibration context, calibrated image, or corrected image. (summarize) Specifies the coordinate system whose origin is positioned at the base of the robot holding the camera. (more details...)
M_TOOL_COORDINATE_SYSTEM	Specifies the coordinate system used to position the camera. This coordinate system is not necessarily associated with the real camera position. (summarize) Specifies the coordinate system used to position the camera. (more details...)

DstCoordinateSystem

Specifies the coordinate system in which to return the coordinates. This parameter must be set to one of the following values:

For specifying the type of the destination coordinate system
Value	Description
M_ABSOLUTE_COORDINATE_SYSTEM	Specifies an implicit and fixed coordinate system from which all other world coordinate systems are defined. INFO INFO
M_CAMERA_COORDINATE_SYSTEM	Specifies the coordinate system whose origin corresponds to the effective pinhole of the camera and whose Z-axis points in the direction that the camera is facing. INFO INFO
M_LASER_LINE_COORDINATE_SYSTEM	Specifies the coordinate system whose origin is on the first laser line at the point closest to the origin of the absolute coordinate system. INFO INFO
M_PIXEL_COORDINATE_SYSTEM	Specifies the pixel coordinate system of the image passed to CalibrationOrImageId (corrected or uncorrected); if a camera calibration context is passed instead, the pixel coordinate system is of any image that has the same pixel-to-world mapping as the specified camera calibration context. INFO INFO
M_RELATIVE_COORDINATE_SYSTEM	Specifies the relative coordinate system. INFO INFO
M_ROBOT_BASE_COORDINATE_SYSTEM	Specifies the coordinate system whose origin is positioned at the base of the robot holding the camera. INFO INFO
M_TOOL_COORDINATE_SYSTEM	Specifies the coordinate system used to position the camera. INFO INFO

NumPoints

Specifies the number of points to convert.

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 SrcCoordXArrayPtr, SrcCoordYArrayPtr, or SrcCoordZArrayPtr parameter.

SrcCoordXArrayPtr