bilateral_filterbilateral_filterBilateralFilterBilateralFilter (Operator)

Name

bilateral_filterbilateral_filterBilateralFilterBilateralFilter — bilateral filtering of an image.

Signature

bilateral_filter(Image, ImageJoint : ImageBilateral : SigmaSpatial, SigmaRange, GenParamName, GenParamValue : )

Herror bilateral_filter(const Hobject Image, const Hobject ImageJoint, Hobject* ImageBilateral, double SigmaSpatial, double SigmaRange, const char* GenParamName, double GenParamValue)

Herror T_bilateral_filter(const Hobject Image, const Hobject ImageJoint, Hobject* ImageBilateral, const Htuple SigmaSpatial, const Htuple SigmaRange, const Htuple GenParamName, const Htuple GenParamValue)

void BilateralFilter(const HObject& Image, const HObject& ImageJoint, HObject* ImageBilateral, const HTuple& SigmaSpatial, const HTuple& SigmaRange, const HTuple& GenParamName, const HTuple& GenParamValue)

HImage HImage::BilateralFilter(const HImage& ImageJoint, double SigmaSpatial, double SigmaRange, const HTuple& GenParamName, const HTuple& GenParamValue) const

HImage HImage::BilateralFilter(const HImage& ImageJoint, double SigmaSpatial, double SigmaRange, const HString& GenParamName, double GenParamValue) const

HImage HImage::BilateralFilter(const HImage& ImageJoint, double SigmaSpatial, double SigmaRange, const char* GenParamName, double GenParamValue) const

HImage HImage::BilateralFilter(const HImage& ImageJoint, double SigmaSpatial, double SigmaRange, const wchar_t* GenParamName, double GenParamValue) const   (Windows only)

static void HOperatorSet.BilateralFilter(HObject image, HObject imageJoint, out HObject imageBilateral, HTuple sigmaSpatial, HTuple sigmaRange, HTuple genParamName, HTuple genParamValue)

HImage HImage.BilateralFilter(HImage imageJoint, double sigmaSpatial, double sigmaRange, HTuple genParamName, HTuple genParamValue)

HImage HImage.BilateralFilter(HImage imageJoint, double sigmaSpatial, double sigmaRange, string genParamName, double genParamValue)

Description

bilateral_filterbilateral_filterBilateralFilterBilateralFilterBilateralFilter performs a joint bilateral filtering on the input ImageImageImageImageimage using the guidance image ImageJointImageJointImageJointImageJointimageJoint and returns the result in ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateral. ImageImageImageImageimage and ImageJointImageJointImageJointImageJointimageJoint must be of the same size and type.

SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatial 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.

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

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

Influence of the Joint Image

Each pixel of ImageImageImageImageimage is filtered with a filter mask that depends on ImageJointImageJointImageJointImageJointimageJoint. The filter mask combines a Gaussian closeness function depending on SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatial and a Gaussian similarity function that weights gray value differences depending on SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange.

Examples for local filter masks depending on ImageJointImageJointImageJointImageJointimageJoint: 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 ImageImageImageImageimage and ImageJointImageJointImageJointImageJointimageJoint are identical, bilateral_filterbilateral_filterBilateralFilterBilateralFilterBilateralFilter behaves like an edge-preserving smoothing where SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatial defines the size of the filter mask. Pixels at edges that have a contrast significantly greater than SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange are preserved, while pixels in homogeneous areas are smoothed.

(1) (2) (3)
(1) ImageImageImageImageimage and (2) ImageJointImageJointImageJointImageJointimageJoint are identical. That leads to edge-preserving smoothing in (3) ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateral.

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

(1) (2) (3)
(1) ImageImageImageImageimage and (2) ImageJointImageJointImageJointImageJointimageJoint are different. (3) ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateral: Only edges are preserved where ImageJointImageJointImageJointImageJointimageJoint has edges.

If ImageJointImageJointImageJointImageJointimageJoint is constant, bilateral_filterbilateral_filterBilateralFilterBilateralFilterBilateralFilter is equivalent to a Gaussian smoothing with SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatial (see gauss_filtergauss_filterGaussFilterGaussFilterGaussFilter or smooth_imagesmooth_imageSmoothImageSmoothImageSmoothImage).

(1) (2) (3)
(1) ImageImageImageImageimage. (2) ImageJointImageJointImageJointImageJointimageJoint is constant. (3) ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateral is equal to ImageImageImageImageimage after Gaussian smoothing.

Influence of the smoothing parameters

