ClassesClassesClassesClasses | | | | Operators

edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix (Operator)


edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix — Extract sub-pixel precise edges using Deriche, Lanser, Shen, or Canny filters.


edges_sub_pix(Image : Edges : Filter, Alpha, Low, High : )

Herror edges_sub_pix(const Hobject Image, Hobject* Edges, const char* Filter, double Alpha, const Hlong Low, const Hlong High)

Herror T_edges_sub_pix(const Hobject Image, Hobject* Edges, const Htuple Filter, const Htuple Alpha, const Htuple Low, const Htuple High)

Herror edges_sub_pix(Hobject Image, Hobject* Edges, const HTuple& Filter, const HTuple& Alpha, const HTuple& Low, const HTuple& High)

HXLDContArray HImage::EdgesSubPix(const HTuple& Filter, const HTuple& Alpha, const HTuple& Low, const HTuple& High) const

void EdgesSubPix(const HObject& Image, HObject* Edges, const HTuple& Filter, const HTuple& Alpha, const HTuple& Low, const HTuple& High)

HXLDCont HImage::EdgesSubPix(const HString& Filter, double Alpha, const HTuple& Low, const HTuple& High) const

HXLDCont HImage::EdgesSubPix(const HString& Filter, double Alpha, Hlong Low, Hlong High) const

HXLDCont HImage::EdgesSubPix(const char* Filter, double Alpha, Hlong Low, Hlong High) const

void HOperatorSetX.EdgesSubPix(
[in] IHUntypedObjectX* Image, [out] IHUntypedObjectX*Edges, [in] VARIANT Filter, [in] VARIANT Alpha, [in] VARIANT Low, [in] VARIANT High)

IHXLDContX* HImageX.EdgesSubPix(
[in] BSTR Filter, [in] double Alpha, [in] VARIANT Low, [in] VARIANT High)

static void HOperatorSet.EdgesSubPix(HObject image, out HObject edges, HTuple filter, HTuple alpha, HTuple low, HTuple high)

HXLDCont HImage.EdgesSubPix(string filter, double alpha, HTuple low, HTuple high)

HXLDCont HImage.EdgesSubPix(string filter, double alpha, int low, int high)


edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix detects step edges using recursively implemented filters (according to Deriche, Lanser and Shen) or the conventionally implemented “derivative of Gaussian” filter (using filter masks) proposed by Canny. Thus, the following edge operators are available:

'deriche1', 'lanser1', 'deriche2', 'lanser2', 'shen', 'mshen', 'canny', 'sobel', and 'sobel_fast'

(parameter FilterFilterFilterFilterFilterfilter).

The extracted edges are returned as sub-pixel precise XLD contours in EdgesEdgesEdgesEdgesEdgesedges. For all edge operators except 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast", the following attributes are defined for each edge point (see get_contour_attrib_xldget_contour_attrib_xldGetContourAttribXldget_contour_attrib_xldGetContourAttribXldGetContourAttribXld):

