edges_imageedges_imageEdgesImageEdgesImageedges_image (Operator)

Name

edges_imageedges_imageEdgesImageEdgesImageedges_image — Extract edges using Deriche, Lanser, Shen, or Canny filters.

Signature

edges_image(Image : ImaAmp, ImaDir : Filter, Alpha, NMS, Low, High : )

Herror edges_image(const Hobject Image, Hobject* ImaAmp, Hobject* ImaDir, const char* Filter, double Alpha, const char* NMS, const Hlong Low, const Hlong High)

Herror T_edges_image(const Hobject Image, Hobject* ImaAmp, Hobject* ImaDir, const Htuple Filter, const Htuple Alpha, const Htuple NMS, const Htuple Low, const Htuple High)

void EdgesImage(const HObject& Image, HObject* ImaAmp, HObject* ImaDir, const HTuple& Filter, const HTuple& Alpha, const HTuple& NMS, const HTuple& Low, const HTuple& High)

HImage HImage::EdgesImage(HImage* ImaDir, const HString& Filter, double Alpha, const HString& NMS, const HTuple& Low, const HTuple& High) const

HImage HImage::EdgesImage(HImage* ImaDir, const HString& Filter, double Alpha, const HString& NMS, Hlong Low, Hlong High) const

HImage HImage::EdgesImage(HImage* ImaDir, const char* Filter, double Alpha, const char* NMS, Hlong Low, Hlong High) const

HImage HImage::EdgesImage(HImage* ImaDir, const wchar_t* Filter, double Alpha, const wchar_t* NMS, Hlong Low, Hlong High) const   (Windows only)

static void HOperatorSet.EdgesImage(HObject image, out HObject imaAmp, out HObject imaDir, HTuple filter, HTuple alpha, HTuple NMS, HTuple low, HTuple high)

HImage HImage.EdgesImage(out HImage imaDir, string filter, double alpha, string NMS, HTuple low, HTuple high)

HImage HImage.EdgesImage(out HImage imaDir, string filter, double alpha, string NMS, int low, int high)

def edges_image(image: HObject, filter: str, alpha: float, nms: str, low: Union[int, float], high: Union[int, float]) -> Tuple[HObject, HObject]

Description

edges_imageedges_imageEdgesImageEdgesImageEdgesImageedges_image 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. Furthermore, a very fast variant of the Sobel filter can be used. Thus, the following edge operators are available:

'deriche1'"deriche1""deriche1""deriche1""deriche1""deriche1", 'lanser1'"lanser1""lanser1""lanser1""lanser1""lanser1", 'deriche1_int4'"deriche1_int4""deriche1_int4""deriche1_int4""deriche1_int4""deriche1_int4", 'deriche2'"deriche2""deriche2""deriche2""deriche2""deriche2", 'lanser2'"lanser2""lanser2""lanser2""lanser2""lanser2", 'deriche2_int4'"deriche2_int4""deriche2_int4""deriche2_int4""deriche2_int4""deriche2_int4", 'shen'"shen""shen""shen""shen""shen", 'mshen'"mshen""mshen""mshen""mshen""mshen", 'canny'"canny""canny""canny""canny""canny", and 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast"

(parameter FilterFilterFilterFilterfilterfilter).

The edge amplitudes (gradient magnitude) are returned in ImaAmpImaAmpImaAmpImaAmpimaAmpima_amp.

For all filters except 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast", the edge directions are returned in ImaDirImaDirImaDirImaDirimaDirima_dir. For 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast", the edge direction is not computed to speed up the filter. Consequently, ImaDirImaDirImaDirImaDirimaDirima_dir is an empty image object. The edge operators 'deriche1'"deriche1""deriche1""deriche1""deriche1""deriche1" respectively 'deriche2'"deriche2""deriche2""deriche2""deriche2""deriche2" are also available for int4-images, and return the signed filter response instead of its absolute value. This behavior can be obtained for byte-images as well by selecting 'deriche1_int4'"deriche1_int4""deriche1_int4""deriche1_int4""deriche1_int4""deriche1_int4" respectively 'deriche2_int4'"deriche2_int4""deriche2_int4""deriche2_int4""deriche2_int4""deriche2_int4" as filter. This can be used to calculate the second derivative of an image by applying edges_imageedges_imageEdgesImageEdgesImageEdgesImageedges_image (with parameter value 'lanser2'"lanser2""lanser2""lanser2""lanser2""lanser2") to the signed first derivative. Edge directions are stored in 2-degree steps, i.e., an edge direction of x degrees in mathematically positive sense and with respect to the horizontal axis is stored as x / 2 in the edge direction image. Furthermore, the direction of the change of intensity is taken into account. Let denote the image gradient. Then the following edge directions are returned as r/2: Points with edge amplitude 0 are assigned the edge direction 255 (undefined direction).

