BrainSkin


 A program to create an unfolded surface that wraps the brain (skin)
 and Gyrification Indices.

Usage 1:
  BrainSkin <-SURF> <-skingrid VOL> <-prefix PREFIX>
            [<-plimit PLIM>] [<-dlimit DLIM>] [<-segdo SEGDO>]


  Mandatory parameters:
     (-SURF):  An option for specifying the surface to smooth or
                 the domain over which DSET is defined.
                 (For option's syntax, see 'Specifying input surfaces'
                 section below).
     -skingrid VOL: A high-res volume to provide a grid for voxelization
                    steps. Typically this is the same volume used with
                    for the -sv option.
     -prefix PREFIX: Prefix to use for variety of output files.
                     Default is 'brainskin' and overwrite is turned on.

  Parameters used when finding node pairs spanning sulci:
     -plimit PLIM: maximum length of path along surface in mm.
                    Node pairing not considered if nodes are more than
                    PLIM along the surface.
                    Default is 50.
     -dlimit DLIM: maximum length of euclidean distance in mm.
                   Node pairing not considered if nodes have a Euclidean
                   distance of more than DLIM.
                   Default is 1000 mm. (no limit)
     -segdo SEGDO: Output a displayable object file that contains
                   segments between paired nodes.
             See 'Ctrl+Alt+s' in SUMA's interactive help

 Parameters for voxelization step:
     -voxelize VOXMETH: Voxelization method VOXMETH. Choose from:
                        slow: Sure footed but slow.
                        fast: Faster and works OK.
                        mask: Fastest and works OK too (default)
     -infill INFILLMETH: Infill method INFILLMETH. Choose from:
                        slow: proper infill, but not needed.
                        fast: brutish infill, all we need. (default)

  Esoteric Options:
     -out FILE: Output intermediary results from skin forming step

Output:
  Surfaces:
     PREFIX.stitch.gii: A bunch of triangles for closing the surface.
     PREFIX.skin.gii: Initial skin surface
     PREFIX.skin_simp.gii: Reduced mesh version of initial skin surface.
     PREFIX.skin.isotopic.gii: Original surface inflated inside skin surface
  Datasets:
     PREFIX.ptchvox+orig: Surface patching voxels.
     PREFIX.surfvox+orig: Voxels inside original surface
     PREFIX.skinvox+orig: Mix of ptchvox and surfvox.
     PREFIX.infilled+orig: skin vox dataset filled in.
     PREFIX.niml.dset: Results of computations for finding node pairs
                       that span sulci.
     PREFIX.areas.niml.dset: Results of computations for inflating
                             initial surface inside skin surface.
  Displayable Objects
     PREFIX.1D.do: Segments between node pairs spanning sulci.
