Operator Reference

HALCON Operator Reference / Filters / Smoothing
ClassesClasses | | Operators

binomial_filterbinomial_filterBinomialFilterBinomialFilterbinomial_filter (Operator)

binomial_filterbinomial_filterBinomialFilterBinomialFilterbinomial_filter — Smooth an image using the binomial filter.

Signature

binomial_filter(Image : ImageBinomial : MaskWidth, MaskHeight : )

Herror binomial_filter(const Hobject Image, Hobject* ImageBinomial, const Hlong MaskWidth, const Hlong MaskHeight)

Herror T_binomial_filter(const Hobject Image, Hobject* ImageBinomial, const Htuple MaskWidth, const Htuple MaskHeight)

void BinomialFilter(const HObject& Image, HObject* ImageBinomial, const HTuple& MaskWidth, const HTuple& MaskHeight)

HImage HImage::BinomialFilter(Hlong MaskWidth, Hlong MaskHeight) const

static void HOperatorSet.BinomialFilter(HObject image, out HObject imageBinomial, HTuple maskWidth, HTuple maskHeight)

HImage HImage.BinomialFilter(int maskWidth, int maskHeight)

def binomial_filter(image: HObject, mask_width: int, mask_height: int) -> HObject

Description

binomial_filterbinomial_filterBinomialFilterBinomialFilterbinomial_filter smooths the image ImageImageImageimageimage using a binomial filter with a mask size of MaskWidthMaskWidthMaskWidthmaskWidthmask_width * MaskHeightMaskHeightMaskHeightmaskHeightmask_height pixels and returns the smoothed image in ImageBinomialImageBinomialImageBinomialimageBinomialimage_binomial. The binomial filter is a very good approximation of a Gaussian filter that can be implemented extremely efficiently using only integer operations. Hence, binomial_filterbinomial_filterBinomialFilterBinomialFilterbinomial_filter is very fast. Let m = MaskHeightMaskHeightMaskHeightmaskHeightmask_height and n = MaskWidthMaskWidthMaskWidthmaskWidthmask_width. Then, the filter coefficients are given by binomial coefficients as follows: Here, i = 0, ..., m-1 and j = 0, ..., n-1. The binomial filter performs approximately the same smoothing as a Gaussian filter with , where for simplicity it is assumed that m = n. In detail, the relationship between n and is:

n
3 0.7523
5 1.0317
7 1.2505
9 1.4365
11 1.6010
13 1.7502
15 1.8876
17 2.0157
19 2.1361
21 2.2501
23 2.3586
25 2.4623
27 2.5618
29 2.6576
31 2.7500
33 2.8395
35 2.9262
37 3.0104

If different values are chosen for MaskHeightMaskHeightMaskHeightmaskHeightmask_height and MaskWidthMaskWidthMaskWidthmaskWidthmask_width, the above relation between n and still holds and refers to the amount of smoothing in the row and column directions.

binomial_filterbinomial_filterBinomialFilterBinomialFilterbinomial_filter can be executed on OpenCL devices for all supported image types.

For an explanation of the concept of smoothing filters see the introduction of chapter Filters / Smoothing.

Attention

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

  • Supports OpenCL compute devices.
  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).
  • Multithreading scope: global (may be called from any thread).
  • Automatically parallelized on tuple level.
  • Automatically parallelized on channel level.
  • Automatically parallelized on domain level.

Parameters

ImageImageImageimageimage (input_object)  (multichannel-)image(-array) → objectHImageHObjectHObjectHobject (byte* / uint2* / real*) *allowed for compute devices

Input image.

ImageBinomialImageBinomialImageBinomialimageBinomialimage_binomial (output_object)  (multichannel-)image(-array) → objectHImageHObjectHObjectHobject * (byte / uint2 / real)

Smoothed image.

MaskWidthMaskWidthMaskWidthmaskWidthmask_width (input_control)  integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Filter width.

Default: 5

List of values: 1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31, 33, 35, 37

MaskHeightMaskHeightMaskHeightmaskHeightmask_height (input_control)  integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Filter height.

Default: 5

List of values: 1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31, 33, 35, 37

Result

If the parameter values are correct the operator binomial_filterbinomial_filterBinomialFilterBinomialFilterbinomial_filter returns the value 2 ( H_MSG_TRUE) . The behavior in case of empty input (no input images available) is set via the operator set_system('no_object_result',<Result>)set_system("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

read_imageread_imageReadImageReadImageread_image, grab_imagegrab_imageGrabImageGrabImagegrab_image

Possible Successors

regiongrowingregiongrowingRegiongrowingRegiongrowingregiongrowing, thresholdthresholdThresholdThresholdthreshold, sub_imagesub_imageSubImageSubImagesub_image, dyn_thresholddyn_thresholdDynThresholdDynThresholddyn_threshold, auto_thresholdauto_thresholdAutoThresholdAutoThresholdauto_threshold

Alternatives

gauss_filtergauss_filterGaussFilterGaussFiltergauss_filter, smooth_imagesmooth_imageSmoothImageSmoothImagesmooth_image, derivate_gaussderivate_gaussDerivateGaussDerivateGaussderivate_gauss, isotropic_diffusionisotropic_diffusionIsotropicDiffusionIsotropicDiffusionisotropic_diffusion

See also

mean_imagemean_imageMeanImageMeanImagemean_image, anisotropic_diffusionanisotropic_diffusionAnisotropicDiffusionAnisotropicDiffusionanisotropic_diffusion, sigma_imagesigma_imageSigmaImageSigmaImagesigma_image, gen_lowpassgen_lowpassGenLowpassGenLowpassgen_lowpass

Module

Foundation

ClassesClasses | | Operators