#### write label data, vtxcols, MGHannot data ####
-------------------------------------------
funct: "All Visible To Label (left-click-W)"
  set label <outfile>    [must end in *.label]
  write_val_visible_vertices
-------------------------------------------
funct: "Labeled Vals to VtxCol (mid-click-W)"
  set label <label2convert>
  label_to_vtxcol_label
-------------------------------------------
funct: "Labeled Vals to Label (shift-mid-click-W)"
  set label <outfile>
  write_val_annoted_vertices
-------------------------------------------
funct: "AnnotCol Vals to Label (shift-left-click-W)"
  set label <outfile>
  write_val_annotedcol_vertices <r> <g> <b>
-------------------------------------------
funct: "AnnotCols Vals to Labels (shift-ctrl-left-clk-W)"
  set label <outfilepref>   [just: {lh,rh}-pref]
  write_val_annotedcols_vertices
-------------------------------------------
funct: "Selected Vertices/Vals to Label (ctrl-left-click-W)"
  set label <outfile>
  write_val_selected_list_to_label
-------------------------------------------
funct: "Assemble MGH Annot from LUT (ctrl-mid-clk-W)"
  set lulabel <CsurfColorLut.txt>
  set anlabel <outfile>
  write_mgh_annot
-------------------------------------------
funct: "Searchlights On Label (shift-ctrl-mid-click-W)"
  set label <outfile>
  write_searchlights <fillneartype> <criterion>
-------------------------------------------
funct: "AnnotCol Vals to Named (shift-ctrl-right-clk-W)"
  [output auto-named]
  write_val_annotedcol_autoname <r> <g> <b>
-------------------------------------------
funct: "Write Curr VtxCols to ColsFile (ctrl-right-clk-W)"
  set label <outfile>   [must end in *.cols]
  write_vtxcol_label
-------------------------------------------
funct: "Write Adjusted Phase to Label (shift-right-clk-W)"
  set label <outfile>
  write_adjphase_vertices
-------------------------------------------
funct: "Write StatIDs to RandCol MGH Annot (no hotkey)"
  set label <outfile>
  write_statids2randcolannot
-------------------------------------------
funct: "Sort Label By Dist Last Clicked Vtx (no hotkey)"
  set label <outfile>
  write_sorted_by_pathdist_label
-------------------------------------------
funct: "Write Region Centers to scriptsdir (no hotkey)"
  write_annot_region_centers
-------------------------------------------


Detailed Description of Label "W" Button Actions

-------------------------------------------
funct: "All Visible To Label (left-click-W)"
  set label <outfile>
  write_val_visible_vertices:
-------------------------------------------

Write out an ASCII label file using the name
$label (name in entry to left).  Any vertex
without its ripflag (invisible flag) set will be
written to the file -- that is, anything that is
currently visible in the surface window!
Typically, vertices-to-save are first selected by
doing a closed-line cut (AREA) followed by a FILL
*before* writing the label file.

N.B.: if you display a label with "D" and then
immediately write out a label file with "W", with
the whole surface visible, you won't make a copy
of the displayed label but will instead replace
the original (typically small) label file with
one that covers the whole surface (usu. not
intended!).

To edit an existing label, read in its data *and*
re-cut it with shift-middle-click "R" on the
"label:" line (N.B.: the "C" button also recuts
the label, but it clears the data fields).

Vertex number (field 1)

The first field in each label file line is
the vertex number.

Surface x,y,z Coordinates (fields 2,3,4)

The next three fields are the x,y,z coordinates
of each vertex.  There are five different
possibilities:

  (1) .orig surf coord
  (2) .orig surf coord incl. elevation along normal
  (3) .orig coord converted to MNI Talairach
  (4) .orig coord conv. to MNI Talairach w/elev. on normal
  (5) coord from current surface (e.g., .inflated)

In the first case, the x,y,z coordinates written
into the label file are come from the $origcoords
surface, which is typically $hemi.orig,
regardless of which surface is currently being
displayed.

