guided_filterguided_filterGuidedFilterGuidedFilterguided_filter (Operator)


guided_filterguided_filterGuidedFilterGuidedFilterguided_filter — Guided filtering of an image.


guided_filter(Image, ImageGuide : ImageGuided : Radius, Amplitude : )

Herror guided_filter(const Hobject Image, const Hobject ImageGuide, Hobject* ImageGuided, const Hlong Radius, double Amplitude)

Herror T_guided_filter(const Hobject Image, const Hobject ImageGuide, Hobject* ImageGuided, const Htuple Radius, const Htuple Amplitude)

void GuidedFilter(const HObject& Image, const HObject& ImageGuide, HObject* ImageGuided, const HTuple& Radius, const HTuple& Amplitude)

HImage HImage::GuidedFilter(const HImage& ImageGuide, Hlong Radius, double Amplitude) const

static void HOperatorSet.GuidedFilter(HObject image, HObject imageGuide, out HObject imageGuided, HTuple radius, HTuple amplitude)

HImage HImage.GuidedFilter(HImage imageGuide, int radius, double amplitude)

def guided_filter(image: HObject, image_guide: HObject, radius: int, amplitude: float) -> HObject


guided_filterguided_filterGuidedFilterGuidedFilterGuidedFilterguided_filter filters the input ImageImageImageImageimageimage using the guidance image ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide and returns the result in ImageGuidedImageGuidedImageGuidedImageGuidedimageGuidedimage_guided. ImageImageImageImageimageimage and ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide must be of the same size and type.

The RadiusRadiusRadiusRadiusradiusradius is the size of the filter mask. Bigger values increase the area of influence of the filter and less detail is preserved. The value of RadiusRadiusRadiusRadiusradiusradius does not influence the runtime of the operator.

AmplitudeAmplitudeAmplitudeAmplitudeamplitudeamplitude is used to decide what is an edge and what is a homogeneous area. Bigger values of AmplitudeAmplitudeAmplitudeAmplitudeamplitudeamplitude lead to stronger edges being smoothed. As a rule of thumb, AmplitudeAmplitudeAmplitudeAmplitudeamplitudeamplitude should be lower than the contrast of the edges that should be preserved. Please note that the contrast in uint2 or real images may differ significantly from the default values of AmplitudeAmplitudeAmplitudeAmplitudeamplitudeamplitude and adjust the parameter accordingly.

Influence of the Guidance Image

If ImageImageImageImageimageimage and ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide are identical, guided_filterguided_filterGuidedFilterGuidedFilterGuidedFilterguided_filter behaves like an edge-preserving smoothing with a filter mask with RadiusRadiusRadiusRadiusradiusradius. Pixels at edges that have a contrast significantly greater than AmplitudeAmplitudeAmplitudeAmplitudeamplitudeamplitude are preserved, while pixels in homogeneous areas are smoothed. Hence, guided_filterguided_filterGuidedFilterGuidedFilterGuidedFilterguided_filter is a fast alternative to anisotropic_diffusionanisotropic_diffusionAnisotropicDiffusionAnisotropicDiffusionAnisotropicDiffusionanisotropic_diffusion or bilateral_filterbilateral_filterBilateralFilterBilateralFilterBilateralFilterbilateral_filter.

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

If ImageImageImageImageimageimage and ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide are different, ImageImageImageImageimageimage is smoothed with a filter mask with RadiusRadiusRadiusRadiusradiusradius, except in areas where ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide has edges with a contrast significantly greater than AmplitudeAmplitudeAmplitudeAmplitudeamplitudeamplitude.

(1) (2) (3)
(1) ImageImageImageImageimageimage and (2) ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide are different. (3) ImageGuidedImageGuidedImageGuidedImageGuidedimageGuidedimage_guided: Only edges are preserved where ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide has edges.
If ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide is constant, guided_filterguided_filterGuidedFilterGuidedFilterGuidedFilterguided_filter is equivalent to 2 consecutive calls of mean_imagemean_imageMeanImageMeanImageMeanImagemean_image with mask size 2*RadiusRadiusRadiusRadiusradiusradius+1.
(1) (2) (3)
(2) ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide is constant. This is equivalent to a double smoothing of (1) ImageImageImageImageimageimage with mean_imagemean_imageMeanImageMeanImageMeanImagemean_image. (3) ImageGuidedImageGuidedImageGuidedImageGuidedimageGuidedimage_guided

