Index of /sereno/csurf

############################################################################
csurf -- tk/X11/OpenGL progs for surface-based fMRI analysis/average/display
############################################################################

Csurf -- Winter 2025

Csurf provides applications for high-resolution surface- and
volume-based analysis and display of retinotopic and other kinds
of phase-encoded data.  It also includes tools for high-resolution
surface reconstruction.

=====================================================================
NEW: CsurfMaps1 vis/aud/som topological maps parcellation (fsaverage)
=====================================================================

Download sites:
  https://pages.ucsd.edu/~msereno/csurf
  https://mri.sdsu.edu/sereno/csurf

Files (all csurf0.8 *.tgz files unpack to just "curf"):
  ### primary download
  csurf0.8-mac-241112.tgz        MacOS 10.6+
  csurf0.8-linux64-241112.tgz    64-bit Linux CentOS 5.9+
  ### other download
  Csurf.app0.8-mac-241112.tgz    same as Mac above, with dockable app wrapper
  csurf0.8-linux32-241112.tgz    32-bit Linux CentOS 5.9+
  csurf0.8-macPPC-220812.tgz	 PowerPC (MacOS 10.4) 
  csurf0.8-irix-220812.tgz       IRIX 6.5.19
  ### data download
  fsaverage.tgz                  fs5.3 fsaverage w/CsurfMaps + fixed surfs/area
  fsaverage-ADDITIONS.tgz        just CsurfMaps1 additions to subj fsaverage
  fsaverage-labels/              unpacked CsurfMap1 labels/movies/illus/mapdata
  cereb/                         human post-mortem cerebellum surfaces, data

Csurf has facilities for:

  visual/auditory/somatomotor/cognitve topological map parcellations
  fourier phase map analysis (incl freq permutation test)
  surface-based clustering and FDR correction
  surface spotlight cross-correlation (incl complex-valued)
  fieldsign calculation and display
  complex-valued cross-subject topological map averaging
  curv/real/cmplx-phase/cmplx-amp surface gradient calculation and display
  multifactor spherical morphing (incl dual complex-valued map-driven)
  14 real and complex color scales, including user-defined LUT's
  extensive label manipulation tools (single labels, MGH annotation files)
  'unique-voxel' surface-based stats and timecourse extraction
     (i.e., use 1 representative vtx for each funct vox)
  precise manual registration
  display transparent labels, surf-normals/surface-gradient-arrows/DTi
  divergent/convergent stereo surface viewing
  render frames, scripted dynamic movies, offscreen/high-res bitmaps

A spreadsheet like interface is used to perform cross-subject
complex-valued retinotopic, tonotopic, and somatotopic averages
(surface-based and 3D).

