| MIL 10 Reference
| Customize Help
| Save Settings

MregControl


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
MregCalculate
MregDraw
Synopsis
Control a registration context, registration element, or registration result buffer setting.
Syntax
void MregControl(
MIL_ID ContextOrResultId, //in
MIL_INT Index, //in
MIL_INT64 ControlType, //in
MIL_DOUBLE ControlValue //in
)
Description

This function allows you to control a setting of a registration context itself, one (or all) of the registration elements contained therein (correlation-stitching registration context only), or a correlation-stitching registration result buffer. For registration contexts and registration elements, these settings control the execution of MregSetLocation() and MregCalculate() operations. For correlation-stitching registration result buffers, these settings control the execution of MregDraw() and MregTransformImage() operations.

All the control type settings can be inquired using MregInquire().

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
ContextOrResultId

Specifies the identifier of the registration context or correlation-stitching registration result buffer whose settings to modify; you cannot control settings of an extended depth of field (EDoF) result buffer. The registration context or the registration result buffer must have been previously allocated on the system using MregAlloc() or MregAllocResult(), respectively.

Index

Specifies that a registration context, an individual registration element (of a correlation-stitching registration context), or a registration result buffer is controlled. Set this parameter to one of the following values:

function map For the registration context, registration element, or registration result buffer
CollapseValue Description
Collapse M_DEFAULT

Specifies the default value.

If an M_STITCHING registration context is specified, same as M_ALL.

If an M_EXTENDED_DEPTH_OF_FIELD registration context is specified, same as M_CONTEXT.

If a registration result buffer is specified, same as M_GENERAL.

(summarize)
Collapse M_ALL

Applies the specified control setting to all registration elements, if a correlation-stitching registration context is specified. Note that this setting is not available for an M_EXTENDED_DEPTH_OF_FIELD registration context.

(summarize)
Collapse M_CONTEXT

Controls a general setting of a registration context, if one is specified.
Collapse M_GENERAL

Controls a general setting of a correlation-stitching registration result buffer, if one is specified.
Collapse Value

Specifies the index of the individual registration element to control, if a correlation-stitching registration context is specified. Note that this setting is not available for an M_EXTENDED_DEPTH_OF_FIELD registration context.

(summarize)
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 corresponding ControlValue parameter settings are used to control M_STITCHING registration context settings; in this case, the Index parameter must have been set to M_CONTEXT.

function map For operation settings of M_STITCHING registration contexts
CollapseControlType Description
ControlValue
Collapse M_ACCURACY

Sets the accuracy of the registration calculation. Accuracy depends on the image's dynamic range, sharpness, and noise. The best accuracy is achieved for well-contrasted noise-free images. INQ

(summarize)
Collapse M_DEFAULT

Same as M_HIGH.
Collapse M_HIGH

Specifies high accuracy. Registration will be calculated with subpixel accuracy.

(summarize)
Collapse M_LOW

Specifies low accuracy. Registration will be calculated with pixel accuracy.

(summarize)
Collapse M_LOCATION_DELTA

Sets the maximum displacement that will be applied to any pixel in the images during registration, relative to its initial location set using MregSetLocation(). With a larger maximum displacement, you can align the images even if the location that was set using MregSetLocation() was not precise. However, this can lead to a longer calculation time. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 5%.
Collapse 0 < Value <= 100.0

Specifies the maximum displacement as a percentage. The displacement is expressed an a percentage of the biggest dimension of the images to align.

(summarize)
Collapse M_MIN_OVERLAP

Sets the minimum overlap that should exist between an image and its reference image so that the registration calculation can optimize the match in their overlapping region. If the minimum overlap is not met, the optimization step will not be performed for this image. Instead, the transformation that was set using MregSetLocation() becomes the optimal transformation.

The image's registration result element will indicate that the registration operation failed for this image. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 20.0%.
Collapse 0 < Value <= 100.0

Specifies the minimum overlap as a percentage. The overlap is expressed as a percentage of the smallest of the two images.

(summarize)
Collapse M_NUMBER_OF_ELEMENTS

Sets the number of registration elements in the registration context. If you reduce the number of registration elements, the settings of the ones that remain are kept unchanged. If you increase the number of registration elements, the new ones are initialized with the default settings.

You should have at least as many registration elements as the number of images that you want to register. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 256.
Collapse 1 <= Value < 8192

Specifies the number of registration elements.
Collapse M_SCORE_TYPE

Sets the type of score calculated during registration. This calculated score can be retrieved after registration using MregGetResult() with M_SCORE. INQ

(summarize)
Collapse M_CORRELATION

Specifies to calculate the score based on the normalized grayscale correlation in the overlapped region.
Collapse M_NONE

