This program will apply a Butterworth, Gabor, or weighted combination of Gaussian filters to each x, y, and z or x, y, and time volume in the input. These filters are applied in the frequency domain; the advantages or disadvantages of this technique as opposed to the filtering in the spatial domain that is done with 3D Filter are
Also of practical note is that the types of filters offered by this application and by the applications that filter in the spatial domain are quite different, and the availability of the filter you want will frequently limit your choice to one or the other.
The controls in the user interface include a standard set of controls for selecting the input file, output file, and region of interest and for starting and interrupting processing. The other controls are organized as follows:
Overview | Region processing | Swap z/time | Filter types | Inverse filter | Preprocessing | Edge handling | Output size | Command line
Priism | 2D Filter (spatial domain) | Convolution | 2D Filter (frequency domain) 3D Filter (spatial domain)
The three dimensions used for filtering can either be x, y, and z or x, y, and time. When the toggle button labeled "Swap z/time" is off, the program uses x, y, and z as the dimensions to filter. When that toggle button is on, the program uses x, y, and time as the dimensions to filter. When you select a new input file, the program will automatically select the dimension to use as the third dimension. If the file has more than one z section or only one time point, the program will use the z dimension as the third dimension; otherwise, it will use the time dimension as the third dimension.
Overview | Region processing | Swap z/time | Filter types | Inverse filter | Preprocessing | Edge handling | Output size | Command line
Four different types of filters are currently supported: Butterworth, Gabor, weighted combination of Gaussians, one minus a Gaussian times another Gaussian. Descriptions of the forms of these filters and the input parameters specific to each are given below.
A Butterworth filter has the following characteristics:
Two variants of Butterworth filters are provided, a smoothing filter which passes low frequencies and attenuates the high frequency components of the input and a sharpening filter which attenuates the low frequency components. The frequency which marks the transition between the slightly attenuated and highly attenuated frequencies is the cutoff frequency: the frequency response at the cutoff frequency is 1 / sqrt(2). In the input controls this frequency is specified as a fraction of the Nyquist frequency. The sharpness of the transition between the slightly and highly attenuated frequencies increases as the order of the filter increases.
A Gabor filter is a good choice for selecting the components of an image that contribute to a limited range of frequencies. The range selected has two components: one centered at a (kx, ky, kz) of
cf * (cos(a) * sin(b), sin(a) * sin(b), cos(b))
where kx is the x frequency, ky is the y frequency, kz is the z (or time) frequency, cf is the central frequency magnitude specified in the dialog, a is the central frequency theta, b is the central frequency phi. The other is at the same distance from zero frequency but radially opposite from the first. Both components are limited by an elliptical Gaussian envelope. One axis of the envelope is oriented along the radial direction from the zero frequency to the central frequency. Another axis (the "theta direction") is parallel to the plane kz = 0 and perpendicular to the radial axis. The width of the envelope along the axes is given in term of the sigma for the Gaussian.
The frequency response of this filter is radially symmetric about the zero frequency and is the weighted sum of up to four Gaussian envelopes. The number of Gaussians summed to give the filter is controlled by the field labeled Number of filters to combine. For each Gaussian there is central frequency, a width specified in terms of the Gaussian's sigma, and the amplitude at the central frequency. One common choice for the amplitudes of the Gaussians ensures that the frequency response at zero frequency is one. This generates a filter that does not change the mean of the data.
The frequency response of this filter is radially symmetric about the zero frequency and is one minus a Gaussian envelope multiplied by another, optional, Gaussian. For each Gaussian, there is a central frequency and a width, specified in terms of the Gaussian's sigma.
Overview | Region processing | Swap z/time | Filter types | Inverse filter | Preprocessing | Edge handling | Output size | Command line
Instead of applying the filter, you can apply it's inverse by turning on the "inverse" toggle button. The inverse filter is computed as a simplified Wiener filter:
H*(k) / (H(k) H*(k) + C)
where H(k) is the frequency response of the filter to be inverted, H*(k) is complex conjugate of H(k), and C is a non-negative constant. The application allows C to be set in two ways:
To set the value of C, "Set Wiener parameters" button in the main dialog to open the dialog with the controls for modifying C. If the "absolute" toggle button is on in that dialog, the value in the "Wiener factor" field is the value of C. If the "absolute" toggle button is off, the value in the "Wiener factor" field is the value of the multiplicative constant, and the three values in the "Cutoff frequencies" field are, respectively, the values of kxl, kyl, and kzl in units of cycles per pixel (i.e. the Nyquist frequency has a value of 0.5).
Overview | Swap z/time | Region processing | Filter types | Inverse filter | Preprocessing | Edge handling | Output size | Command line
The input region can be processed to remove an offset or trend before the data is padded and filtered. To display the controls for this processing, press the button labeled Set preprocessing in the main dialog. There are five types of processing that can be done; select one by pressing the appropriate toggle in the dialog. The processing options are:
Overview | Region processing | Swap z/time | Filter types | Inverse filter | Preprocessing | Edge handling | Output size | Command line
The dimensions of the input region can be extended by adding elements at the end of each dimension. This is typically done for two reasons:
To display the controls for the amount of padding and the values of the elements added, press the button labeled Set edge handling in the main dialog. For each dimension the Width field sets the number of elements that will be added. When the toggle labelled Use default width is on, the Width field will automatically be set so the padded size can be efficiently handled. There are three ways in which the values of the added elements are set. These are:
Overview | Region processing | Swap z/time | Filter types | Inverse filter | Preprocessing | Edge handling | Output size | Command line
The size of the region written to the output file may be different than the input size. The size is influenced by the controls to pad the input data before filtering, and the controls, described here, to trim the filtered result before saving it. To display the trimming controls, press the button labeled Set output size in the main dialog. This will open a dialog in which there is a set of controls for each dimension filtered. First the input size and the padded size of the region are listed. Below that are the toggles which control how the size in that dimension is trimmed. There are two mutually exclusive options for trimming:
Overview | Region processing | Swap z/time | Filter types | Inverse filter | Preprocessing | Edge handling | Output size | Command line
FFilter3D accepts the command-line arguments described in Region.html. In addition, FFilter3D accepts the options shown below (optional parts are shown in brackets). If mutually exclusive options (i.e. for selection of the type of filter or preprocessing), the last option that appears on the command line takes precedence. The defaults are to use a 2nd order Butterworth lowpass filter with a cutoff frequency of half of Nyquist, no preprocessing, padding with zeros to an efficient size in all directions, and to trim the output, if necessary, so that it is the same size as the selected input region.
-3d=z or -3d=t
-butterworth_smooth=filter_order:cutoff_freq
-butterworth_sharpen=filter_order:cutoff_freq
-fenhance=center_freq1:sigma1 or -fenhance=center_freq1:sigma1:center_freq2:sigma2
-gabor=freq_mag:freq_theta:freq_phi:sigma_radial:sigma_theta:sigma_phi
-gaussian_bank=filter_count
-gauss1=center_freq:sigma:amplitude
-gauss2=center_freq:sigma:amplitude
-gauss1 but sets the attributes for the
second filter in the bank of Gaussian filters.
-gauss3=center_freq:sigma:amplitude
-gauss1 but sets the attributes for the
third filter in the bank of Gaussian filters.
-gauss4=center_freq:sigma:amplitude
-gauss1 but sets the attributes for the
fourth filter in the bank of Gaussian filters.
-inverse
-subtract=value or -subtract=mean
-linear_detrend
-polyfit=n
-wiener=w
-wiener_cut option, this parameter
is used directly; otherwise, it is used as a multiplier for the average
amplitude of the high frequency components of the input volume divided
by the average amplitude for all frequency components in the input volume.
The default value is ten. The specified value must not be negative.
-wiener_cut=k or -wiener_cut=kx:ky:kz
-xpad=default or -xpad=n
-xpad_value=mean or -xpad_value=ramp or -xpad_value=rv[:iv]
-xpad_value=mean causes the data to be padded with the
mean value. -xpad_value=ramp causes the data to be padded
with values which range linearly from the value at one boundary to the
value at the other boundary. The last form causes the data to be
padded with a constant value whose real component is rv and
whose imaginary component is iv. If the imaginary component
is omitted, it is assumed to be zero.
-ypad=default or -ypad=n
-xpad but specifies the amount of padding
in the y dimension.
-ypad_value=mean or -ypad_value=ramp or -ypad_value=rv[:iv]
-xpad_value but specifies the padding values
for the y dimension.
-zpad=default or -zpad=n
-xpad but specifies the amount of padding
in the z dimension.
-zpad_value=mean or -zpad_value=ramp or -zpad_value=rv[:iv]
-xpad_value but specifies the padding values
for the z dimension.
-xtrim=default or -xtrim=n
-ytrim=default or -ytrim=n
-xtrim but controls the amount trimmed
from the y dimension before output.
-ztrim=default or -ztrim=n
-xtrim but controls the amount trimmed
from the z dimension before output.
As an example, the following command-line removes second order trends from the data in raw.dat, applies a Gabor filter, and places the result in out.dat:
FFilter3D raw.dat out.dat -polyfit=2 \
-gabor=0.24:135:45:0.16:0.16:0.16
Overview | Region processing | Swap z/time | Filter types | Inverse filter | Preprocessing | Edge handling | Output size | Command line