Example:
   BrainSkin -spec std60.DemoSubj_lh.spec \
         -surf_A std60.lh.pial.asc \
         -sv DemoSubj_SurfVol+orig \
         -skingrid DemoSubj_SurfVol+orig. \
         -prefix stitched.std60.lh.f \
         -segdo stitched.std60.lh.1D.do \
         -overwrite

  Usage 2: Use a smooth surface to model outer contours of a mask volume

  BrainSkin <-vol_skin MASK> <-vol_hull MASK> [-prefix  PREFIX]

     -vol_skin MASK: Deform an Icosahedron to match the outer
                     boundary of a mask volume.
     -no_zero_attraction: With vol_skin, the surface will try to shrink
                          aggressively, even if there is no promise of
                          non-zero values below. Use this option if
                          you do not want zero values to attract the surface
                          inwards. This option is only useful with -vol_skin
                          and it must follow it.
     -vol_hull MASK: Deform an Icosahedron to match the convex
                     hull of a mask volume.
     -vol_skin and -vol_hull are mutually exclusive
     -node_dbg N: Output debugging information for node N for -vol_skin
                  and -vol_hull options.

  The program exits after creating the surface.
 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

 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.
     As with option -i, you can load template
     spec files with symbolic notation trickery as in:
                    suma -spec MNI_N27
     which will load the all the surfaces from template MNI_N27
     at the original FreeSurfer mesh density.
  The string following -spec is formatted in the following manner:
     HEMI:TEMPLATE:DENSITY where:
     HEMI specifies a hemisphere. Choose from 'l', 'r', 'lh', 'rh', 'lr', or
          'both' which is the default if you do not specify a hemisphere.
     TEMPLATE: Specify the template name. For now, choose from MNI_N27 if
               you want surfaces from the MNI_N27 volume, or TT_N27
               for the Talairach version.
               Those templates must be installed under this directory:
                 /home/afniHQ/.afni/data/
               If you have no surface templates there, download one of:
                 https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI_N27.tgz
                 https://afni.nimh.nih.gov/pub/dist/tgz/suma_TT_N27.tgz
                 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.
              This parameter is optional.
     The order in which you specify HEMI, TEMPLATE, and DENSITY, does
     not matter.
     For template surfaces, the -sv option is provided automatically, so you
     can have SUMA talking to AFNI with something like:
             suma -spec MNI_N27:ld60 &
             afni -niml /home/afniHQ/.afni/data/suma_MNI_N27

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

  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.
      -send_kth kth: Send the kth element to SUMA (default is 1).
                     This allows you to cut down on the number of elements
                     being sent to SUMA.
      -sh <SumaHost>: 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).
      -feed_afni: Send updates to AFNI via SUMA's talk.
   -np PORT_OFFSET: Provide a port offset to allow multiple instances of
                    AFNI <--> SUMA, AFNI <--> 3dGroupIncorr, or any other
                    programs that communicate together to operate on the same
                    machine.
                    All ports are assigned numbers relative to PORT_OFFSET.
         The same PORT_OFFSET value must be used on all programs
           that are to talk together. PORT_OFFSET is an integer in
           the inclusive range [1025 to 65500].
         When you want to use multiple instances of communicating programs,
           be sure the PORT_OFFSETS you use differ by about 50 or you may
           still have port conflicts. A BETTER approach is to use -npb below.
   -npq PORT_OFFSET: Like -np, but more quiet in the face of adversity.
   -npb PORT_OFFSET_BLOC: Similar to -np, except it is easier to use.
                          PORT_OFFSET_BLOC is an integer between 0 and
                          MAX_BLOC. MAX_BLOC is around 4000 for now, but
                          it might decrease as we use up more ports in AFNI.
                          You should be safe for the next 10 years if you
                          stay under 2000.
                          Using this function reduces your chances of causing
                          port conflicts.

         See also afni and suma options: -list_ports and -port_number for
            information about port number assignments.

         You can also provide a port offset with the environment variable
            AFNI_PORT_OFFSET. Using -np overrides AFNI_PORT_OFFSET.

   -max_port_bloc: Print the current value of MAX_BLOC and exit.
                   Remember this value can get smaller with future releases.
                   Stay under 2000.
   -max_port_bloc_quiet: Spit MAX_BLOC value only and exit.
   -num_assigned_ports: Print the number of assigned ports used by AFNI
                        then quit.
   -num_assigned_ports_quiet: Do it quietly.

     Port Handling Examples:
     -----------------------
         Say you want to run three instances of AFNI <--> SUMA.
         For the first you just do:
            suma -niml -spec ... -sv ...  &
            afni -niml &
         Then for the second instance pick an offset bloc, say 1 and run
            suma -niml -npb 1 -spec ... -sv ...  &
            afni -niml -npb 1 &
         And for yet another instance:
            suma -niml -npb 2 -spec ... -sv ...  &
            afni -niml -npb 2 &
         etc.

         Since you can launch many instances of communicating programs now,
            you need to know wich SUMA window, say, is talking to which AFNI.
            To sort this out, the titlebars now show the number of the bloc
            of ports they are using. When the bloc is set either via
            environment variables AFNI_PORT_OFFSET or AFNI_PORT_BLOC, or
            with one of the -np* options, window title bars change from
            [A] to [A#] with # being the resultant bloc number.
         In the examples above, both AFNI and SUMA windows will show [A2]
            when -npb is 2.



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