-------------------------------------------
entry variable: $patch -- absolute name patch file
-------------------------------------------
$SUBJECTS_DIR/$name/surf/$hemi.$type.patch.<3d,flat>

The "patch:" entry at the upper left shows the
current surface patch loaded (if any).  To load a
different patch for the current subject and
hemisphere, select a new available patch from the
"patch:" dropdown.  It will be auto-loaded (don't
have to click "R").

To select a new patch without loading it, do a
shift-select (e.g., to use a patch as a mask).

Relative name assumes same dir as above.  Home
dir of subject can be abbreviated as tilde (~).
Absolute name OK, too.

Patch files (binary, MSB) contain a list of
vertex numbers and 'replacement' 3D locations for
each listed vertex (possibly a subset) in the
base surface:

  header: [magic] vtxcnt
  vtxnum x y z
  vtxnum x y z
  ...

A negative vertex number indicates that the
vertex is on a cut border.  Any missing vertex
will not be shown.

Since a patch contain no information about faces,
a patch can only be read after first having read
a complete, base surface for a hemisphere (which
contains the specification of neighbor relations
and faces).

The patch naming convention is:

  $hemi.<patchtype>.patch.<3d,flat>

For example:

  rh.occip.patch.3d
  rh.occip.patch.flat
  rh.full.patch.3d
  rh.full.patch.flat

In order to get the settings (rot/scale/trans) in
the "Views" tab of Help -> Expert Preferences to
apply to a patch, the patchtype infix must start
with "full" or "occip" ("cortex" is a synonym for
"full", and "occ" is a synonym for "occip").

When a surface has been flattened, the
z-coordinate for all vertices is set to zero.

A patch can also be used like a label to "mask"
(show only vertices in patch) or "cut" (cut away
vertices in patch) (see "M" and "C" buttons on
"patch:" line).  This ignores the 'replacement'
3D vertex coordinates.

N.B.: a 2D patch won't be visible if its back
surface or one of its edges are toward the
viewer.  Therefore, to be sure a patch is visible
in tksurfer (given the default orientation of
patches in x,y,z space), be sure to first execute
the following two tcl commands:

  restore_zero_position
  rotate_brain_x -90

This is automatically done by the RESTORE button,
or when a patch is read with "R" on the "patch:"
line.

As mentioned above, the in-plane rotation,
scaling, and x-y position of the patch are
typically fine-tuned to fill the display window
using csurf -> Preferences -> Expert Preferences
-> Views (tab).  These entries will be filled
with useful starting values for full hemisphere
patches as well as smaller occipital patches.

================================================
HOWTO make cuts for full flattening
================================================

  (1) relaxation cuts -- LEFT-CLICK seq, LINE
  (2) remove midline -- LEFT-CLICK seq, AREA
  (3) fill keep region -- one LEFT-CLICK, FILL
  (4) save patch file -- WRITE (?h.full.patch.3d)

================================================
HOWTO touch-up a patch (use MESH to see dangling)
================================================

  (1) small trim: select list of vtxs, left-clk-PNTS
  (2) repair small cut: select edge vtxs, mid-clk-PNTS
  (3) repair big cut: make covering label, "label:" mid-clk-D

================================================
HOWTO flatten a 3D patch
================================================

  (1) select 3d patch in csurf ("patch:" combobox)
  (2) SubjectTools or MGHTools -> Flatten Surface

================================================
HOWTO use a patch to edit another surface/patch
================================================

A patch can be used to edit the current surface
(or another currently displayed patch).  The "M"
and "C" buttons on the "patch:" line will use the
patch in the entry to "M=mask" (delete anything
*not in* that selected patch) or "C=cut" (delete
anything *in* that selected patch).

Because selecting a patch from the "patch:"
dropdown normally auto-loads it, press left-Shift
when choosing the mask/cut patch to just select a
patch without auto-loading it.

These operations only use the vertex list in the
editing patch and ignore the vertex coordinates,
so a 3d patch from an inflated surface, for
example, can be used to edit any surface or patch
from that subject.


================================================
Binary patch file formats:

 old 2-byte short patch (binary, vertex subset):

  [no magic number]
  4-byte int patch vertex count
  [patch: vertex count sets of 4,2,2,2 bytes]
  4-byte int [+,-]1-based vertexnum (neg->border)
  [signed,1-based vtxnums -> pos,0-based to use]
  2-byte short patch vertex x-pos (mm*100)
  2-byte short patch vertex y-pos (mm*100)
  2-byte short patch vertex z-pos (mm*100)
   ...

 new 4-byte float patch (binary, vertex subset):

  4-byte int -1 magic number
  4-byte int patch vertex count
  [patch: vertex count sets of 4,4,4,4 bytes]
  4-byte int [+,-]1-based vertexnum (neg->border)
  [signed,1-based vtxnums -> pos,0-based to use]
  4-byte float patch vertex x-pos (mm)
  4-byte float patch vertex y-pos (mm)
  4-byte float patch vertex z-pos (mm)
   ...

