You are here: Start » Function Reference » Image » Image Local Transforms » SmoothImage_Bilateral

SmoothImage_Bilateral

Header:	FIL.h
Namespace:	fil
Module:	FoundationPro

Smooths an image while preserving sharp edges.

Syntax

void fil::SmoothImage_Bilateral
(
	const fil::Image& inImage,
	ftl::Optional<const fil::Image&> inEdgesImage,
	ftl::Optional<const fil::Region&> inRoi,
	const float inDistanceSigma,
	const float inColorSigma,
	fil::BilateralSamplingMethod::Type inSamplingMethod,
	const int inIterationCount,
	fil::Image& outImage
)

Parameters

Name	Type	Range	Default	Description
inImage	const Image&			Input image
inEdgesImage	Optional<const Image&>		NIL	Image to be used for edge detection
inRoi	Optional<const Region&>		NIL	Range of pixels to be processed
inDistanceSigma	const float	0.0 - 128.0	5.0f	Sigma used when calculating the gaussian difference two pixel positions
inColorSigma	const float	0.0 -	35.0f	Sigma used when calculating the gaussian difference between two colors
inSamplingMethod	BilateralSamplingMethod::Type		Poisson	Whether to use a naive (full) or a subsampling method
inIterationCount	const int	1 -	1	Determines how many times the bilateral filter will be run
outImage	Image&			Output image

Description

The bilateral filter is a low pass filtering algorithm weighting pixels not just in the spatial domain (which is what the gaussian filter does) but also in the color domain. This allows the filter to consider only the pixels that are both nearby and similar in color. The resulting image is smoothed but sharp edges are maintained.

A different image can be used for color distance calculations if the inEdgesImage parameter is set. This allows to transfer edges from other images or preserve edges only for part of an image.

The filter can be run in a iterative mode. When inIterationCount is set to a value greater than 1 the filter runs inIterationCount times using the result from the previous iteration as the edges image in the next.

The algorithm is computationally complex so, if high accuracy is not needed, Poisson Disk subsampling can be used to significantly speed up the algorithms execution time with minimal looses in quality.

Examples

Example input image

Output image with distance sigma set to 5 and color sigma set to 35

Output image with distance sigma set to 10 and color sigma set to 35

Edges image that is grey everywhere outside of a circle and the resulting output image.

Edges image which is different from the input image and the resulting output image.

Output image with distance sigma set to 5 and color sigma set to 35 after one iteration

Output image with distance sigma set to 5 and color sigma set to 35 after three iterations

Remarks

The inDistanceSigma parameter behaves similarly to standard deviation in the gaussian filter.

Higher values of inColorSigma allow the filter to blend pixel that differ more in terms of color.

Hardware Acceleration

This operation supports automatic parallelization for multicore and multiprocessor systems.

Errors

List of possible exceptions:

Error type	Description
DomainError	Image and edges image must be of the same size in SmoothImage_Bilateral.
DomainError	Image and edges image must be of the same type in SmoothImage_Bilateral.
DomainError	Image and edges image must have the same depth in SmoothImage_Bilateral.
DomainError	Region exceeds an input image in SmoothImage_Bilateral.