The following examples show the influence of SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange 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 ImageImageImageImageimage and ImageJointImageJointImageJointImageJointimageJoint.
Filter result with SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange = 1: No effect because SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange is below noise level. Therefore noise is treated as edge and preserved.
Filter result with SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange = 25: Noise is smoothed, edges are preserved.
Filter result with SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange = 50: The weaker edge is smoothed, the stronger edge is preserved.
Filter result with SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange = 100: Both edges are smoothed.

Generic Parameters

The following values for GenParamNameGenParamNameGenParamNameGenParamNamegenParamName are supported:

'sampling_method'"sampling_method""sampling_method""sampling_method""sampling_method"

Per default, bilateral_filterbilateral_filterBilateralFilterBilateralFilterBilateralFilter 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""sampling_method""sampling_method""sampling_method", the used approximation can be selected. Possible values are:

'grid'"grid""grid""grid""grid" (default)

Uses a regular grid for subsampling the filter masks.

'poisson_disk'"poisson_disk""poisson_disk""poisson_disk""poisson_disk"

Uses a Poisson disk sampling. This method is slower than 'grid'"grid""grid""grid""grid", but may produce less artifacts.

'exact'"exact""exact""exact""exact"

Uses all available points. This method is slowest, but the most accurate. If 'exact'"exact""exact""exact""exact" is used, 'sampling_ratio'"sampling_ratio""sampling_ratio""sampling_ratio""sampling_ratio" is ignored.

'sampling_ratio'"sampling_ratio""sampling_ratio""sampling_ratio""sampling_ratio"

Controls how many points are used for the subsampling of the local filter masks.

By setting 'sampling_ratio'"sampling_ratio""sampling_ratio""sampling_ratio""sampling_ratio" to 1.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_filterbilateral_filterBilateralFilterBilateralFilterBilateralFilter 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: ImageJointImageJointImageJointImageJointimageJoint constant, SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatial = 25, SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange = 15.

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

(1) (2)
(1) Input ImageImageImageImageimage and (2) ImageJointImageJointImageJointImageJointimageJoint 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 is done on the basis of the following formula: where is a closeness function is a similarity function is a normalization factor where and are the gray values of ImageImageImageImageimage and ImageJointImageJointImageJointImageJointimageJoint at the pixel position , and is the neighborhood around the pixel .

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

Execution Information

Parameters

ImageImageImageImageimage (input_object)  (multichannel-)image(-array) objectHImageHImageHobject (byte / uint2 / real)

Image to be filtered.

ImageJointImageJointImageJointImageJointimageJoint (input_object)  (multichannel-)image(-array) objectHImageHImageHobject (byte / uint2 / real)

Joint image.

ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateral (output_object)  (multichannel-)image(-array) objectHImageHImageHobject * (byte / uint2 / real)

Filtered output image.

SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatial (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Size of the Gaussian of the closeness function.

Default value: 3.0

Suggested values: 1.0, 2.0, 3.0, 10.0

Restriction: SigmaSpatial > 0.6

SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRange (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Size of the Gaussian of the similarity function.

Default value: 20.0

Suggested values: 3.0, 10.0, 20.0, 50.0, 100.0

Restriction: SigmaRange > 0.0001

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  attribute.name(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Generic parameter name.

Default value: []

List of values: 'sampling_method'"sampling_method""sampling_method""sampling_method""sampling_method", 'sampling_ratio'"sampling_ratio""sampling_ratio""sampling_ratio""sampling_ratio"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  attribute.value(-array) HTupleHTupleHtuple (real / integer / string) (double / int / long / string) (double / Hlong / HString) (double / Hlong / char*)

Generic parameter value.

Default value: []

Suggested values: 'grid'"grid""grid""grid""grid", 'poisson_disk'"poisson_disk""poisson_disk""poisson_disk""poisson_disk", 'exact'"exact""exact""exact""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

Possible Predecessors

read_imageread_imageReadImageReadImageReadImage

Possible Successors

thresholdthresholdThresholdThresholdThreshold, dyn_thresholddyn_thresholdDynThresholdDynThresholdDynThreshold, var_thresholdvar_thresholdVarThresholdVarThresholdVarThreshold, regiongrowingregiongrowingRegiongrowingRegiongrowingRegiongrowing

Alternatives

guided_filterguided_filterGuidedFilterGuidedFilterGuidedFilter, anisotropic_diffusionanisotropic_diffusionAnisotropicDiffusionAnisotropicDiffusionAnisotropicDiffusion, median_imagemedian_imageMedianImageMedianImageMedianImage

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