AFNI program: SurfSmooth
Output of -help
Usage: SurfSmooth <-spec SpecFile> <-surf_A insurf> <-met method>
Some methods require additional options detailed below.
I recommend using the -talk_suma option to watch the
progression of the smoothing in real-time in suma.
Method specific options:
LB_FEM: <-input inData.1D> <-fwhm f>
This method is used to filter data
on the surface.
LM: [-kpb k] [-lm l m] [-surf_out surfname]
This method is used to filter the surface's
geometry (node coordinates).
NN_geom: smooth by averaging coordinates of
nearest neighbors.
This method causes shrinkage of surface
and is meant for test purposes only.
Common options:
[-Niter N] [-output out.1D] [-h/-help]
[-add_index] [-ni_text|-ni_binary] [-talk_suma]
Detailed usage:
-spec SpecFile: Name of specfile containing surface of interest.
If the surface does not have a spec file, use the
program quickspec to create one.
-surf_A insurf: Name of surface of interest.
NOTE: i_TYPE inSurf option is now obsolete.
-met method: name of smoothing method to use. Choose from:
LB_FEM: The method by Chung et al. 03.
This method is used for filtering
data on the surface not for smoothing the
surface's geometry per se. See References below.
LM: The smoothing method proposed by G. Taubin 2000
This method is used for smoothing
a surface's geometry. See References below.
NN_geom: A simple nearest neighbor coordinate smoothing.
This interpolation method causes surface shrinkage
that might need to be corrected with the -match_*
options below.
Options for LB_FEM:
-input inData.1D: file containing data (in 1D format)
Each column in inData.1D is processed separately.
The number of rows must equal the number of
nodes in the surface. You can select certain
columns using the [] notation adopted by AFNI's
programs.
-fwhm f: Full Width at Half Maximum in surface coordinate units (usuallly mm)
of an equivalent Gaussian filter had the surface been flat.
With curved surfaces, the equation used to estimate FWHM is
an approximation.
Blurring on the surface depends on the geodesic instead
of the Euclidean disntaces. See Ref #1 for more details
on this parameter.
Options for LM:
-kpb k: Band pass frequency (default is 0.1).
values should be in the range 0 < k < 10
-lm and -kpb options are mutually exclusive.
-lm l m: Lambda and Mu parameters. Sample values are:
0.6307 and -.6732
NOTE: -lm and -kpb options are mutually exclusive.
-surf_out surfname: Writes the surface with smoothed coordinates
to disk. For SureFit and 1D formats, only the
coord file is written out.
NOTE: -surf_out and -output are mutually exclusive.
Options for NN_geom:
-match_size r: Adjust node coordinates of smoothed surface to
approximates the original's size.
Node i on the filtered surface is repositioned such
that |c i| = 1/N sum(|cr j|) where
c and cr are the centers of the smoothed and original
surfaces, respectively.
N is the number of nodes that are within r [surface
coordinate units] along the surface (geodesic) from node i.
j is one of the nodes neighboring i.
-match_vol tol: Adjust node coordinates of smoothed surface to
approximates the original's volume.
Nodes on the filtered surface are repositioned such
that the volume of the filtered surface equals,
within tolerance tol, that of the original surface.
See option -vol in SurfaceMetrics for information about
and calculation of the volume of a closed surface.
Common options:
-Niter N: Number of smoothing iterations (default is 100)
For practical reasons, this number must be a multiple of 2
NOTE: For LB_FEM method, the number of iterations controls the
iteration steps (dt in Ref #1).
dt = fwhm*fwhm / (16*Niter*log(2));
dt must satisfy conditions that depend on the internodal
distance and the spatial derivatives of the signals being
filtered on the surface.
As a rule of thumb, if increasing Niter does not alter
the results then your choice is fine (smoothing has converged).
For an example of the artifact caused by small Niter see:
http://afni.nimh.nih.gov/sscc/staff/ziad/SUMA/SuSmArt/DSart.html
-output out.1D: Name of output file.
The default is inData_sm.1D with LB_FEM method
and NodeList_sm.1D with LM method.
-add_index : Output the node index in the first column.
This is not done by default.
SUMA communication options:
-talk_suma: Send progress with each iteration to SUMA.
-refresh_rate rps: Maximum number of updates to SUMA per second.
The default is the maximum speed.
-sh : Name (or IP address) of the computer running SUMA.
This parameter is optional, the default is 127.0.0.1
-ni_text: Use NI_TEXT_MODE for data transmission.
-ni_binary: Use NI_BINARY_MODE for data transmission.
(default is ni_binary).
Common Debugging Options:
[-trace]: Turns on In/Out debug and Memory tracing.
For speeding up the tracing log, I recommend
you redirect stdout to a file when using this option.
For example, if you were running suma you would use:
suma -spec lh.spec -sv ... > TraceFile
This option replaces the old -iodbg and -memdbg.
[-TRACE]: Turns on extreme tracing.
[-nomall]: Turn off memory tracing.
[-yesmall]: Turn on memory tracing (default).
NOTE: For programs that output results to stdout
(that is to your shell/screen), the debugging info
might get mixed up with your results.
Sample commands lines for data smoothing:
SurfSmooth -spec quick.spec -surf_A NodeList.1D -met LB_FEM \
-input in.1D -Niter 100 -fwhm 8 -add_index \
-output in_sm8.1D
This command filters (on the surface) the data in in.1D
and puts the output in in_sm8.1D with the first column
containing the node index and the second containing the
filtered version of in.1D.
The surface used in this example had no spec file, so
a quick.spec was created using:
quickspec -tn 1D NodeList.1D FaceSetList.1D
You can colorize the input and output data using ScaleToMap:
ScaleToMap -input in.1D 0 1 -cmap BGYR19 \
-clp MIN MAX > in.1D.col \
ScaleToMap -input in_sm8.1D 0 1 -cmap BGYR19 \
-clp MIN MAX > in_sm8.1D.col \
For help on using ScaleToMap see ScaleToMap -help
Note that the MIN MAX represent the minimum and maximum
values in in.1D. You should keep them constant in both
commands in order to be able to compare the resultant colorfiles.
You can import the .col files with the 'c' command in SUMA.
You can send the data to SUMA with each iteration.
To do so, start SUMA with these options:
suma -spec quick.spec -niml &
and add these options to SurfSmooth's command line above:
-talk_suma -refresh_rate 5
Sample commands lines for surface smoothing:
SurfSmooth -spec quick.spec -surf_A NodeList.1D -met LM \
-output NodeList_sm100.1D -Niter 100 -kpb 0.1
This command smoothes the surface's geometry. The smoothed
node coordinates are written out to NodeList_sm100.1D.
Sample command for considerable surface smoothing and inflation
back to original size:
SurfSmooth -spec quick.spec -surf_A NodeList.1D -met NN_geom \
-output NodeList_inflated.1D -Niter 200 -match_vol 0.1
References:
(1) M.K. Chung et al. Deformation-based surface morphometry
applied to gray matter deformation.
Neuroimage 18 (2003) 198-213
M.K. Chung Statistical morphometry in computational
neuroanatomy. Ph.D. thesis, McGill Univ.,
Montreal, Canada
(2) G. Taubin. Mesh Signal Processing.
Eurographics 2000.
See Also:
ScaleToMap to colorize the output, however it is better
to load surface datasets directly into SUMA and colorize
them interactively.
++ SUMA version 2.5000, June 10 2004
Compile Date:
Aug 3 2004
Ziad S. Saad SSCC/NIMH/NIH ziad@nih.gov
This page generated on
Tue Aug 3 16:42:50 EDT 2004