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.
       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.
 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.
     -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.
    -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.
       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.
 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.

    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)
    -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. 
    -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)
   -overwrite: Overwrite existing output dataset.
               Equivalent to setting env. AFNI_DECONFLICT=OVERWRITE
   -ok_1D_text: Zero out uncommented text in 1D file.
                Equivalent to setting env. AFNI_1D_ZERO_TEXT=YES
   -Dname=val: Set environment variable 'name' to value 'val'
             For example: -DAFNI_1D_ZERO_TEXT=YES
   -Vname=: Print value of environment variable 'name' to stdout and quit.
            This is more reliable that the shell's env query because it would
            include envs set in .afnirc files and .sumarc files for SUMA
            programs.
             For example: -VAFNI_1D_ZERO_TEXT=
   -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.
   -h_find WORD: Look for lines in this programs's -help output that match
                 (approximately) WORD.
   -h_view: Open help in text editor. AFNI will try to find a GUI editor
            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
            on your machine. You can control which it should use by
            setting environment variable AFNI_GUI_EDITOR.
   -skip_afnirc: Do not read the afni resource (like ~/.afnirc) file.
   -pad_to_node NODE: Output a full dset from node 0 to MAX_NODE-1
                   ** Instead of directly setting NODE to an integer you 
                      can set NODE to something like:
                   ld120 (or rd17) which sets NODE to be the maximum 
                      node index on an Icosahedron with -ld 120. See 
                      CreateIcosahedron for details.
                   d:DSET.niml.dset which sets NODE to the maximum node found
                      in dataset DSET.niml.dset.
                   ** This option is for surface-based datasets only.
                      Some programs may not heed it, so check the output if
                      you are not sure.
   -pif SOMETHING: Does absolutely nothing but provide for a convenient
                   way to tag a process and find it in the output of ps -a
   -echo_edu: Echos the entire command line to stdout (without -echo_edu)
              for edification purposes



Compile Date:
   May 10 2013

   Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov 
This page auto-generated on Sat May 11 16:35:54 EDT 2013