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:
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
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:
- $x$, $y$ and $z$ represent the offsets from the pixel to process,
- $\sigma_x$, $\sigma_y$ and $\sigma_z$ is the standard deviation along each axis.
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 outputImage.
// 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 = nullptr );
This function returns outputImage.
// Function prototype.
gaussian_filter_3d(input_image: idt.ImageType,
filter_mode: GaussianFilter3d.FilterMode = GaussianFilter3d.FilterMode.SEPARABLE,
standard_deviation: Union[Iterable[int], Iterable[float]] = [1, 1, 1],
kernel_size_factor: float = 2,
output_type: GaussianFilter3d.OutputType = GaussianFilter3d.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
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
| Parameter Name | Description | Type | Supported Values | Default Value | |||||
|---|---|---|---|---|---|---|---|---|---|
 |
inputImage |
The input image. The type of image can be integer or float. |
Image | Binary, Label, Grayscale or Multispectral | nullptr | ||||
|
filterMode |
The algorithm implementation used to compute the gaussian filter.
|
Enumeration | SEPARABLE | |||||
|
standardDeviation |
The standard deviation value for each direction (X, Y, Z) in voxel units. Each value must be greater or equal to 0.0. | Vector3d | >=0 | {1.f, 1.f, 1.f} | ||||
|
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 | ||||
|
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.
|
Enumeration | SAME_AS_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 | |||||
 |
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_image |
The input image. The type of image can be integer or float. |
image | Binary, Label, Grayscale or Multispectral | None | ||||
|
filter_mode |
The algorithm implementation used to compute the gaussian filter.
|
enumeration | SEPARABLE | |||||
|
standard_deviation |
The standard deviation value for each direction (X, Y, Z) in voxel units. Each value must be greater or equal to 0.0. | vector3d | >=0 | [1, 1, 1] | ||||
|
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 | ||||
|
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.
|
enumeration | SAME_AS_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_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 | |||||
|---|---|---|---|---|---|---|---|---|---|
|
inputImage |
The input image. The type of image can be integer or float. |
Image | Binary, Label, Grayscale or Multispectral | null | ||||
|
filterMode |
The algorithm implementation used to compute the gaussian filter.
|
Enumeration | SEPARABLE | |||||
|
standardDeviation |
The standard deviation value for each direction (X, Y, Z) in voxel units. Each value must be greater or equal to 0.0. | Vector3d | >=0 | {1f, 1f, 1f} | ||||
|
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 | ||||
|
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.
|
Enumeration | SAME_AS_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 | |||||
|
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 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() );