| MIL 10 Reference
| Customize Help
| Save Settings

MbufControlNeighborhood


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

Available on Windows
Available on Linux

Partially supported on:
Partially supported on Matrox GPU processing driver
Partially supported on Matrox Solios eA/XA
Partially supported on Matrox Solios ecl/xcl/ev-cl

Fully supported on:
Fully supported on Host system
Fully supported on Matrox CronosPlus
Fully supported on Matrox GigE Vision driver
Fully supported on Matrox IEEE 1394 IIDC driver
Fully supported on Matrox Iris GT
Fully supported on Matrox Morphis
Fully supported on Matrox Morphis QxT
Fully supported on Matrox Orion HD
Fully supported on Matrox Radient eCL
Fully supported on Matrox Radient eV-CXP
Fully supported on Matrox USB3 Vision driver (requires Update 19)
Fully supported on Matrox Vio

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
Available on Matrox Supersight
function map Function map
Examples
MbufControlArea
MbufCopy
Synopsis
Change an operation control type setting of a kernel buffer or structuring element buffer.
Syntax
void MbufControlNeighborhood(
MIL_ID BufId, //in
MIL_INT64 OperationControlType, //in
MIL_INT OperationValue //in
)
Description

This function changes the setting of an operation control type of the specified kernel buffer or structuring element buffer. The operation control type settings establish how to perform a neighborhood operation when using the specified kernel buffer or structuring element buffer.

Neighborhood operations that do not use a kernel buffer or structuring element buffer typically use the default values; the default normalization factor is the exception. For predefined filters, the normalization factor is automatically set to use the full data range of the destination buffer without overflows, and the result is given in the number of bits of the destination buffer. To specify a different normalization factor, define a custom filter and set the required normalization factor, using the M_NORMALIZATION_FACTOR operation control type.

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
BufId

Specifies the identifier of the kernel buffer or structuring element buffer. You must have already allocated this buffer, using MbufAlloc1d() or MbufAlloc2d().

OperationControlType

Specifies the operation to perform during a neighborhood operation when using the specified buffer.

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

OperationValue

Specifies the new value to assign to the operation setting specified by the OperationControlType parameter.

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

Parameter associations

The tables below list possible values for the OperationControlType and OperationValue parameters.

The following OperationControlType and corresponding OperationValue parameter settings are used to control general operation settings.

function map For controlling general operation settings
CollapseOperationControlType Description
MIL system-specific
tooltip (†)
OperationValue
Collapse M_DEFAULT

Sets all operation control types to their default operation value.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_NULL

Implements the default behavior.

This is the default value.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_ABSOLUTE_VALUE

Sets whether to take the absolute value of the results. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Same as M_DISABLE.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_DISABLE

Specifies not to take the absolute value of the result.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_ENABLE

Specifies to take the absolute value of the result.

Note that for a structuring element buffer, you cannot take the absolute value of a result.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_OFFSET_CENTER_X

Sets the X-coordinate of the center pixel of the kernel or structuring element.

M_OFFSET_CENTER_X is ignored if M_FILTER_MODE is set to M_RECURSIVE. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Specifies the X-coordinate of the top-left pixel of the central elements.

 † a b c d e f g h i j k l m n o p q r s
Collapse 0 <= Value < SizeX

Specifies the value of the X-coordinate.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_OFFSET_CENTER_Y

Sets the Y-coordinate of the center of the kernel or structuring element.

M_OFFSET_CENTER_Y is ignored if M_FILTER_MODE is set to M_RECURSIVE. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Specifies the Y-coordinate of the top-left pixel of the central elements.

 † a b c d e f g h i j k l m n o p q r s
Collapse 0 <= Value < SizeY

Specifies the value of the Y-coordinate.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_OVERSCAN

Sets the type of overscan used to handle the border pixels of a source image.

M_OVERSCAN is ignored if M_FILTER_MODE is set to M_RECURSIVE. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Specifies that MIL automatically selects the type of overscan to optimize speed and logic according to the specified operation and the target system.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_DISABLE

Specifies that no overscan will be used, unless processing the border pixels is faster than ignoring them; in the latter case, MIL automatically selects the overscan to optimize speed according to the specified operation and the target system.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_FAST

Specifies that MIL automatically selects the overscan to optimize 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_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)
† a b c d e f g h i j k l m n o p q r s
Collapse M_MIRROR