For the second case (freesurfer surface
coordinates), turn ON $normdsampsearchflag (top
tickbox on popup from left-click on "label:"
label).  N.B.: this is now ON by default.  In
this case, the x,y,z coordinates will be elevated
along the normal to each vertex.  The elevation
distance can either be a fraction of the local
cortical thickness (if $normdfracflag is ON,
where the fraction is halfway between
$normdfracsamp and $normdfracmax) or a fixed
distance in mm (if $normdfracflag is OFF, where
the distance is halfway between $normdsamp and
$normdmax).  All those parameters are on the
popup.

For the third and fourth cases (Talairach
coordinates), turn on $usetalcoordsflag
(middle-click upper left "c2lab" tickbox), and
control elevation along the normal as above.

N.B.: the elevation along the normal should
usually be the same as that used when the 3D data
was sampled to the surface by the PAINT button.
The sampling parameters are save on the
SessionTools -> Setup Align/Funct Scans panel).

For the last case, left-click "c2lab" (no
elevation along normal possible in this case).

A different gray/white matter surface than .orig
can be used by resetting $origcoords with a tcl
script like this:

  setfile origcoords rh.orig2
  setfile origcoords /abs/path/to/surface

e.g., by using EDIT and RUN at middle upper left
of surfer tools panel (N.B.: this has no effect
if the current surface is a patch).

N.B.: if a patch has been displayed, the z coord
will be 0.0 for every vertex in this case.

Overlay Data (fields 5, optionally 6)

The data in the .val field that is written into
the label file comes from the currently visible
overlay data.  If no overlay data has been read,
the values will all be 0.0.  If the loaded data
is complex ($complexvalflag is set), then the
.val2 field is also written out (6 entries per
line instead of 5).

See help for the label entry field for more
information and examples of the label file
format.

-------------------------------------------
funct: "Labeled Vals to VtxCol (mid-click-W)"
  set label <label2convert>
  label_to_vtxcol_label
-------------------------------------------

If the "W" button is middle-clicked (instead of
default left-clicked), an alternate write label
function is called:

  label_to_vtxcol_label

This function reads the label file in the entry
to the left and then converts the data in it
using current color scale settings to a
"vertex-color label".

The filename of the vertex-color label ($vclabel)
is parallel to the label from which it was
created:

  ~/label/rh-V1.label => label in entry
  ~/label/rh-V1.cols => vertex-color label made

A vertex-color label (suffix: .cols) contains the
actual colors of each rendered vertex in a label
given all the tksurfer panel settings at the time
the vertex-color label is created (e.g.,
colscale, fmid, anglecycles, etc).  Note that
these colors are *before* lighting calculations
have been applied, so the same *.cols file can be
correctly displayed on differently shaped
surfaces.

Vertex-color labels can be used to assemble
results rendered with different color scales on a
single brain surface (see help for the label "R"
button).

The format of the vertex-color label file is a
single header line, followed by the number of
vertices followed by lines containing 4 entries
(vtxnum r g b). The rgb values are in the range
of 0.0 to 1.0, for example:

#!ascii , from subject claudia2
13617
26402   0.009   0.986   0.009
26403   0.016   0.975   0.016
26404   0.042   0.934   0.042
...

-------------------------------------------
funct: "Labeled Vals to Label (shift-mid-click-W)"
  set label <outfile>
  write_val_annoted_vertices
-------------------------------------------

If the "W" button is *shift*-middle-clicked
(instead of default left-clicked), yet another
alternate write label function is called:

  write_val_annoted_vertices

This function checks at each vertex whether an
annotation is being displayed (transparent label
location displayed with "D"), and then writes out
the values for those vertices (from vertex.val
field -- and vertex.val2 field if $complexvalflag
is set) to the label name in the entry.

N.B.: if an MGH annotation file is loaded, the
output label file will include all regions (see
next to write out one region from an annotation
file).

This is a short-cut way of using one or more
labels to save out a subset of the data currently
displayed on a surface that doesn't require
re-cutting the label.

N.B.: if $annotbordflag is ON (toggle with
shift-middle-click on leftmost tickbox on
"label:" line), only border vertices will be
included in each label.

-------------------------------------------
funct: "AnnotCol Vals to Label (shift-left-click-W)"
  set label <outfile>
  write_val_annotedcol_vertices <r> <g> <b>
-------------------------------------------

