ij.plugin.filter
Class GaussianBlur

java.lang.Object
  ij.plugin.filter.GaussianBlur

All Implemented Interfaces:

ij.gui.DialogListener, ExtendedPlugInFilter, PlugInFilter

public class GaussianBlur
extends java.lang.Object
implements ExtendedPlugInFilter, ij.gui.DialogListener

This plug-in filter uses convolution with a Gaussian function for smoothing. 'Radius' means the radius of decay to exp(-0.5) ~ 61%, i.e. the standard deviation sigma of the Gaussian (this is the same as in Photoshop, but different from the previous ImageJ function 'Gaussian Blur', where a value 2.5 times as much has to be entered. - Like all convolution operations in ImageJ, it assumes that out-of-image pixels have a value equal to the nearest edge pixel. This gives higher weight to edge pixels than pixels inside the image, and higher weight to corner pixels than non-corner pixels at the edge. Thus, when smoothing with very high blur radius, the output will be dominated by the edge pixels and especially the corner pixels (in the extreme case, with a blur radius of e.g. 1e20, the image will be raplaced by the average of the four corner pixels). - For increased speed, except for small blur radii, the lines (rows or columns of the image) are downscaled before convolution and upscaled to their original length thereafter. Version 03-Jun-2007 M. Schmid with preview, progressBar stack-aware, snapshot via snapshot flag; restricted range for resetOutOfRoi

Field Summary

Fields inherited from interface ij.plugin.filter.ExtendedPlugInFilter

KEEP_PREVIEW

Fields inherited from interface ij.plugin.filter.PlugInFilter

CONVERT_TO_FLOAT, DOES_16, DOES_32, DOES_8C, DOES_8G, DOES_ALL, DOES_RGB, DOES_STACKS, DONE, FINAL_PROCESSING, NO_CHANGES, NO_IMAGE_REQUIRED, NO_UNDO, PARALLELIZE_STACKS, ROI_REQUIRED, SNAPSHOT, STACK_REQUIRED, SUPPORTS_MASKING

Constructor Summary

GaussianBlur()
Default constructor

Method Summary

boolean	blur(ImageProcessor ip, double radius) Gaussian Filtering of an ImageProcessor.
void	blur1Direction(FloatProcessor ip, double sigma, double accuracy, boolean xDirection, int extraLines) Blur an image in one direction (x or y) by a Gaussian.
void	blurFloat(FloatProcessor ip, double sigmaX, double sigmaY, double accuracy) Gaussian Filtering of a FloatProcessor.
void	blurGaussian(ImageProcessor ip, double sigmaX, double sigmaY, double accuracy) Gaussian Filtering of an ImageProcessor.
void	convolveLine(float[] input, float[] pixels, float[][] kernel, int readFrom, int readTo, int writeFrom, int writeTo, int point0, int pointInc) Convolve a line with a symmetric kernel and write to a separate array, possibly the pixels array of a FloatProcessor (as a row or column or part thereof)
boolean	dialogItemChanged(ij.gui.GenericDialog gd, java.awt.AWTEvent e) Listener to modifications of the input fields of the dialog
(package private) void	downscaleLine(float[] pixels, float[] cache, float[] kernel, int reduceBy, int pixel0, int unscaled0, int length, int pointInc, int newLength) Scale a line (row or column of a FloatProcessor or part thereof) down by a factor reduceBy and write the result into cache.
(package private) float[]	makeDownscaleKernel(int unitLength)
float[][]	makeGaussianKernel(double sigma, double accuracy, int maxRadius) Create a 1-dimensional normalized Gaussian kernel with standard deviation sigma and the running sum over the kernel Note: this is one side of the kernel only, not the full kernel as used by the Convolver class of ImageJ.
(package private) float[]	makeUpscaleKernel(int unitLength) Create a kernel for upscaling.
static void	resetOutOfRoi(ImageProcessor ip, int radius) Set the processed pixels above and below the roi rectangle back to their previous value (i.e., snapshot buffer).
void	run(ImageProcessor ip) This method is invoked for each slice during execution
void	setNPasses(int nPasses) Set the number of passes of the blur1Direction method.
int	setup(java.lang.String arg, ImagePlus imp) Method to return types supported
int	showDialog(ImagePlus imp, java.lang.String command, PlugInFilterRunner pfr) Ask the user for the parameters
(package private) void	showProgress(double percent)
(package private) void	upscaleLine(float[] cache, float[] pixels, float[] kernel, int reduceBy, int pixel0, int unscaled0, int writeFrom, int writeTo, int pointInc) Scale a line up by factor reduceBy and write as a row or column (or part thereof) to the pixels array of a FloatProcessor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GaussianBlur

public GaussianBlur()

Default constructor

Method Detail

setup

public int setup(java.lang.String arg,
                 ImagePlus imp)

Method to return types supported

Specified by:

setup in interface PlugInFilter

Parameters:

arg - unused

imp - The ImagePlus, used to get the spatial calibration

Returns:

Code describing supported formats etc. (see ij.plugin.filter.PlugInFilter & ExtendedPlugInFilter)

showDialog

public int showDialog(ImagePlus imp,
                      java.lang.String command,
                      PlugInFilterRunner pfr)

Ask the user for the parameters

Specified by:

showDialog in interface ExtendedPlugInFilter

Parameters:

imp - The active image already passed in the setup(arg, imp) call. It will be null, however, if the NO_IMAGE_REQUIRED flag has been set.

command - The command that has led to the invocation of the plugin-filter. Useful as a title for the dialog.

pfr - The PlugInFilterRunner calling this plugin-filter. It can be passed to a GenericDialog by addPreviewCheckbox to enable preview by calling the run(ip) method of this plugin-filter. pfr can be also used later for calling back the PlugInFilterRunner, e.g., to obtain the slice number currently processed by run(ip).

Returns:

The method should return a combination (bitwise OR) of the flags specified in interfaces PlugInFilter and ExtendedPlugInFilter.

dialogItemChanged

public boolean dialogItemChanged(ij.gui.GenericDialog gd,
                                 java.awt.AWTEvent e)

Listener to modifications of the input fields of the dialog

Specified by:

dialogItemChanged in interface ij.gui.DialogListener

setNPasses

public void setNPasses(int nPasses)

Set the number of passes of the blur1Direction method. If called by the PlugInFilterRunner of ImageJ, an ImagePlus is known and conversion of RGB images to float as well as the two filter directions are taken into account. Otherwise, the caller should set nPasses to the number of 1-dimensional filter operations required.

Specified by:

setNPasses in interface ExtendedPlugInFilter

run

public void run(ImageProcessor ip)

This method is invoked for each slice during execution

Specified by:

run in interface PlugInFilter

Parameters:

ip - The image subject to filtering. It must have a valid snapshot if the height of the roi is less than the full image height.

blur

public boolean blur(ImageProcessor ip,
                    double radius)

Gaussian Filtering of an ImageProcessor. This method is for compatibility with the previous code (before 1.38r) and uses a low-accuracy kernel, only slightly better than the previous ImageJ code

blurGaussian

public void blurGaussian(ImageProcessor ip,
                         double sigmaX,
                         double sigmaY,
                         double accuracy)

Gaussian Filtering of an ImageProcessor. If filtering is not applied to the full image height, the ImageProcessor must have a valid snapshot.

Parameters:

ip - The ImageProcessor to be filtered.

sigmaX - Standard deviation of the Gaussian in x direction (pixels)

sigmaY - Standard deviation of the Gaussian in y direction (pixels)

accuracy - Accuracy of kernel, should not be above 0.02. Better (lower) accuracy needs slightly more computing time.

blurFloat

public void blurFloat(FloatProcessor ip,
                      double sigmaX,
                      double sigmaY,
                      double accuracy)

Gaussian Filtering of a FloatProcessor. This method does NOT include resetOutOfRoi(ip), i.e., pixels above and below the roi rectangle will be also subject to filtering in x direction and must be restored afterwards (unless the full image height is processed).

Parameters:

ip - The FloatProcessor to be filtered.

sigmaX - Standard deviation of the Gaussian in x direction (pixels)

sigmaY - Standard deviation of the Gaussian in y direction (pixels)

accuracy - Accuracy of kernel, should not be above 0.02. Better (lower) accuracy needs slightly more computing time.

blur1Direction

public void blur1Direction(FloatProcessor ip,
                           double sigma,
                           double accuracy,
                           boolean xDirection,
                           int extraLines)

Blur an image in one direction (x or y) by a Gaussian.

Parameters:

ip - The Image with the original data where also the result will be stored

sigma - Standard deviation of the Gaussian

accuracy - Accuracy of kernel, should not be > 0.02

xDirection - True for bluring in x direction, false for y direction

extraLines - Number of lines (parallel to the blurring direction) below and above the roi bounds that should be processed.

downscaleLine

void downscaleLine(float[] pixels,
                   float[] cache,
                   float[] kernel,
                   int reduceBy,
                   int pixel0,
                   int unscaled0,
                   int length,
                   int pointInc,
                   int newLength)

Scale a line (row or column of a FloatProcessor or part thereof) down by a factor reduceBy and write the result into cache. Input line pixel # unscaled0 will correspond to output line pixel # 0. unscaled0 may be negative. Out-of-line pixels of the input are replaced by the edge pixels.

makeDownscaleKernel

float[] makeDownscaleKernel(int unitLength)

upscaleLine

void upscaleLine(float[] cache,
                 float[] pixels,
                 float[] kernel,
                 int reduceBy,
                 int pixel0,
                 int unscaled0,
                 int writeFrom,
                 int writeTo,
                 int pointInc)

Scale a line up by factor reduceBy and write as a row or column (or part thereof) to the pixels array of a FloatProcessor.

makeUpscaleKernel

float[] makeUpscaleKernel(int unitLength)

Create a kernel for upscaling. The kernel function is a convolution of four unit squares, i.e., four uniform kernels with value +1 from -0.5 to +0.5 (in downscaled coordinates). The second derivative of this kernel is smooth, the third is not. Its standard deviation is 1/sqrt(3) in downscaled cordinates. The kernel runs from [-2 to +2[, corresponding to array index 0 ... 4*unitLength (whereby the last point is not in the array any more).

convolveLine

public void convolveLine(float[] input,
                         float[] pixels,
                         float[][] kernel,
                         int readFrom,
                         int readTo,
                         int writeFrom,
                         int writeTo,
                         int point0,
                         int pointInc)

Convolve a line with a symmetric kernel and write to a separate array, possibly the pixels array of a FloatProcessor (as a row or column or part thereof)

Parameters:

input - Input array containing the line

pixels - Float array for output, can be the pixels of a FloatProcessor

kernel - "One-sided" kernel array, kernel[0][n] must contain the kernel itself, kernel[1][n] must contain the running sum over all kernel elements from kernel[0][n+1] to the periphery. The kernel must be normalized, i.e. sum(kernel[0][n]) = 1 where n runs from the kernel periphery (last element) to 0 and back. Normalization should include all kernel points, also these not calculated because they are not needed.

readFrom - First array element of the line that must be read. writeFrom-kernel.length or 0.

readTo - Last array element+1 of the line that must be read. writeTo+kernel.length or input.length

writeFrom - Index of the first point in the line that should be written

writeTo - Index+1 of the last point in the line that should be written

point0 - Array index of first element of the 'line' in pixels (i.e., lineNumber * lineInc)

pointInc - Increment of the pixels array index to the next point (for an ImageProcessor, it should be 1 for a row, width for a column)

makeGaussianKernel

public float[][] makeGaussianKernel(double sigma,
                                    double accuracy,
                                    int maxRadius)

Create a 1-dimensional normalized Gaussian kernel with standard deviation sigma and the running sum over the kernel Note: this is one side of the kernel only, not the full kernel as used by the Convolver class of ImageJ. To avoid a step due to the cutoff at a finite value, the near-edge values are replaced by a 2nd-order polynomial with its minimum=0 at the first out-of-kernel pixel. Thus, the kernel function has a smooth 1st derivative in spite of finite length.

Parameters:

sigma - Standard deviation, i.e. radius of decay to 1/sqrt(e), in pixels.

accuracy - Relative accuracy; for best results below 0.01 when processing 8-bit images. For short or float images, values of 1e-3 to 1e-4 are better (but increase the kernel size and thereby the processing time). Edge smoothing will fail with very poor accuracy (above approx. 0.02)

maxRadius - Maximum radius of the kernel: Limits kernel size in case of large sigma, should be set to image width or height. For small values of maxRadius, the kernel returned may have a larger radius, however.

Returns:

A 2*n array. Array[0][n] is the kernel, decaying towards zero, which would be reached at kernel.length (unless kernel size is limited by maxRadius). Array[1][n] holds the sum over all kernel values > n, including non-calculated values in case the kernel size is limited by maxRadius.

resetOutOfRoi

public static void resetOutOfRoi(ImageProcessor ip,
                                 int radius)

Set the processed pixels above and below the roi rectangle back to their previous value (i.e., snapshot buffer). This is necessary since ImageJ only restores out-of-roi pixels inside the enclosing rectangle of the roi (If the roi is non-rectangular and the SUPPORTS_MASKING flag is set).

Parameters:

ip - The image to be processed

radius - The range above and below the roi that should be processed

showProgress

void showProgress(double percent)