gsmooth

• purpose
• usage
• examples
• comments
• error messages

Purpose:

This program will perform Gaussian smoothing of the input image.

Usage:

gsmooth input FWHM-x FWHM-y FWHM-z output [options]

options:

[-m maskfile]

restricts smooth to non-zero values in mask

[-o]

grants permission to overwrite output

[-p]

prevents default wraparound padding for periodic data)

[-r]

prevents default rescaling of data

[-s]

smears any wraparound padding into data

[-v]

suppresses notification of magnitude of rescaling)

where the following definitions apply:

input

the name of the file to be smoothed

FWHM-x

The full-width-at-half-maximum of the x-axis smoothing filter in millimeters (or whatever units you use for pixel sizes) not in units of pixels.

FWHM-y

The full-width-at-half-maximum of the y-axis smoothing filter in millimeters (or whatever units you use for pixel sizes) not in units of pixels.

FWHM-z

The full-width-at-half-maximum of the z-axis smoothing filter in millimeters (or whatever units you use for pixel sizes) not in units of pixels.

output

@usage 6@

maskfile

the name of the mask file

Examples:

• File pet1.img will be smoothed in-plane using an 8mm x 8mm (spatially isotropic since the x and y smoothing dimensions are identical) Gaussian filter and between planes using a 4 mm Gaussian filter to generate file spet1.img.
• The output will be rescaled, and the magnitude of the rescaling will be printed on the screen.
• An existing file called spet1.img not be overwritten
• Wraparound padding will be used, but will not be smeared into the data itself.

• Same as above except that no rescaling will be performed.

• Same as above except that smoothing will be masked according to nonzero values in file mask1.img.

Comments:

• This program uses Fourier convolution to smooth the input data. In order to prevent wraparound effects (e.g., smoothing data from the first plane into the last plane and vice versa), the image is padded with zeros in all three dimensions before smoothing. In order to prevent these zeros from smearing into the data (e.g., thereby making the first and last planes much darker than the middle planes) the program normalizes the data based on the extent to which it is contaminated by padding zeros.
• If you use the -s option, the normalization to compensate for contamination by padding zeros is eliminated. It is unlikely that you ever want to use this option except to convince yourself that it is a good idea to do such compensation.If you have periodic data, use the -p option instead to eliminate padding completely.
• If a mask file is specified, a similar normalization procedure to that used to exclude padding zeros is used to exclude areas within the mask.
• If your data is truly periodic (not likely for imaging data, the -p option will prevent the use of padding zeros. The Fourier routines implemented here do not demand that the data length be exact multiples of two, though the routine can become quite slow for arrays with dimensions that are large prime numbers when the -p option is used.
• It is critical that the voxel sizes in the header of the file that you are smoothing be correct since these values are used to convert the smoothing filter dimensions from units of millimeters to units of pixels. If your results look much smoother or much less smooth that what you expect, incorrect voxel dimensions are a likely culprit. In general, it is a good idea to always check the header voxel dimensions using scanheader before using this routine.
• If the image that you are smoothing has missing data (e.g., if it has been resliced from a different orientation), you will need to use a mask file with the -m option to prevent this missing data from being smoothed into the result. The easiest approach is to simply respecify the file that you are smoothing as the mask file.

Error messages: (alphabetical by case)

A file name must follow -m

• supply the mask file name

FWHM_x must be a nonnegative number

• provide a nonnegative number

FWHM_y must be a nonnegative number

• provide a nonnegative number

FWHM_z must be a nonnegative number

• provide a nonnegative number

File name that follows -m cannot start with -

• use a mask file that does not start with -

Sorry, flag -____ is not defined for this program

• review command line for undefined flags

The -m flag should only be used once

• don't redefine the mask file

the - flag cannot be used at the start of the input or output file name

• check syntax

unable to parse arguments, argument ____ was expected to consist of a - followed by a single character

• check syntax