gsmooth

• purpose
• usage
• examples
• comments
• error messages

Purpose:

Usage:

• [-o] (grants overwrite permission)
• [-r] (prevents rescaling of data)
• [-p] (prevents wraparound padding for periodic data)
• [-s] (smears any wraparound padding into data)
• [-v] (suppress notification of magnitude of rescaling
• [-m maskfile] (smoothing restricted to non-zero mask values)

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

The name of the output 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.
• 
  
• This program will propagate normalization (.nrm) files if and only if the -r option is used.

Error messages: (alphabetical by case)

A file name must follow -m

• recheck your command line

File name that follows -m cannot start with -

• recheck your command line

Files ____ and ____ have incompatible dimensions

• the file that you are smoothing and the mask file have different dimensions.

Smoothing kernels must all be nonnegative numbers

• recheck your command line

Sorry, flag -____ is not defined for this program

• recheck your command line

The -m flag should only be used once

• recheck your command line

WARNING: x dimension of filter was too small, no x smoothing applied

• The filter you specified is too narrow to be represented, the output should be otherwise correct.

WARNING: y dimension of filter was too small, no y smoothing applied

• The filter you specified is too narrow to be represented, the output should be otherwise correct.

WARNING: z dimension of filter was too small, no z smoothing applied

• The filter you specified is too narrow to be represented, the output should be otherwise correct.

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

• recheck your command line

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

• recheck your command line