ImageDev

GaussianFilter3d

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

Access to parameter description

This algorithm performs a 3D smoothing filter whose impulse response is a Gaussian function. $$ f(x,y,z) = e^{ \frac{-x ^ 2 }{2\sigma_x ^ 2 } }e^{ \frac{-y ^ 2 }{2\sigma_y ^ 2 }} e^{ \frac{-z ^ 2 }{2\sigma_z ^ 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 separable way (a three-dimensional convolution separated in three 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 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
See related example

Function Syntax

This function returns the outputImage output parameter.
// Function prototype.
std::shared_ptr< iolink::ImageView >
gaussianFilter3d( std::shared_ptr< iolink::ImageView > inputImage,
                  GaussianFilter3d::FilterMode filterMode,
                  iolink::Vector3d standardDeviation,
                  double kernelSizeFactor,
                  GaussianFilter3d::OutputType outputType,
                  bool lowMemory,
                  std::shared_ptr< iolink::ImageView > outputImage = NULL );
This function returns the outputImage output parameter.
// Function prototype.
gaussian_filter_3d( input_image,
                    filter_mode = GaussianFilter3d.FilterMode.SEPARABLE,
                    standard_deviation = [1, 1, 1],
                    kernel_size_factor = 2,
                    output_type = GaussianFilter3d.OutputType.SAME_AS_INPUT,
                    low_memory = False,
                    output_image = None )
This function returns the outputImage output parameter.
// Function prototype.
public static IOLink.ImageView
GaussianFilter3d( IOLink.ImageView inputImage,
                  GaussianFilter3d.FilterMode filterMode = ImageDev.GaussianFilter3d.FilterMode.SEPARABLE,
                  double[] standardDeviation = null,
                  double kernelSizeFactor = 2,
                  GaussianFilter3d.OutputType outputType = ImageDev.GaussianFilter3d.OutputType.SAME_AS_INPUT,
                  bool lowMemory = false,
                  IOLink.ImageView outputImage = null );

Class Syntax

Parameters

Class Name GaussianFilter3d

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, Y, and Z directions.
RECURSIVE This mode uses an Infinite Impulse Response algorithm on the X, Y, and Z directions.
Enumeration SEPARABLE
input
standardDeviation
The standard deviation value for each direction (X, Y, Z) in voxel units. Each value must be greater than 0.0. Vector3d >=0 {1.f, 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

Object Examples

auto foam = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam.vip" );

GaussianFilter3d gaussianFilter3dAlgo;
gaussianFilter3dAlgo.setInputImage( foam );
gaussianFilter3dAlgo.setFilterMode( GaussianFilter3d::FilterMode::SEPARABLE );
gaussianFilter3dAlgo.setStandardDeviation( {1.0, 1.0, 1.0} );
gaussianFilter3dAlgo.setKernelSizeFactor( 2.0 );
gaussianFilter3dAlgo.setOutputType( GaussianFilter3d::OutputType::SAME_AS_INPUT );
gaussianFilter3dAlgo.setLowMemory( false );
gaussianFilter3dAlgo.execute();

std::cout << "outputImage:" << gaussianFilter3dAlgo.outputImage()->toString();
foam = imagedev.read_vip_image(imagedev_data.get_image_path("foam.vip"))

gaussian_filter_3d_algo = imagedev.GaussianFilter3d()
gaussian_filter_3d_algo.input_image = foam
gaussian_filter_3d_algo.filter_mode = imagedev.GaussianFilter3d.SEPARABLE
gaussian_filter_3d_algo.standard_deviation = [1.0, 1.0, 1.0]
gaussian_filter_3d_algo.kernel_size_factor = 2.0
gaussian_filter_3d_algo.output_type = imagedev.GaussianFilter3d.SAME_AS_INPUT
gaussian_filter_3d_algo.low_memory = False
gaussian_filter_3d_algo.execute()

print( "output_image:", str( gaussian_filter_3d_algo.output_image ) );
ImageView foam = Data.ReadVipImage( @"Data/images/foam.vip" );

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

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

Function Examples

auto foam = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam.vip" );

auto result = gaussianFilter3d( foam, GaussianFilter3d::FilterMode::SEPARABLE, {1.0, 1.0, 1.0}, 2.0, GaussianFilter3d::OutputType::SAME_AS_INPUT, false );

std::cout << "outputImage:" << result->toString();
foam = imagedev.read_vip_image(imagedev_data.get_image_path("foam.vip"))

result = imagedev.gaussian_filter_3d( foam, imagedev.GaussianFilter3d.SEPARABLE, [1.0, 1.0, 1.0], 2.0, imagedev.GaussianFilter3d.SAME_AS_INPUT, False )

print( "output_image:", str( result ) );
ImageView foam = Data.ReadVipImage( @"Data/images/foam.vip" );

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

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