McalTransformImage

See also

User Guide:

Adjusting blob analysis processing controls After fixturing Camera calibration propagation Physically correcting an image Steps to performing a camera calibration Uniform camera calibration and other camera calibration modes

Reference:

MbufAlloc2d MbufInquire McalAlloc McalGrid McalInquire McalList McalUniform McalWarp MimWarp

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
defectdetectionprocfunc.cpp
defectdetectionprocfunc_capandcontent.cpp
gumpackinspection.cpp
mcal.cpp
mcal.cs
mcal.vb
multiviewannotations.cpp
profiledisplay.cpp
stereorectification.cpp
targetalignmenttask.cpp
unwarpmultiviewcylinder.cpp
variouscodereadings.cpp

McalTransformCoordinateList

Function Map

Table:

For specifying the camera calibration context

- InterpolationMode

Table:	For specifying the type of interpolation to perform
+ combination:	For specifying overscan

- OperationType

Table:

For specifying the function's operation type

- ControlFlag

Table:	For specifying the type of result to output
+ combination:	For specifying how to position and scale the source image in the destination image

Compilation information

Synopsis

Physically transform an image by removing distortions, or create LUTs that can be used to do the same.

Syntax

void McalTransformImage(

MIL_ID SrcImageBufId,	//in
MIL_ID DstImageOrLutId,	//in
MIL_ID CalibrationId,	//in
MIL_INT64 InterpolationMode,	//in
MIL_INT64 OperationType,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function removes distortions in an image by physically transforming the image according to a specified camera calibration context. This function can also just extract the warping lookup tables (LUTs) that would be used to transform the image; you can then use these LUTs to transform images with the same distortions, using MimWarp().

Typically, the image is transformed such that:

Its pixel coordinate system is aligned with its relative coordinate system.
All the pixels in the destination image are square and represent the same size in world units.
It is scaled and positioned in the destination image according to the specified fill mode.

After transformation, the image will be considered physically corrected if an M_FULL_CORRECTION operation was performed, and the fill mode scaled the image such that all its pixels are square and represent the same size in world units.

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

SrcImageBufId

Specifies the identifier of the source image buffer.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

DstImageOrLutId

Specifies the identifier of the destination image buffer or LUT buffer.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

When transforming the image (M_WARP_IMAGE), set this parameter to the image buffer that has an appropriate size for the selected fill mode.

When extracting the X or Y warping LUT required for the image transformation (M_EXTRACT_LUT_X or M_EXTRACT_LUT_Y), set this parameter to a 32-bit signed, M_LUT buffer that has the same size as the destination image being passed to MimWarp().

While the transformed image retains the MIL identifier of the camera calibration context associated with the source image, the transformed image itself has a uniform world-to-pixel mapping. Propagating the camera calibration information of the transformed image will pass both the identifier of the camera calibration context associated with the source image along with the uniform world-to-pixel mapping of the transformed image established during McalTransformImage().

CalibrationId

Specifies the camera calibration context with which to transform the image.

For specifying the camera calibration context
Value	Description
M_DEFAULT	Specifies that the camera calibration context associated with the source image will be used. If the source image is not associated with a camera calibration context, a MIL error is returned. (summarize) Specifies that the camera calibration context associated with the source image will be used. (more details...)
MIL calibration context identifier	Specifies the identifier of a valid camera calibration context, which you have calibrated using McalGrid(), McalList(), McalUniform(), or McalWarp(). If the source image is also associated with a camera calibration context, it will have precedence over the calibration context passed here, unless the calibration context identifiers differ and the source image does not have a constant pixel size. (summarize) Specifies the identifier of a valid camera calibration context, which you have calibrated using McalGrid(), McalList(), McalUniform(), or McalWarp(). (more details...)

InterpolationMode

Specifies the interpolation mode to use when associating destination pixels with source points. This parameter must be set to one of the following values:

For specifying the type of interpolation to perform
Value	Description
M_DEFAULT	Same as M_NEAREST_NEIGHBOR + M_OVERSCAN_ENABLE.
M_BICUBIC +	Specifies bicubic interpolation. The new value is determined by taking a weighted average of the 16 values (4x4) that surround the source point. Note that the sum of the weights used for bicubic interpolation might be greater than one. If this occurs and the result reflects an overflow or underflow, the result is saturated according to the depth and data type of the destination buffer. (summarize) Specifies bicubic interpolation. (more details...)
M_BILINEAR +	Specifies bilinear interpolation. The new value is determined by taking a weighted average of the 4 values (2x2) that surround the source point. (summarize) Specifies bilinear interpolation. (more details...)
M_NEAREST_NEIGHBOR +	Specifies nearest neighbor interpolation. The new value is that of the pixel closest to the source point. (summarize) Specifies nearest neighbor interpolation. (more details...)

Combination values for any of the possible values of the InterpolationMode parameter.

You can add one of the following values to the above-mentioned values to specify how to determine the value of a destination pixel when its associated point falls outside the source buffer.

For specifying overscan
Combination value	Description
M_OVERSCAN_CLEAR	Sets the destination pixel to 0, if the associated point falls outside the source buffer.
M_OVERSCAN_DISABLE	Leaves the destination pixel as is, if the associated point falls outside the source buffer.
M_OVERSCAN_ENABLE	Uses pixels from the source buffer's ancestor buffer, if the associated point falls outside the source buffer. If the source buffer is not a child buffer or if the associated point falls outside the ancestor buffer, it leaves the destination pixel as is. This is the default value. (summarize) Uses pixels from the source buffer's ancestor buffer, if the associated point falls outside the source buffer. (more details...)
M_OVERSCAN_FAST	Specifies that MIL will automatically select the overscan that optimizes speed, according to the specified operation and the target system. The overscan could be hardware-specific thereby having a different behavior than the other supported overscan modes. Note that when using M_OVERSCAN_FAST, the destination pixels in the overscan area are undefined. The pixels can therefore contain different values from one function call to the next, even if the function's parameter values are the same. (summarize) Specifies that MIL will automatically select the overscan that optimizes speed, according to the specified operation and the target system. (more details...)

OperationType

Specifies the function's operation type. This parameter must be set to the following value:

For specifying the function's operation type
Value	Description
M_DEFAULT	Same as M_FULL_CORRECTION.
M_CORRECT_LENS_DISTORTION_ONLY	Specifies a partial correction of the source image by only removing lens distortion, without modifying the perspective effect. In this case, the destination image is not calibrated. This operation is only supported for 3D-based camera calibration modes (M_TSAI_BASED or M_3D_ROBOTICS). (summarize) Specifies a partial correction of the source image by only removing lens distortion, without modifying the perspective effect. (more details...)
M_FULL_CORRECTION	Specifies a full correction of the source image. This corrects all distortions of the source image based on the provided camera calibration context. (summarize) Specifies a full correction of the source image. (more details...)

ControlFlag

Specifies the function's control flag. This parameter must be set to the following value:

For specifying the type of result to output
Value	Description
M_DEFAULT	Same as M_WARP_IMAGE.
M_EXTRACT_LUT_X +	Extracts the X warping LUT for the image transformation. You can use the extracted LUT to transform an image using MimWarp() with the OperationMode parameter to M_WARP_LUT + M_FIXED_POINT + 10. Since the LUTs are generated with 10 fractional bits, you must specify this number of fractional bits when you call MimWarp(). Note, InterpolationMode must be set to M_DEFAULT. (summarize) Extracts the X warping LUT for the image transformation. (more details...)
M_EXTRACT_LUT_Y +	Extracts the Y warping LUT for the image transformation. You can use the extracted LUT to transform an image using MimWarp() with the OperationMode parameter to M_WARP_LUT + M_FIXED_POINT + 10. Since the LUTs are generated with 10 fractional bits, you must specify this number of fractional bits when you call MimWarp(). Note, InterpolationMode must be set to M_DEFAULT. (summarize) Extracts the Y warping LUT for the image transformation. (more details...)
M_WARP_IMAGE +	Transforms the source image and fits it into the destination image according to the specified fill mode.

Combination values for the values listed in For specifying the type of result to output.

You can add one of the following values to the above-mentioned values to specify the fill mode.

Essentially, these values allow you to specify how to position and scale the source image in the destination image.

For specifying how to position and scale the source image in the destination image
Combination value	Description
M_CLIP	Specifies that the source image is positioned and scaled such that every destination pixel maps to a valid source pixel. This fill mode does not produce any invalid pixels in the destination image, but some information might be lost. (summarize) Specifies that the source image is positioned and scaled such that every destination pixel maps to a valid source pixel. (more details...)
M_FIT	Specifies that the source image is positioned and scaled such that every source pixel maps to a valid destination pixel. This fill mode might produce invalid (undefined) pixels in the destination image, but no information is lost. This is the default value. (summarize) Specifies that the source image is positioned and scaled such that every source pixel maps to a valid destination pixel. (more details...)
M_USE_DESTINATION_CALIBRATION	Specifies that the source image is positioned and scaled using the camera calibration information of the destination image. The source image is positioned such that its relative coordinate system is placed at the same location as the current relative coordinate system of the destination image. In addition, the source image is scaled to have the same pixel-to-world mapping as the destination image. To use this option, the destination image must be a calibrated image with a uniform pixel size. To apply a camera calibration to the destination image that just scales and offsets the world coordinate system from the pixel coordinate system, use McalUniform() on the destination buffer prior to calling McalTransformImage(). Note that this option only affects how the image is positioned and scaled in the destination image; the source image is always corrected according to the camera calibration setting of the CalibrationId parameter. This option cannot be used with M_EXTRACT_LUT_X or M_EXTRACT_LUT_Y or when OperationType is set to M_CORRECT_LENS_DISTORTION_ONLY. (summarize) Specifies that the source image is positioned and scaled using the camera calibration information of the destination image. (more details...)

Compilation information

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