'edge_direction'"edge_direction""edge_direction""edge_direction""edge_direction""edge_direction": Edge direction
'angle'"angle""angle""angle""angle""angle":          Direction of the normal vectors to the
                           contour (oriented such that the normal
                           vectors point to the right side of the
                           contour as the contour is traversed from
                           start to end point; the angles are given
                           with respect to the row axis of the
'response'"response""response""response""response""response":       Edge amplitude (color gradient magnitude)

The “filter width” (i.e., the amount of smoothing) can be chosen arbitrarily for all edge operators except 'sobel'"sobel""sobel""sobel""sobel""sobel" and 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast", and can be estimated by calling info_edgesinfo_edgesInfoEdgesinfo_edgesInfoEdgesInfoEdges for concrete values of the parameter AlphaAlphaAlphaAlphaAlphaalpha. It decreases for increasing AlphaAlphaAlphaAlphaAlphaalpha for the Deriche, Lanser and Shen filters and increases for the Canny filter, where it is the standard deviation of the Gaussian on which the Canny operator is based. “Wide” filters exhibit a larger invariance to noise, but also a decreased ability to detect small details. Non-recursive filters, such as the Canny filter, are realized using filter masks, and thus the execution time increases for increasing filter width. In contrast, the execution time for recursive filters does not depend on the filter width. Thus, arbitrary filter widths are possible using the Deriche, Lanser and Shen filters without increasing the run time of the operator. The resulting advantage in speed compared to the Canny operator naturally increases for larger filter widths. As border treatment, the recursive operators assume that the images to be zero outside of the image, while the Canny operator repeats the gray value at the image's border. Comparable filter widths can be obtained by the following choices of AlphaAlphaAlphaAlphaAlphaalpha:

     Alpha('lanser1')   = Alpha('deriche1'),
     Alpha('deriche2')  = Alpha('deriche1') / 2,
     Alpha('lanser2')   = Alpha('deriche2'),
     Alpha('shen')      = Alpha('deriche1') / 2,
     Alpha('mshen')     = Alpha('shen'),
     Alpha('canny')     = 1.77 / Alpha('deriche1').

The originally proposed recursive filters ('deriche1', 'deriche2', 'shen') return a biased estimate of the amplitude of diagonal edges. This bias is removed in the corresponding modified version of the operators ('lanser1', 'lanser2' and 'mshen'), while maintaining the same execution speed.

For relatively small filter widths (11 x 11), i.e., for Alpha ('lanser2' = 0.5), all filters yield similar results. Only for “wider” filters differences begin to appear: the Shen filters begin to yield qualitatively inferior results. However, they are the fastest of the implemented operators that supprt arbitrary mask sizes, closely followed by the Deriche operators. The two Sobel filters, which use a fixed mask size of (3 x 3), are faster than the other filters. Of these two, the filter 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast" is significantly faster than 'sobel'"sobel""sobel""sobel""sobel""sobel".

edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix links the edge points into edges by using an algorithm similar to a hysteresis threshold operation, which is also used in lines_gausslines_gaussLinesGausslines_gaussLinesGaussLinesGauss. Points with an amplitude larger than HighHighHighHighHighhigh are immediately accepted as belonging to an edge, while points with an amplitude smaller than LowLowLowLowLowlow are rejected. All other points are accepted as edges if they are connected to accepted edge points (see also lines_gausslines_gaussLinesGausslines_gaussLinesGaussLinesGauss and hysteresis_thresholdhysteresis_thresholdHysteresisThresholdhysteresis_thresholdHysteresisThresholdHysteresisThreshold).

Because edge extractors are often unable to extract certain junctions, a mode that tries to extract these missing junctions by different means can be selected by appending '_junctions'"_junctions""_junctions""_junctions""_junctions""_junctions" to the values of FilterFilterFilterFilterFilterfilter that are described above. This mode is analogous to the mode for completing junctions that is available in lines_gausslines_gaussLinesGausslines_gaussLinesGaussLinesGauss.

The edge operator 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast" has the same semantics as all the other edge operators. Internally, howver, it is based on significantly simplified variants of the individual processing steps (hysteresis thresholding, edge point linking, and extraction of the subpixel edge positions). Therefore, 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast" in some cases may return slightly less accurate edge positions and may select different edge parts.

edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix can be executed on OpenCL devices for the filter types 'canny'"canny""canny""canny""canny""canny" and 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast". This will require up to width*height*29 bytes of pinned memory. Since allocating memory is an expensive operation, it would make sense to set the pinned memory cache to at least this size (using set_compute_device_paramset_compute_device_paramSetComputeDeviceParamset_compute_device_paramSetComputeDeviceParamSetComputeDeviceParam for parameter 'pinned_mem_cache_capacity'"pinned_mem_cache_capacity""pinned_mem_cache_capacity""pinned_mem_cache_capacity""pinned_mem_cache_capacity""pinned_mem_cache_capacity", or to disable pinned memory completely (using set_compute_device_paramset_compute_device_paramSetComputeDeviceParamset_compute_device_paramSetComputeDeviceParamSetComputeDeviceParam for parameter 'alloc_pinned'"alloc_pinned""alloc_pinned""alloc_pinned""alloc_pinned""alloc_pinned"), in which case the normal memory cache is used. Note that the results can vary from the CPU implementation.


Since edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix uses Gauss convolution internally for the 'canny'"canny""canny""canny""canny""canny" filter, the same limitations for OpenCL apply as for derivate_gaussderivate_gaussDerivateGaussderivate_gaussDerivateGaussDerivateGauss: AlphaAlphaAlphaAlphaAlphaalpha must be choosen small enough that the required filter mask is less than 129 pixels in size. Also, edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix is not available on OpenCL devices for HALCON XL, as double precision floating point arithmetic would be required, but OpenCL devices are optimized for single precision arithmetic.



ImageImageImageImageImageimage (input_object)  singlechannelimage objectHImageHImageHImageHImageXHobject (byte / uint2 / real)

Input image.

EdgesEdgesEdgesEdgesEdgesedges (output_object)  xld_cont-array objectHXLDContHXLDContHXLDContArrayHXLDContXHobject *

Extracted edges.

FilterFilterFilterFilterFilterfilter (input_control)  string HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (char*)

Edge operator to be applied.

Default value: 'canny' "canny" "canny" "canny" "canny" "canny"

List of values: 'canny'"canny""canny""canny""canny""canny", 'canny_junctions'"canny_junctions""canny_junctions""canny_junctions""canny_junctions""canny_junctions", 'deriche1'"deriche1""deriche1""deriche1""deriche1""deriche1", 'deriche1_junctions'"deriche1_junctions""deriche1_junctions""deriche1_junctions""deriche1_junctions""deriche1_junctions", 'deriche2'"deriche2""deriche2""deriche2""deriche2""deriche2", 'deriche2_junctions'"deriche2_junctions""deriche2_junctions""deriche2_junctions""deriche2_junctions""deriche2_junctions", 'lanser1'"lanser1""lanser1""lanser1""lanser1""lanser1", 'lanser1_junctions'"lanser1_junctions""lanser1_junctions""lanser1_junctions""lanser1_junctions""lanser1_junctions", 'lanser2'"lanser2""lanser2""lanser2""lanser2""lanser2", 'lanser2_junctions'"lanser2_junctions""lanser2_junctions""lanser2_junctions""lanser2_junctions""lanser2_junctions", 'mshen'"mshen""mshen""mshen""mshen""mshen", 'mshen_junctions'"mshen_junctions""mshen_junctions""mshen_junctions""mshen_junctions""mshen_junctions", 'shen'"shen""shen""shen""shen""shen", 'shen_junctions'"shen_junctions""shen_junctions""shen_junctions""shen_junctions""shen_junctions", 'sobel'"sobel""sobel""sobel""sobel""sobel", 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast", 'sobel_junctions'"sobel_junctions""sobel_junctions""sobel_junctions""sobel_junctions""sobel_junctions"

List of values (for compute devices): 'canny'"canny""canny""canny""canny""canny", 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast"

AlphaAlphaAlphaAlphaAlphaalpha (input_control)  real HTupleHTupleHTupleVARIANTHtuple (real) (double) (double) (double) (double) (double)

Filter parameter: small values result in strong smoothing, and thus less detail (opposite for 'canny').

Default value: 1.0

Suggested values: 0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 0.9, 1.1

Typical range of values: 0.2 ≤ Alpha Alpha Alpha Alpha Alpha alpha ≤ 50.0

Minimum increment: 0.01

Recommended increment: 0.1

Restriction: Alpha > 0.0

LowLowLowLowLowlow (input_control)  integer HTupleHTupleHTupleVARIANTHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double) (Hlong / double) (Hlong / double)

