| MIL 10 Reference
| Customize Help
| Save Settings

McalTransformImage


See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
McalTransformCoordinateList
McalTransformResult
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 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 if there is complementary information.
Parameters
This function is not supported on the selected boards.
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 calibration context associated with the source image, the transformed image itself has a uniform world-to-pixel mapping. Propagating the calibration information of the transformed image will pass both the identifier of the 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 calibration context with which to transform the image.

function map For specifying the calibration context
CollapseValue Description
Collapse M_DEFAULT

Specifies that the calibration context associated with the source image will be used.

If the source image is not associated with a calibration context, a MIL error is returned.

(summarize)
Collapse MIL calibration context identifier

Specifies the identifier of a valid calibration context, which you have calibrated using McalGrid(), McalList(), McalUniform(), or McalWarp().

If the source image is also associated with a 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)
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:

function map For specifying the type of interpolation to perform
CollapseValue Description
Collapse M_DEFAULT

Same as M_NEAREST_NEIGHBOR + M_OVERSCAN_ENABLE.
Collapse M_BICUBIC +

Specifies bicubic interpolation. When using bicubic interpolation, saturation is performed according to the type of the destination buffer.

(summarize)
Collapse M_BILINEAR +

Specifies bilinear interpolation. No saturation is performed.

(summarize)
Collapse M_NEAREST_NEIGHBOR +

Specifies nearest-neighbor interpolation. No saturation is performed.

(summarize)
Combination constants 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.

function map For specifying overscan
CollapseCombination value Description
Collapse M_OVERSCAN_CLEAR

Sets the destination pixel to 0, if the associated point falls outside the source buffer.
Collapse M_OVERSCAN_DISABLE

Leaves the destination pixel as is, if the associated point falls outside the source buffer.
Collapse 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, leave the destination pixel as is.

This is the default value.

(summarize)
Collapse 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)
OperationType

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

function map For specifying the function's operation type
CollapseValue Description
Collapse M_DEFAULT

Same as M_FULL_CORRECTION.
Collapse 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 calibration modes (M_TSAI_BASED or M_3D_ROBOTICS).

(summarize)
Collapse M_FULL_CORRECTION

Specifies a full correction of the source image. This corrects all distortions of the source image based on the provided calibration context.

(summarize)
ControlFlag

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

function map For specifying the type of result to output
CollapseValue Description
Collapse M_DEFAULT

Same as M_WARP_IMAGE.
Collapse 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)
Collapse 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)
Collapse M_WARP_IMAGE +

Transforms the source image and fits it into the destination image according to the specified fill mode.
Combination constants 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.

function map For specifying how to position and scale the source image in the destination image
CollapseCombination value Description
Collapse 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)
Collapse 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)
Collapse M_USE_DESTINATION_CALIBRATION

Specifies that the source image is positioned and scaled using the 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 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 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)
Compilation information
Header Include mil.h.
Library Use mil.lib; milcal.lib.
DLL Requires mil.dll; milcal.dll.
PROC NONE PROC NONE SIGNED DEFAULT DEFAULT BICUBIC BILINEAR NEAREST NEIGHBOR OVERSCAN CLEAR OVERSCAN DISABLE OVERSCAN ENABLE OVERSCAN FAST DEFAULT CORRECT LENS DISTORTION ONLY FULL CORRECTION DEFAULT EXTRACT LUT X EXTRACT LUT Y WARP IMAGE CLIP FIT USE DESTINATION CALIBRATION