| Customize Help
| Save Settings

McalTransformCoordinateList


Function Map
Syntax
Description
Parameters
- CalibrationOrImageId
- TransformType
Table: For specifying pixel-to-world or world-to-pixel
+ combination: For specifying coordinates are packed
+ combination: For specifying to return invalid points
- NumPoints
- SrcCoordXArrayPtr
- SrcCoordYArrayPtr
- DstCoordXArrayPtr
- DstCoordYArrayPtr
Compilation information
Synopsis
Convert a list of coordinates between their world and pixel values.
Syntax
void McalTransformCoordinateList(
MIL_ID CalibrationOrImageId, //in
MIL_INT64 TransformType, //in
MIL_INT NumPoints, //in
const MIL_DOUBLE *SrcCoordXArrayPtr, //in
const MIL_DOUBLE *SrcCoordYArrayPtr, //in
MIL_DOUBLE *DstCoordXArrayPtr, //out
MIL_DOUBLE *DstCoordYArrayPtr //out
)
Description

This function converts a list of coordinates from their pixel value to their world value (or vice versa). The conversion can be performed according to a camera calibration context, calibrated image, or corrected image.

Note that, if you changed the origin and/or orientation of the relative coordinate system (using McalRelativeOrigin() or McalSetCoordinateSystem()), world coordinates will be returned, or assumed to be given, with respect to this relative coordinate system.

This function converts the coordinates of a point by making a line connecting the center of the camera's lens with the point provided, and then finding the intersection of that line with the required plane. To convert an image pixel to a world point, this function defines a line connecting the center of the camera's lens with the image plane, and then returns the intersection of this line with the world plane.

However, if the image plane is not parallel to 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 and in the relative coordinate system, that point in the relative coordinate system is returned. However, if the line traced through the specified point in the image plane does not intersect the XY (Z=0) plane of the relative coordinate system, M_INVALID_POINT is returned since there is no intersection. If the line's intersection with the XY (Z=0) plane of the relative coordinate system is behind the camera, then the mathematically computed value is returned, even though it is not the correct world location of the point specified in the image.

However, using M_NO_POINTS_BEHIND_CAMERA returns M_INVALID_POINT if the returned point is behind the camera.

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 the camera calibration context, calibrated image, or corrected image. 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.

TransformType

Specifies whether to perform a pixel-to-world or world-to-pixel conversion. This parameter must be set to one of the following values:

function map For specifying pixel-to-world or world-to-pixel
Click to summarizeValue Description
Click to summarize M_PIXEL_TO_WORLD +

Converts from pixel to world.
Click to summarize M_WORLD_TO_PIXEL +

Converts from world to pixel.
Combination value for the values listed in For specifying pixel-to-world or world-to-pixel.

You can add the following value to the above-mentioned values to specify coordinates are packed.

function map For specifying coordinates are packed
Click to summarizeCombination value Description
Click to summarize M_PACKED

Specifies that the source coordinates are passed in a packed format and/or that the result coordinates should be returned in a packed format depending on what you pass to the SrcCoordYArrayPtr and DstCoordYArrayPtr parameters.

If SrcCoordYArrayPtr is passed M_NULL, SrcCoordXArrayPtr is assumed to be a packed set of X- and Y-coordinates.

If DstCoordYArrayPtr is passed M_NULL, DstCoordXArrayPtr is filled with a packed set of X- and Y-coordinates.

If both SrcCoordYArrayPtr and DstCoordYArrayPtr are passed M_NULL, SrcCoordXArrayPtr is assumed to be a packed set of X- and Y-coordinates, and DstCoordXArrayPtr is filled with a packed set of X- and Y-coordinates.

(summarize)
Combination values for any of the possible values of the TransformType parameter.

You can add one of the following values to the above-mentioned values to set the return values of invalid points.

function map For specifying to return invalid points
Click to summarizeCombination value Description
Click to summarize M_NO_EXTRAPOLATED_POINTS

Specifies that if a pixel involved in the transformation is not inside the calibrated region, M_INVALID_POINT will be returned, instead of a coordinate resulting from the extrapolation. The calibrated region is defined as the image region covered by the camera calibration grid. This can be displayed by calling McalDraw() with M_DRAW_VALID_REGION.

This value only applies to piecewise linear camera calibrations (M_LINEAR_INTERPOLATION); if it is set and the image has any other type of camera calibration, it is ignored.

(summarize)
Click to summarize M_NO_POINTS_BEHIND_CAMERA

Specifies that M_INVALID_POINT is returned when a computed point is mathematically valid but physically impossible (behind the camera).

If this value does not apply to the specified transformation type, then it is ignored.

(summarize)
NumPoints

Specifies the number of points in the coordinate list.

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

SrcCoordXArrayPtr
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:(NumPoints)
  • 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:((NumPoints) * 2)

Specifies the address of the array of the input X-coordinates.

SrcCoordYArrayPtr
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:(NumPoints)

Specifies the address of the array of the input Y-coordinates.

This parameter can be set to M_NULL when TransformType is set to M_PACKED. See the description of M_PACKED for more details.

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

Specifies the address of the array in which to place the output X-coordinates.

If M_NO_POINTS_BEHIND_CAMERA is used and one of the source points cannot be converted, the entry in the destination array corresponding to such point is set to M_INVALID_POINT.

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

Specifies the address of the array in which to place the output Y-coordinates.

This parameter can be set to M_NULL when TransformType is set to M_PACKED. See the description of M_PACKED for more details.

If M_NO_POINTS_BEHIND_CAMERA is used and one of the source points cannot be converted, the entry in the destination array corresponding to such point is set to M_INVALID_POINT.

Compilation information
Header Include mil.h.
Library Use mil.lib; milcal.lib.
DLL Requires mil.dll; milcal.dll.
NULL PROC CALIBRATED TRUE PROC PIXEL TO WORLD WORLD TO PIXEL PACKED NO EXTRAPOLATED POINTS NO POINTS BEHIND CAMERA NULL NULL NULL NULL