Influence of the smoothing parameters

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

Rolling Guided Filter

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

In the following example, the rolling guided filter is used to separate the texture from the original image.

(1) (2) (3)
Texture removal with the rolling guided filter: (1) Original, (2) separated structure, (3) separated texture.
* Apply the rolling guided filter
* (use a constant guide for the first iteration).
gen_image_proto(Image, ImageStructure, 0)gen_image_proto(Image, ImageStructure, 0)GenImageProto(Image, ImageStructure, 0)GenImageProto(Image, ImageStructure, 0)GenImageProto(Image, ImageStructure, 0)gen_image_proto(Image, ImageStructure, 0)
for I := 1 to 4 by 1
guided_filter(Image, ImageStructure, ImageStructure, 1.5, 60)guided_filter(Image, ImageStructure, ImageStructure, 1.5, 60)GuidedFilter(Image, ImageStructure, ImageStructure, 1.5, 60)GuidedFilter(Image, ImageStructure, ImageStructure, 1.5, 60)GuidedFilter(Image, ImageStructure, ImageStructure, 1.5, 60)guided_filter(Image, ImageStructure, ImageStructure, 1.5, 60)
* Separate texture by subtracting large structures from the original.
sub_image(Image, ImageStructure, ImageTexture, 1, 128)sub_image(Image, ImageStructure, ImageTexture, 1, 128)SubImage(Image, ImageStructure, ImageTexture, 1, 128)SubImage(Image, ImageStructure, ImageTexture, 1, 128)SubImage(Image, ImageStructure, ImageTexture, 1, 128)sub_image(Image, ImageStructure, ImageTexture, 1, 128)

Since guided_filterguided_filterGuidedFilterGuidedFilterGuidedFilterguided_filter with a constant ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide is similar to mean_imagemean_imageMeanImageMeanImageMeanImagemean_image, the first iteration could be replaced by a call of mean_imagemean_imageMeanImageMeanImageMeanImagemean_image (or a similar smoothing filter), which is faster.

Mathematical Background

The calculation of the filtered gray value at the position is done according to the following formula: where and where and are the gray values of ImageImageImageImageimageimage and ImageGuideImageGuideImageGuideImageGuideimageGuideimage_guide at the pixel position , is the neighborhood with radius RadiusRadiusRadiusRadiusradiusradius around the pixel , , , , and are the mean of all , , , or in , is the standard deviation of all gray values of in , and is the number of pixels in .

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

Execution Information


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

Input image.

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

Guidance image.

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

Output image.

RadiusRadiusRadiusRadiusradiusradius (input_control)  integer HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Radius of the filtering operation.

Default value: 3

Suggested values: 1, 2, 3, 5, 10

Restriction: Radius > 0

AmplitudeAmplitudeAmplitudeAmplitudeamplitudeamplitude (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Controls the influence of edges on the smoothing.

Default value: 20.0

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

Restriction: Amplitude > 0

Example (HDevelop)

read_image (Image, 'mreut')
* Edge-preserving smoothing
guided_filter (Image, Image, ImageGuided, 5, 20)
* Rolling filter (5 iterations)
gen_image_proto (Image, ImageGuide, 0)
for I := 1 to 5 by 1
  guided_filter (Image, ImageGuide, ImageGuide, 5, 20)

Possible Predecessors


Possible Successors

thresholdthresholdThresholdThresholdThresholdthreshold, dyn_thresholddyn_thresholdDynThresholdDynThresholdDynThresholddyn_threshold, regiongrowingregiongrowingRegiongrowingRegiongrowingRegiongrowingregiongrowing


bilateral_filterbilateral_filterBilateralFilterBilateralFilterBilateralFilterbilateral_filter, anisotropic_diffusionanisotropic_diffusionAnisotropicDiffusionAnisotropicDiffusionAnisotropicDiffusionanisotropic_diffusion, median_imagemedian_imageMedianImageMedianImageMedianImagemedian_image


Kaiming He, Jian Sun, Xiaoou Tang: “Guided Image Filtering”; IEEE Transactions on Pattern Analysis and Machine Intelligence; PAMI-35, no. 6; S. 1397-1409; 2013.