bilateral_filterbilateral_filterBilateralFilterBilateralFilterbilateral_filter (Operator)

Name

bilateral_filterbilateral_filterBilateralFilterBilateralFilterbilateral_filter — 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)

def bilateral_filter(image: HObject, image_joint: HObject, sigma_spatial: float, sigma_range: float, gen_param_name: MaybeSequence[str], gen_param_value: MaybeSequence[Union[int, float, str]]) -> HObject

Description

bilateral_filterbilateral_filterBilateralFilterBilateralFilterBilateralFilterbilateral_filter performs a joint bilateral filtering on the input ImageImageImageImageimageimage using the guidance image ImageJointImageJointImageJointImageJointimageJointimage_joint and returns the result in ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateralimage_bilateral. ImageImageImageImageimageimage and ImageJointImageJointImageJointImageJointimageJointimage_joint must be of the same size and type.

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

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

GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_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 ImageImageImageImageimageimage is filtered with a filter mask that depends on ImageJointImageJointImageJointImageJointimageJointimage_joint. The filter mask combines a Gaussian closeness function depending on SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatialsigma_spatial and a Gaussian similarity function that weights gray value differences depending on SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRangesigma_range.

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

(1) (2) (3)
(1) ImageImageImageImageimageimage and (2) ImageJointImageJointImageJointImageJointimageJointimage_joint are identical. That leads to edge-preserving smoothing in (3) ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateralimage_bilateral.

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

(1) (2) (3)
(1) ImageImageImageImageimageimage and (2) ImageJointImageJointImageJointImageJointimageJointimage_joint are different. (3) ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateralimage_bilateral: Only edges are preserved where ImageJointImageJointImageJointImageJointimageJointimage_joint has edges.

If ImageJointImageJointImageJointImageJointimageJointimage_joint is constant, bilateral_filterbilateral_filterBilateralFilterBilateralFilterBilateralFilterbilateral_filter is equivalent to a Gaussian smoothing with SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatialsigma_spatial (see gauss_filtergauss_filterGaussFilterGaussFilterGaussFiltergauss_filter or smooth_imagesmooth_imageSmoothImageSmoothImageSmoothImagesmooth_image).

(1) (2) (3)
(1) ImageImageImageImageimageimage. (2) ImageJointImageJointImageJointImageJointimageJointimage_joint is constant. (3) ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateralimage_bilateral is equal to ImageImageImageImageimageimage after Gaussian smoothing.

Influence of the smoothing parameters

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

Generic Parameters

The following values for GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name are supported:

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

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

'grid'"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""poisson_disk"

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

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

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

'sampling_ratio'"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""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_filterBilateralFilterBilateralFilterBilateralFilterbilateral_filter 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: ImageJointImageJointImageJointImageJointimageJointimage_joint constant, SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatialsigma_spatial = 25, SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRangesigma_range = 15.
* Apply the rolling bilateral filter
* (use a constant guide for the first iteration).
gen_image_proto(Image, ImageJoint, 128)gen_image_proto(Image, ImageJoint, 128)GenImageProto(Image, ImageJoint, 128)GenImageProto(Image, ImageJoint, 128)GenImageProto(Image, ImageJoint, 128)gen_image_proto(Image, ImageJoint, 128)
for I := 1 to 6 by 1
bilateral_filter(Image, ImageJoint, ImageJoint, 25, 15, [], [])bilateral_filter(Image, ImageJoint, ImageJoint, 25, 15, [], [])BilateralFilter(Image, ImageJoint, ImageJoint, 25, 15, [], [])BilateralFilter(Image, ImageJoint, ImageJoint, 25, 15, [], [])BilateralFilter(Image, ImageJoint, ImageJoint, 25, 15, [], [])bilateral_filter(Image, ImageJoint, ImageJoint, 25, 15, [], [])
endfor
(1) (2)
(1) Input ImageImageImageImageimageimage and (2) ImageJointImageJointImageJointImageJointimageJointimage_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 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 ImageImageImageImageimageimage and ImageJointImageJointImageJointImageJointimageJointimage_joint 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

ImageImageImageImageimageimage (input_object)  (multichannel-)image(-array) objectHImageHObjectHImageHobject (byte / uint2 / real)

Image to be filtered.

ImageJointImageJointImageJointImageJointimageJointimage_joint (input_object)  (multichannel-)image(-array) objectHImageHObjectHImageHobject (byte / uint2 / real)

Joint image.

ImageBilateralImageBilateralImageBilateralImageBilateralimageBilateralimage_bilateral (output_object)  (multichannel-)image(-array) objectHImageHObjectHImageHobject * (byte / uint2 / real)

Filtered output image.

SigmaSpatialSigmaSpatialSigmaSpatialSigmaSpatialsigmaSpatialsigma_spatial (input_control)  real HTuplefloatHTupleHtuple (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

SigmaRangeSigmaRangeSigmaRangeSigmaRangesigmaRangesigma_range (input_control)  real HTuplefloatHTupleHtuple (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

GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control)  attribute.name(-array) HTupleMaybeSequence[str]HTupleHtuple (string) (string) (HString) (char*)

Generic parameter name.

Default value: []

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

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control)  attribute.value(-array) HTupleMaybeSequence[Union[int, float, str]]HTupleHtuple (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""grid", 'poisson_disk'"poisson_disk""poisson_disk""poisson_disk""poisson_disk""poisson_disk", 'exact'"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_imageReadImageReadImageReadImageread_image

Possible Successors

thresholdthresholdThresholdThresholdThresholdthreshold, dyn_thresholddyn_thresholdDynThresholdDynThresholdDynThresholddyn_threshold, var_thresholdvar_thresholdVarThresholdVarThresholdVarThresholdvar_threshold, regiongrowingregiongrowingRegiongrowingRegiongrowingRegiongrowingregiongrowing

Alternatives

guided_filterguided_filterGuidedFilterGuidedFilterGuidedFilterguided_filter, anisotropic_diffusionanisotropic_diffusionAnisotropicDiffusionAnisotropicDiffusionAnisotropicDiffusionanisotropic_diffusion, median_imagemedian_imageMedianImageMedianImageMedianImagemedian_image

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