Specifies that no score is calculated; it is set to 100%.

This is the default value.

(summarize)
Collapse M_TRANSFORMATION_TYPE

Sets the type of transformation that the registration calculation will use to optimize the match in the images' overlapping regions. INQ

(summarize)
Collapse M_DEFAULT

Same as M_TRANSLATION.
Collapse M_PERSPECTIVE

Specifies that a perspective warping can be performed to optimize the match in the overlapping regions.
Collapse M_TRANSLATION

Specifies that a translation can be performed to optimize the match in the overlapping regions.
Collapse M_TRANSLATION_ROTATION

Specifies that a translation and a rotation can be performed to optimize the match in the overlapping regions.
Collapse M_TRANSLATION_ROTATION_SCALE

Specifies that a translation, a rotation, and a scale operation can be performed to optimize the match in the overlapping regions.

The following ControlType and corresponding ControlValue parameter settings are used to control settings of registration elements (one or all) of a M_STITCHING registration context.

function map For registration elements (one or all) of an M_STITCHING registration context
CollapseControlType Description
ControlValue
Collapse M_OPTIMIZE_LOCATION

Sets whether to perform the optimization step of the registration calculation for the registration element's image. If you choose not to perform the optimization calculation, the transformation that you set with MregSetLocation() becomes the optimal transformation for this image. When MregCalculate() is called, the transformation is converted so that it maps the image into the global pixel coordinate system instead of into its reference image's pixel coordinate system. INQ

(summarize)
Collapse M_DEFAULT

Same as M_ENABLE.
Collapse M_DISABLE

Specifies not to perform the optimization calculation.
Collapse M_ENABLE

Specifies to perform the optimization calculation.
Collapse M_REFERENCE_X

Sets the X-coordinate of the origin of the image's pixel coordinate system.

This is an advanced control type and changing the origin of an image's pixel coordinate system will affect various aspects of the registration process. This origin is used when specifying the approximate location of the image in its registration element's image (MregSetLocation()); you must specify the location of the origin with respect to the origin of the reference element's image. Similarly, if you use the image to position other images, specify locations relative to this origin. The position of your mosaic in the destination image buffer depends on the mosaic's reference coordinate system (MregControl() with M_MOSAIC_STATIC_INDEX), which can be the coordinate system of a particular image. Finally, you can convert coordinates to and from an image's pixel coordinate system, with MregTransformCoordinate() and MregTransformCoordinateList(). If you modify the origin of an image's pixel coordinate system, you must keep the origin's new location in mind when performing any of these operations. INQ

(summarize)
Collapse M_DEFAULT

Specifies that the default X-coordinate of the origin will be used.

The default value is 0.0.

(summarize)
Collapse M_CENTER_ELEMENT

Specifies the X-coordinate of the origin to be at the center of the image.
Collapse Value

Specifies the X-coordinate of the origin, in pixels. The value can be specified with subpixel accuracy.

(summarize)
Collapse M_REFERENCE_Y

Sets the Y-coordinate of the origin of the image's pixel coordinate system.

This is an advanced control type and changing the origin of an image's pixel coordinate system will affect various aspects of the registration process. This origin is used when specifying the approximate location of the image in its registration element's image (MregSetLocation()); you must specify the location of the origin with respect to the origin of the reference element's image. Similarly, if you use this image to position other images, specify locations relative to this origin. The position of your mosaic in the destination image buffer depends on the mosaic's reference coordinate system (MregControl() with M_MOSAIC_STATIC_INDEX), which can be the coordinate system of a particular image. Finally, you can convert coordinates to and from an image's pixel coordinate system, with MregTransformCoordinate() and MregTransformCoordinateList(). If you modify the origin of an image's pixel coordinate system, you must keep the origin's new location in mind when performing any of these operations. INQ

(summarize)
Collapse M_DEFAULT

Specifies that the default Y-coordinate of the origin will be used.

The default value is 0.0.

(summarize)
Collapse M_CENTER_ELEMENT

Specifies the Y-coordinate of the origin to be at the center of the image.
Collapse Value

Specifies the Y-coordinate of the origin, in pixels. The value can be specified with subpixel accuracy.

(summarize)

The following ControlType and corresponding ControlValue parameter settings are used to control the settings of a M_STITCHING_RESULT result buffer; in this case, the Index parameter must be set to M_GENERAL.

function map For M_STITCHING_RESULT result buffers
CollapseControlType Description
ControlValue
Collapse M_MOSAIC_COMPOSITION

Sets which image's pixel values to use when composing the mosaic and two or more images overlap. INQ

(summarize)
Collapse M_DEFAULT

