bilateral_filterBilateralFilterBilateralFilterbilateral_filterbilateral_filter🔗

Short description🔗

bilateral_filterBilateralFilterBilateralFilterbilateral_filterbilateral_filter — bilateral filtering of an image.

Signature🔗

bilateral_filter( image Image, image ImageJoint, out image ImageBilateral, real SigmaSpatial, real SigmaRange, attribute.name GenParamName, attribute.value GenParamValue )

Description🔗

bilateral_filterBilateralFilter performs a joint bilateral filtering on the input Imageimageimage using the guidance image ImageJointimageJointimage_joint and returns the result in ImageBilateralimageBilateralimage_bilateral. Imageimageimage and ImageJointimageJointimage_joint must be of the same size and type.

SigmaSpatialsigmaSpatialsigma_spatial defines the size of the filter mask and corresponds to the standard deviation of a conventional Gauss filter. Bigger values increase the area of influence of the filter and less detail is preserved.

SigmaRangesigmaRangesigma_range is used to modify the filter mask depending on the pixels of ImageJointimageJointimage_joint around the current pixel. Only pixels in areas with weak edges that have a contrast lower than SigmaRangesigmaRangesigma_range contribute to the smoothing. Please note that the contrast in uint2 or real images may differ significantly from the default values of SigmaRangesigmaRangesigma_range and adjust the parameter accordingly.

GenParamNamegenParamNamegen_param_name and GenParamValuegenParamValuegen_param_value currently can be used to control the trade-off between accuracy and speed (see below).

Influence of the Joint Image🔗

Each pixel of Imageimageimage is filtered with a filter mask that depends on ImageJointimageJointimage_joint. The filter mask combines a Gaussian closeness function depending on SigmaSpatialsigmaSpatialsigma_spatial and a Gaussian similarity function that weights gray value differences depending on SigmaRangesigmaRangesigma_range.

Examples for local filter masks depending on ImageJointimageJointimage_joint: Left: In homogeneous areas the filter mask is nearly Gaussian. Center: The filter mask follows the line. That means, only the dark pixels are smoothed and the edge is preserved. Right: The filter mask resembles the corner. Note that the filter mask extends across the shadow into areas with similar gray values.

If Imageimageimage and ImageJointimageJointimage_joint are identical, bilateral_filterBilateralFilter behaves like an edge-preserving smoothing where SigmaSpatialsigmaSpatialsigma_spatial defines the size of the filter mask. Pixels at edges that have a contrast significantly greater than SigmaRangesigmaRangesigma_range are preserved, while pixels in homogeneous areas are smoothed.



(1)	(2)	(3)

(1) Imageimageimage and (2) ImageJointimageJointimage_joint are identical. That leads to edge-preserving smoothing in (3) ImageBilateralimageBilateralimage_bilateral.

If Imageimageimage and ImageJointimageJointimage_joint are different, each pixel of Imageimageimage is smoothed with a filter mask that is influenced by ImageJointimageJointimage_joint. Pixels at positions where ImageJointimageJointimage_joint has strong edges with a contrast significantly greater than SigmaRangesigmaRangesigma_range are smoothed less than pixels in homogeneous areas.



(1)	(2)	(3)

(1) Imageimageimage and (2) ImageJointimageJointimage_joint are different. (3) ImageBilateralimageBilateralimage_bilateral: Only edges are preserved where ImageJointimageJointimage_joint has edges.

If ImageJointimageJointimage_joint is constant, bilateral_filterBilateralFilter is equivalent to a Gaussian smoothing with SigmaSpatialsigmaSpatialsigma_spatial (see gauss_filterGaussFilter or smooth_imageSmoothImage).



(1)	(2)	(3)

(1) Imageimageimage. (2) ImageJointimageJointimage_joint is constant. (3) ImageBilateralimageBilateralimage_bilateral is equal to Imageimageimage after Gaussian smoothing.

Influence of the smoothing parameters🔗

The following examples show the influence of SigmaRangesigmaRangesigma_range on an artificial image. In this image, the noise level is 10 gray values, the left edge has a contrast of 50 gray values, the right edge has a contrast of 100 gray values. The yellow line shows a gray-value profile of a horizontal cross section.