The “filter width” (i.e., the amount of smoothing) can be chosen arbitrarily for all filters except 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast" (where the filter width is 3x3 and AlphaAlphaAlphaAlphaalphaalpha is ignored), and can be estimated by calling info_edgesinfo_edgesInfoEdgesInfoEdgesInfoEdgesinfo_edges 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. The signal-noise-ratio of the filters is comparable for 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'"deriche1""deriche1""deriche1""deriche1""deriche1", 'deriche2'"deriche2""deriche2""deriche2""deriche2""deriche2", 'shen'"shen""shen""shen""shen""shen") return a biased estimate of the amplitude of diagonal edges. This bias is removed in the corresponding modified version of the operators ('lanser1'"lanser1""lanser1""lanser1""lanser1""lanser1", 'lanser2'"lanser2""lanser2""lanser2""lanser2""lanser2" and 'mshen'"mshen""mshen""mshen""mshen""mshen"), while maintaining the same execution speed.

For relatively small filter widths (11 x 11), i.e., for AlphaAlphaAlphaAlphaalphaalpha('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 --- closely followed by the Deriche operators.

edges_imageedges_imageEdgesImageEdgesImageEdgesImageedges_image optionally offers to apply a non-maximum-suppression (NMSNMSNMSNMSNMSnms = 'nms'"nms""nms""nms""nms""nms"/'inms'"inms""inms""inms""inms""inms"/'hvnms'"hvnms""hvnms""hvnms""hvnms""hvnms"; 'none'"none""none""none""none""none" if not desired) and hysteresis threshold operation (LowLowLowLowlowlow,HighHighHighHighhighhigh; at least one negative if not desired) to the resulting edge image. Conceptually, this corresponds to the following calls:
nonmax_suppression_dir(...,NMS,...)nonmax_suppression_dir(...,NMS,...)NonmaxSuppressionDir(...,NMS,...)NonmaxSuppressionDir(...,NMS,...)NonmaxSuppressionDir(...,NMS,...)nonmax_suppression_dir(...,NMS,...)
hysteresis_threshold(...,Low,High,999,...)hysteresis_threshold(...,Low,High,999,...)HysteresisThreshold(...,Low,High,999,...)HysteresisThreshold(...,Low,High,999,...)HysteresisThreshold(...,Low,High,999,...)hysteresis_threshold(...,Low,High,999,...).

Note that the hysteresis threshold operation is not applied if NMSNMSNMSNMSNMSnms is set to 'none'"none""none""none""none""none".

For 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast", the same non-maximum-suppression is performed for all values of NMSNMSNMSNMSNMSnms except 'none'"none""none""none""none""none". Additionally, for 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast" the resulting edges are thinned to a width of one pixel.

edges_imageedges_imageEdgesImageEdgesImageEdgesImageedges_image 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".

Attention

The OpenCL implementation of edges_imageedges_imageEdgesImageEdgesImageEdgesImageedges_image will generally compute results that differ somewhat from the CPU implementation.

Since edges_imageedges_imageEdgesImageEdgesImageEdgesImageedges_image uses Gauss convolution internally for the 'canny'"canny""canny""canny""canny""canny" filter, the same limitations for OpenCL apply as for derivate_gaussderivate_gaussDerivateGaussDerivateGaussDerivateGaussderivate_gauss: AlphaAlphaAlphaAlphaalphaalpha must be chosen small enough that the required filter mask is less than 129 pixels in size.

Note that filter operators may return unexpected results if an image with a reduced domain is used as input. Please refer to the chapter Filters.

Execution Information

Parameters

ImageImageImageImageimageimage (input_object)  singlechannelimage(-array) objectHImageHObjectHImageHobject (byte / uint2 / int4 / real)

Input image.

ImaAmpImaAmpImaAmpImaAmpimaAmpima_amp (output_object)  (multichannel-)image(-array) objectHImageHObjectHImageHobject * (byte / uint2 / int4 / real)

Edge amplitude (gradient magnitude) image.

ImaDirImaDirImaDirImaDirimaDirima_dir (output_object)  image(-array) objectHImageHObjectHImageHobject * (direction)

Edge direction image.

FilterFilterFilterFilterfilterfilter (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Edge operator to be applied.

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

List of values: 'canny'"canny""canny""canny""canny""canny", 'deriche1'"deriche1""deriche1""deriche1""deriche1""deriche1", 'deriche1_int4'"deriche1_int4""deriche1_int4""deriche1_int4""deriche1_int4""deriche1_int4", 'deriche2'"deriche2""deriche2""deriche2""deriche2""deriche2", 'deriche2_int4'"deriche2_int4""deriche2_int4""deriche2_int4""deriche2_int4""deriche2_int4", 'lanser1'"lanser1""lanser1""lanser1""lanser1""lanser1", 'lanser2'"lanser2""lanser2""lanser2""lanser2""lanser2", 'mshen'"mshen""mshen""mshen""mshen""mshen", 'shen'"shen""shen""shen""shen""shen", 'sobel_fast'"sobel_fast""sobel_fast""sobel_fast""sobel_fast""sobel_fast"

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 HTuplefloatHTupleHtuple (real) (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

NMSNMSNMSNMSNMSnms (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Non-maximum suppression ('none', if not desired).

Default value: 'nms' "nms" "nms" "nms" "nms" "nms"

List of values: 'hvnms'"hvnms""hvnms""hvnms""hvnms""hvnms", 'inms'"inms""inms""inms""inms""inms", 'nms'"nms""nms""nms""nms""nms", 'none'"none""none""none""none""none"

LowLowLowLowlowlow (input_control)  integer HTupleUnion[int, float]HTupleHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double)

Lower threshold for the hysteresis threshold operation (negative, if no thresholding is desired).

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 > 1 || Low < 0

HighHighHighHighhighhigh (input_control)  integer HTupleUnion[int, float]HTupleHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double)

Upper threshold for the hysteresis threshold operation (negative, if no thresholding is desired).

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 > 1 || High < 0 && High >= Low

Example (HDevelop)

read_image(Image,'fabrik')
edges_image(Image,Amp,Dir,'lanser2',0.5,'none',-1,-1)
hysteresis_threshold(Amp,Margin,20,30,30)

Example (C)

read_image(&Image,"fabrik");
edges_image(Image,&Amp,&Dir,"lanser2",0.5,"none",-1,-1);
hysteresis_threshold(Amp,&Margin,20,30,30);

Example (HDevelop)

read_image(Image,'fabrik')
edges_image(Image,Amp,Dir,'lanser2',0.5,'none',-1,-1)
hysteresis_threshold(Amp,Margin,20,30,30)

Example (HDevelop)

read_image(Image,'fabrik')
edges_image(Image,Amp,Dir,'lanser2',0.5,'none',-1,-1)
hysteresis_threshold(Amp,Margin,20,30,30)

Example (HDevelop)

read_image(Image,'fabrik')
edges_image(Image,Amp,Dir,'lanser2',0.5,'none',-1,-1)
hysteresis_threshold(Amp,Margin,20,30,30)

Result

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

Possible Predecessors

info_edgesinfo_edgesInfoEdgesInfoEdgesInfoEdgesinfo_edges

Possible Successors

thresholdthresholdThresholdThresholdThresholdthreshold, hysteresis_thresholdhysteresis_thresholdHysteresisThresholdHysteresisThresholdHysteresisThresholdhysteresis_threshold, close_edges_lengthclose_edges_lengthCloseEdgesLengthCloseEdgesLengthCloseEdgesLengthclose_edges_length

Alternatives

sobel_dirsobel_dirSobelDirSobelDirSobelDirsobel_dir, frei_dirfrei_dirFreiDirFreiDirFreiDirfrei_dir, kirsch_dirkirsch_dirKirschDirKirschDirKirschDirkirsch_dir, prewitt_dirprewitt_dirPrewittDirPrewittDirPrewittDirprewitt_dir, robinson_dirrobinson_dirRobinsonDirRobinsonDirRobinsonDirrobinson_dir

See also

info_edgesinfo_edgesInfoEdgesInfoEdgesInfoEdgesinfo_edges, nonmax_suppression_ampnonmax_suppression_ampNonmaxSuppressionAmpNonmaxSuppressionAmpNonmaxSuppressionAmpnonmax_suppression_amp, hysteresis_thresholdhysteresis_thresholdHysteresisThresholdHysteresisThresholdHysteresisThresholdhysteresis_threshold, bandpass_imagebandpass_imageBandpassImageBandpassImageBandpassImagebandpass_image

References

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.

Module

Foundation