| MIL 10 Reference
| Customize Help
| Save Settings

McalControl


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
McalAssociate
McalDraw
Synopsis
Control the calibration information of a calibration context or calibrated image.
Syntax
void McalControl(
MIL_ID CalibratedMilObjectId, //in
MIL_INT64 ControlType, //in
MIL_DOUBLE ControlValue //in
)
Description

This function changes a calibration setting of a calibration context or calibrated image.

If you control a calibration setting of a calibrated image with an M_VECTOR_AND_RASTER ROI, the raster information will be discarded, causing the ROI to become an M_VECTOR ROI. See MbufSetRegion() for more information.

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
CalibratedMilObjectId

Specifies the identifier of the calibration context or calibrated image.

ControlType

Specifies the setting to change.

See the Parameter associations section for possible values that can be specified.

ControlValue

Specifies the setting's new value.

See the Parameter associations section for possible values that can be specified.

Parameter associations

The tables below list possible values for the ControlType and ControlValue parameters.

The following ControlType and ControlValue parameter settings can be specified for a calibration context:

function map For a calibration context
CollapseControlType Description
ControlValue
Collapse M_CALIBRATION_PLANE

Sets the plane in which the calibration points are defined. INQ

(summarize)
Collapse M_DEFAULT

Same as M_ABSOLUTE_COORDINATE_SYSTEM.
Collapse M_ABSOLUTE_COORDINATE_SYSTEM

Specifies that the calibration points are defined in the absolute coordinate system.
Collapse M_RELATIVE_COORDINATE_SYSTEM

Specifies that the calibration points are defined in the relative coordinate system.
Collapse M_CCD_ASPECT_RATIO

Sets the width-to-height ratio of the individual elements of the CCD. If this value is not set and is required by the calibration mode, the ratio will default to 1.0. INQ

(summarize)
Collapse 1.0

Specifies that the width and height of the CCD element are equal.

This is the default value.

(summarize)
Collapse Value > 0

Specifies the value of the width of a CCD element divided by its height.
Collapse M_FOREGROUND_VALUE

Sets whether the circles in a circle grid, used with McalGrid(), are lighter or darker than the background. INQ

(summarize)
Collapse M_DEFAULT

Determines the appropriate setting automatically.
Collapse M_FOREGROUND_BLACK

Specifies that the grid's circles are darker than the background.
Collapse M_FOREGROUND_WHITE

Specifies that the grid's circles are lighter than the background.
Collapse M_GRID_CORNER_HINT_X

Specifies the approximate X-coordinate, in the pixel coordinate system, of the top-left corner of the calibration grid in the real world.

If the image of the calibration grid is rotated, such that the real-world top-left corner of the grid is not located in the top-left corner of the image, M_GRID_CORNER_HINT_X specifies where in the rotated image the real-world top-left corner is.

The corner grid point nearest to the specified coordinates (M_GRID_CORNER_HINT_X and M_GRID_CORNER_HINT_Y) will be used. Note that there can be at least 2 valid corners and at most 4 corners to the grid, depending on whether the grid is a rectangle or a square, respectively, so the approximate X-coordinate does not have to be very precise.

This control type is only used for calibrations performed using McalGrid(). INQ

(summarize)
Collapse M_DEFAULT

Same as M_NONE.
Collapse M_NONE

Specifies to use the top-left grid point in the image.
Collapse Value

Specifies the X-coordinate of the hint point, in the image.
Collapse M_GRID_CORNER_HINT_Y

Specifies the approximate Y-coordinate, in the pixel coordinate system, of the top-left corner of the calibration grid in the real world.

If the image of the calibration grid is rotated, such that the real-world top-left corner of the grid is not located in the top-left corner of the image, M_GRID_CORNER_HINT_Y specifies the Y-coordinate of the real-world top-left corner of the calibration grid in the pixel coordinate system.

The corner grid point nearest to the specified coordinates (M_GRID_CORNER_HINT_X and M_GRID_CORNER_HINT_Y) will be used. Note that there can be at least 2 valid corners and at most 4 corners to the grid, depending on whether the grid is a rectangle or a square, respectively, so the approximate X-coordinate does not have to be very precise.

This control type is only used for calibrations performed using McalGrid(). INQ

(summarize)
Collapse M_DEFAULT

Same as M_NONE.
Collapse M_NONE

Specifies to use the top-left grid point in the image.
Collapse Value

Specifies the Y-coordinate of the hint point, in the image.
Collapse M_LINK_TOOL_AND_CAMERA

Creates a rigid link between the camera coordinate system and the tool coordinate system.

By default, a rigid link exists between the tool and camera coordinate systems such that moving one automatically moves the other accordingly. However, this can be broken using M_LINK_TOOL_AND_CAMERA set to M_DISABLE. You can then set the tool coordinate system to a known location without affecting the camera coordinate system (and the pixel-to-world mapping). After moving the tool coordinate system, you can then re-establish the link so that you move the camera coordinate system by moving the tool coordinate system. INQ

(summarize)
Collapse M_DEFAULT

Same as M_ENABLE.
Collapse M_DISABLE

Specifies to remove the link between the two coordinate systems, allowing both to be moved independently.
Collapse M_ENABLE

Specifies to link the two coordinate systems, allowing both to be moved together.
Collapse M_LOCALIZATION_NB_ITERATIONS_MAX

Specifies the maximum number of iterations to attempt to fit the provided points when calculating the new position of the camera or relative coordinate system, when using McalList() and McalGrid() with M_DISPLACE_CAMERA_COORD or M_DISPLACE_RELATIVE_COORD respectively. If the specified number of iterations is large, the computation could take longer to run, but the algorithm will be more robust. If M_LOCALIZATION_NB_OUTLIERS_MAX is set to 0, only 1 iteration is required and no more will be performed. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 250.
Collapse Value >= 1

