AFNI program: ConvertSurface

Output of -help


Usage:  ConvertSurface <-i_TYPE inSurf> <-o_TYPE outSurf> 
                       [<-sv SurfaceVolume [VolParam for sf surfaces]>] 
                       [-tlrc] [-MNI_rai/-MNI_lpi][-xmat_1D XMAT]
    reads in a surface and writes it out in another format.
    Note: This is a not a general utility conversion program. 
    Only fields pertinent to SUMA are preserved.

 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.
       stl: STL format, ascii or binary.
            This format of no use for much of the surface-based
            analyses. Objects are defined as a soup of triangles
            with no information about which edges they share. STL is only
            useful for taking surface models to some 3D printing 
            software.
       mni: MNI .obj format, ascii only.
            Only vertex, triangulation, and node normals 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.
       obj: OBJ file format for triangular meshes only. The following
            primitives are preserved: v (vertices), f (faces, triangles
            only), and p (points)
 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.

 You can also specify multiple surfaces after -i option. This makes
 it possible to use wildcards on the command line for reading in a bunch
 of surfaces at once.

     -onestate: Make all -i_* surfaces have the same state, i.e.
                they all appear at the same time in the viewer.
                By default, each -i_* surface has its own state. 
                For -onestate to take effect, it must precede all -i
                options with on the command line. 
     -anatomical: Label all -i surfaces as anatomically correct.
                Again, this option should precede the -i_* options.

 More variants for option -i:
