MedgeCalculate

MIL_ID ContextId,	//in
MIL_ID SourceImageId,	//in
MIL_ID SourceDeriv1Id,	//in
MIL_ID SourceDeriv2Id,	//in
MIL_ID SourceDeriv3Id,	//in
MIL_ID EdgeResultId,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function extracts edges and calculates edge features in the source image buffer or in the derivative image buffers. You can also use this function to perform post-calculations on included edges of an Edge Finder result buffer.

Results are stored in the specified Edge Finder result buffer. Select which edge features to calculate with MedgeControl(). Include, exclude, or delete edges that meet a specified criterion with MedgeSelect(). Note that to calculate new features and/or select features of a new set of edges, MedgeCalculate() must be called after MedgeControl() and/or MedgeSelect().

If the source image or derivative images are calibrated, results are calculated in the world coordinate system, otherwise they are calculated in the pixel coordinate system.

If the source image or derivative images are calibrated, you can retrieve results in real-world or in pixel units. However, in the presence of distortion, some results are meaningless when converted from real-world to pixel units (for example, Feret angles). For example, if an edge appears warped in the source image, but the calibration context of the source image compensates for this during the extraction, the resulting Feret angles are meaningful in the real-world coordinate system, and meaningless in the pixel coordinate system.

Calculations are typically done on a source image buffer (SourceImageId), where MedgeCalculate() calculates the required derivative image buffers that are used to extract edges. In this case, the derivative image buffers (SourceDeriv1Id, SourceDeriv2Id, and SourceDeriv3Id) must be set to M_NULL. However, if you specify your own derivative image buffers, the edge extraction process is done with them instead. In this case, SourceImageId must be set to M_NULL. Note that, when specifying your own derivative image buffers, the majority of processing control settings remain in effect, except for filter settings (for example, M_FILTER_SMOOTHNESS).

When calculated by Edge Finder, derivative buffers are always consistent (for example, they have the same scaling factor) and are always normalized to 10-bit images such that the maximum output value is 1024 for 8-bit source images. When you provide the derivative buffers, they should respect these limitations for best performance.

To avoid repeatedly calculating time-consuming edge features for all edges in a source image, MedgeCalculate() can also perform post-calculations on included edges of an Edge Finder result buffer. That is, once the results of a calculation have been stored in an Edge Finder result buffer, you can select a subset of edges from that Edge Finder result buffer (with MedgeSelect()) and/or add new features for calculation to that Edge Finder result buffer (with MedgeControl()), and then perform the post-calculation with MedgeCalculate(). In this case, processing time greatly decreases since calculations are not unnecessarily repeated. The operation of selecting edges and adding new features can be repeated until the required result is calculated. To perform post-calculations on the included edges of an Edge Finder result buffer, set SourceImageId, SourceDeriv1Id, SourceDeriv2Id, and SourceDeriv3Id to M_NULL.

Note that there are some restrictions when post-calculating edges; for more information, see the Post-calculation subsection of the Calculating and retrieving results section of Chapter 8: Edge Finder.

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

ContextId

Specifies the Edge Finder context to use for the extraction. The Edge Finder context must have been previously allocated on the required system using MedgeAlloc().

SourceImageId

Specifies the source image buffer from which to extract edges. Typically, the source image buffer should be 1-band 8-bit unsigned. Other buffer depths and types are generally accepted, but can slightly decrease performance. Note that 3-band source image buffers are only supported when extracting edge contours. When the source image buffer is 32-bit float, Edge Finder uses floating-point precision calculations.

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.

If you specify your own derivative image buffers, or if you are performing post-calculations on the included edges of an Edge Finder result buffer, this parameter must be set to M_NULL.

SourceDeriv1Id

Specifies the X-source derivative image buffer used to extract edges. When the Edge Finder context type is M_CONTOUR, SourceDeriv1Id specifies the first derivative of the image in the X-direction. When the Edge Finder context type is M_CREST, SourceDeriv1Id specifies the second derivative of the image in the X-direction.

Derivative image buffers must be 1-band 16-bit signed or 1-band 32-bit float. In addition, all derivative image buffers must be consistent (for example, they must have the same scaling factor), and they must be of the same type and size. When the derivative image buffers are 32-bit float, Edge Finder uses floating-point precision calculations.

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.

If you specify a source image buffer, or if you are performing post-calculations on the included edges of an Edge Finder result buffer, this parameter must be set to M_NULL.

SourceDeriv2Id

Specifies the Y-source derivative image buffer used to extract edges. When the Edge Finder context type is M_CONTOUR, SourceDeriv2Id specifies the first derivative of the image in the Y-direction. When the Edge Finder context type is M_CREST, SourceDeriv2Id specifies the second derivative of the image in the Y-direction.

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.

If you specify a source image buffer, or if you are performing post-calculations on the included edges of an Edge Finder result buffer, this parameter must be set to M_NULL.

SourceDeriv3Id

Specifies the source cross-derivative image buffer used to extract edges. The cross-derivative can only be specified if the Edge Finder context type is M_CREST. If the Edge Finder context type is M_CONTOUR, set SourceDeriv3Id to M_NULL.

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.

If you specify a source image buffer, or if you are performing post-calculations on the included edges of an Edge Finder result buffer, this parameter must be set to M_NULL.

EdgeResultId

Specifies the Edge Finder result buffer in which to write the results of the extraction. The Edge Finder result buffer must have been previously allocated on the required system using MedgeAllocResult().

[Matrox Solios eA/XA; Matrox Solios ecl/xcl/ev-cl]

The Edge Finder result buffer (EdgeResultId) must be allocated on the same system as the Edge Finder context (ContextId). If it is not, an error will occur.

ControlFlag

Specifies whether optimal performance during Edge Finder calculations is ensured. This parameter can only be used when providing derivative image buffers. When providing a source image buffer, optimal performance is always ensured; therefore, this parameter must be set to M_DEFAULT.

When providing derivative image buffers, this parameter must be set to one of the following values:

For the derivative image buffers
Value	Description
M_DEFAULT	Specifies that optimal performance is not ensured.
M_NO_CHECK	Specifies that optimal performance is ensured. M_NO_CHECK should only be used if each derivative image buffer has pixel values that do not go beyond the range of positive or negative 1024 (that is, 10-bit signed values). This ensures optimal performance since Edge Finder does not have to verify unnecessary values. (summarize) Specifies that optimal performance is ensured. (more details...)

Compilation information

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