If the "W" button is *shift*-left-clicked
(instead of default left-clicked), yet another
alternate write label function is called:

  write_val_annotedcol_vertices <r> <g> <b>

This function is dumps vertex data for a single
color label from a displayed MGH annotation file.

The tksurfer interface takes the r,g,b values
from the current settings of r,g,b in the fields
to the right of the MESH button.  If an MGH
annotation has been displayed, those entries will
be automatically updated with the current
annotation color when any surface vertex is
clicked.

This function checks at each vertex whether an
annotation with the specified r,g,b values is
being displayed (transparent label location
displayed with "D") in the specified color, and
then writes out the values for those vertices
from the vertex.val field (and vertex.val2 field
if $complexvalflag is set) to the label name in
the entry.

HOWTO summary:

  1) load vertex data of interest to .val(.val2)
  2) display transparent MGH annot w/left-click "D"
  3) click one colored label to use (loads r,g,b color)
  4) set name in "label:" entry to desired output file
  5) Shift-left-click-"W"

N.B.: if $annotbordflag is ON (toggle with
shift-middle-click on leftmost tickbox on
"label:" line), only border vertices will be
included in each label.

N.B.: to display and dump data to label files
from a subset of labels, see the help for the "D"
button on the "label:" line (shift-R-click-D).

-------------------------------------------
funct: "AnnotCols Vals to Labels (shift-ctrl-left-clk-W)"
  set label <outfilepref>   [just: {lh,rh}-pref]
  write_val_annotedcols_vertices
-------------------------------------------

If the "W" button is *ctrl*-*shift*-left-clicked
(instead of default left-clicked), yet another
alternate write label function is called:

  write_val_annotedcols_vertices

This function is like the previous one, except
that it dumps vertex data for *every* color label
from the currently displayed MGH annotation file
into separate label files for each differently
colored region.

N.B.: instead of entering the name of a single
label file in the "label:" entry, you must enter
a prefix in the following form (for the last
component of the pathname):

  .../{rh,lh}-<infix>

That is:

  1) $hemi must match current
  2) third char must be '-' (dash)
  3) infix must be at least 1 character long

For infix "TEST" with the rh of HCP-MMP1, this
will generate a series of 180 label files
containing current vertex data that look like
this:

  .../rh-TEST_R_V1_ROI.label
  .../rh-TEST_R_MST_ROI.label
  .../rh-TEST_R_V6_ROI.label
  .../rh-TEST_R_V2_ROI.label
  [etc]

N.B.: if $annotbordflag is ON (toggle with
shift-middle-click on leftmost tickbox on
"label:" line), only border vertices will be
included in the labels.

N.B.: to display and dump data to label files
from a subset of labels, see the help for the "D"
button on the "label:" line (shift-R-click-D).

-------------------------------------------
funct: "Selected Vertices/Vals to Label (ctrl-left-click-W)"
  set label <outfile>
  write_val_selected_list_to_label
-------------------------------------------

If the "W" button is *ctrl*-left-clicked (instead
of default left-clicked), yet another alternate
write label function is called:

  write_val_selected_list_to_label

This dumps vertex data for all currently selected
vertices to a label file.

Like default write_val_visible_vertices, it loads
original surface coordinates (if not already
loaded), and can instead dump current surface
coordinates (if $usecurrcoordsflag is set to 1).

The inverse of this is read_label_to_select
(ctrl-left-click "D" on "label:" line).

N.B.: this function is sensitive to the state of
$bigcursorflag.  If $bigcursorflag is ON (see
R-click popup from REDRAW button) when this
function is executed, the the neighbors of
selected vertices will be included in the output
label.  This is useful when you want to outline
where a cut should be made using one surface,
convert those outlines to a label, and then
display that label on a different surface - for
example, to outline the cerebellar vermis on the
highly folded smoothwm surface where it is easier
to see, save that outline as a label, then
display it on the inflated surface, where the
cuts are much easier to make.

-------------------------------------------
funct: "Assemble MGH Annot from LUT (ctrl-mid-clk-W)"
  set lulabel <CsurfColorLut.txt>
  set anlabel <outfile>
  write_mgh_annot
-------------------------------------------