-----------------------------
 You can also load standard-mesh spheres that are formed in memory
 with the following notation
     -i ldNUM:  Where NUM is the parameter controlling
                the mesh density exactly as the parameter -ld linDepth
                does in CreateIcosahedron. For example: 
                    suma -i ld60
                create on the fly a surface that is identical to the
                one produced by: CreateIcosahedron -ld 60 -tosphere
     -i rdNUM: Same as -i ldNUM but with NUM specifying the equivalent
               of parameter -rd recDepth in CreateIcosahedron.

 To keep the option confusing enough, you can also use -i to load
 template surfaces. For example:
           suma -i lh:MNI_N27:ld60:smoothwm 
 will load the left hemisphere smoothwm surface for template MNI_N27 
 at standard mesh density ld60.
 The string following -i is formatted thusly:
     HEMI:TEMPLATE:DENSITY:SURF where:
     HEMI specifies a hemisphere. Choose from 'l', 'r', 'lh' or 'rh'.
          You must specify a hemisphere with option -i because it is 
          supposed to load one surface at a time. 
          You can load multiple surfaces with -spec which also supports 
          these features.
     TEMPLATE: Specify the template name. For now, choose from MNI_N27 if
               you want to use the FreeSurfer reconstructed surfaces from
               the MNI_N27 volume, or TT_N27
               Those templates must be installed under this directory:
                 /home/afniHQ/.afni/data/
               If you have no surface templates there, download
                 https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI_N27.tgz
               and/or
                 https://afni.nimh.nih.gov/pub/dist/tgz/suma_TT_N27.tgz
               and/or
                 https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI152_2009.tgz
               and untar them under directory /home/afniHQ/.afni/data/
     DENSITY: Use if you want to load standard-mesh versions of the template
              surfaces. Note that only ld20, ld60, ld120, and ld141 are in
              the current distributed templates. You can create other 
              densities if you wish with MapIcosahedron, but follow the
              same naming convention to enable SUMA to find them.
     SURF: Which surface do you want. The string matching is partial, as long
           as the match is unique. 
           So for example something like: suma -i l:MNI_N27:ld60:smooth
           is more than enough to get you the ld60 MNI_N27 left hemisphere
           smoothwm surface.
     The order in which you specify HEMI, TEMPLATE, DENSITY, and SURF, does
     not matter.
     For template surfaces, the -sv option is provided automatically, so you
     can have SUMA talking to AFNI with something like:
             suma -i l:MNI_N27:ld60:smooth &
             afni -niml /home/afniHQ/.afni/data/suma_MNI_N27 

    -ipar_TYPE ParentSurf specifies the parent surface. Only used
            when -o_fsp is used, see -o_TYPE options.
 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 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.
       stl: STL format, ascii or binary (see also STL under option -i_TYPE).
       byu: BYU format, ascii or binary.
       mni: MNI obj format, ascii only.
       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.
       obj: No support for writing OBJ format exists yet.
 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.

  Alternate GIFTI output qualifiers:
     You can alternately set gifti data arrays encoding with:
        -xml_ascii: For ASCII  (human readable)
        -xml_b64:   For Base64 (more compact)
        -xml_b64gz: For Base64 GZIPPED (most compact, needs gzip libraries)
     If AFNI_NIML_TEXT_DATA environment variable is set to YES, the
     the default is -xml_ascii, otherwise it is -xml_b64

    -orient_out STR: Output coordinates in STR coordinate system. 
                      STR is a three character string following AFNI's 
                      naming convention. The program assumes that the   
                      native orientation of the surface is RAI, unless you 
                      use the -MNI_lpi option. The coordinate transformation
                      is carried out last, just before writing the surface 
                      to disk.
    -native: Write the output surface in the coordinate system native to its
             format.
             Option makes sense for BrainVoyager, Caret/SureFit and 
             FreeSurfer surfaces.
             But the implementation for Caret/Surefit is not finished yet 
             (ask if needed).
    -make_consistent: Check the consistency of the surface's mesh (triangle
                      winding). This option will write out a new surface 
                      even if the mesh was consistent.
                      See SurfQual -help for mesh checks.
    -flip_orient: Flip the winding of the triangles
    -radial_to_sphere rad: Push each node along the center-->node direction
                           until |center-->node| = rad.
    -acpc: Apply acpc transform (which must be in acpc version of 
        SurfaceVolume) to the surface vertex coordinates. 
        This option must be used with the -sv option.
    -tlrc: Apply Talairach transform (which must be a talairach version of 
        SurfaceVolume) to the surface vertex coordinates. 
        This option must be used with the -sv option.
    -MNI_rai/-MNI_lpi: Apply Andreas Meyer Lindenberg's transform to turn 
        AFNI tlrc coordinates (RAI) into MNI coord space 
        in RAI (with -MNI_rai) or LPI (with -MNI_lpi)).
        NOTE: -MNI_lpi option has not been tested yet (I have no data
        to test it on. Verify alignment with AFNI and please report
        any bugs.
        This option can be used without the -tlrc option.
        But that assumes that surface nodes are already in
        AFNI RAI tlrc coordinates .
   NOTE: The vertex coordinates coordinates of the input surfaces are only
         transformed if -sv option is used. If you do transform surfaces, 
         take care not to load them into SUMA with another -sv option.

    -patch2surf: Change a patch, defined here as a surface with a mesh that
                 uses only a subset of the full nodelist, to a surface
                 where all the nodes in nodelist are used in the mesh.
                 Note that node indices will no longer correspond between
                 the input patch and the output surface.
    -merge_surfs: Merge multitudes of surfaces on the command line into one
                  big surface before doing anything else to the surface.
                  This is for the moment the only option for which you 
                  should specify more than one input surface on the command
                  line. For example:
            ConvertSurface -i lh.smoothwm.gii -i rh.smoothwm.gii \
                           -merge_surfs       -o_gii lrh.smoothwm.gii

   Options for coordinate projections:
   -node_depth DEPTHPREF: Project all coordinates onto the principal 
                          direction and output of depth/height of each
                          node relative to the outlying projection point.
                          This option is processed right before -pc_proj, 
                          should that option also be requested.
                          This option outputs file DEPTHPREF.pcdepth.1D.dset
                          which contains node index, followed by depth, then 
                          height of node. See also same option in SurfPatch

    -pc_proj ONTO PREFIX: Project coordinates onto ONTO, where ONTO is one 
                   of the parameters listed below.
              ONTO values for plane projections along various normals:
                       PC0_plane = normal is 1st principal vector
                       PC1_plane = normal is  2nd principal vector
                       PC2_plane = normal is  3rd principal vector
                       PCZ_plane = normal is  component closest to Z axis
                       PCY_plane = normal is  component closest to Y axis
                       PCX_plane = normal is  component closest to X axis
              ONTO values for line projections:
                       PC0_dir   = project along 1st principal vector
                       PC1_dir   = project along 2nd principal vector
                       PC2_dir   = project along 3rd principal vector
                       PCZ_dir   = project along component closest to Z axis
                       PCY_dir   = project along component closest to Y axis
                       PCX_dir   = project along component closest to X axis
              PREFIX is used to form the name of the output file containing 
                       the projected coordinates. File PREFIX.xyzp.1D.coord
                       contains the projected coordinates.
    Note: This is the last operation to be performed by this program, 
          and no surfaces are written out in the end.

    Options for applying arbitrary affine transform:
    [xyz_new] = [Mr] * [xyz_old - cen] + D + cen
    -xmat_1D mat: Apply transformation specified in 1D file mat.1D.
                  to the surface's coordinates.
                  [mat] = [Mr][D] is of the form:
                  r11 r12 r13 D1
                  r21 r22 r23 D2
                  r31 r32 r33 D3
                  or
                  r11 r12 r13 D1 r21 r22 r23 D2 r31 r32 r33 D3
    -ixmat_1D mat: Same as xmat_1D except that mat is replaced by inv(mat)
        NOTE: For both -xmat_1D and -ixmat_1D, you can replace mat with 
              one of the special strings:
              'RandShift', 'RandRigid', or 'RandAffine' which would create
              a transform on the fly. 
              You can also use 'NegXY' to flip the sign of X and Y 
              coordinates.
    -seed SEED: Use SEED to seed the random number generator for random
                matrix generation
    -XYZscale sX sY sZ: Scale the coordinates by sX sY sZ.
                        This option essentially turns sX sY sZ.
                        into a -xmat_1D option. So you cannot mix
                        and match.
    -xcenter x y z: Use vector cen = [x y z]' for rotation center.
                    Default is cen = [0 0 0]'
    -polar_decomp: Apply polar decomposition to mat and preserve
                   orthogonal component and shift only. 
                   For more information, see cat_matvec's -P option.
                   This option can only be used in conjunction with
                   -xmat_1D

   [-novolreg]: Ignore any Rotate, Volreg, Tagalign, 
                or WarpDrive transformations present in 
                the Surface Volume.
   [-noxform]: Same as -novolreg
   [-setenv "'ENVname=ENVvalue'"]: Set environment variable ENVname
                to be ENVvalue. Quotes are necessary.
             Example: suma -setenv "'SUMA_BackgroundColor = 1 0 1'"
                See also options -update_env, -environment, etc
                in the output of 'suma -help'
  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.


Global Options (available to all AFNI/SUMA programs)
  -h: Mini help, at time, same as -help in many cases.
  -help: The entire help output
  -HELP: Extreme help, same as -help in majority of cases.
  -h_view: Open help in text editor. AFNI will try to find a GUI editor
  -hview : on your machine. You can control which it should use by
           setting environment variable AFNI_GUI_EDITOR.
  -h_web: Open help in web browser. AFNI will try to find a browser.
  -hweb : on your machine. You can control which it should use by
          setting environment variable AFNI_GUI_EDITOR. 
  -h_find WORD: Look for lines in this programs's -help output that match
                (approximately) WORD.
  -h_raw: Help string unedited
  -h_spx: Help string in sphinx loveliness, but do not try to autoformat
  -h_aspx: Help string in sphinx with autoformatting of options, etc.
  -all_opts: Try to identify all options for the program from the
             output of its -help option. Some options might be missed
             and others misidentified. Use this output for hints only.
  


Compile Date:
   Oct 31 2024

   Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov 
This page auto-generated on Thu Oct 31 09:43:29 PM EDT 2024