McalTransformCoordinate

See also

User Guide:

Camera calibration How coordinates and non-positional results are transformed Inquiring about your camera calibration Working with real-world units

Reference:

MbufInquire McalAlloc McalDraw McalInquire McalRelativeOrigin McalSetCoordinateSystem

Availability

Not available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Matrox Indio (Update 53 or Update 68) (w)

Not supported on Matrox Concord PoE with ToE (Update 82) (z)

Fully supported on:

Fully supported on Host system (a)

Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Fully supported on Matrox Morphis (g)

Fully supported on Matrox Morphis QxT (h)

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Fully supported on Matrox Solios eA/XA (l)

Fully supported on Matrox Solios ecl/xcl/ev-cl (m)

Fully supported on Matrox USB3 Vision driver (Update 19) (o)

Fully supported on Matrox RadientPro-CL (Update 7) (p)

Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)

Fully supported on Matrox GenTL driver (Update 34) (v)

Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

calibratedruler.cpp
colorrelativecalibration.cpp
registeredgoldentemplate.cpp
simple3dbinpicking.cpp

McalStream

McalTransformCoordinate3dList

Function Map

Syntax

Description

Parameters

- CalibrationOrImageId

- TransformType

Table:	For specifying pixel-to-world or world-to-pixel
+ combination:	For specifying to return invalid points

- X

- Y

- ResXPtr

Table:

For specifying the potential return values of the X-coordinate

- ResYPtr

Table:

For specifying the potential return values of the Y-coordinate

Compilation information

Synopsis

Convert coordinates between their world and pixel values.

Syntax

void McalTransformCoordinate(

MIL_ID CalibrationOrImageId,	//in
MIL_INT64 TransformType,	//in
MIL_DOUBLE X,	//in
MIL_DOUBLE Y,	//in
MIL_DOUBLE *ResXPtr,	//out
MIL_DOUBLE *ResYPtr	//out

)

Description

This function converts a pair 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 image 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:

For specifying pixel-to-world or world-to-pixel
Value	Description
M_PIXEL_TO_WORLD +	Converts from pixel to world.
M_WORLD_TO_PIXEL +	Converts from world to pixel.

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 specify the return of invalid points.

For specifying to return invalid points
Combination value	Description
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 region can be displayed by calling McalDraw() with M_DRAW_VALID_REGION. This combination value only applies to piecewise linear camera calibrations (M_LINEAR_INTERPOLATION); if this combination value is specified and the object passed to CalibrationOrImageId has any other type of camera calibration, this combination value is ignored. (summarize) 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. (more details...)
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) Specifies that M_INVALID_POINT is returned when a computed point is mathematically valid but physically impossible (behind the camera). (more details...)

Specifies the X-coordinate of the input.

Specifies the Y-coordinate of the input.

ResXPtr

Specifies the address of the variable in which to place the returned value of the X-coordinate. One of the following can be written to the address.

For specifying the potential return values of the X-coordinate
Value	Description
M_INVALID_POINT	Specifies a non-valid coordinate.
Value	Specifies the transformed X-coordinate as a value.

ResYPtr

Specifies the addres of the variable in which to place the returned value of the Y-coordinate. One of the following can be written to the address.

For specifying the potential return values of the Y-coordinate
Value	Description
M_INVALID_POINT	Specifies a non-valid coordinate.
Value	Specifies the transformed Y-coordinate as a value.

Compilation information

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