If the "W" button is *ctrl*-*middle*-clicked
(instead of default left-clicked), a popup is
made that runs yet an alternate write label
function:

  write_mgh_annot

This assembles multiple labels into a single MGH
annotation file using all of the region names and
colors from an MGH FreeSurfer LUT file.

(1) MGH FreeSurfer Color Lookup Table (LUT)
  [default name:]
  $CSURF_DIR/lib/lut/CsurfColorLUT.txt

(2) output .annot file
  [default name:]
  $SUBJECTS_DIR/$subject/label/$hemi-MY_ANNOT.annot

The dropdowns are loaded with all *.txt and
*.annot files in the default directories.

Change the "MY_ANNOT" infix to something more
useful (this is the default to avoid accidental
overwrites).  Here is an example of the format of
an MGH FreeSurfer LUT file (empty lines or lines
starting with '#' are ignored).  The numbers in
the "id" column cannot overlap, but they may
contain 'holes'.

#!ascii , CsurfColorLUT.txt (in $CSURF_DIR/lib/lut)
#------------------------------------------
#id	region(=labelinfix)		R      G      B      A
#------------------------------------------
 0	Unknown		0      0       0       0
 1	V1_lower		150   0      100    0
 2	V1_upper		150   0      120    0
14	V3_lower		0      50     200    0
15	VP_upper		0      50     220    0

To quickly comment-in or comment-out blocks of
regions from the output annotation, two
additional pseudo-comemnt directives are
recognized (the first of the three hash marks
must be the first character on the line, and and
the string must exactly match):

### include_following
### exclude_following

These toggle inclusion/exclusion of any following
region until the next (optional) directive.  You
can comment these directives out like this:

# ### include_following

N.B.: Though csurf tksurfer will accept and
display a FreeSurfer Color LUT containing
non-zero values for column A (alpha,
transparency), MGH tksurfer/freeview requires
that the color LUT value of alpha always be 0
(100% transparent, AKA invisible).  Therefore,
for compatibility, always use 0 as the last entry
in each FreeSurfer Color LUT line.  The
transparency of all labels can be adjusted
afterward with set_annot_alpha.

Each region or structure name (except "Unknown")
must have a corresponding csurf dash-style label
file in the current subject's label directory.
Using the example above for the right hemisphere
of the subject, fsaverage, the following label
files must exist:

  $SUBJECTS_DIR/fsaverage/label/rh-V1_lower.label
  $SUBJECTS_DIR/fsaverage/label/rh-V1_upper.label
  $SUBJECTS_DIR/fsaverage/label/rh-V3_lower.label
  $SUBJECTS_DIR/fsaverage/label/rh-VP_upper.label

If any are missing, they will be omitted from the
final combined annotation file.

Finally, click READY to assemble an MGH
annotation file containing these labels in these
colors.  The new assembled annotation file will
be displayed, followed by the number of hits per
vertex (this will be 2 on borders).  To
re-display the assembled annotation at another
time, select it, and use "D" on the "label:"
line.

The process will fail if there are any duplicate
region id numbers *or* duplicate colors in the
color LUT file (duplicates reported in popups).

Input labels may overlap.  The number of hits per
vertex (e.g., if labels overlap) is saved into
the .stat field and swapped to the surface at the
end to make it visible.  To save it, select a new
wfile name (e.g., <annotname>_nhits-$hemi.w) and
use "W" on the "val:" line.

Since the final annotation file will only contain
one region name and one color per vertex, the
last label file (as defined by the order of
regions in the LUT file) that contains a
particular vertex will control the structure name
and color for that vertex.

Vertices on the surface not included in any label
will be given structure name "Unknown" and will
always be displayed as completely transparent
(alpha=0).  The transparency of all other
structures is controlled by the "tran" entry at
the upper right.

Although csurf tksurfer read_mgh_annot can accept
*.annot files containing non-sequential region
idnums, these files will crash mris_convert and
are sometimes not read properly by freeview,
which uses similar utils/colortable.c functions.
Therefore, when tksurfer write_mgh_annot reads an
input FreeSurfer color LUT containing
non-sequential idnums, it will renumber them
sequentially in the .annot output file.