Lower threshold for the hysteresis threshold operation.

Default value: 20

Suggested values: 5, 10, 15, 20, 25, 30, 40

Typical range of values: 1 ≤ Low Low Low Low Low low ≤ 255

Minimum increment: 1

Recommended increment: 5

Restriction: Low > 0

HighHighHighHighHighhigh (input_control)  integer HTupleHTupleHTupleVARIANTHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double) (Hlong / double) (Hlong / double)

Upper threshold for the hysteresis threshold operation.

Default value: 40

Suggested values: 10, 15, 20, 25, 30, 40, 50, 60, 70

Typical range of values: 1 ≤ High High High High High high ≤ 255

Minimum increment: 1

Recommended increment: 5

Restriction: High > 0 && High >= Low

Example (HDevelop)


Example (C)


Example (HDevelop)


Example (HDevelop)


Example (HDevelop)


Example (HDevelop)



Let A be the number of pixels in the domain of ImageImageImageImageImageimage. Then the runtime complexity is O(A*Sigma) for the Canny filter and O(A) for the recursive Lanser, Deriche, and Shen filters.

The amount of temporary memory required is dependent on the height H of the domain of ImageImageImageImageImageimage and the width W of ImageImageImageImageImageimage. Let S = W*H, then edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix requires at least 60*S bytes of temporary memory during execution for all edge operators except 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast". For 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast", at least 9*S bytes of temporary memory are required.


