binomial_filterBinomialFilterBinomialFilterbinomial_filterbinomial_filter🔗

Short description🔗

binomial_filterBinomialFilterBinomialFilterbinomial_filterbinomial_filter — Smooth an image using the binomial filter.

Signature🔗

binomial_filter( image Image, out image ImageBinomial, integer MaskWidth, integer MaskHeight )

Description🔗

binomial_filterBinomialFilter smooths the image Imageimageimage using a binomial filter with a mask size of MaskWidth * MaskHeight pixels and returns the smoothed image in ImageBinomialimageBinomialimage_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_filterBinomialFilter is very fast. Let \(m = \textrm{MaskHeight}\) and \(n = \textrm{MaskWidth}\). Then, the filter coefficients \(b_{ij}\) are given by binomial coefficients

\[\begin{eqnarray*} {l \choose k} = \frac{l!}{k!(l-k)!} \end{eqnarray*}\]

as follows:

\[\begin{eqnarray*} b_{ij} = \frac{1}{2^{n+m-2}} {m-1 \choose i} {n-1 \choose j} \end{eqnarray*}\]

Here, i = 0, …, m-1 and j = 0, …, n-1. The binomial filter performs approximately the same smoothing as a Gaussian filter with \(\sigma = \sqrt{n-1}/2\), where for simplicity it is assumed that \(m = n\). In detail, the relationship between \(n\) and \(\sigma\) is:

\(n\)	\(\sigma\)
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 MaskHeightmaskHeightmask_height and MaskWidthmaskWidthmask_width, the above relation between \(n\) and \(\sigma\) still holds and refers to the amount of smoothing in the row and column directions.

binomial_filterBinomialFilter 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🔗

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🔗

Imageimageimage (input_object) (multichannel-)image(-array) → object (byte* / uint2* / real*)HObject (byte* / uint2* / real*)HImage (byte* / uint2* / real*)HObject (byte* / uint2* / real*)Hobject (byte* / uint2* / real*) *allowed for compute devices

Input image.

ImageBinomialimageBinomialimage_binomial (output_object) (multichannel-)image(-array) → object (byte / uint2 / real)HObject (byte / uint2 / real)HImage (byte / uint2 / real)HObject (byte / uint2 / real)Hobject * (byte / uint2 / real)

Smoothed image.

MaskWidthmaskWidthmask_width (input_control) integer → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Filter width.

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

MaskHeightmaskHeightmask_height (input_control) integer → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Filter height.

Default: 55
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_filterBinomialFilter 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>). If necessary an exception is raised.

Combinations with other operators🔗

Combinations

Possible predecessors

read_imageReadImage, grab_imageGrabImage

Possible successors

regiongrowingRegiongrowing, thresholdThreshold, sub_imageSubImage, dyn_thresholdDynThreshold, auto_thresholdAutoThreshold

Alternatives

gauss_filterGaussFilter, smooth_imageSmoothImage, derivate_gaussDerivateGauss, isotropic_diffusionIsotropicDiffusion

Module🔗

Foundation