A second workaround needed to avoid mris_convert
crashes and freeview fail-to-reads is that the
header field in the output *.annot file for the
maximum idnum (which is a separate field from
idnum count) must be incremented by 1 over the
actual value (e.g., for sequentially renumbered
idnums 0,1,2,3, idmax must be set to 4, not 3).
Csurf tksurfer read_mgh_annot accepts either
incremented or incremented idmax.  The field that
has to be incremented is "maxstruc" here:

  https://surfer.nmr.mgh.harvard.edu/fswiki/LabelsClutsAnnotationFiles

How to do assemble an annotation with a tcl
script:

  ### set infile (default, but any source OK)
  set lulabel $CSURF_DIR/lib/lut/CsurfColorLUT.txt
  ### set outfile (setfile is csurf-specific glob)
  setfile anlabel ~/label/$hemi-MY_ANNOT.annot
  ### make annotation
  write_mgh_annot

-------------------------------------------
funct: "Searchlights On Label (shift-ctrl-mid-click-W)"
  set label <outfile>
  write_searchlights <fillneartype> <criterion>
-------------------------------------------

If the "W" button is *shift*-*ctrl*-middle-clicked
(instead of default left-clicked), yet another
alternate write label function is called:

  write_searchlights <fillneartype> <criterion>

This generates a single ASCII file of the
concatenated searchlights (vertex number lists)
for each vertex in the label, using distances
from the currently displayed surface.  Here is an
example format:

  #!ascii , 82934 searchlight centers, lab=/usr0/sessions/fsaverage/label/rh-MY_AREA.label, surf=rh.inflated,  fillneartype=1, criterion=250
  searchlight 0 vertex 3457
  3456
  3459
  ...
  searchlight 1 vertex 3878
  3874
  3881
  ...
  [to searchlight 82933]

When used interactively, the first function
argument, $fillneartype, is taken from the most
recent middle-click on the lower right buttons,
N, A, and R:

  middle-click N (number of vtxs: fillneartype=0)
  middle-click A (area in mm^2: fillneartype=1)
  middle-click R (radius in mm: fillneartype=2)

The second function argument, $criterion, is
taken from the entry between the N and A buttons.
Its meaning depends on the fillneartype (number
of vertices, area in mm^2, or radius in mm).

N.B.: for $fillneartype 1=area and 2=radius, the
number of vertices in each searchlight will vary
slightly.  To get a fixed number in each
searchlight, use $fillneartype=0.

For 250-vertex searchlights, this operation takes
roughly 1 min for every 2500 vertices in a label.

'Representative vertex' searchlights

To generate searchlights that only contain
'representative' unique vertices -- that is,
using only one vertex for each uniquely sampled
3D stat voxel -- load a 3D data set to specify
voxels, sample voxels to surface, and calculate
representative vertices before writing out
searchlights.

To find representative vertices interactively:

  left-click "val:" => changes to "val3d:"
  "val:" entry => select BRIK to define voxels
  left-click "R" => read BRIK
  left-click "label:" => set sampling parms in popup
  left-click "PAINT" => sample to surf, find uniqvox
  left-click-"UQ" => calc uniq vtxs

To find representative vertices in a tcl script:

  ### read 3D data BRIK to define voxels
  setfile statpatt */scandir1/some3Ddata+orig.BRIK
  read_native_stat 0          ;# 0 means real
  ### set sampling parms
  set normdsampsearchflag 1   ;# turn on norm search
  set normdfracsamp 0.5       ;# begin search
  set normdfracmax 0.5        ;# end search
  ### sample 3D data to surface, record uni vox IDs's
  paint_surface 0             ;# 0=justpaint
  ### calc/select/write uniq vtxs from uniq vox ID's
  find_uniqsamp_vertices
  select_uniqsamp_vertices
  write_uniqsamp_vertices

Finally, open the cross correlation panel with a
left-click on the "X" on the "label:" line and
tick:

  searchlightuniqflag

and optionally, if a fixed number of vertices per
searchlight are required (only works with the "N"
fillneartype=0 criterion):

  numafteruniqflag

The ASCII output file of searchlights is written
into the current subject's label directory:

  $SUBJECT_DIR/$subject/label/Spotlights.txt

