McalTransformCoordinate3dList

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 for a coordinate system.

Using this function, you can convert between the following:

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 in the XY-plane (Z=0) of the relative coordinate system 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.