-------------------------------------------
var,funct: write FreeSurfer ASCII surface
  set outsurf <surface>
  write_ascii_surface
-------------------------------------------

Large Panel Only: [fn-]F3

The "ASC" button on the "outsurf:" line on the
large fn-F3 panel writes out current surface as a
FreeSurfer ASCII file whose name is current value
of $outsurf (entry at left) after auto-appending
".asc" if it isn't already there.

The button checks overwrite but the equivalent
tclfunct, write_ascii_surface, doesn't.

Writes either a triangle or quandrangle file
depending on input surface and flags.  For a
triangle input file, a triangle output file is
written.  For a quadrangle input file, it may
have been subdivided into triangles upon read (if
$dividequadsflag is set to 1).  If so, it can
still be written out as quadrangles if
$undividequadsflag is set to 1.  Those two flags
can be set per-subject in csurf -> Expert
Preferences -> Surf Tab:

  "divide each quad into 2 trianagles" => dividequdsflag
  "write div'd->tri quads as quads" => undividequadsflag

Here is the same thing in pseudo code:

  if (vertices_per_face == 4) {
    write vertices coords list
    write quadface corners list
  }
  if (vertices_per_face == 3) {
    if (dividequadsdoneflag && undividequadsflag) {
      write vertices coords list
      write quadface corners list
    }
    else {   /* default tri input */
      write vertices coords list
      write triface corners list
    }
  }

Those flags can be set in Expert Preferences.

The format of the file is:

  --line 1 begins with "#!ascii"
  --line 2 contains vertex and face counts
  --list x,y,z coords each vertex (implicit num'd)
  --list vertex numbers of each face (implicitly num'd)

For example, a triangle surface file looks like:

  #!ascii version of surface -- FreeSurfer triangles ...
  153827 307650 
  8.523451 -92.493668 11.540395
  8.326207 -92.494865 11.582228
  ...
  ...
  0.804889 22.503111 18.786871
  0.761208 22.427162 18.935295
  0 1 3
  4 3 1
  ...
  ...
  122012 122938 121995
  121116 121982 122919

A fourth entry (e.g., 0) on each vertex
or face line is ignored.

A quad file is similar except that each face in
the face list has 4 entries instead of 3, and the
header line must include at least the string
"quadrang", for example:

  #!ascii version of surface -- FreeSurfer quadrangles ...
