-------------------------------------------
 The SubjectTools -> Fill WM (hi-res) menu item
 starts a background process to generate a white
 matter volume differently colored for the left
 and right hemisphere
-------------------------------------------
A 3-D region growing process is started from
specified right and left hemisphere points within
the white matter volume (wm/ COR dir, or wm.mgz),
which can be either 256^3 or 512^3.

 input3D: $SUBJECTS_DIR/$name/mri/wm[.mgz]

 output3D: $SUBJECTS_DIR/$name/mri/filled[.mgz]

Overview

First, RH and LH white matter seed starting
locations are manually defined by clicking points
in tkmedit (viewing the "wm[.mgz] data set) and
reading out native coordinates (N.B.: versus
Talairach coords in MGH freesurfer).  The seeds
can be anywhere in the respective white matter
halves.

Midbrain and callosal "cutting planes" are then
defined (see below for details).

Finally, fill algorithm parameters can be
adjusted (best not to change the conventional RH
and LH seed colors).

Region-growing algorithm

There are three stages to the "flood fill"
operation for each seed.  In the first stage, a
the region-growing algorithm builds up a
connected 3D volume from the inside-out.

Since this may result in internal voids, in the
second stage, the region-growing is performed
from the outside-in, up to the previously filled
volume.  This eliminates internal voids.

Finally, in the third stage , the volume is
refilled once more from inside-out to eliminate
any external voids that might have been
introduced in step two.

Specifying Cutting Planes -- details

To restrict the fill to the upper brainstem and
cortical white matter of a single hemisphere, two
"cutting planes" (actually thin 3D volumes) must
be specified.  These two volumes are each
specified by their bounding boxes (three pairs of
limits in the AP, IS, RL directions).  In each
case, one pair of limits will be only 3 voxels
wide.

First open the "wm[.mgz]" data set in tkmedit.
Then open the Expert Preferences -> WMFill tab to
enter the numbers you find.  The bounding boxes
are easily and quickly found and recorded by
using the following procedure.

Callosum Cut

  1) go to CORONAL view, click on mid callosum
  2) go to SAGITTAL view
  3) P/A:  posterior, anterior ends of callosum
  4) I/S:  zero to superior/top edge of callosum
  6) R/L:  one pix right and left of current R/L

Midbrain Cut

  1) go to near-midline SAGITTAL view, click just
       *below* inferior colliculus, just *above*
       where cerebellar white matter joins brainstem
  2) go to HORIZONTAL view
  3) P/A:  posterior, anterior ends of midbrain
  4) I/S:  one pix above and below current I/S
  5) R/L:  right and left of brainstem

For each pair of numbers, the second number
should be larger than the first.  Don't forget
that the CORONAL and HORIZONTAL views are
radiological, so smaller coords (the first entry
in each pair) are to the right in the display.

Adjustable Fill Parameters

These include the maximum number of back and
forth cycles for each fill, and the minimum
number filled per cycle before quitting (e.g.
100).  These two determine how many "wiggles" can
be filled (because the fill algorithm makes back
and forth passes, filling one additional "wiggle"
each pass).

Another adjustment is to the maximum same
neighbors during fill (the "wormhole filter").
With high quality data, a more accurate surface
can be obtained by turning Max Same Neigh down to
8.  If the data is noisy, this will introduce
more artifactual "wormholes".

Special cases

To fill a single volume, set the seed for one
hemisphere to a position outside the object in a
dark region with a voxel value below the fill
threshold ("thr:").

To disable the callosum and/or midbrain cutting
plane, set their inferior and superior limits to
0 and 1 (I=0, S=1).