-------------------------------------------
funct: "AnnotCol Vals to Named (shift-ctrl-right-clk-W)"
  [output auto-named]
  write_val_annotedcol_autoname <r> <g> <b>
-------------------------------------------

If the "W" button is *shift*-*ctrl*-right-clicked
(instead of default left-clicked), yet another
alternate write label function is called:

  write_val_annotedcol_autoname <r> <g> <b>

Once an MGH annotation has been loaded, this
function generates a single ASCII label file from
the currently clicked annotation region.  To pick
which region, first click it, which loads its r,g,b
values (into r,g,b fields right of "MESH" button).

This also saves any displayed data currently in
the .val(.val2) into the label (else zero if none
displayed).

The output label file is auto-named using the
current annotation region name, and is written
into the subject's label directory, for example:

  ~/label/rh-R_a9-46v_ROI.label

This allows extraction of annotation region, for
example, to edit it.  Except for output file
name, same as write_val_annotedcol_vertices.

-------------------------------------------
funct: "Write Curr VtxCols to ColsFile (ctrl-right-clk-W)"
  set label <outfile>   [must end in *.cols]
  write_vtxcol_label
-------------------------------------------

If the "W" button is *ctrl*-right-clicked
(instead of default left-clicked), yet another
alternate write label function is called:

  write_vtxcol_label

This writes any visible vertices that currently
have vtxcol "paint" to a new vtxcol file.  The
label file suffix entered in the "label:" line
entry must end in *.cols.  No file is written if
there are no currently visible vertices that have
been vtxcol'd.

Can used to combine vtxcol labels, or to save
vtxcol's generated by linrampphase2vtxcol.

-------------------------------------------
funct: "Write Adjusted Phase to Label (shift-right-clk-W)"
  set label <outfile>
  write_adjphase_vertices
-------------------------------------------

If the "W" button is *shift*-right-clicked
(instead of default left-clicked), yet another
alternate write label function is called:

  write_adjphase_vertices

During normal operation, the complex-valued phase
in Fourier analyzed data is processed on the fly
to generate a tweakable color map.  But the
underlying phase data - which contains offsets
due to hemodynamic delays as well as the starting
stimulus position, as well as phase reversals for
opposite hemispheres - is never modified.

This function provides a way to generate a
complex-valued label with estimated polar angle
that removes those offsets and reversals.

It requires that the original complex-valued
Fourier analyzed polar angle data has been
loaded, and that $angle_cycles is set to a
non-integral value (like 1.0001, to trigger a
polar angle color scale).  This function takes
account of the settings of $angle_cycles,
$angle_offset, $revphaseflag, and $invphaseflag
to write out an adjusted phase.

To obtain a label file containing polar angles
approximately between -pi/2 and pi/2 (positive
for the upper field, and negative for the lower
field, same for either hemisphere) given a
standard 64-sec cycle mapper stimulus starting at
zero degrees (right horizontal meridian) and
progressing in a counterclockwise direction,
adjust those parameters for each hemisphere
approximately as follows, before calling
write_adjphase_vertices:

  ### right hemisphere
  set angle_cycles 1.001
  set angle_offset 0.96
  set revphaseflag 1

  ### left hemisphere
  set angle_cycles 1.001
  set angle_offset 0.46
  set revphaseflag 0

The phases are written out as a 6-arg, ASCII
label file containing amplitude 1 complex
numbers.

Increasing $angle_cycles will linearly expand the
range of polar angles in the output file.  This
can be useful for data averaged across subjects,
where there will be a reduced range of polar
angles due to slight intersubject spatial
offsets, especially in the case of small visual
areas.  This causes a 'regression to the
horizontal meridian' in cross-subject average
data (too much blue).

To interactively check what the output will be,
click a vertex and check the value of "adja" in
the csurf log (final value on the first log line
output from a click on a vertex).  Ignore the
displayed colors (which will be reversed from the
'standard' polar angle scale, which is
lower/horiz/upper -> green/blue/red).

If the resulting adjusted phase label file is
read back in, to verify that the polar angles in
it are correct, click a vertex and look at the
val/val2 phase angle on the third log line output
from a click on a vertex, *not* the value of
"adja", which will now, confusingly, be
re-adjusted.

