-------------------------------------------
 The MGHTools -> Flatten Surface menu item starts
 a two-part background process to create the
 flattened left and right hemisphere cortical
 surfaces (or surface portions)
-------------------------------------------
(1a) Flatten Right Hemisphere Surfaces
(1b) Flatten Left Hemisphere Surfaces

The input files are specified by the current
selection in the "patch:" entry.  For example,
"full.patch.3d" in the entry means, use these
input surfaces:

  $SUBJECTS_DIR/$name/surf/rh.full.patch.3d
  $SUBJECTS_DIR/$name/surf/lh.full.patch.3d

The output files in this case, will be:

  $SUBJECTS_DIR/$name/surf/rh.full.patch.flat
  $SUBJECTS_DIR/$name/surf/lh.full.patch.flat

To flatten only one hemisphere, first select
"RIGHT" or "LEFT".

To re-flatten a surface patch, select an
already-flattened surface in the "patch:" entry.
There will be a warning that you are
re-flattening an already flat surface (in case
this was not what you intended).  Note that in
this case, the final output will overwrite the
already flat input file, so copy it aside, or
start with a differently named copy if this is
not what you want.


Save/review flattening steps

For large complex-shaped surfaces (e.g., cut
cerebellum) it may help to re-flatten the
surface.  In addition, you may want to use an
intermediate step (e.g., of a re-flattening)
instead of the final result, which sometimes gets
stuck in a crinkled local minimum.  To save the
surfaces for intermediate steps, use a non-zero
value for:

  Expert Preferences -> Flatten tab -> write every x iter

When this is set to 0 (default), only the final
patch is saved.  If you are re-flattening, note
that this overwrite the input patch if you didn't
first copy it aside.  If this entry is instead
set to 10, for example, then given an input file:

  ~/surf/rh.ant.patch.flat

MGH Tools -> Flatten Surface Patch will write out
a series of patches named as follows:

  ~/surf/rh.ant.patch.flat0000
  ~/surf/rh.ant.patch.flat0010
  ~/surf/rh.ant.patch.flat0020
  . . .

as well as the final non-numbered output:

  ~/surf/rh.ant.patch.flat

To review the intermediate stages, use
flattenmovie.tcl to render some or all of them to
tiffs.  The relevant adjustable parameters in
flattenmovie.tcl are:

  f
  minflat
  maxflat
  every

where "f" is the starting frame number (so you
can append to a movie frame series by setting it
to a non-zero value), "min/maxflat" are the
beginning and ending appended numbers on the
intermediate patches above, and "every" is like
"write every x iter" (but it can be even less
often than that).

Note that flattenmovie generates a series of
sequentially numbered (%04d) frames so they can
be recognized as a frame sequence by QuickTime.
Note that this inconveniently requires
multiplying the frame number of the tiff by
"every" to find the patch number suffix.