Same as M_LAST_IMAGE.
Collapse M_AVERAGE_IMAGE

Specifies to use the average value of the images' pixels in the overlapping region.
Collapse M_FIRST_IMAGE

Specifies to use the pixels of the image associated with the registration result element with the lowest index.
Collapse M_FUSION_IMAGE

Specifies to fuse the images by progressively blending overlapping pixels. That is, overlapping pixel values are modified (blended) to form a transitional portion. Blending is based on the distance between each pixel and the edges of the images in the mosaic.

(summarize)
Collapse M_LAST_IMAGE

Specifies to use the pixels of the image associated with the registration result element with the highest index.
Collapse M_SUPER_RESOLUTION

Specifies to use a super-resolution algorithm to create the mosaic.

For best results, the image alignment should be accurate. To perform registration calculations with subpixel accuracy, call MregControl() with M_ACCURACY set to M_HIGH. The source images should be of good quality with clear, distinct features in the overlapping region.

To customize the super-resolution process, set the point-spread function, its radius, and the degree of smoothness to use, with M_SR_PSF_TYPE, M_SR_PSF_RADIUS, and M_SR_SMOOTHNESS respectively.

(summarize)
Collapse M_MOSAIC_OFFSET_X

Sets the X-offset between the origin of the coordinate system used to compose the mosaic and the left side of the destination image buffer. The coordinate system used to compose the mosaic is the one specified with M_MOSAIC_STATIC_INDEX. INQ

(summarize)
Collapse M_DEFAULT

Same as M_ALIGN_LEFT.
Collapse M_ALIGN_LEFT

Specifies that the X-offset (in pixels) will be calculated such that the left-most part of the mosaic will be aligned with the left side of the destination image buffer.
Collapse Value

Specifies the X-offset, in pixels.
Collapse M_MOSAIC_OFFSET_Y

Sets the Y-offset between the origin of the coordinate system used to compose the mosaic and the top of the destination image buffer. The coordinate system used to compose the mosaic is the one specified with M_MOSAIC_STATIC_INDEX. INQ

(summarize)
Collapse M_DEFAULT

Same as M_ALIGN_TOP.
Collapse M_ALIGN_TOP

Specifies that the Y-offset (in pixels) will be calculated such that the top-most part of the mosaic will be aligned with the top of the destination image buffer.
Collapse Value

Specifies the Y-offset, in pixels.
Collapse M_MOSAIC_SCALE

Sets the scale factor to apply to the images before composition of the mosaic. A value greater than 1.0 produces an enlarged mosaic, while a value less than 1.0 produces a reduced one. INQ

(summarize)
Collapse 0.0 < Value <= 10.0

Specifies the scale factor.

The default value is 1.0.

(summarize)
Collapse M_MOSAIC_STATIC_INDEX

Sets the coordinate system relative to which the mosaic will be composed. This can be a registered image's pixel coordinate system or the global pixel coordinate system. If you select an image's pixel coordinate system, that image will appear upright in the mosaic, and the other images will be oriented relative to it.

By default, the origin of the mosaic will appear at the top-left corner of the destination image buffer. You can adjust the horizontal and vertical offset of the origin using M_MOSAIC_OFFSET_X and M_MOSAIC_OFFSET_Y. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value. By default, the mosaic will be composed with respect to the pixel coordinate system of the image associated with registration result element 0.

(summarize)
Collapse M_ALL

Specifies that the coordinate system will be chosen such that the minimum change is done on all images during the mosaic composition. This setting is only available when composing a mosaic with only two images.

(summarize)
Collapse M_REGISTRATION_GLOBAL

Specifies that the mosaic will be composed with respect to the global pixel coordinate system.
Collapse 0 <= Value <= NumberOfElements-1

Specifies the index of the registration result element whose image's pixel coordinate system will be used as the reference coordinate system.
Collapse M_SR_PSF_RADIUS

Sets the radius of the M_CIRCULAR and M_GAUSSIAN point-spread functions (PSF). For M_GAUSSIAN, the radius corresponds to the standard deviation. For M_SQUARE, the radius corresponds to half the size of the square side.

This control type is only taken into account when M_MOSAIC_COMPOSITION is set to M_SUPER_RESOLUTION and M_SR_PSF_TYPE is not set to M_DISABLE. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.5 pixels.
Collapse Value >= 0.0

Specifies the radius of the PSF, in pixel units at the scale of the source images.
Collapse M_SR_PSF_TYPE

Sets the type of point-spread function (PSF) to use during super-resolution calculations to model the blurring in source images.

The point-spread function describes how a small point of light in the world is blurred by the acquisition setup (lens and CCD). Use M_SR_PSF_RADIUS to set the radius of the PSF.