To see the standard colors for the adjusted data,
set parameters as follows (N.B.: same for both
hemispheres):

  set angle_cycles 1.6
  set angle_offset 0.5
  set revphaseflag 1

-------------------------------------------
funct: "Write StatIDs to RandCol MGH Annot (no hotkey)"
  set label <outfile>
  write_statids2randcolannot
-------------------------------------------

This reads the .stat field, assuming that there
are integers there and writes a random color
annotation file for each unique .stat integer.

Designed to save the results of running:

  neighop_val2stat <neiorder:1-6> <operation=3>
  grow_stat_idnums

The first function generates non-overlapping
patches of nearest vertex neighbor order size
(first- to sixth-order neighbors).  For
fsaverage, the neighbor counts for the different
order neighbors are:

  1-neighbors: 7
  2-neighbors: 19
  3-neighbors: 37
  4-neighbors: 61
  5-neighbors: 91
  6-neighbors: 127

The grow_stat_idnums function then fills in the
gaps as fairly as possible.

This was used to generate simulated cerebellar
granule cell patches.  For more details, see the
R-click help for the SMOOTH button under the
topic "paintballs".

-------------------------------------------
funct: "Sort Label By Dist Last Clicked Vtx (no hotkey)"
  set label <outfile>
  write_sorted_by_pathdist_label
-------------------------------------------

This reads the current label ("label:" entry) and
then sorts the lines in the file by the Euclidean
distance along a path from the last interactively
selected vertex (e.g., the beginning of a
single-vertex-wide label path).  It simply copies
any overlay data that may or may not be included
in the original label file.

The second vertex will be the closest to the
initially selected vertex, the third vertex will
be the closest to the second vertex, and so on
(so this is not equivalent to merely sorting
vertices by distance from the initial vertex).

Standard freesurfer/csurf labels are normally
written in vertex number order (but since the
csurf/freesurfer label-reading code ignores the
order of lines in the label file, the sorted file
will still be readable).  However, an external
program can now use the re-ordered lines in the
sorted output file to find the path order.

This function can successfuly sort a path label
containing a series of vertices along a line that
curves back on itself (as long as it doesn't
cross itself, since there is no linearity
constraint).

N.B.: this function overwrites the input label,
but first saves it aside with a tilde (~) suffix.

This is useful for sampling data (e.g., phase
data) along an arbitrary curved line of vertices.
First, save a standard label from a sequence of
selected vertices (write_val_selected_list_to_label,
or "Selected Vertices to Label" from R-click help
pop-up on "W" on "label:" line) that contains the
phase data you want, then path-sort that line
label using this function ("Sort Label By Dist
Last Clicked Vtx" on same popup).

This was first written to sort the geodesic path
output of mris_pmake.  It is also useful for sorting
a single vertex line label made by selecting
vertices along a line, but not necessarily in exact
path order (e.g., if missed vertices have been
filled in after roughing out the line).

-------------------------------------------
funct: "Write Region Centers to scriptsdir (no hotkey)"
  write_annot_region_centers
-------------------------------------------

This writes out the 3D average location (current
surface coordinates) of the vertices in each
region of an MGH annotation.  The vertex nearest
the average is found and its vertex number
appended.

This average calculation occurs when any label is
read with the "D" button on the "label:" line.

N.B.: the average is calculated from the surface
visible at the time the annotation file was read.
If the surface is subsequently interactively
changed, be sure to re-read the annotation file.

The ASCII file, AnnotRegionCenters.txt, is
written to the subject's scriptdir, e.g.,
$SUBJECTS_DIR/fsaverage/scripts, and looks
like this:

#IDnum  RegionName      Avgx    Avgy    Avgz    NearestVtxNum
#------------------------------------------------------------
#0      Unknown         [omit]
1       V1_lower        -29.51  -117.25 -20.54  9454
2       V1_upper        -27.02  -108.95 -34.63  90544
3       V2_lower        -25.82  -126.61 -14.81  156659
4       V2_upper        -22.74  -111.07 -45.03  62841
5       V3              -23.85  -129.02 -5.84   24153
6       VP              -14.54  -110.01 -49.08  62867
...

