-------------------------------------------
var,funct: load surface (topology must match startup)
  set insurf <surface>
  read_binary_surface
-------------------------------------------
N.B.: entry variable: $surfext -- surface suffix

Read/Load Surface

The "surf:" entry at the upper left shows the
*suffix* of the current surface (e.g., for
surface "rh.inflated", just "inflated" will be
shown).  To load a different surface for the
current subject and hemisphere, select a new
available surface (e.g., orig, smoothwm, white,
pial, inflated, sphere, sphere.reg) from the
"surf:" dropdown.

The new surface must have the same number of
vertices and faces as the surface tksurfer was
started up with.  The current surface pose,
magnification, and statistical overlay data (if
any) are preserved.

The suffix for a surface can also by typed into
the entry followed by <Return>.  An invalid entry
will reload the initial surface.  Finally, an
absolute path to a surface file can be entered
(it will be stripped to a suffix after it loads).

This entry uses the C/tcl function:

  read_binary_surface

to read the current surface in $insurf.  The
function can read native freesurfer triangular or
quadrangular surfaces in binary or ASCII format
(the C/tcl funct read_ascii_surface is a synonym
for read_binary_surface).  A number of other
surface formats are also auto-detected and
readable by this function:

  native FreeSurfer tri or quad: (binary)
  native FreeSurfer tri or quad: (ASCII)
  ICO tri: FreeSurfer icosahedral (ASCII)
  VTK tri: visualization toolkit format (ASCII)
  OFF tri: object file format (ASCII)
  GIFTI tri: NIFTI surface format (base64 ASCII)
  OBJ tri: Alias Wavefront (ASCII)
  SRF tri: Brain Voyager (binary)

The surface file format is auto-detected.  If
GIFTI surfaces are present matching the
case-sensitive pattern:

  *.{L,R}.*.surf.gii

their full names are loaded (since they usually
have no initial lh,rh prefix), and similarly for
OBJ files and SRF files matching these patterns:

  *.obj
  *.srf

If the tksurfer start-up surface is a triangular
surface, it can't be updated/changed to a
same-vertex-count quadrangular surface (can't
know which edges to remove) using this entry.
The reverse, however works (startup with quad
surface, update with same-vertex tri surface).

Since *.srf surfaces have left-handed coordinates
(PIL vs. freesurfer RAS coordinates), they will
appear mirror-imaged in tksurfer (a right hemi will
look like a left hemi, and vice versa, and you will
get a warning panel the first two times you open
the surface).  The surface coordinates can be
mirror-imaged (e.g., in order to save the surface
as a native freesurfer surface) with "FlipHemi" at
the upper right of the larger F3 interface (this
flips the sign of the x-coordinate).


Write Surface -- large interface panel ([fn]-F3)

The current state of a surface can be written
using the larger tksurfer interface available
with [fn]-F3 (typed with mouse focus on tksurfer
tools panel).  You can also toggle to the big
interface with the "i" button at the far upper
left on the smaller interface (and the far upper
right on the larger interface).

The upper right "outsurf:" entry has 7 buttons
(formats) on the right for writing out the
current surface:

  W	native freesurfer tri/quad formats (binary)
  ASC	native freesurfer format (ASCII)
  VTK	vtk 3.0 format (ASCII)
  OFF	object file fmt, incl color: OFF,COFF (ASCII)
  STL	stereolithography format: 3D printer (ASCII)
  GLB	glTF 2.0: GL transmission format (binary)
  OBJ	Alias/Wavefront object format (ASCII)

The corresponding tcl/C functions for writing
each of these six file types are:

  write_binary_surface
  write_ascii_surface
  write_vtk_surface
  write_off_surface
  write_stl_surface
  write_glb_surface
  write_obj_surface

See the R-click help for each button for more
details on each kind of output format.


Surface Geometry Binary Input File Formats

The following specification has been copied for
convenience from Help -> Csurf.  All of the
following surface formats are auto-detected by
the tcl/C function:

  read_binary_surface

