Index of /sereno/csurf
############################################################################
csurf -- tk/X11/OpenGL progs for surface-based fMRI analysis/average/display
############################################################################
Csurf -- Summer 2024
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-240426.tgz MacOS 10.6+
csurf0.8-linux64-240426.tgz 64-bit Linux CentOS 5.9+
### other download
Csurf.app0.8-mac-240426.tgz same as Mac above, with dockable app wrapper
csurf0.8-linux32-240426.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 also display and use the HCP-MMP1
parcellation (included in fsaverage-ADDITIONS).
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)