ImageDev

GaussianFilter2d

Applies a two-dimensional Gaussian filter using either a separable finite kernel, or a recursive algorithm.

Access to parameter description

This algorithm performs a 2D smoothing filter whose impulse response is a Gaussian function. $$ f(x,y) = e^{ \frac{-x ^ 2 }{2\sigma_x ^ 2 } }e^{ \frac{-y ^ 2 }{2\sigma_y ^ 2 } } $$ Where: It can be applied using either a separable or a recursive filter.

The separable mode is based on a Finite Impulse Response (FIR) algorithm applied in a separable way (a two-dimensional convolution separated in two one-dimensional filters). Using this mode, the computation time is proportional to the kernel size, which is determined by using the standard deviation and the kernel size factor.

The recursive mode is based on an Infinite Impulse Response (IIR) algorithm. It computes the sum of one causal and one anti-causal filter where previous results are used to compute the next result. Using this mode, the time is independent of the standard deviation. Consequently, the computation is slower than the FIR mode for small standard deviation, and faster for large standard deviation. Furthermore, as the support of the filter is infinite (not limited by a kernel size), the result of this mode is more precise.

See also

Function Syntax

This function returns outputImage. 
// Function prototype
std::shared_ptr< iolink::ImageView >
gaussianFilter2d( std::shared_ptr< iolink::ImageView > inputImage,
                  GaussianFilter2d::FilterMode filterMode,
                  iolink::Vector2d standardDeviation,
                  double kernelSizeFactor,
                  GaussianFilter2d::OutputType outputType,
                  bool lowMemory,
                  std::shared_ptr< iolink::ImageView > outputImage = nullptr );
This function returns outputImage. 
// Function prototype.
gaussian_filter_2d(input_image: idt.ImageType,
                   filter_mode: GaussianFilter2d.FilterMode = GaussianFilter2d.FilterMode.SEPARABLE,
                   standard_deviation: Union[Iterable[int], Iterable[float]] = [1, 1],
                   kernel_size_factor: float = 2,
                   output_type: GaussianFilter2d.OutputType = GaussianFilter2d.OutputType.SAME_AS_INPUT,
                   low_memory: bool = False,
                   output_image: idt.ImageType = None) -> idt.ImageType
This function returns outputImage. 
// Function prototype.
public static IOLink.ImageView
GaussianFilter2d( IOLink.ImageView inputImage,
                  GaussianFilter2d.FilterMode filterMode = ImageDev.GaussianFilter2d.FilterMode.SEPARABLE,
                  double[] standardDeviation = null,
                  double kernelSizeFactor = 2,
                  GaussianFilter2d.OutputType outputType = ImageDev.GaussianFilter2d.OutputType.SAME_AS_INPUT,
                  bool lowMemory = false,
                  IOLink.ImageView outputImage = null );

Class Syntax

Parameters

Parameter Name Description Type Supported Values Default Value
input
inputImage
The input image. The type of image can be integer or float. Image Binary, Label, Grayscale or Multispectral nullptr
input
filterMode
The algorithm implementation used to compute the gaussian filter.
SEPARABLE This mode uses a Finite Impulse Response algorithm on the X and Y directions.
RECURSIVE This mode uses an Infinite Impulse Response algorithm on the X and Y directions.
Enumeration SEPARABLE
input
standardDeviation
The standard deviation value for each direction (X, Y) in pixel units. Each value must be greater or equal to 0.0. Vector2d >=0 {1.f, 1.f}
input
kernelSizeFactor
This parameter is used to compute the size of the kernel applied in the SEPARABLE mode. The kernel size value is twice the kernelSizeFactor multiplied by the standard deviation associated with the axis. If the resulting kernel size is even, it is incremented by one in order to ensure an odd kernel size. This parameter is ignored in RECURSIVE mode. Float64 >0 2
input
outputType
The output data type. It can either be the same as the input type, or forced to be float. In the case of floating input images, this parameter has no effect.
SAME_AS_INPUT The output image has same type as the input image. In the case of integer images, this mode can lead to a loss of precision.
FLOAT_32_BIT The output image type is forced to floating point.
Enumeration SAME_AS_INPUT
input
lowMemory
This parameter defines if the SEPARABLE algorithm must limit its memory usage. If equal to false, a temporary 32-bit float image is used to store the result before casting it to the output type. The result is thus less precise and faster to compute when this parameter is set to true. This parameter is ignored in RECURSIVE mode. Bool false
output
outputImage
The output image. Dimensions, calibration, and interpretation of the output image are forced to the same values as the input. Image nullptr
Parameter Name Description Type Supported Values Default Value
input
input_image
The input image. The type of image can be integer or float. image Binary, Label, Grayscale or Multispectral None
input
filter_mode
The algorithm implementation used to compute the gaussian filter.
SEPARABLE This mode uses a Finite Impulse Response algorithm on the X and Y directions.
RECURSIVE This mode uses an Infinite Impulse Response algorithm on the X and Y directions.
enumeration SEPARABLE
input
standard_deviation
The standard deviation value for each direction (X, Y) in pixel units. Each value must be greater or equal to 0.0. vector2d >=0 [1, 1]
input
kernel_size_factor
This parameter is used to compute the size of the kernel applied in the SEPARABLE mode. The kernel size value is twice the kernelSizeFactor multiplied by the standard deviation associated with the axis. If the resulting kernel size is even, it is incremented by one in order to ensure an odd kernel size. This parameter is ignored in RECURSIVE mode. float64 >0 2
input
output_type
The output data type. It can either be the same as the input type, or forced to be float. In the case of floating input images, this parameter has no effect.
SAME_AS_INPUT The output image has same type as the input image. In the case of integer images, this mode can lead to a loss of precision.
FLOAT_32_BIT The output image type is forced to floating point.
enumeration SAME_AS_INPUT
input
low_memory
This parameter defines if the SEPARABLE algorithm must limit its memory usage. If equal to false, a temporary 32-bit float image is used to store the result before casting it to the output type. The result is thus less precise and faster to compute when this parameter is set to true. This parameter is ignored in RECURSIVE mode. bool False
output
output_image
The output image. Dimensions, calibration, and interpretation of the output image are forced to the same values as the input. image None
Parameter Name Description Type Supported Values Default Value
input
inputImage
The input image. The type of image can be integer or float. Image Binary, Label, Grayscale or Multispectral null
input
filterMode
The algorithm implementation used to compute the gaussian filter.
SEPARABLE This mode uses a Finite Impulse Response algorithm on the X and Y directions.
RECURSIVE This mode uses an Infinite Impulse Response algorithm on the X and Y directions.
Enumeration SEPARABLE
input
standardDeviation
The standard deviation value for each direction (X, Y) in pixel units. Each value must be greater or equal to 0.0. Vector2d >=0 {1f, 1f}
input
kernelSizeFactor
This parameter is used to compute the size of the kernel applied in the SEPARABLE mode. The kernel size value is twice the kernelSizeFactor multiplied by the standard deviation associated with the axis. If the resulting kernel size is even, it is incremented by one in order to ensure an odd kernel size. This parameter is ignored in RECURSIVE mode. Float64 >0 2
input
outputType
The output data type. It can either be the same as the input type, or forced to be float. In the case of floating input images, this parameter has no effect.
SAME_AS_INPUT The output image has same type as the input image. In the case of integer images, this mode can lead to a loss of precision.
FLOAT_32_BIT The output image type is forced to floating point.
Enumeration SAME_AS_INPUT
input
lowMemory
This parameter defines if the SEPARABLE algorithm must limit its memory usage. If equal to false, a temporary 32-bit float image is used to store the result before casting it to the output type. The result is thus less precise and faster to compute when this parameter is set to true. This parameter is ignored in RECURSIVE mode. Bool false
output
outputImage
The output image. Dimensions, calibration, and interpretation of the output image are forced to the same values as the input. Image null