There are two main types of surface formats for
individual brains in FreeSurfer.  The first
format contains quadrangles, which come from the
faces of the voxels categorized as white matter
touching not white matter.

  Quad Surface File Format (short vtx coords):
    -------------- header ---------------------
      3-byte magic number (16777215)
      3-byte int vertex count (~150,000)
      3-byte int face count (~150,000)
    ---------- vertex positions ---------------
      [vertex triples are implicitly numbered]
      2-byte int vertex x-position (mm x 100)
      2-byte int vertex y-position (mm x 100)
      2-byte int vertex z-position (mm x 100)
      ... [x,y,z triples up to vertex count]
    ---- vertex numbers around each face ------
      [faces are implicitly numbered]
      [vtx nums here implicit from above, 0-based]
      [num each face ordered CCW from outside]
      corner1 corner2 corner3 corner4
      ... [quadruples up to face count]
    -------------------------------------------

  New Quad Surface File Format (float vtx coord):
    -------------- header ---------------------
      3-byte magic number (16777213)
      3-byte int vertex count (~150,000)
      3-byte int face count (~150,000)
    ---------- vertex positions ---------------
      [vertex triples are implicitly numbered]
      4-byte float vertex x-position (mm)
      4-byte float vertex y-position (mm)
      4-byte float vertex z-position (mm)
      ... [x,y,z triples up to vertex count]
    ---- vertex numbers around each face ------
      [faces are implicitly numbered]
      [vtx nums here implicit from above, 0-based]
      [num each face ordered CCW from outside]
      corner1 corner2 corner3 corner4
      ... [quadruples up to face count]
    -------------------------------------------

  ASCII Quadrangle Surface File Format (ASCII):
    -------------- header ---------------------
      #!ascii ... quadrangles  ...
      vertexcount facecount
    ---------- vertex positions ---------------
      [vertex triples are implicitly numbered]
      x y z
      x y z
      ... [x,y,z triples up to vertex count]
    ---- vertex numbers around each face ------
      [faces are implicitly numbered]
      corner1  corner2  corner3  corner4
      corner1  corner2  corner3  corner4
      ... [quadruples up to face count]
    -------------------------------------------