Original image with overlaid gray profile, used as Imageimageimage and ImageJointimageJointimage_joint.

Filter result with SigmaRangesigmaRangesigma_range = 1: No effect because SigmaRangesigmaRangesigma_range is below noise level. Therefore noise is treated as edge and preserved.

Filter result with SigmaRangesigmaRangesigma_range = 25: Noise is smoothed, edges are preserved.

Filter result with SigmaRangesigmaRangesigma_range = 50: The weaker edge is smoothed, the stronger edge is preserved.

Filter result with SigmaRangesigmaRangesigma_range = 100: Both edges are smoothed.

Generic Parameters🔗

The following values for GenParamNamegenParamNamegen_param_name are supported:

'sampling_method'"sampling_method" Per default, bilateral_filterBilateralFilter uses an approximation of the bilateral filter that only uses a subset of sampled points for the calculation of the local filter masks.

By setting 'sampling_method'"sampling_method", the used approximation can be selected. Possible values are:
- 'grid'"grid" (default) Uses a regular grid for subsampling the filter masks.
- 'poisson_disk'"poisson_disk" Uses a Poisson disk sampling. This method is slower than 'grid'"grid", but may produce less artifacts.
- 'exact'"exact" Uses all available points. This method is slowest, but the most accurate. If 'exact'"exact" is used, 'sampling_ratio'"sampling_ratio" is ignored.
'sampling_ratio'"sampling_ratio" Controls how many points are used for the subsampling of the local filter masks.

By setting 'sampling_ratio'"sampling_ratio" to 1.01.0, the exact method is used. Using a lower sampling ratio leads to faster filtering, but also to slightly less accurate results.

Suggested values: 0.25, 0.5, 0.75, 1.0

Default: 0.50

Rolling Bilateral Filter🔗

bilateral_filterBilateralFilter can be applied iteratively. In this case, the result of one iteration is used as guidance image for the next iteration. This can be useful, e.g., to remove small structures from the original image even if they have a high contrast.

The following example shows the effect of a rolling filter on an artificial image. In this image, the noise level is 10 gray values, the contrast between dark and bright areas is 100 gray values, the left bright bar is 10 pixels wide, the right bar is 40 pixels wide. The yellow line shows a gray-value profile of a horizontal cross section. Used parameters: ImageJointimageJointimage_joint constant, SigmaSpatialsigmaSpatialsigma_spatial = 25, SigmaRangesigmaRangesigma_range = 15.


`* Apply the rolling bilateral filter`
`* (use a constant guide for the first iteration).`
`gen_image_proto(Image, ImageJoint, 128)GenImageProto(Image, ImageJoint, 128)GenImageProto(Image, ImageJoint, 128)gen_image_proto(Image, ImageJoint, 128)gen_image_proto(Image, ImageJoint, 128)`
`for I := 1 to 6 by 1`
\(\qquad\)`bilateral_filter(Image, ImageJoint, ImageJoint, 25, 15, [], [])BilateralFilter(Image, ImageJoint, ImageJoint, 25, 15, [], [])BilateralFilter(Image, ImageJoint, ImageJoint, 25, 15, [], [])bilateral_filter(Image, ImageJoint, ImageJoint, 25, 15, [], [])bilateral_filter(Image, ImageJoint, ImageJoint, 25, 15, [], [])`
`endfor`



(1)	(2)

(1) Input Imageimageimage and (2) ImageJointimageJointimage_joint for first iteration of the rolling filter.

Result after first iteration: The smaller bar is removed.

Result after third iteration: The edges of the right bar are partly restored.

Result after sixth iteration: The edges of the right bar are restored completely.

Mathematical Background🔗