Object Examples

auto polystyrene = ioformat::readImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "polystyrene.tif" );

GaussianFilter2d gaussianFilter2dAlgo;
gaussianFilter2dAlgo.setInputImage( polystyrene );
gaussianFilter2dAlgo.setFilterMode( GaussianFilter2d::FilterMode::SEPARABLE );
gaussianFilter2dAlgo.setStandardDeviation( {1.0, 1.0} );
gaussianFilter2dAlgo.setKernelSizeFactor( 2.0 );
gaussianFilter2dAlgo.setOutputType( GaussianFilter2d::OutputType::SAME_AS_INPUT );
gaussianFilter2dAlgo.setLowMemory( false );
gaussianFilter2dAlgo.execute();

std::cout << "outputImage:" << gaussianFilter2dAlgo.outputImage()->toString();

polystyrene = ioformat.read_image(imagedev_data.get_image_path("polystyrene.tif"))

gaussian_filter_2d_algo = imagedev.GaussianFilter2d()
gaussian_filter_2d_algo.input_image = polystyrene
gaussian_filter_2d_algo.filter_mode = imagedev.GaussianFilter2d.SEPARABLE
gaussian_filter_2d_algo.standard_deviation = [1.0, 1.0]
gaussian_filter_2d_algo.kernel_size_factor = 2.0
gaussian_filter_2d_algo.output_type = imagedev.GaussianFilter2d.SAME_AS_INPUT
gaussian_filter_2d_algo.low_memory = False
gaussian_filter_2d_algo.execute()

print("output_image:", str(gaussian_filter_2d_algo.output_image))

ImageView polystyrene = ViewIO.ReadImage( @"Data/images/polystyrene.tif" );

GaussianFilter2d gaussianFilter2dAlgo = new GaussianFilter2d
{
    inputImage = polystyrene,
    filterMode = GaussianFilter2d.FilterMode.SEPARABLE,
    standardDeviation = new double[]{1.0, 1.0},
    kernelSizeFactor = 2.0,
    outputType = GaussianFilter2d.OutputType.SAME_AS_INPUT,
    lowMemory = false
};
gaussianFilter2dAlgo.Execute();

Console.WriteLine( "outputImage:" + gaussianFilter2dAlgo.outputImage.ToString() );

Function Examples

auto polystyrene = ioformat::readImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "polystyrene.tif" );

auto result = gaussianFilter2d( polystyrene, GaussianFilter2d::FilterMode::SEPARABLE, {1.0, 1.0}, 2.0, GaussianFilter2d::OutputType::SAME_AS_INPUT, false );

std::cout << "outputImage:" << result->toString();

polystyrene = ioformat.read_image(imagedev_data.get_image_path("polystyrene.tif"))

result = imagedev.gaussian_filter_2d(polystyrene, imagedev.GaussianFilter2d.SEPARABLE, [1.0, 1.0], 2.0, imagedev.GaussianFilter2d.SAME_AS_INPUT, False)

print("output_image:", str(result))

ImageView polystyrene = ViewIO.ReadImage( @"Data/images/polystyrene.tif" );

IOLink.ImageView result = Processing.GaussianFilter2d( polystyrene, GaussianFilter2d.FilterMode.SEPARABLE, new double[]{1.0, 1.0}, 2.0, GaussianFilter2d.OutputType.SAME_AS_INPUT, false );

Console.WriteLine( "outputImage:" + result.ToString() );