The second surface file format contains triangles.
These are initially made by subdividing each
voxel-face quadrangle into two triangles.

  Triangle Surface File Format:
    -------------- header ---------------------
      3-byte magic number (16777214)
      less-than-200-char '\n'-terminated string
      [e.g., "created by %s=user on %s=time\n"]
      4-byte int vertex count (~150,000)
      4-byte int face count (~300,000)
    ---------- vertex positions ---------------
      [vertex triples are implicitly numbered]
      4-byte float vertex x-position (mm)
      4-byte float vertex y-position (mm)
      4-byte float vertex z-position (mm)
      ... [x,y,z triples up to vertex count]
    ---- vertex numbers around each face ------
      [faces are implicitly numbered]
      [vtx nums here implicit from above, 0-based]
      [num each face ordered CCW from outside]
      corner1 corner2 corner3
      ... [triples up to face count]
    -------------------------------------------

  ICO Triangle Surface File Format (ASCII):
    ---------- vertex positions ---------------
      163842  (ico7: ASCII vertex count)
      1   x1   y1   z1      (ic7.tri: radius=1)
      2   x1   y1   z2
      ... [numbered x,y,z triples to vtx count]
    ---- vertex numbers around each face ------
      327680   (ico7: ASCII face count)
      1   corner1  corner2  corner3
      2   corner1  corner2  corner3
      [vtx nums here are explicit nums above]
      [num each face ordered CCW from outside]
      ... [numbered triples to face count]
    -------------------------------------------

  ASCII Triangle Surface File Format (ASCII):
    -------------- header ---------------------
      #!ascii ... [triangles] ...
      vertexcount facecount
    ---------- vertex positions ---------------
      [vertex triples are implicitly numbered]
      x y z
      x y z
      ... [x,y,z triples up to vertex count]
    ---- vertex numbers around each face ------
      [faces are implicitly numbered]
      corner1  corner2  corner3
      corner1  corner2  corner3
      ... [triples up to face count]
    -------------------------------------------

  VTK Triangle Surface File Format (ASCII):
    -------------- header ---------------------
      # vtk DataFile Version 3.0
      <filename or other single-line info>
      ASCII
      DATASET POLYDATA
      POINTS <vertexcount> float
    ---------- vertex positions ---------------
      [vertex triples are implicitly numbered]
      x y z
      x y z
      ... [x,y,z triples up to vertex count]
    ---- vertex numbers around each face ------
      POLYGONS <facecount> <totaltokens>
      [faces are implicitly numbered]
      3  corner1  corner2  corner3
      3  corner1  corner2  corner3
      ... [4-tuples up to face count]
    -------------------------------------------
      [optional columns of vertex overlay data]
      [ignored if file read as surface]
      POINT_DATA <vertexcount>
      SCALARS EmbedVertex float <columncount>
      LOOKUP_TABLE default
      column1value column2value ... [columncount entries]
      column1value column2value ... [columncount entries]
      ... [implicitly num'd tuples to vertexcount]
    -------------------------------------------

  OFF Triangle Surface File Format (ASCII):
    -------------- header ---------------------
      OFF (or COFF)
      # comment line ...
      <vertex-count> <face-count> <edge-count>
    ---------- vertex positions ---------------
      [vertex triples are implicitly numbered]
      x y z
      x y z
      ... [x,y,z triples up to vertex count]
    ---- vertex numbers around each face ------
      [faces are implicitly numbered]
      3  corner1  corner2  corner3
      3  corner1  corner2  corner3
      ... [4-tuples up to face count]
    -------------------------------------------

  GIFTI Triangle Surface File Format (ASCII)
    -------------- header ---------------------
      <?xml version="1.0" encoding="UTF-8"?>
      <GIFTI xmlns:xsi="http://www.w3.org/...
         ...
         Version="1"
         NumberOfDataArrays="2">
        ...
        <DataArray Intent="NIFTI_INTENT_POINTSET"
                   DataType="NIFTI_TYPE_FLOAT32"
                   ArrayIndexingOrder="RowMajorOrder"
                   Dimensionality="2"
                   Dim0="32492"
                   Dim1="3"
                   Encoding="GZipBase64Binary"
                   Endian="LittleEndian"
                   ExternalFileName=""
                   ExternalFileOffset="0">
              ...
          <Data>
            [usu: base64 encoded gzipped binary floats]
          </Data>
        </DataArray>
        <DataArray Intent="NIFTI_INTENT_TRIANGLE"
                   DataType="NIFTI_TYPE_INT32"
                   ArrayIndexingOrder="RowMajorOrder"
                   Dimensionality="2"
                   Dim0="64980"
                   Dim1="3"
                   Encoding="GZipBase64Binary"
                   Endian="LittleEndian"
                   ExternalFileName=""
                   ExternalFileOffset="0">
          ...
          <Data>
            [usu: base64 encoded gzipped binary ints]
          </Data>
        </DataArray>
      </GIFTI>
    -------------------------------------------

  OBJ (Wavefront) Triangle Surface File Format (ASCII):
    -------------- header ---------------------
      # comment line (no req'd header)
      [vertex triples implicitly numbered]
      "v"  x  y  z  [r  g  b]
      "v"  x  y  z  [r  g  b]
      ... [x,y,z triples or sextuples up to vertex count]

      [normal triples implicitly num'd, norm maybe!=1]
      [N.B.: currently ignored here and recalc'd as usual]
      "vn"  x  y  z
      "vn"  x  y  z
      ... [x,y,z triples up to vertex count]

      [face triples implicitly num'd]
      [entries: vtx, vtx/tex, vtx//norm, vtx/tex/norm]
      [N.B.: vtx/tex/norm nums are 1-based!]
      [N.B.: ignores tex/norm nums]
      "f" vtx1 vtx2 vtx3
               *or*
      "f" vtx1/tex1 vtx2/tex2 vtx3/tex3
               *or*
      "f" vtx1//norm1 vtx2//norm2 vtx3//norm3
               *or*
      "f" vtx1/tex1/norm1 vtx2/tex2/norm2 vtx3/tex3/norm3
      ... [triples up to face count]
    -------------------------------------------

  SRF (BrainVoyager) Triangle Surface File Format (binary):
    -------------- header ---------------------
     4-byte float version (4)
     4-byte int reserved (must be 0)
     4-byte int vertexcnt
     4-byte int facecnt
     4-byte float centx
     4-byte float centy
     4-byte float centz
     vertexcnt*4-byte floats x (N.B.: left-handed coords!)
     vertexcnt*4-byte floats y
     vertexcnt*4-byte floats z
     vertexcnt*4-byte floats normal x (inward pointing!)
     vertexcnt*4-byte floats normal y
     vertexcnt*4-byte floats normal z
     4*4-byte float convex curv color r,g,b,a
     4*4-byte float concave curv color r,g,b,a
     vertexcnt*4-byte int vertex colors
     foreach vertex
       4-byte int neighbor count [N.B.: varies]
       count*4-byte int neighbors
     facecnt*3*4-byte int face corner vtx numbers
     [optional triangle strips]
    -------------------------------------------