Specifies a type of overscan that processes the border pixels of a source image using overscan pixel values that mirror the source buffer pixel values. That is, the overscan pixel values will be a mirror copy of the source buffer's borders. For example:

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_REPLACE

Specifies a type of overscan that processes the border pixels of a source image using overscan pixel values set to the overscan replacement value (M_OVERSCAN_REPLACE_VALUE).

 † a b c d e f g h i j k l m n o p q r s
Collapse M_TRANSPARENT

Specifies a type of overscan that processes the border pixels of a source image using transparent overscan pixel values. That is, the overscan pixel values will be those of the ancestor buffer. If they are not available, a mirror type overscan is used instead.

(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific

Points falling outside the source image are undefined.

 † d l m
Collapse M_OVERSCAN_REPLACE_VALUE

Sets a replacement value for the overscan pixel values.

Note that to use this control type, M_OVERSCAN must be set to M_REPLACE. In addition, M_OVERSCAN_REPLACE_VALUE is ignored if M_FILTER_MODE is set to M_RECURSIVE. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Specifies the default value; the default value is 0.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_REPLACE_MAX

Specifies that the overscan neighborhood pixel values will be set to the maximum value of the source buffer.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_REPLACE_MIN

Specifies that the overscan neighborhood pixel values will be set to the minimum value of the source buffer.

 † a b c d e f g h i j k l m n o p q r s
Collapse Value

Specifies the value of the overscan neighborhood pixels.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_SATURATION

Sets whether to saturate the results. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Same as M_DISABLE.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_DISABLE

Specifies not to saturate results, except when MIL can take advantage of optimization routines to accelerate the processing. In the latter case, results will be saturated and processing will be done in hardware.

When it is not possible to run hardware processing optimization routines, results that overflow the buffer are undefined.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_ENABLE

Specifies to saturate results. A result that overflows or underflows will be set to the maximum or minimum value (respectively) that can be represented in the destination buffer.

If the saturation, normalization, and absolute value settings are specified for a kernel buffer, the saturation is performed after the normalization factor and the absolute value operations have been applied.

(summarize)
† a b c d e f g h i j k l m n o p q r s

For M_KERNEL data buffers only, you can set this parameter to one of the following values.

function map For the operation settings of M_KERNEL data buffers
CollapseOperationControlType Description
OperationValue
Collapse M_FILTER_MODE

Sets the mode in which to apply the filter. Use M_FILTER_TYPE to set the type of the filter. INQ

(summarize)
Collapse M_DEFAULT

Same as M_KERNEL.
Collapse M_KERNEL

Specifies the use of a non-recursive implementation of the filter. In this mode, a kernel is used to perform the neighborhood operation. The kernel size is specified when allocating the kernel buffer using MbufAlloc1d() or MbufAlloc2d(), although the kernel size can be constrained by the available hardware resources. When using an IIR filter in this mode, the filtering is done using a kernel approximation (FIR) of the recursive filter.

When using an IIR filter, this mode is not as efficient as M_RECURSIVE for large kernels.

(summarize)
Collapse M_RECURSIVE

Specifies the use of a recursive implementation of an Infinite Impulse Response (IIR) filter, when applicable. If this mode actually used a kernel, the kernel size would be theoretically infinite.

M_RECURSIVE is not supported if M_FILTER_TYPE is set to M_USER_DEFINED.

(summarize)
Collapse M_FILTER_OPERATION

Sets the type of neighborhood operation to perform using the selected filter.

M_FILTER_OPERATION is ignored if M_FILTER_TYPE is set to M_USER_DEFINED. INQ

(summarize)
Collapse M_DEFAULT

Same as M_SMOOTH.
Collapse M_EDGE_DETECT

Computes the gradient of the image using the Shen-Castan or Canny-Deriche filter.
Collapse M_EDGE_DETECT_SQR

Computes the square of the gradient of the image using the Shen-Castan or Canny-Deriche filter.
Collapse M_FIRST_DERIVATIVE_X

Computes the first derivative of the image with respect to X using the Shen-Castan or Canny-Deriche filter.
Collapse M_FIRST_DERIVATIVE_Y

Computes the first derivative of the image with respect to Y using the Shen-Castan or Canny-Deriche filter.
Collapse M_HORIZ_EDGE

Computes the absolute value of the horizontal derivative of the image using the Shen-Castan or Canny-Deriche filter.
Collapse M_LAPLACIAN_EDGE

Computes the Laplacian values of the image using the Shen-Castan or Canny-Deriche filter.
Collapse M_SECOND_DERIVATIVE_X

Computes the second derivative of the image with respect to X using the Shen-Castan or Canny-Deriche filter.
Collapse M_SECOND_DERIVATIVE_XY

Computes the second derivative of the image with respect to X and Y using the Shen-Castan or Canny-Deriche filter.
Collapse M_SECOND_DERIVATIVE_Y

Computes the second derivative of the image with respect to Y using the Shen-Castan or Canny-Deriche filter.
Collapse M_SHARPEN

Performs a sharpening operation on the image using the Shen-Castan or Canny-Deriche filter.
Collapse M_SMOOTH

Performs a smoothing operation on the image using the Shen-Castan or Canny-Deriche filter.
Collapse M_VERT_EDGE

Computes the absolute value of the vertical derivative of the image using the Shen-Castan or Canny-Deriche filter.
Collapse M_FILTER_SMOOTHNESS

Sets the degree of smoothness (strength of denoising) applied by the filter during the neighborhood operation.

M_FILTER_SMOOTHNESS is ignored if M_FILTER_TYPE is set to M_USER_DEFINED. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 50.0.
Collapse 0 <= Value <= 100

Specifies the smoothness value.

A value of 100 results in a strong noise reduction effect, while a value of 0 has almost no noise reduction effect.

(summarize)
Collapse M_FILTER_TYPE

Sets the type of filter used to perform the neighborhood operation. The type of filter determines the distribution of the neighborhoods' influence.

For IIR filter types, the content of the kernel buffer is ignored even if M_FILTER_MODE is set to M_KERNEL. M_FILTER_OPERATION and M_FILTER_SMOOTHNESS determine the filter values. INQ

(summarize)
Collapse M_DEFAULT

Same as M_USER_DEFINED.
Collapse M_DERICHE

Specifies a Canny-Deriche Infinite Support filter. This is an exponential weighting function, of the general form:

This is an IIR filter.

For the Canny-Deriche filter, the neighborhoods' influence decreases much slower as the distance from the central pixel increases, compared to the Shen-Castan filter (see M_SHEN control value).

Use M_FILTER_MODE, M_FILTER_OPERATION, and M_FILTER_SMOOTHNESS to set the mode of the filter, the type of operation to perform using the filter, and the degree of smoothness (strength of denoising) applied to the images by the filter, respectively.

(summarize)
Collapse M_SHEN

Specifies a Shen-Castan Infinite Support Exponential filter. This is an exponential weighting function, of the general form:

This is an IIR filter.

For the Shen-Castan filter, the neighborhoods' influence decreases much faster as the distance from the central pixel increases, compared to the Canny-Deriche filter (see M_DERICHE control value).

Use M_FILTER_MODE, M_FILTER_OPERATION, and M_FILTER_SMOOTHNESS to set the mode of the filter, the type of operation to perform using the filter, and the degree of smoothness (strength of denoising) applied to the images by the filter, respectively.

(summarize)
Collapse M_USER_DEFINED

Specifies a user-defined filter. This is an FIR filter.

M_USER_DEFINED is not supported if M_FILTER_MODE is set to M_RECURSIVE.

(summarize)
Collapse M_NORMALIZATION_FACTOR

Sets the normalization factor to apply to the result.

Note that for a structuring element buffer, you cannot specify a normalization factor. INQ

(summarize)
Collapse M_DEFAULT

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

Specifies the normalization factor.

If the factor produces an overflow in the destination, saturation might occur, depending on the M_SATURATION control type.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT NULL ABSOLUTE VALUE DEFAULT DISABLE ENABLE OFFSET CENTER X DEFAULT OFFSET CENTER Y DEFAULT OVERSCAN DEFAULT DISABLE FAST MIRROR REPLACE TRANSPARENT OVERSCAN REPLACE VALUE DEFAULT REPLACE MAX REPLACE MIN SATURATION DEFAULT DISABLE ENABLE FILTER MODE DEFAULT KERNEL RECURSIVE FILTER OPERATION DEFAULT EDGE DETECT EDGE DETECT SQR FIRST DERIVATIVE X FIRST DERIVATIVE Y HORIZ EDGE LAPLACIAN EDGE SECOND DERIVATIVE X SECOND DERIVATIVE XY SECOND DERIVATIVE Y SHARPEN SMOOTH VERT EDGE FILTER SMOOTHNESS DEFAULT FILTER TYPE DEFAULT DERICHE SHEN USER DEFINED NORMALIZATION FACTOR DEFAULT