The calculation of the filtered gray values \(I'_{i}\) is done on the basis of the following formula:

\[\begin{eqnarray*} I'_{i} = \frac{1}{K_{i}} \sum_{k\in \omega_{i}} c_{ik} \cdot s_{ik} \cdot I_{k} \end{eqnarray*}\]

where \(c_{ik}\) is a closeness function

\[\begin{eqnarray*} c_{ik}= exp \left( \frac{-\|i-k\|^2}{2 \cdot SigmaSpatial^2} \right) \end{eqnarray*}\]

\(s_{ik}\) is a similarity function

\[\begin{eqnarray*} s_{ik}= exp \left(\frac{-(J_{i}-J_{k})^2}{2 \cdot SigmaRange^2}\right) \end{eqnarray*}\]

\(K_{i}\) is a normalization factor

\[\begin{eqnarray*} K_{i} = \sum_{k\in \omega_{i}} c_{ik} \cdot s_{ik} \end{eqnarray*}\]

where \(I'_{i}\), \(I_{i}\) and \(J_{i}\) are the gray values of Imageimageimage and ImageJointimageJointimage_joint at the pixel position \(i\), and \(\omega_{i}\) is the neighborhood around the pixel \(i\).

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

Execution information🔗

Execution information

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)

Image to be filtered.

ImageJointimageJointimage_joint (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)

Joint image.

ImageBilateralimageBilateralimage_bilateral (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)

Filtered output image.

SigmaSpatialsigmaSpatialsigma_spatial (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Size of the Gaussian of the closeness function.

Default: 3.03.0
Suggested values: 1.0, 2.0, 3.0, 10.01.0, 2.0, 3.0, 10.0
Restriction: SigmaSpatial > 0.6

SigmaRangesigmaRangesigma_range (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Size of the Gaussian of the similarity function.

Default: 20.020.0
Suggested values: 3.0, 10.0, 20.0, 50.0, 100.03.0, 10.0, 20.0, 50.0, 100.0
Restriction: SigmaRange > 0.0001

GenParamNamegenParamNamegen_param_name (input_control) attribute.name(-array) → (string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)

Generic parameter name.

Default: [][]
List of values: 'sampling_method', 'sampling_ratio'"sampling_method", "sampling_ratio"

GenParamValuegenParamValuegen_param_value (input_control) attribute.value(-array) → (real / integer / string)HTuple (double / Hlong / HString)HTuple (double / int / long / string)MaybeSequence[Union[int, float, str]]Htuple (double / Hlong / char*)

Generic parameter value.

Default: [][]
Suggested values: 'grid', 'poisson_disk', 'exact', 0.5, 0.25, 0.75, 1.0

Example🔗

(HDevelop)

read_image (Image, 'mreut')
* Edge-preserving smoothing
bilateral_filter (Image, Image, ImageBilateral, 5, 20, [], [])
* Rolling filter (5 iterations)
gen_image_proto (Image, ImageJoint, 0)
for I := 1 to 5 by 1
  bilateral_filter (Image, ImageJoint, ImageJoint, 5, 20, [], [])
endfor

Combinations with other operators🔗

Combinations

Possible predecessors

read_imageReadImage

Possible successors

thresholdThreshold, dyn_thresholdDynThreshold, var_thresholdVarThreshold, regiongrowingRegiongrowing

Alternatives

guided_filterGuidedFilter, anisotropic_diffusionAnisotropicDiffusion, median_imageMedianImage

References🔗

C. Tomasi, R. Manduchi: ‘’Bilateral filtering for gray and color images’‘; Sixth International Conference in Computer Vision; S. 839-846; January 1998.

F. Banterle, M. Corsini, P. Cignoni, R. Scopigno: ‘’A Low-Memory, Straightforward and Fast Bilateral Filter Through Subsampling in Spatial Domain’‘; Computer Graphics Forum, no. 1, vol 31; S. 19-23; February 2012.

G. Petschnigg, R. Szeliski, M. Agrawala, M. Cohen, H. Hoppe, K. Toyama: ‘’Digital Photography with Flash and No-flash Image Pairs’‘; ACM Trans., no. 3, vol. 23; S. 9; August 2004.

R. Bridson: ‘’Fast Poisson Disk Sampling in Arbitrary Dimensions’‘; ACM SIGGRAPH 2007 Sketches, no. 22; 2007.

Module🔗

Foundation