Usage: MapIcosahedron <-spec specFile>
[-rd recDepth] [-ld linDepth]
[-morph morphSurf]
[-it numIt] [-prefix fout]
[-NN_dset_map DSET]
[-dset_map DSET] [-fix_cut_surfaces]
[-verb] [-help] [...]
Creates new versions of the original-mesh surfaces using the mesh
of an icosahedron.
-spec specFile: spec file containing original-mesh surfaces
including the spherical and warped spherical surfaces.
You cannot use a specfile that has surfaces from both hemispheres.
Such spec files are usually called *_both.spec
You will need to run MapIcosahedron separately on each hemisphere
then use the program inspec to merge the two new spec files.
Say MapIcosahedron produced std.LH.spec and std.RH.spec,
you can use the following to merge them:
inspec -LRmerge std.LH_SPEC.spec std.RH_SPEC.spec \
-prefix std.BOTH_SPEC.spec
-rd recDepth: recursive (binary) tessellation depth for icosahedron.
(optional, default:3) See CreateIcosahedron for more info.
-ld linDepth: number of edge divides for linear icosahedron tessellation
(optional, default uses binary tessellation).
See CreateIcosahedron -help for more info.
*Note: Enter -1 for recDepth or linDepth to let program
choose a depth that best approximates the number of nodes in
original-mesh surfaces.
-morph morphSurf:
-NN_dset_map DSET: Map DSET onto the new mesh.
Use Nearest Neighbor interpolation
-dset_map DSET: Same as NN_dset_map but with barycentric interpolation
*Note: You can use repeated instances of either -NN_dset_map or -dset_map
to process multiple datasets at once.
Old Usage:
----------
State name of spherical surface to which icosahedron
is inflated. Typical example for FreeSurfer surfaces would be
'sphere.reg', and that's the default used by the program.
New Usage:
----------
State name or filename of spherical surface to which icosahedron
is inflated. Typical example for FreeSurfer surfaces would be
'sphere.reg', and that's the default used by the program.
Searching is first done assuming a State name and if that does
not return exactly one match, a search based on the filename
is carried out.
The following four options affect the geometric center and radius
settings of morphSurf. In previous versions, the geometric center
was set to the center of mass. A better estimate of the geometric
center is now obtained and this might make standard-mesh surfaces
less sensitive to distortions in the spherical surfaces.
With this change, the coordinates of the nodes will be silghtly
different from in previous versions. If you insist on the old
method, use the option -use_com below.
----------------------------------------------------------------
-sphere_at_origin: Geometric center of morphSurf sphere is at
0.0 0.0 0.0. This is usually the case but
if you do not know, let the program guess.
-sphere_center cx cy cz: Geometric center of morphSurf sphere.
If not specified, it will be estimated.
Note: It is best to specify cx cy cz or use -sphere_at_origin
when the center is known.
-use_com: (ONLY for backward compatibility)
Use this option to make the center of mass of morpSurf.
be the geometric center estimate. This is not optimal,
use this option only for backward compatibility.
The new results, i.e. without -use_com, should always be
better.
-sphere_radius R: Radius of morphSurf sphere. If not specified,
this would be the average radius of morpSurf.
----------------------------------------------------------------
-it numIt: number of smoothing iterations
(optional, default none).
-prefix FOUT: prefix for output files.
(optional, default 'std.')
-morph_sphere_check: Do some quality checks on morphSurf and exit.
This option now replaces -sph_check and -sphreg_check
See output of SurfQual -help for more info on this
option's output.
**********************************************
-sph_check and -sphreg_check are now OBSOLETE.
[-sph_check]:(OBSOLETE, use -morph_sphere_check instead)
Run tests for checking the spherical surface (sphere.asc)
The program exits after the checks.
This option is for debugging FreeSurfer surfaces only.
[-sphreg_check]: (OBSOLETE, use -morph_sphere_check instead)
Run tests for checking the spherical surface (sphere.reg.asc)
The program exits after the checks.
This option is for debugging FreeSurfer surfaces only.
-sph_check and -sphreg_check are mutually exclusive.
**********************************************
-all_surfs_spec: When specified, includes original-mesh surfaces
and icosahedron in output spec file.
(optional, default does not include original-mesh surfaces)
-verb: verbose.
-fix_cut_surfaces: Check and fix standard-mesh surfaces with cuts for
cross-cut connections.
-check_cut_surfaces: (default) Check standard-mesh surfaces with cuts for
cross-cut connections.
-forget_cut_surface: Do not check standard-mesh surfaces with cuts for
cross-cut connections.
-write_nodemap: (default) Write a file showing the mapping of each
node in the icosahedron to the closest
three nodes in the original mesh.
The file is named by the prefix of the output
spec file and suffixed by MI.1D
NOTE I: This option is useful for understanding what contributed
to a node's position in the standard meshes (STD_M).
Say a triangle on the STD_M version of the white matter
surface (STD_WM) looks fishy, such as being large and
obtuse compared to other triangles in STD_M. Right
click on that triangle and get one of its nodes (Ns)
search for Ns in column 0 of the MI.1D file. The three
integers (N0, N1, N2) on the same row as Ns will point
to the three nodes on the original meshes (sphere.reg)
to which Ns (from the icosahedron) was mapped. Go to N1
(or N0 or N2) on the original sphere.reg and examine the
mesh there, which is best seen in mesh view mode ('p' button).
It will most likely be the case that the sphere.reg mesh
there would be highly distorted (quite compressed).
NOTE II: The program also outputs a new mapping file in the format
that SurfToSurf likes. This format has the extension .niml.M2M
This way you can use SurfToSurf to map a new dataset from original
to standard meshes in the same way that MapIcosahedron would have
carried out the mapping.
For example, the following command creates standard meshes and
also maps thickness data onto the new meshes:
MapIcosahedron -spec rh.spec -ld 60 \
-dset_map rh.thickness.gii.dset \
-prefix std.60.
Say you want to map another (SOMEDSET) dataset defined on the
original mesh onto the std.60 mesh and use the same mapping derived
by MapIcosahedron. The command for that would be:
SurfToSurf -i_fs std.60.rh.smoothwm.asc \
-i_fs rh.smoothwm.asc \
-prefix std.60. \
-mapfile std.60.rh.niml.M2M \
-dset rh.SOMEDSET.gii.dset
-no_nodemap: Opposite of write_nodemap
-write_dist PREFIX: write distortions to PREFIX.LABEL
The mapping for 0,0,0-centered surfaces was previously distorted.
Write a file containing the node-wise distortion vectors.
One could then summarize that file using 1d_tool.py, as in:
1d_tool.py -collapse_cols euclidean_norm -show_mmms \
-infile PREFIX.LABEL.txt
or simply write out the euclidean norms for suma display:
1d_tool.py -collapse_cols euclidean_norm \
-infile PREFIX.LABEL.txt -write PREFIX.enorm.1D
NOTE 1: The algorithm used by this program is applicable
to any surfaces warped to a spherical coordinate
system. However for the moment, the interface for
this algorithm only deals with FreeSurfer surfaces.
This is only due to user demand and available test
data. If you want to apply this algorithm using surfaces
created by other programs such as SureFit and Caret,
Send saadz@mail.nih.gov a note and some test data.
NOTE 2: At times, the standard-mesh surfaces are visibly
distorted in some locations from the original surfaces.
So far, this has only occurred when original spherical
surfaces had topological errors in them.
See SurfQual -help and SUMA's online documentation
for more detail.
Compile Date:
Oct 17 2024
Brenna D. Argall LBC/NIMH/NIH
(contact) Ziad S. Saad SSC/NIMH/NIH saadz@mail.nih.gov