edges_sub_pixedges_sub_pixEdgesSubPixedges_sub_pixEdgesSubPixEdgesSubPix returns 2 (H_MSG_TRUE) if all parameters are correct and no error occurs during execution. If the input is empty the behaviour can be set via set_system('no_object_result',<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>). If necessary, an exception is raised.

Possible Successors

segment_contours_xldsegment_contours_xldSegmentContoursXldsegment_contours_xldSegmentContoursXldSegmentContoursXld, gen_polygons_xldgen_polygons_xldGenPolygonsXldgen_polygons_xldGenPolygonsXldGenPolygonsXld, select_shape_xldselect_shape_xldSelectShapeXldselect_shape_xldSelectShapeXldSelectShapeXld


sobel_dirsobel_dirSobelDirsobel_dirSobelDirSobelDir, frei_dirfrei_dirFreiDirfrei_dirFreiDirFreiDir, kirsch_dirkirsch_dirKirschDirkirsch_dirKirschDirKirschDir, prewitt_dirprewitt_dirPrewittDirprewitt_dirPrewittDirPrewittDir, robinson_dirrobinson_dirRobinsonDirrobinson_dirRobinsonDirRobinsonDir, edges_imageedges_imageEdgesImageedges_imageEdgesImageEdgesImage

See also

info_edgesinfo_edgesInfoEdgesinfo_edgesInfoEdgesInfoEdges, hysteresis_thresholdhysteresis_thresholdHysteresisThresholdhysteresis_thresholdHysteresisThresholdHysteresisThreshold, bandpass_imagebandpass_imageBandpassImagebandpass_imageBandpassImageBandpassImage, lines_gausslines_gaussLinesGausslines_gaussLinesGaussLinesGauss, lines_facetlines_facetLinesFacetlines_facetLinesFacetLinesFacet


S.Lanser, W.Eckstein: “Eine Modifikation des Deriche-Verfahrens zur Kantendetektion”; 13. DAGM-Symposium, München; Informatik Fachberichte 290; Seite 151 - 158; Springer-Verlag; 1991.
S.Lanser: “Detektion von Stufenkanten mittels rekursiver Filter nach Deriche”; Diplomarbeit; Technische Universität München, Institut für Informatik, Lehrstuhl Prof. Radig; 1991.
J.Canny: “Finding Edges and Lines in Images”; Report, AI-TR-720; M.I.T. Artificial Intelligence Lab., Cambridge; 1983.
J.Canny: “A Computational Approach to Edge Detection”; IEEE Transactions on Pattern Analysis and Machine Intelligence; PAMI-8, vol. 6; S. 679-698; 1986.
R.Deriche: “Using Canny's Criteria to Derive a Recursively Implemented Optimal Edge Detector”; International Journal of Computer Vision; vol. 1, no. 2; S. 167-187; 1987.
R.Deriche: “Optimal Edge Detection Using Recursive Filtering”; Proc. of the First International Conference on Computer Vision, London; S. 501-505; 1987.
R.Deriche: “Fast Algorithms for Low-Level Vision”; IEEE Transactions on Pattern Analysis and Machine Intelligence; PAMI-12, no. 1; S. 78-87; 1990.
S.Castan, J.Zhao und J.Shen: “Optimal Filter for Edge Detection Methods and Results”; Proc. of the First European Conference on Computer Vision, Antibes; Lecture Notes on computer Science; no. 427; S. 12-17; Springer-Verlag; 1990.


2D Metrology

ClassesClassesClassesClasses | | | | Operators