AFNI program: SurfToSurf
Output of -help
Usage: SurfToSurf <-i_TYPE S1> [<-sv SV1>]
<-i_TYPE S2> [<-sv SV1>]
[<-prefix PREFIX>]
[<-output_params PARAM_LIST>]
[<-node_indices NODE_INDICES>]
[<-proj_dir PROJ_DIR>]
[<-data DATA>]
[<-node_debug NODE>]
[<-debug DBG_LEVEL>]
[-make_consistent]
This program is used to interpolate data from one surface (S2)
to another (S1), assuming the surfaces are quite similar in
shape but having different meshes (non-isotopic).
This is done by projecting each node (nj) of S1 along the normal
at nj and finding the closest triangle t of S2 that is intersected
by this projection. Projection is actually bidirectional.
If such a triangle t is found, the nodes (of S2) forming it are
considered to be the neighbors of nj.
Values (arbitrary data, or coordinates) at these neighboring nodes
are then transfered to nj using barycentric interpolation or
nearest-node interpolation.
Nodes whose projections fail to intersect triangles in S2 are given
nonsensical values of -1 and 0.0 in the output.
Mandatory input:
Two surfaces are required at input. See -i_TYPE options
below for more information.
Optional input:
-prefix PREFIX: Specify the prefix of the output file.
The output file is in 1D format at the moment.
Default is SurfToSurf
-output_params PARAM_LIST: Specify the list of mapping
parameters to include in output
PARAM_LIST can have any or all of the following:
NearestTriangleNodes: Use Barycentric interpolation (default)
and output indices of 3 nodes from S2
that neighbor nj of S1
NearestNode: Use only the closest node from S2 (of the three
closest neighbors) to nj of S1 for interpolation
and output the index of that closest node.
NearestTriangle: Output index of triangle t from S2 that
is the closest to nj along its projection
direction.
DistanceToSurf: Output distance (signed) from nj, along
projection direction to S2.
This is the parameter output by the precursor
program CompareSurfaces
ProjectionOnSurf: Output coordinates of projection of nj onto
triangle t of S2.
Data: Output the data from S2, interpolated onto S1
If no data is specified via the -data option, then
the XYZ coordinates of SO2's nodes are considered
the data.
-data DATA: 1D file containing data to be interpolated.
Each row i contains data for node i of S2.
You must have one row for each node making up S2.
In other terms, if S2 has N nodes, you need N rows
in DATA.
Each column of DATA is processed separately (think
sub-bricks, and spatial interpolation).
You can use [] selectors to choose a subset
of columns.
If -data option is not specified and Data is in PARAM_LIST
then the XYZ coordinates of SO2's nodes are the data.
-node_indices NODE_INDICES: 1D file containing the indices of S1
to consider. The default is all of the
nodes in S1. Only one column of values is
allowed here, use [] selectors to choose
the column of node indices if NODE_INDICES
has multiple columns in it.
-proj_dir PROJ_DIR: 1D file containing projection directions to use
instead of the node normals of S1.
Each row should contain one direction for each
of the nodes forming S1.
-make_consistent: Force a consistency check and correct triangle
orientation of S1 if needed. Triangles are also
oriented such that the majority of normals point
away from center of surface.
The program might not succeed in repairing some
meshes with inconsistent orientation.
Specifying input surfaces using -i or -i_TYPE options:
-i_TYPE inSurf specifies the input surface,
TYPE is one of the following:
fs: FreeSurfer surface.
If surface name has .asc it is assumed to be
in ASCII format. Otherwise it is assumed to be
in BINARY_BE (Big Endian) format.
Patches in Binary format cannot be read at the moment.
sf: SureFit surface.
You must specify the .coord followed by the .topo file.
vec (or 1D): Simple ascii matrix format.
You must specify the coord (NodeList) file followed by
the topo (FaceSetList) file.
coord contains 3 floats per line, representing
X Y Z vertex coordinates.
topo contains 3 ints per line, representing
v1 v2 v3 triangle vertices.
ply: PLY format, ascii or binary.
Only vertex and triangulation info is preserved.
byu: BYU format, ascii.
Polygons with more than 3 edges are turned into
triangles.
bv: BrainVoyager format.
Only vertex and triangulation info is preserved.
dx: OpenDX ascii mesh format.
Only vertex and triangulation info is preserved.
Requires presence of 3 objects, the one of class
'field' should contain 2 components 'positions'
and 'connections' that point to the two objects
containing node coordinates and topology, respectively.
gii: GIFTI XML surface format.
Note that if the surface filename has the proper extension,
it is enough to use the -i option and let the programs guess
the type from the extension.
Specifying surfaces using -t* options:
-tn TYPE NAME: specify surface type and name.
See below for help on the parameters.
-tsn TYPE STATE NAME: specify surface type state and name.
TYPE: Choose from the following (case sensitive):
1D: 1D format
FS: FreeSurfer ascii format
PLY: ply format
BYU: byu format
SF: Caret/SureFit format
BV: BrainVoyager format
GII: GIFTI format
NAME: Name of surface file.
For SF and 1D formats, NAME is composed of two names
the coord file followed by the topo file
STATE: State of the surface.
Default is S1, S2.... for each surface.
Specifying a Surface Volume:
-sv SurfaceVolume [VolParam for sf surfaces]
If you supply a surface volume, the coordinates of the input surface.
are modified to SUMA's convention and aligned with SurfaceVolume.
You must also specify a VolParam file for SureFit surfaces.
Specifying a surface specification (spec) file:
-spec SPEC: specify the name of the SPEC file.
Specifying a surface using -surf_? method:
-surf_A SURFACE: specify the name of the first
surface to load. If the program requires
or allows multiple surfaces, use -surf_B
... -surf_Z .
You need not use _A if only one surface is
expected.
SURFACE is the name of the surface as specified
in the SPEC file. The use of -surf_ option
requires the use of -spec option.
Specifying output surfaces using -o or -o_TYPE options:
-o_TYPE outSurf specifies the output surface,
TYPE is one of the following:
fs: FreeSurfer ascii surface.
fsp: FeeSurfer ascii patch surface.
In addition to outSurf, you need to specify
the name of the parent surface for the patch.
using the -ipar_TYPE option.
This option is only for ConvertSurface
sf: SureFit surface.
For most programs, you are expected to specify prefix:
i.e. -o_sf brain. In some programs, you are allowed to
specify both .coord and .topo file names:
i.e. -o_sf XYZ.coord TRI.topo
The program will determine your choice by examining
the first character of the second parameter following
-o_sf. If that character is a '-' then you have supplied
a prefix and the program will generate the coord and topo names.
vec (or 1D): Simple ascii matrix format.
For most programs, you are expected to specify prefix:
i.e. -o_1D brain. In some programs, you are allowed to
specify both coord and topo file names:
i.e. -o_1D brain.1D.coord brain.1D.topo
coord contains 3 floats per line, representing
X Y Z vertex coordinates.
topo contains 3 ints per line, representing
v1 v2 v3 triangle vertices.
ply: PLY format, ascii or binary.
byu: BYU format, ascii or binary.
gii: GIFTI format, ascii.
You can also enforce the encoding of data arrays
by using gii_asc, gii_b64, or gii_b64gz for
ASCII, Base64, or Base64 Gzipped.
If AFNI_NIML_TEXT_DATA environment variable is set to YES, the
the default encoding is ASCII, otherwise it is Base64.
Note that if the surface filename has the proper extension,
it is enough to use the -o option and let the programs guess
the type from the extension.
[-novolreg|-noxform]: Ignore any Rotate, Volreg, Tagalign,
or WarpDrive transformations present in
the Surface Volume.
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.
++ SUMA version 2006_7_3
CVS tag:
SUMA_2005_04_29_1733
Compile Date:
Jan 29 2009
Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov
Shruti Japee LBC/NIMH/NIH shruti@codon.nih.gov
This page auto-generated on
Fri Jan 30 20:02:43 EST 2009