IsoSurface


Usage: A program to perform isosurface extraction from a volume.
  Based on code by Thomas Lewiner (see below).

  IsoSurface  < -input VOL | -shape S GR >
              < -isoval V | -isorange V0 V1 | -isocmask MASK_COM >
              [< -o_TYPE PREFIX>] [-Tsmooth KPB NITER]
              [< -debug DBG >]

  Mandatory parameters:
     You must use one of the following two options:
     -input VOL: Input volume.
     -shape S GR: Built in shape.
                  where S is the shape number,
                  between 0 and 9 (see below).
                  and GR is the grid size (like 64).
                  If you use -debug 1 with this option
                  a .1D volume called mc_shape*.1D is
                  written to disk. Watch the debug output
                  for a command suggesting how to turn
                  this 1D file into a BRIK volume for viewing
                  in AFNI.
     You must use one of the following iso* options:
     -isorois: Create isosurface for each unique value in the input volume
               This outputs multiple surfaces that are automatically named
               using PREFIX and the label and key corresponding to each of
               the ROIs to the extent that they are available.
               Example:
           IsoSurface -isorois -input TTatlas+tlrc'[0]' -o_gii auto.all
           suma -onestate -i auto.all.k*.gii
               You can also follow -isorois with the only ROI keys you want
               considered as in:
           IsoSurface -isorois 276 277 54 input TTatlas+tlrc'[0]'-o_gii auto
     -isorois+dsets: Same as -isorois, but also write out a labeled dataset
                     for each surface.               Example:
           IsoSurface -isorois+dsets -input TTatlas+tlrc'[0]' -o_gii auto.all
           suma -onestate -i auto.all.k*.gii
     -mergerois [LAB_OUT]: Combine all surfaces from isorois into one surface
                 If you specify LAB_OUT then a dataset with ROIs labels is
                 also written out and named LAB_OUT
                Example:
           IsoSurface -isorois -mergerois auto.all.niml.dset \
                      -input TTatlas+tlrc'[0]' -o_gii auto.all
           suma -i auto.all.gii
     -mergerois+dset: Same as -mergerois PREFIX, where PREFIX is the
                      prefix of the name you will use for the output surface.
                      The reason for this convenience function is that
                      suma now automatically loads a dataset that has the
                      same prefix as the loaded surface and this option saves
                      you from having to manually match the names.

     -isoval V: Create isosurface where volume = V
     -isorange V0 V1: Create isosurface where V0 <= volume < V1
     -isocmask MASK_COM: Create isosurface where MASK_COM != 0
        For example: -isocmask '-a VOL+orig -expr (1-bool(a-V))'
        is equivalent to using -isoval V.
     NOTE: -isorange and -isocmask are only allowed with -xform mask
            See -xform below for details.
     NOTE NOTE: Sometimes you can get the equivalent of the negative space
                of what you're expecting. If that is the case, try padding
                your volume with zeros on all sides and try again.
                You can do the padding with something like:
                3dZeropad -I 2 -S 2 -R 2 -L 2 -A 2 -P 2 -prefix ...

     -Tsmooth KPB NITER: Smooth resultant surface using the Taubin smoothing
                         approach in SurfSmooth and with parameters KPB and
                         NITER. If unsure, try -Tsmooth 0.1 100 for a start.
  Optional Parameters:
     -autocrop: Crop input volume (and any internally computed volume) before
                doing IsoSurface extraction. When you're running the program
                on largely empty datasets or with -isorois* then using
                -autocrop will make the program run faster. Either way
                the output should not change however.
     -remesh EDGE_FRACTION: Remesh the surface(s) to result in a surface with
                            N_edges_new = N_edges_old x EDGE_FRACTION
                            EDGE_FRACTION should be between 0.0 and 1.0
     -xform XFORM:  Transform to apply to volume values
                    before searching for sign change
                    boundary. XFORM can be one of:
            mask: values that meet the iso* conditions
                  are set to 1. All other values are set
                  to -1. This is the default XFORM.
            shift: subtract V from the dataset and then
                   search for 0 isosurface. This has the
                   effect of constructing the V isosurface
                   if your dataset has a continuum of values.
                   This option can only be used with -isoval V.
            none: apply no transforms. This assumes that
                  your volume has a continuum of values
                  from negative to positive and that you
                  are seeking to 0 isosurface.
                  This option can only be used with -isoval 0.
     -o_TYPE PREFIX: prefix of output surface.
        where TYPE specifies the format of the surface
        and PREFIX is, well, the prefix.
        TYPE is one of: fs, 1d (or vec), sf, ply.
        Default is: -o_ply

 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.


     -debug DBG: debug levels of 0 (default), 1, 2, 3.
        This is no Rick Reynolds debug, which is oft nicer
        than the results, but it will do.

  Built In Shapes:
     0: Cushin
     1: Sphere
     2: Plane
     3: Cassini
     4: Blooby
     5: Chair
     6: Cyclide
     7: 2 Torus
     8: mc case
     9: Drip

  NOTE:
  The code for the heart of this program is a translation of:
  Thomas Lewiner's C++ implementation of the algorithm in:
  Efficient Implementation of Marching Cubes' Cases with Topological Guarantees
  by Thomas Lewiner, Helio Lopes, Antonio Wilson Vieira and Geovan Tavares
  in Journal of Graphics Tools.
  http://www-sop.inria.fr/prisme/personnel/Thomas.Lewiner/JGT.pdf

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