-------------------------------------------
entry variable: $script -- current tcl script
-------------------------------------------
default: $CSURF_DIR/lib/tcl/twocond-views.tcl

The "tcl:" entry contains the current tcl script
to EDIT or run (GO).  When tksurfer has been
started from csurf it will typically be set to
the small tcl script that was used to start
tksurfer (rather than the default above).

The tcl script can be entered as absolute path:

  /tmp/my_script.tcl

or a path beginning with a poundsign (#), which
is an abbreviation for the standard script
library directory, $CSURF_DIR/lib/tcl:

  #/phasemovie.tcl

or as a relative path:

  my_script.tcl

which will look in the current working directory.
If tksurfer was started from csurf, the current
working directory will be the scripts directory
for the current session (or subject):

  $FUNCTIONALS_DIR/$session/image/scripts

or:

  $SUBJECTS_DIR/$subject/scripts

which is a good place in which to save save
session-specific (or subject-specific) tcl
scripts.  Any tcl scripts in there at tksurfer
startup will also appear in the "tcl:" dropdown.

Finally, there will always be the following entry
at the bottom of the dropdown:

  ~/tmp/TmpTclScript.tcl

which is a path to the tmp dir in the subject's
directory.  To edit and run a tmp script, do:

  select ~/tmp/TmpTclScript.tcl from the "tcl:" dropdown
  "EDIT" to open it in an editor (initially empty)
  [add tcl commands]
  [save]
  "GO" to run the script

Here is a tiny tmp script that sets the value of
a single variable and then displays its current
value in a pop-up:

  # set fmid and display its value
  set fmid 3.0
  confirmalert "fmid = $fmid"
  
Leaving the tcl script up in the editor gives
access to the tcl interpreter (without having to
start tksurfer from the command line).  Use
"return" to return early from a tcl script (to
skip the rest of it).

-------------------------------------------
Using variables/functions in user tcl scripts
-------------------------------------------

To find out the name of built-in tcl variables
and functions (linked to tksurfer C variables and
functions) that can be referenced and set/used in
scripts, use:

  tksurfer -h

Most of these variables and functions are linked
to C variables in tksurfer.c, so setting them in
a tcl global scope will update the C variable.

Some of the most commonly used tcl/C variables
that can be used in scripts include:

  $hemi		curr hemi (rh or lh)
  $scandir		curr scandir in "image" subdir
  $val		curr input/ouput wfile (full path)
  $label		curr input/ouput label (full path)
  $rgb		curr rgb output file (full path)

A commonly used tcl interface variable (no C) is:

  $smoothsteps		interface tcl var

Some of the most commonly used tcl/C functions
that can be used in scripts include:

  make_lateral_view			RESTORE button
  rotate_brain_x <deg>
  rotate_brain_y <deg>
  translate_brain_x <mm/currscale>
  translate_brain_y <mm/currscale>
  scale_brain <factor>
  redraw
  read_binary_values			uses $val
  write_binary_values			uses $val
  read_label_to_val			uses $label
  read_label_to_annot_using_col <r> <g> <b>
  write_val_visible_vertices			uses $label
  save_rgb			uses $rgb

The functions for reading and writing files
typically take no arguments but rather use the
current setting of a particular tcl/C filename
variable.  This filename is typically globbed
using the tcl-only function, "setfile", a
csurf-specific glob that expands abbreviations in
the path such as tilde (~), which stands for the
current subject and an asterisk (*) which stands
for the current session,  For example:

  setfile val */$scandir/polar+orig-$hemi.w
  setfile label ~/label/$hemi.BA3b
  setfile label */$scandir/$hemi-UniqSampVtxs.label
  setfile rgb */rgb/polar-$hemi-inflated-lat.tiff

The R-click help panels list the tcl variables
and function(s) they control/call at the top.

Look at $CSURF_DIR/lib/tcl/zz-examples/*.tcl for
examples of special-purpose scripts.

-------------------------------------------
HOWTO automate a set of interactive steps
-------------------------------------------

To automate a sequence of interactive steps,
simply left-click the "tcl:" label text (see its
R-click help).

This will echo (and save) the tcl commands
executed by each interface click so that they can
be copied into an cmdline script.

-------------------------------------------
Non-interactive command line operation
-------------------------------------------

The tcl script examples above assume that
tksurfer has already been started.  It is also
possible to start tksurfer and pass it a tcl
script name as an argument so that it can be
completely controlled non-interactively from a
command line shell.

Here is an example of a complete tcl script to
open a graphics window, read in a particular
surface (inflated), a curvature data set (curv),
a complex-valued overlay statistic data set
(polar1{_r,_i}-$hemi.w), and then render a
slightly rotated lateral view of the brain and
exit:

  open_window
  setfile insurf ~/surf/$hemi.inflated
  read_binary_surface
  setfile curv ~/surf/$hemi.curv
  read_binary_curv
  make_lateral_view
  set overlayflag 1
  set complexvalflag 1
  set statprefix polar1
  setfile val */$scandir/${statprefix}_i-$hemi.w
  smooth_val 10
  push_val_val2
  setfile val */$scandir/${statprefix}_r-$hemi.w
  smooth_val 10
  make_lateral_view
  rotate_brain_y 20
  redraw
  setfile rgb ~/rgb/polar1-rh-inflated-lat2.tiff
  save_rgb
  exit

Put these commands into a file, test.tcl,
in a functional session scripts directory.
This script can be run from the command line
as follows:

  cd $FUNCTIONALS_DIR/130625MS/image/scripts
  tksurfer marty rh smoothwm -tcl test.tcl

This script will work for any subject, session,
or hemisphere.  The only variable that has to be
adjusted is $statprefix.  The variables $hemi,
$subject, $session, and $scandir are autoset from
the command line and context).

If no images need to be viewed or saved (e.g.,
read vertwise file, perform surface-based
operations, write output date), it is not
necessary to open a graphics (GLX) window
(open_window, make_lateral view, redraw, etc).

Running tksurfer from a MacOS 10.11+ shell script

N.B.: on MacOS 10.11+, the environment variable 
DYLD_LIBRARY_PATH is *not* passed into a shell
script, which will prevent tksurfer from seeing
the csurf X11 tcl/tk libraries.  To use tksurfer 
in a MacOS 10.11+ shell script, include the
following line before the first call to tksurfer:

csh/tcsh:
 setenv DYLD_LIBRARY_PATH $CSURF_LIBRARY_PATH

sh/bash:
 export DYLD_LIBRARY_PATH=$CSURF_LIBRARY_PATH

-------------------------------------------
Standard movie-making tcl scripts
-------------------------------------------

There are 8 tcl scripts in $CSURF_DIR/lib/tcl for
making movies that can be run after a surface has
been displayed:

 offsetmovie.tcl		=> test all settings of $angle_offset
 phasemovie.tcl		=> moving phase stripe movie
 movie360.tcl		=> rotating brain loops, diff axes
 inflatemovie.tcl		=> inflation loop movies
 flattenmovie.tcl		=> flatten movies (adj pos/scale)
 annot2roi.tcl		=> fsavg annot -> 1sub -> 3D ROIs
 searchlightdiff.tcl		=> searchlight diffs (avg,types,var)
 explodemovie.tcl		=> for SFN 1992 :-}

These will loaded into the dropdown along with
any local tcl scripts in the current session and
subject "scripts" directories.

For more details, consult the R-click pop-up help
after opening one of the "RUN SCRIPT" panels with
the "GO" button on the "tcl:" line.

With minor additions (commented-out examples
inside), these can also be run from the command
line using:

  tksurfer <subj> <name> <hemi> <surfext> -tcl <script.tcl>