The topological maps parcellation (*.annot, *.label.gii) are included
in $CSURF_DIR/subject/fsaverage-ADDITIONS, along with the fixed
inflated_avg surfaces, and fixed original surface area files (that
don't suffer from sulcal shrinkage), and finally, area-preserving
flattenings made from them (also available as a separate download
as fsaverage-ADDITIONS.tgz here).  There is a csurf sh script,
$CSURF_DIR/bin/noarch/update-fsaverage, to safely and non-destructively
copy these files into your writable copy of the $SUBJECTS_DIR/fsaverage
subject.

Every interface action in tksurfer and tkmedit can report its tcl
script equivalent, so any interface action can be easily scripted
for non-interactive command line operation (no graphics window
required if no bitmap saving).  All command line programs run by
csurf are explicitly logged.

Csurf is designed to be used alongside a standard, separate
installation of MGH freesurfer that will be used for making standard
resolution surfaces.  It can display and use the HCP-MMP1 parcellation
(included in fsaverage-ADDITIONS), and can read and write all
standard MGH formats (quad/tri/ico/ascii surfaces, *.mgh, *.mgz,
*.annot, *.gii, *.label, *.curv., *.area, etc), as well as BrainVoyager
formats (*.srf, *.poi), and other surface formats (*.vtk, *.off,
*.stl, *.obj, *.glb).

Csurf also provides command line utilities and a user interface for
manual surface reconstruction of hi-res 0.5mm^3/512^3 images.  These
higher-res surfaces will have ~700K vertices per cortical hemisphere
(vs.  ~150K), and up to 6M vertices for even higher resolution,
more complex surfaces (e.g., cerebellum).

N.B.: csurf is easiest to use with a standard 3-button mouse! (on
Mac, you can stick with the trackpad if you enable the XQuartz ->
Preferences -> Input bindings of option-click for middle-click, and
command-click for right click (same spatial relation as a real right
handed mouse).

Written by Martin Sereno (msereno@ucsd.edu), 1996-present at UCSD,
UCL/Birkbeck, and SDSU (170K lines).  Original kernel of IRIX C/GL
code for surface reconstruction and display by Anders Dale and
Martin Sereno (1989-1998) (Dale and Sereno, 1993; Sereno, Dale et
al., 1995), revised, rewritten, and extended by Bruce Fischl, Doug
Greve, Kevin Teich, Nick Schmansky, and others at MGH (1998-present)
(Dale, Fischl, Sereno, 1999; Fischl, Dale, Sereno, 1999; Fischl,
Sereno, Tootell, Dale, 1999), with surface-based averaging utilities,
complex F statistics, and surface clustering by Don Hagler (2002-2006)
(Hagler, Saygin, Sereno, 2006; Hagler, Riecke, Sereno, 2007), and
topological maps parcellation by Sereno, Sood, and Huang (2022).

Path and environment setup scripts are included for csh/tcsh
(FreeSurferEnv.csh) and sh/bash/zsh (FreeSurferEnv.sh).  The compile
script, mk0, is written in POSIX sh.

External library versions currently used (unmodified tarfiles
included in source distribution, patched during mk0 compile):

  tcl8.5.18-src.tar.gz
  tk8.5.18-src.tar.gz
  Tix8.4.3-src.tar.gz
  tiff-3.8.2.tar.gz
  mpeg_play-2.3-src.tar.gz
  mpeg_encode-1.5b-src.tar.gz

If you use this software, give credit to UCSD/UCL/SDSU csurf (me,
Anders Dale, Don Hagler), MGH freesurfer (for included mri_surf2surf)
and AFNI (for included afni, 3dvolreg, 3dDeconvolve, 3dmerge,
3dcalc).  If you use the topological maps parcellation, give credit
to Sereno, Sood, and Huang (2022).

Hi-res surface manipulation or "full fourier" operations require
at least 16G RAM (e.g., flattening a 4M vertex surface or full
fourier operations on hi-res EPI's).

Some recent papers/talks using this software include:

  The Shape of Thought
  https://pages.ucsd.edu/~msereno/movies/talks/Sereno-Shape-Of-Thought.mp4

  On Brainmaps
  https://pages.ucsd.edu/~msereno/movies/talks/Sereno-On-Brainmaps.mp4

  Sereno, M.I., M.R. Sood, and R.-S. Huang (2022) Topological maps
  and brain computations from low to high. Frontiers in Neuroscience
  16:787737
  https://pages.ucsd.edu/~msereno/papers/MapsLowToHigh22.pdf

  Sereno, M.I., J. Diedrichsen, M. Tachrount, G. Testa-Silva, H.
  d'Arceuil, and C. De Zeeuw (2020) The human cerebellum has almost
  80% of the surface area of the neocortex.  Proceedings of the
  National Academy of Sciences USA 117:19538-19543.
  https://pages.ucsd.edu/~msereno/papers/Cereb20.pdf

  Sood, M. and M.I. Sereno (2018) Estimating the cortex-wide overlap
  between wordless narrative scene comprehension, reading comprehension,
  and topological visual, auditory, and somatomotor maps. bioRxiv
  264002.
  https://www.biorxiv.org/content/biorxiv/early/2018/02/18/264002.full.pdf

  Kuehn, E., P. Haggard, A. Villringer, B. Pleger, and M.I. Sereno
  (2018) Visually-driven maps in area 3b. Journal of Neuroscience
  38:1295-1310.
  https://pages.ucsd.edu/~msereno/papers/VisDrivenSomato18.pdf

  Huang, R.-S. and M.I. Sereno (2018) Chapter 7. Multisensory and
  Sensorimotor Maps. In: The Parietal Lobe. Neurological and
  Neuropsychological Deficits (Handbook of Clinical Neurology), G.
  Vallar, H.B. Coslett (eds.), volume 151, Elsevier, pp. 141-161.
  https://pages.ucsd.edu/~msereno/papers/VisualAreas18.pdf

  Ganepola, T., Z.N. Nagy, A. Ghosh, T. Papadopoulo, D.C. Alexander,
  and M.I. Sereno (2018) Using diffusion MRI to discriminate areas
  of cortical grey matter. Neuroimage 182:456-468.
  https://pages.ucsd.edu/~msereno/papers/VisualAreas18.pdf

  Dick, F.K., M.I. Lehet, M.F. Callaghan, T.A. Keller, M.I. Sereno,
  and L. Holt (2017) Extensive tonotopic mapping across auditory
  cortex is recapitulated by spectrally-directed attention and
  systematically related to cortical myeloarchitecture. Journal of
  Neuroscience 37:12187-12201.
  https://pages.ucsd.edu/~msereno/papers/AttenTono17.pdf

  Sood, M. and M.I. Sereno (2016) Areas activated during naturalistic
  reading comprehension overlap topological visual, auditory, and
  somatotomotor maps. Human Brain Mapping 37:2784-2810.
  https://pages.ucsd.edu/~msereno/papers/LangMaps16.pdf

  Huang, R.-S. and M.I. Sereno (2013) Bottom-up retinotopic
  organization supports top-down mental imagery. The Open Neuroimaging
  Journal 7:58-67.
  https://pages.ucsd.edu/~msereno/papers/ImaginedNav13.pdf


############################################################################
HOWTO install csurf (from dated tarfiles)
############################################################################

-----------------------------------
HOWTO Manually Install/Update csurf
-----------------------------------

These programs have been tested on MacOS 10.6.8 to MacOS 10.16,
and on CentOS 5.9 to CentOS 7.6, and Ubuntu 12.04 to 20.04.

The programs that have graphical interfaces -- csurf, tksurfer,
tkmedit, tkregister, and tkstrip -- require X11.  On Mac OS X, first
install XQuartz.app (or MacPorts X11.app), and then be sure that
/usr/X11 and /usr/X11R6 are just links to /opt/X11 (sometimes Apple
deletes this link on update -- remake it, or reinstall XQuartz to
re-make it if there are problems).

Csurf can be installed anywhere.  Here is an example of how to
install it in the user's home directory.  If you already have csurf
installed, move the old version aside, for example:

  cd ~
  mv csurf csurf-221025

Then unpack the new csurf tarfile (it unpacks into just "csurf"):

  cd ~
  tar xvfz csurf0.8-mac-YYMMDD.tgz       # N.B.: unpacks to just "csurf"
           *or*
  tar xvfz csurf0.8-linux64-YYMMDD.tgz   # N.B.: unpacks to just "csurf"
           *or*
  tar xvfz csurf0.8-linux32-YYMMDD.tgz   # N.B.: unpacks to just "csurf"

On MacOS, if you have unpacked the tarfile by double-clicking it
(instead of command line 'tar xvfz <tarfile>' above), you must also
un-quarantine the new unpacked directory with:

  sudo xattr -r -d com.apple.quarantine ~/csurf
                 *or*
  sudo xattr -r -d com.apple.quarantine /Applications/Csurf.app

A csurf sh script to automate csurf install and updates is found here:

  $CSURF_DIR/bin/noarch/update-csurf

or at https://pages.ucsd.edu/~msereno/csurf/fsaverage-labels/bin.
Run it as follows:

  cd ~     # or anywhere else you want to install or update csurf
  update-csurf go

Here are useful aliases to avoid having to remember the un-quarantine
command:

  [sh/bash/zsh: put in ~/.bashrc or ~/.zshrc]
  alias unq="sudo xattr -r -d com.apple.quarantine"

  [csh/tcsh: put in ~/.cshrc or ~/.tcshrc]]
  alias unq "sudo xattr -r -d com.apple.quarantine"

so next time (for a homedir update), you can simply say:

  unq ~/csurf

At any one time, csurf accesses two main data directory trees,
$SUBJECTS_DIR (subject surfaces), and $FUNCTIONALS_DIR (functional
sessions, perhaps multiple functional session directories for a
given subject, as well as cross-subject average sessions).  These
directories can be anywhere (and can be interactively changed in
csurf), and they can be set to the same directory.  They should be
initially defined in your environment before startup.

Keep these data directories *outside* of the csurf distribution for
easier csurf updating.  It's fine to use the same SUBJECTS_DIR for
csurf and MGH freesurfer (viewing an MGH freesurfer subject with
csurf won't damage it for MGH freesurfer in any way).

For cross-subject surface-based averaging, copy the MGH freesurfer
average surface directories (fsaverage and fsaverage_sym) from MGH
freesurfer into your csurf SUBJECTS_DIR so that you own them.  Also,
it's an excellent idea to copy my fixed fsaverage "inflated_avg"
surfaces, area files, and flattenings, and the CsurfMaps1 (and HCP)
annotatation/parcellation files from the csurf distribution, which
are located here:

  $CSURF_DIR/subject/fsaverage-ADDITIONS

into the respective directories of your editable SUBJECTS_DIR copy
of MGH fsaverage.  There is a csurf sh script to automate this
copying in a non-destructive way:

  $CSURF_DIR/bin/noarch/update-fsaverage

---------------------
HOWTO Setup/Run csurf
---------------------

Here is an example of how to initialize the main environment variables
for subjects and sessions directories, and the location of the MGH
freesurfer installation, in tcsh or alternatively, bash (N.B.: keep
the subjects and sessions directories *outside* of both csurf and
MGH freesurfer to make csurf updates easier!):

  [sh/bash/zsh]
  export FSURF_DIR=/Applications/freesurfer   # wherever MGH install is
  export SUBJECTS_DIR=/your/startup/subjects
  export FUNCTIONALS_DIR=/your/startup/sessions
             *or*
  [csh/tcsh]
  setenv FSURF_DIR        /Applications/freesurfer
  setenv SUBJECTS_DIR     /your/startup/subjects
  setenv FUNCTIONALS_DIR  /your/startup/sessions

Here is how to setup the binary and library path variables for the
current shell terminal window:

  cd ~/csurf
  source FreeSurferEnv.sh      # if your shell is bash/zsh
           *or*
  source FreeSurferEnv.csh     # if your shell is csh/tcsh
           *or*
  . FreeSurferEnv.sh           # if your shell is orig Bourne sh :-}

Finally, here is how to start the csurf interface:

  csurf

N.B.: on Mac, you must first install XQuartz, and unquarantine the
new download (see above).  Once installed, it is preferable to run
csurf from an xterm, not from a Terminal (start XQuartz and open
an xterm with cmd-N).

N.B.: beginning on MacOS 10.10+, an obscure change to the window
server resulted in a massive (100x) slowdown of the tk-based X11
interfaces on csurf/tksurfer/tkmedit (I think it is due to an AppNap
bug).  It can counterintuitively be fixed simply by:

  boot computer
  login, start X11/csurf
    [X11 will be slow]
  logout (don't reboot)
  login, start X11/csurf
    [X11 will be fast for a while]

However, the awful slowness often reverts after a while, and logging
out and back in can be a pain, so I have implemented a cover-and-uncover
window hack at tcl/tk panel startup, which makes things bearable.

N.B.: on recent MacOS, by default, you won't be able to access many
of your directories from xterm (e.g., ls ~/Documents will fail)
unless you give /bin/bash (which starts xterm) full disk access:

  # first make tmp link so you can navigate to /bin/bash below
  cd ~; ln -s /bin slashBin
  SystemPreferences->Security&Privacy->Privacy->FullDiskAccess: add /bin/bash
  [OK to rm slashBin symbolic link now]

N.B.: on updates to recent MacOS versions, a key symbolic link that
is required to make X11 binaries work is sometimes removed.  Here
is how to re-make link if it is removed (can also just reinstall
X11):

  cd /private/var/select
  sudo ln -s /opt/X11 X11

Documentation/Help

Documentation is in far right csurf Help menu (first item pops up
a clickable index of all help).  There are over 300 context-sensitive
pop-up help panels available when R-clicking any csurf, tksurfer,
tkmedit, or tkregister interface element (button, tickbox, text
entry).  The interfaces have many exposed buttons for quick access.
Most buttons have multiple, related, alternate functions, now with
more convenient button bar popup menus (also on R-click, if you
just want the button bar, a return closes the help window).

Useful aliases

Here are .bashrc/.zshrc and .tcshrc/.cshrc entries to create an
all-in-one command to setup the environment (N.B.: on Mac, xterm
uses .bashrc but ignores .bash_profile, while Terminal does the
reverse; fix by having .bash_profile only source .bashrc).  This
example assumes the csurf install and the startup subjects and
sessions dirs are in the user's home dir, and that there has been
a default Mac MGH install into /Applications (adapt as needed for
linux MGH /usr/local/freesurfer install):

  [sh/bash/zsh: put in ~/.bashrc or ~/.zshrc]
  alias fs="\
    export FSURF_DIR=/Applications/freesurfer; \
    export SUBJECTS_DIR=~/subjects; \
    export FUNCTIONALS_DIR=~/sessions; \
    pushd ~/csurf; \
    source FreeSurferEnv.sh; \
    popd"
  
  [csh/tcsh: put in ~/.cshrc or ~/.tcshrc]]
  alias fs " \
    setenv FSURF_DIR /Applications/freesurfer; \
    setenv SUBJECTS_DIR ~/subjects; \
    setenv FUNCTIONALS_DIR ~/sessions; \
    pushd ~/csurf; \
    source FreeSurferEnv.csh; \
    popd"

Then, in a new terminal, you can setup the csurf environment, and
start csurf with:

  fs
  csurf

This alias method (or an equivalent bash function method, not shown)
is less invasive than putting 'source FreeSurferEnv' and 'export/setenv'
commands above directly into your .bashrc/.cshrc, because in the
second case, the commands are executed for every new shell.  The
alias/bash-function method only modifies your PATH and CSURF_LIBRARY_PATH
where you need it to be modified.

Finally, here are example aliases to setup (or switch back to) using
MGH freesurfer (example is for a default Mac install) from the
command line (make sure there are no spaces after the backslashes!):

  [sh/bash/zsh]
  alias mg="\
    export FREESURFER_HOME=/Applications/freesurfer; \
    export SUBJECTS_DIR=~/subjects; \
    pushd /Applications/freesurfer; \
    source FreeSurferEnv.sh; \
    popd"

  [csh/tcsh]
  alias mg "\
    setenv FREESURFER_HOME /Applications/freesurfer; \
    setenv SUBJECTS_DIR ~/subjects; \
    pushd /Applications/freesurfer; \
    source FreeSurferEnv.csh; \
    popd"

You can edit the hidden files (e.g., ~/.bashrc, ~/.cshrc, ~/.zshrc)
on Mac in TextEdit as follows:

  open -e ~/.bashrc

If the file doesn't exist, you will need to first create an empty
file with touch (touch won't hurt an existing file), then open it:

  touch ~/.bashrc
  open -e ~/.bashrc


-----------------------------------------------------
HOWTO install CsurfMaps1 parcellation into fsaverage
-----------------------------------------------------

The update-fsaverage script installs the CsurfMaps1 parcellation
(FreeSurfer labels and GIFTI equivalents) into a writable copy of
FreeSurfer subject "fsaverage" in the current $SUBJECTS_DIR.  It
moves aside/renames the original {rh,lh}.inflated_avg surfaces and
{rh,lh}.area files with an ORIG suffix before installing updated
versions.  Finally, it adds less distorted flattenings made from
the fixed inflated_avg surfaces.

N.B.: both of these scripts are included in the standard csurf
distribution (in two locations):

  $CSURF_DIR/bin/noarch
  $CSURF_DIR/subjects/fsaverage-ADDITIONS/scripts

They can also found here:

  https://pages.ucsd.edu/~msereno/csurf/fsaverage-labels/bin

Run the update-fsaverage script as follows:

  [if bash/zsh]
  export SUBJECTS_DIR=<directory_containing_writable_fsaverage>

  [if csh/tcsh]
  setenv SUBJECTS_DIR <directory_containing_writable_fsaverage>

  update-fsaverage go


-------------------------------------------------------------------
HOWTO shrink huge Gnome window title bars, stop auto-max (Linux-only)
-------------------------------------------------------------------

The Gnome window title bars in recent Linux distributions (e.g.,
CentOS 7) are ridiculously thick, wasting screen space and causing
the csurf tool interface windows to overlap the volume/surface
display windows.  Put the following code into ~/.config/gtk-3.0/gtk.css
to shrink them back to normal size (only way I could find to do
it):

/* tested CentOS 7.5: ~/.config/gtk-3.0/gtk.css: shrink window title bars */
window.ssd headerbar.titlebar {
    padding-top: 1px;
    padding-bottom: 1px;
    min-height: 0;
}
window.ssd headerbar.titlebar button.titlebutton {
    padding-top: 1px;
    padding-bottom: 1px;
    min-height: 0;
}

By default, Gnome auto-maximizes windows when they are moved to the
top of the screen.  This verbose shell command was the only way I
could find to stop this highly irritating (to me) behavior:

  gsettings set org.gnome.shell.extensions.classic-overrides edge-tiling false

Not possible (in CentOS 7) to do this with Tweak Tool or dconf-editor
tools.


------------------------------
HOWTO use Csurf.app (Mac-only)
------------------------------

A convenient way to run csurf on Mac is to use Csurf.app, which is
a small wrapper (applescript) around the full Mac csurf install.
The full (identical) unix install is contained inside Csurf.app in
this directory:

  Csurf.app/Contents/MacOS/csurf

To install, double-click the tarfile, Csurf.app0.8-mac-YYMMDD.tgz,
which will unpack to just Csurf.app.  Then drag Csurf.app to
Applications (or anywhere else).

On Mac OS X 10.9+, the just-downloaded application will have been
given a "quarantine" attribute (file metadata).  You can see this
with:

  xattr /Applications/Csurf.app

which immediately after unpacking should return:

  com.apple.quarantine

To remove Csurf.app from quarantine to allow it to run, do:

  sudo xattr -r -d com.apple.quarantine /Applications/Csurf.app

otherwise you will get a misleading error message: "Csurf.app is
damaged and can't be opened.  You should move it to the Trash".
This is Apple's Gatekeeper trying to make your computer behave more
like a locked-down iPhone that only gets approved software from the
Apple Store.  Scientists, however, often use software from other
places.

On startup of Csurf.app, X11/XQuartz is first started (if not
already running), and then the upper left csurf panel should pop
up.  If there is no ~/.csurfrc file (see below), Csurf.app will
create the following directories at startup (if they do not already
exist), and use them as SUBJECTS_DIR and FUNCTIONALS_DIR:

  ~/fsdata/subjects
  ~/fsdata/sessions

It will also assume that you have installed MGH freesurfer in the
standard place (i.e., /Applications/freesurfer).  To change Csurf.app
at startup to load different subjects and/or sessions directories,
open it and use:

  Preferences -> Set Subjects Directory
  Preferences -> Set Funct Sessions Directory

Then set them for next startup with:

  Preferences -> Save Curr Subj/Sess Dirs for Startup

which writes them into ~/.csurfrc.  You can also manually create
or edit that text file. To do this using TextEdit, open a Terminal
and type:

  open -e ~/.csurfrc

which will start up TextEdit.  Put lines into it like this (N.B.:
always use the sh/bash syntax shown here, even if your regular shell
is tcsh/csh):

  export SUBJECTS_DIR=/path/to/your/subjects
  export FUNCTIONALS_DIR=/path/to/your/functionals
  export FSURF_DIR=/some/other/location/of/MGH/freesurfer

The new directory paths will be used the next time you start
Csurf.app.  To get multiple simultaneously-running copes of csurf,
just double-click Csurf.app again.

The reason for adding the new .csurfrc configuration file is that
Csurf.app can't see your current shell variables environment.  The
new configuration file is ignored if you run csurf from the command
line (i.e., startup SUBJECTS_DIR and FUNCTIONALS_DIR are set in
your bashrc or cshrc).


---------------------------------------
HOWTO Three-Button Mouse (Mac-only)
---------------------------------------

On Mac, with a Mac scroll-ball mouse, use System Preferences ->
Mouse to make right mouse button "Secondary Button" and middle mouse
button/scroll wheel "Button 3" to enable right and middle click
(needed for edit-to-black and edit-to-white in tkmedit and help and
alternate functions on many tksurfer buttons).

In Mac OS X 10.9+ (Mavericks, Yosemite, El Capitan, Sierra, High Sierra)
with an apple *trackpad* mouse, there are no longer any Expert Preferences
mouse options for middle click.  However, a 3-button mouse will
still give a middle-click if the following three (counterintuitive)
options are ticked on the X11 -> Preferences -> Input tab:

  x  Emulate three button mouse
  x  Follow system keyboard layout
  x  Enable key equivalents under X11


---------------------------------------
HOWTO Fix Slow X11/Tk Drawing Speed (Mac-only)
---------------------------------------

OpenGL/X11/GLX 3D performance on MacOS is fine.  However, starting
with MacOS 10.10 (Yosemite), X11/tk drawing speed slowed down
catastrophically.  A hack cover/uncover-with-an-xterm workaround
is enabled when csurf runs on MacOS 10.10+.  The problem may be
related to AppNap somehow thinking X11 isn't visible.

On more recent MacOS (e.g., 10.15/Catalina), X11/tk drawing speed
will always be slow on first login and X11 startup after a reboot,
but can be fixed by simply logging out and logging back in without
a reboot (sticks for a while, can be redone).  Options to csurf
(-hack, -nohack) force the use or non-use of the xterm cover/uncover
hack (on by default if OS is 10.10+).  Hopefully, some combination
of updates to MacOS, XQuartz, and/or tk will eventually permanently
fix this aggravating, long-standing problem.


---------------------------------------
HOWTO make AFNI utilities work on Ubuntu 16.04
---------------------------------------

Ubuntu 16.04 is missing libXp, a tiny X11 library for printing,
which is required/linked by AFNI utilities included in this
distribution.  Since AFNI utilities (e.g., 2swap) are used in several
key places, the missing libXp will disable many operations in csurf.

The libXp shared lib isn't available in the 16.04 archives, so here
is how to install the working version from Ubuntu 15.  Get the .deb
file from one of these places:

  https://launchpad.net/ubuntu/+archive/primary/+files/libxp6_1.0.2-2_amd64.deb
  https://pages.ucsd.edu/~msereno/csurf/libs/libxp6_1.0.2-2_amd64.deb

Install it like this:

  sudo dpkg -i libxp6_1.0.2-2_amd64.deb

At startup, csurf now checks if this critical component is missing
(if Debian or Ubuntu).


Current compile environments:

  csurf0.8-mac-YYMMDD.tgz => MacOSX 10.6.8 (64-bit)
  csurf0.8-linux64-YYMMDD.tgz => CentOS 5.9 (64-bit)
  csurf0.8-linux32-YYMMDD.tgz => CentOS 5.9 (32-bit)


############################################################################
HOWTO install Linux csurf0.8 in a virtual machine
############################################################################

Performance in a virtual machine is quite satisfactory.  The only
slowdown detectable is during direct manipulation.  Here are some
historical examples:

### Linux csurf0.8 (32-bit) inside WMWare Player on Windows 7
--download WMWare Player 5
--install 32-bit CentOS 5 or CentOS 6
--install VMWare Tools inside CentOS
--add an X lib for AFNI: e.g., yum install libXp
--unpack csurf0.8 (32-bit linux works better in Windows 7)
--set up environment as above

### Linux csurf0.8 (32-bit) inside VirtualBox on Mac OS X 10.6+
--download Virtual Box (e.g., 4.3.14), default install
--default install from CentOS-5.9-i386-bin-DVD-1of2.iso
--VirtualBoxVM -> Devices -> Install Guest Additions...
--cd /media/VBOXADDITIONS_4.2.6_82870    # adapt as needed for newer
--sh ./VBoxLinuxAdditions.run
[create Shared Folder on host]
--usermod -G vboxsf <your_username>; reboot    # mk shareddir accessible
--unpack csurf tarfile in VM as above


############################################################################
Location of architecture-specific binary and library subdirectories
############################################################################
$CSURF_DIR/bin
$CSURF_DIR/tcltktix/bin
$CSURF_DIR/tcltktix/lib
$CSURF_DIR/afni/bin
$CSURF_DIR/afni/lib
$CSURF_DIR/gsl/lib


############################################################################
HOWTO make csurf use an external full AFNI install (e.g., in /usr/local/afni)
############################################################################
# e.g., link to 64-bit Mac AFNI install in /usr/local/macosx_10.6_Intel_64
cd $CSURF_DIR/afni/bin
mv Darwin-x86_64 Darwin-x86_64~
ln -s /usr/local/macosx_10.6_Intel_64 Darwin-x86_64
# N.B.: can be done automatically by: mk0 afnilink


############################################################################
HOWTO compile csurfsrc.tgz
############################################################################

Compiling csurf programs in csurfsrc.tgz on Mac OS X, Linux (or
IRIX!) requires GNU gcc/g++/make and X11/OpenGL headers (Mac
XCode2/3/4, X11 SDK), sh/bash and an internet connection for AFNI
download.  Contact msereno@sdsu.edu to get the csurfsrc.tgz tarfile.

For example, here is what needs to added to a default install of
CentOS 5.9 (32-bit or 64-bit) in order to compile the csurf programs:

  yum install tcsh                     # only required if you want tcsh
  yum groupinstall "Development Tools" # gcc, g++, tools
  yum install libX11-devel             # compile any X11
  yum install libXp                    # run AFNI
  yum install mesa-libGLU-devel        # compile tksurfer (2023: not needed)
  yum install zlib-devel.i386          # compile tksurfer (libz here)
  yum install libjpeg-devel.i386       # compile tksurfer (libjpeg there)
  yum install libXext-devel.i386       # compile mpeg_play
    [on 64-bit CentOS, omit ".i386" from last 3]

Then the csurf programs can be compiled with:

  tar xvfz csurfsrc.tgz
  cd csurfsrc
  ./mk0 onearch        # POSIX sh script

The mk0 (or mk0.csh) script downloads needed AFNI binaries, then
compiles tcl/tk/tix, libtiff, and csurf programs for the current
architecture, and makes a binary install tarfile in ./dist/csurf.tgz.
The resulting tarfile can be installed in any directory.

If you already have AFNI installed somewhere else, you can instead
have the mk0 script prompt you to make a link to it:

  ./mk0 onearch-afnilink

or you can ignore AFNI completely with:

  ./mk0 onearch-noafni

However, in the last case (no AFNI), motion correction (2swap,
3dvolreg), BRIK concatenation (3dTcat), BRIK deconvolution for
randblock designs (3dDeconvolve), and cross subject spherical
averaging (3dcalc) won't work.

N.B.: if you are compiling csurf in a virtual machine such as
VirtualBox, run mk0 in a *non-shared* directory (i.e., one *not*
visible from host OS), else symbolic links won't be made properly
in the resulting installable tarfile (no problem moving generated
install tarfile to a shared directory *after* it is made).

The script "mk" (no '0') compiles and links a single program for
the current architecture.  Here is an example of how to modify the
source code of one file (tksurfer.c), compile it, and test it,
starting from a csurf source tarfile in /tmp:

  cd /tmp
  tar xvfz csurfsrc.tgz
  cd csurfsrc
  mk0 onearch-noafni    # about 5 min, just do once
  source FreeSurferEnv.csh (or FreeSurferEnv.sh)
  cd tksurfer
  cp tksurfer.c tksurfer.cORIG
  vi tksurfer.c
  mk tksurfer           # binary goes to $CSURF_DIR/bin/<arch>/tksurfer
  [test, re-edit, re-mk, etc, no need to redo mk0]

The architectures that are currently known/well-tested are:

  Darwin-x86_64 (64-bit)
  Linux-i386  (32-bit)
  Linux-x86_64 (64-bit)

Older also working, less maintained:

  Darwin-ppc (macPPC, slightly older tarfile, 2022)
  Darwin-i386 (no curr tarfile)
  IRIX64-mips (irix, slightly older tarfile, 2022)
  IRIX-mips (irix, no curr tarfile)

For now, Mac M1 ARM is classified as Darwin-x86_64 and runs under
Rosetta 2.  I'm working on a native compile given that Apple
previously killed Rosetta 1 (run PowePC binaries on Intel introduced
in 2006) in 2012.


############################################################################
csurf programs (C binaries except indicated)
############################################################################

Graphical interface programs (commandline startup):

  csurf          overall control interface (tcl/tk/tix)
  tksurfer       view/edit/render surf/overlay/labels, shrink on 3vols
  tkmedit        view/edit/render 3Ddata/surf/overlay
  tkregister     hand blink-register two 3D data sets
  tkstrip        run/view skull stripping
  wheel          generate/manipulate color wheel
  bsurf          historical: orig 1997 1K-line tk interface

Data conversion programs (commandline):

  brik2cor       convert BRIK to COR or .mgz w/trilinear 
  cor2brik       COR or .mgz to BRIK w/correct HEAD
  brik2bfloat    AFNI BRIK to bfloat's
  bfloat2brik    bfloat's to AFNI BRIK
  bresize        surfvtxlist <-> BRIK for 3dcalc (Don Hagler)
  mosaic2brik    un-mosaic for un-to3d-able 3D EPI (tcl)
  ima2brik       convenient DICOM list/convert (tcl)
  calcvert       convert/vtxwise math on surf vtxlist data

Hi-Res Surface-making programs (commandline):

  [mksurface]    old surf-making script (csh)
  calcimg        pixelwise math on COR/mgz/BRIK, manip header
  wmfilter       aniso filter plus thresh -> wm.mgz
  fill           3D floodfill segmented wm.mgz -> filled.mgz
  surf           generate lh/rh surfaces from filled.mgz

fMRI analysis programs (commandline):

  rawaverage     avg/concat/time-rev/time-shift 4D xyzt data
  fourier        calc 3D fourier stats, permutation test
  phasecombine   combine 3D fourier stats, phase adjust
  rcxcombine     combine 3D or surface-sampled stats, phase adj
  paint          sample bfloat/BRIK stats to surf, dump ASCII surf
  surfcombine    combine surface-sampled stats (stack based)
  surfclust      cluster-filter surface stats (Don Hagler)
  randsurfclust  calc cluster size for p-val/smoothing (DH)
  multiclust     fill/number mult clusters w/thresh list (DH)

Movie making/conversion/viewing (commandline):

  nmovie         play series of tiffs and/or rgbs as movie
  tiff2mpg       assemble tiff series to mpg1 (tcl)
  mpeg_encode    generate mpeg1 from ppm's
  mpeg_play      mpeg1 viewer
  mytoppm        used by mpeg_encode, tiff/rgb -> ppm
  mri2mpg        use AFNI to generate 3-plane mpgs of BRIK
  mri2jpgs       use AFNI to dump 3-plane jpg sets of BRIK

Misc scripts (commandline):

  mk0            compile all csurf programs (or make src dist)
  mk             compile a single csurf utility
  getonearch     return OS/wordsize
  forceMSB       force BRIK to MSB byte-order (2swap,4swap)
  dti2surf       sample dti to surface, dump ASCII (csh)
  pfbrik         run wmfilter Gauss plane filter on a BRIK
  prf2sess       conv SamSrf subj labels to wfiles in image dir
  fixinflatedavg repair huge triangles at N/S icosahedral poles
  fsavgannot2subj   resample fsaverage annotation to single subj
  update-csurf      script (sh) to automate csurf install/update
  update-fsaverage  add parcellation, fixed surf/area to writable fsaverage (sh)