Specifies the number of expected outliers. Only integer values are accepted.

(summarize)
Collapse M_LOCALIZATION_NB_OUTLIERS_MAX

Specifies the maximum number of possible outliers that can occur in the data set used by McalList() or McalGrid() with M_DISPLACE_CAMERA_COORD or M_DISPLACE_RELATIVE_COORD. If the specified number of outliers is large, more iterations are required to determine which points provide the best solution; therefore, computation can take longer, but the function will be more robust to outliers. Also, the function could fail if the value of M_LOCALIZATION_NB_ITERATIONS_MAX is too low. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.
Collapse Value >= 0

Specifies the number of expected outliers. Only integer values are accepted.

(summarize)
Collapse M_PRINCIPAL_POINT_X

Sets the X-coordinate of the intersection of the camera's optical axis and the image plane. If this value is not set and is required by the specified calibration mode, it will default to half of the image's width. INQ

(summarize)
Collapse Value

Specifies the X-coordinate, in pixels.
Collapse M_PRINCIPAL_POINT_Y

Sets the Y-coordinate of the intersection of the camera's optical axis and the image plane. If this value is not set and is required by the specified calibration mode, it will default to half of the image's height. INQ

(summarize)
Collapse Value

Specifies the Y-coordinate, in pixels.
Collapse M_TOOL_POSITION_X

Sets the X-position of the tool coordinate system in the absolute coordinate system. The X-position is initialized to 0.0. INQ

(summarize)
Collapse Value

Specifies the X-coordinate, in world units.
Collapse M_TOOL_POSITION_Y

Sets the Y-position of the tool coordinate system in the absolute coordinate system. The Y-position is initialized to 0.0. INQ

(summarize)
Collapse Value

Specifies the Y-coordinate, in world units.
Collapse M_TOOL_POSITION_Z

Sets the Z-position of the tool coordinate system in the absolute coordinate system. The Z-position is initialized to 0.0.

When using the linear interpolation or perspective transformation calibration mode, M_TOOL_POSITION_Z must be set to M_DEFAULT.

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the Z-coordinate, in world units.
Collapse M_TRANSFORM_CACHE

Sets whether to use a cache to accelerate the McalTransformImage() function. INQ

(summarize)
Collapse M_DISABLE

Specifies not to use a cache. Not using a cache saves memory but slows down subsequent calls to McalTransformImage().

(summarize)
Collapse M_ENABLE

Specifies to use a cache.

This is the default value.

(summarize)

The following ControlType and ControlValue parameter settings can be specified for a calibrated image:

function map For a calibrated image
CollapseControlType Description
ControlValue
Collapse M_CALIBRATION_CHILD_OFFSET_X

Sets the X-offset of a child buffer, relative to its highest order calibrated parent buffer. INQ

(summarize)
Collapse Value

Specifies the X-offset, relative to the child buffer's highest order calibrated parent buffer.
Collapse M_CALIBRATION_CHILD_OFFSET_Y

Sets the Y-offset of a child buffer, relative to its highest order calibrated parent buffer. INQ

(summarize)
Collapse Value

Specifies the Y-offset, relative to the child buffer's highest order calibrated parent buffer.

The following ControlType and ControlValue parameter settings can be specified for a calibrated image:

function map For a calibrated and corrected image
CollapseControlType Description
ControlValue
Collapse M_GRAY_LEVEL_SIZE_Z

Sets the difference in height corresponding to a difference of one gray level in a fully-corrected depth map. INQ

(summarize)
Collapse M_INVALID_SCALE

Specifies that the image is not a depth map.

This is the default value.

(summarize)
Collapse Value

Specifies the height, in world units, corresponding to a difference of one gray level. Cannot be set to 0.0.

(summarize)
Collapse M_WORLD_POS_Z

Sets the real-world Z-offset of a gray level of 0 in the corrected image, useful in depth maps. INQ

(summarize)
Collapse Value

Specifies the base height of a gray level of 0.

The default value is 0.0.

(summarize)
Type-specific versions of the function
void McalControlInt64 (MIL_ID CalibratedMilObjectId, MIL_INT64 ControlType, MIL_INT64 ControlValue)
Details
Parameters

CalibratedMilObjectId

See CalibratedMilObjectId of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.
Compilation information
Header Include mil.h.
Library Use mil.lib; milcal.lib.
DLL Requires mil.dll; milcal.dll.
NULL PROC CALIBRATION PLANE DEFAULT ABSOLUTE COORDINATE SYSTEM RELATIVE COORDINATE SYSTEM CCD ASPECT RATIO FOREGROUND VALUE DEFAULT FOREGROUND BLACK FOREGROUND WHITE GRID CORNER HINT X DEFAULT NONE GRID CORNER HINT Y DEFAULT NONE LINK TOOL AND CAMERA DEFAULT DISABLE ENABLE LOCALIZATION NB ITERATIONS MAX DEFAULT LOCALIZATION NB OUTLIERS MAX DEFAULT PRINCIPAL POINT X PRINCIPAL POINT Y TOOL POSITION X TOOL POSITION Y TOOL POSITION Z DEFAULT TRANSFORM CACHE DISABLE ENABLE CALIBRATION CHILD OFFSET X CALIBRATION CHILD OFFSET Y GRAY LEVEL SIZE Z INVALID SCALE WORLD POS Z NULL NULL TRUE