The value of this control type is only taken into account when M_MOSAIC_COMPOSITION is set to M_SUPER_RESOLUTION. INQ

(summarize)
Collapse M_DEFAULT

Same as M_GAUSSIAN.
Collapse M_CIRCULAR

Specifies to assume a PSF that models blurring of single points of light into uniform circles in the image.
Collapse M_DISABLE

Specifies that no PSF should be assumed during super-resolution calculations.
Collapse M_GAUSSIAN

Specifies to assume a PSF that models blurring of single points of light into radially symmetric gaussian functions in the image.
Collapse M_SQUARE

Specifies to assume a PSF that models blurring of single points of light into symmetric square functions in the image.
Collapse M_SR_SMOOTHNESS

Sets the smoothness value to use during super-resolution calculations.

Use a high smoothness value to reduce local variations in the mosaic image. This is useful to prevent artifacts caused by noise in the source images.

Use a low smoothness value when there is little noise in the source image. This is useful to preserve the most detail in your mosaic.

This control type is only taken into account when M_MOSAIC_COMPOSITION is set to M_SUPER_RESOLUTION. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 50.0.
Collapse 0.0 <= Value <= 100.0

Specifies the smoothness value.

The following ControlType and corresponding ControlValue parameter settings are used to control M_EXTENDED_DEPTH_OF_FIELD registration context settings; in this case, the Index parameter must be set to M_CONTEXT.

function map For operation settings of M_EXTENDED_DEPTH_OF_FIELD registration contexts
CollapseControlType Description
ControlValue
Collapse M_CIRCLE_OF_CONFUSION_RADIUS_MAX

Sets the maximum radius of the circle of confusion (blurring circle), among the input images. If this control type is set incorrectly, the EDoF image might not be completely in focus, even if it should be possible given the input images. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 8 pixels.
Collapse 1 <= Value <= 256

Specifies the maximum radius of the circle of confusion (blurring circle) in pixels.
Collapse M_MODE

Sets the computation mode of the extended depth of field operation. INQ

(summarize)
Collapse M_DEFAULT

Same as M_RECONSTRUCTION.
Collapse M_FAST

Specifies a faster computation mode. Note that using a faster computation mode can decrease robustness of the registration operation.

(summarize)
Collapse M_RECONSTRUCTION

Specifies a computation mode that favors the quality of the extended depth of field (EDoF) image. This setting can lead to longer computation times.

(summarize)
Collapse M_TRANSLATION_TOLERANCE

Sets the maximum distance between a point of an object that is in focus in one image, and the same point in an image in which the object is out of focus, in pixels. If this control type is set incorrectly, the EDoF image might not be completely in focus, even if it should be possible given the input images. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 1 pixel.
Collapse 1 <= Value <= 4

Specifies the maximum translation distance of a point between two images, in pixels.
Type-specific versions of the function
void MregControlInt64 (MIL_ID ContextOrResultId, MIL_INT Index, MIL_INT64 ControlType, MIL_INT64 ControlValue)
Details
Parameters

ContextOrResultId

See ContextOrResultId of the main function for a description.

Index

See Index 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; milreg.lib.
DLL Requires mil.dll; milreg.dll.
DEFAULT ALL CONTEXT GENERAL ACCURACY DEFAULT HIGH LOW LOCATION DELTA DEFAULT MIN OVERLAP DEFAULT NUMBER OF ELEMENTS DEFAULT SCORE TYPE CORRELATION NONE TRANSFORMATION TYPE DEFAULT PERSPECTIVE TRANSLATION TRANSLATION ROTATION TRANSLATION ROTATION SCALE OPTIMIZE LOCATION DEFAULT DISABLE ENABLE REFERENCE X DEFAULT CENTER ELEMENT REFERENCE Y DEFAULT CENTER ELEMENT MOSAIC COMPOSITION DEFAULT AVERAGE IMAGE FIRST IMAGE FUSION IMAGE LAST IMAGE SUPER RESOLUTION MOSAIC OFFSET X DEFAULT ALIGN LEFT MOSAIC OFFSET Y DEFAULT ALIGN TOP MOSAIC SCALE MOSAIC STATIC INDEX DEFAULT ALL REGISTRATION GLOBAL SR PSF RADIUS DEFAULT SR PSF TYPE DEFAULT CIRCULAR DISABLE GAUSSIAN SQUARE SR SMOOTHNESS DEFAULT CIRCLE OF CONFUSION RADIUS MAX DEFAULT MODE DEFAULT FAST RECONSTRUCTION TRANSLATION TOLERANCE DEFAULT CONTEXT GENERAL DEFAULT GENERAL CONTEXT