Operators

# binomial_filter (Operator)

## Name

binomial_filter — Smooth an image using the binomial filter.

## Description

binomial_filter smooths the image Image using a binomial filter with a mask size of MaskWidth * MaskHeight pixels and returns the smoothed image in ImageBinomial. The binomial filter is a very good approximation of a Gaussian filter that can be implemented extremely efficiently using only integer operations. Hence, binomial_filter is very fast. Let m = MaskHeight and n = MaskWidth. Then, the filter coefficients b_ij are given by binomial coefficients

```/ l \      l!
|   | = ---------
\ k /   k! (l-k)!
```

as follows:

```       1     / m-1 \ / n-1 \
b   = ------ |     | |     |
ij    n+m-2 \  i  / \  j  /
2
```

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

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

## Parallelization

• Supports OpenCL compute devices.
• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Automatically parallelized on tuple level.
• Automatically parallelized on channel level.
• Automatically parallelized on domain level.

## Parameters

Image (input_object)  (multichannel-)image(-array) object (byte* / uint2* / real*) *allowed for compute devices

Input image.

ImageBinomial (output_object)  (multichannel-)image(-array) object (byte / uint2 / real)

Smoothed image.

Filter width.

Default value: 5

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

Filter height.

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