Index of /sereno/csurf
############################################################################
csurf -- tk/X11/OpenGL progs for surface-based fMRI analysis/average/display
############################################################################
Csurf -- Summer 2026
=====================================================================
NEW: ARM compile that works on Tahoe 26.5.1
=====================================================================
Csurf provides linux and mac applications for high-resolution
surface- and volume-based analysis, cross-subject averaging, and
display of retinotopic and other kinds of phase-encoded data. It
includes an fsaverage topological map parcellation as well as tools for
non-standard high-resolution surface reconstruction (high field,
post-mortem).
Download sites:
https://pages.ucsd.edu/~msereno/csurf
https://mri.sdsu.edu/sereno/csurf
Quick start (sh/bash example)
## download/unpack/unquarantine csurf
[download tarfile (mac or linux]
tar xvf csurf0.8-<version>-YYMMDD.tgz # unpack
sudo xattr -r -d com.apple.quarantine csurf # if Mac: unquarantine
## setup required data directory env vars
export SUBJECTS_DIR=/your/startup/subjdir # your subjects
export FUNCTIONALS_DIR=/your/startup/sessdir # your sessions (OK if same)
## so csurf can find standard freesurfer
export FSURF_DIR=/Applications/freesurfer # standard freesurfer install
## setup run environment
cd csurf
source FreeSurferEnv.sh
## install fsaverage w/parcellation, fixed surfaces and area files
cd $SUBJECTS_DIR
[download fsaverage.tgz]
tar xvfz fsaverage.tgz
csurf # start csurf
Files (N.B.: all csurf0.8 *.tgz files unpack to just "csurf"):
### primary download
csurf0.8-mac-260502.tgz MacOS 10.6 to 15.7 (Intel or ARM)
csurf0.8-arm-260622.tgz MacOS 26 (Tahoe, running on ARM)
csurf0.8-linux64-260502.tgz 64-bit Linux CentOS 5.9+
### other download
Csurf.app0.8-mac-260502.tgz same as Mac above, with dockable app wrapper
csurf0.8-linux32-260502.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 + CsurfMaps1 + fixed surfs/area
fsaverage-ADDITIONS.tgz just CsurfMaps1 + fixed surfs/area additions
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, surface normals/surf-gradient-arrows/DTi-arrows
divergent or 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 2025
https://pages.ucsd.edu/~msereno/movies/talks/Sereno-Shape-Of-Thought3.mp4
On Brainmaps
https://pages.ucsd.edu/~msereno/movies/talks/Sereno-On-Brainmaps.mp4
Leong, T.I., A. Li, J.H. Ang, B.L. Reynolds, C.T. Leong, C.U. Choi,
M.I. Sereno, D. Li, V.L.C. Lei, and R.-S. Huang (2026)
Time-resolved hemodynamic responses to sentence-level speech perception,
production, and self-monitoring (preprint).
https://www.biorxiv.org/content/10.64898/2026.04.13.715885v1
Samuelsson, J.G., J.D. Schmahmann, M.I. Sereno, B. Rosen, and
M.S. Hamalainen (2026)
A digital anatomical atlas of the human cerebellum at subfolial resolution
Human Brain Mapping 47:e70497
https://pages.ucsd.edu/~msereno/papers/CerebAtlas26.pdf
Leong, T.I., V.L.C. Lei, J.H. Ang, C.T. Leong, C.U. Choi, M.I. Sereno,
D. Li, and R.-S. Huang (2026)
Tracking bilingual brain processing at high spatiotemporal resolution
reveals where and when second language slows down (preprint).
https://www.biorxiv.org/content/10.64898/2026.02.01.701554v1
Lei, V.L.C., T.I. Leong, C.T. Leong, L. Liu, C.U. Choi, M.I. Sereno,
D. Li, and R.-S. Huang (2024) Phase-encoded fMRI tracks down brainstorms
of natural language processing with sub-second precision. Human Brain
Mapping 45:e26617.
https://pages.ucsd.edu/~msereno/papers/PhaseEncodedLang24.pdf
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, run, and update csurf
############################################################################
These programs have been tested on MacOS 10.6.8 (Snow Leopard) to
MacOS 15.4.1 (Sequoia) and on CentOS 5.9 to CentOS 7.6, and Ubuntu
12.04 to 20.04. There is also an ARM version tested on MacOS 26.5.1
(Tahoe) that fixes the broken OpenGL/GLX in Tahoe.
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). If there is a problem
starting X11 apps, verify that /usr/X11 and /usr/X11R6 are just
links to /opt/X11 (sometimes Apple deletes this link on OS update
-- remake it, or reinstall XQuartz to re-make it if there are
problems).
-----------------------------------
HOWTO Install csurf for the first time
-----------------------------------
To install csurf for the first time, download and unpack one of the
tarfiles above. Csurf can be installed anywhere. First cd to
the directory in which you want to install csurf:
cd <somewhere>
Then unpack the tarfile:
tar xvfz csurf0.8-mac-YYMMDD.tgz # N.B.: unpacks to just "csurf"
*or*
tar xvfz csurf0.8-arm-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, un-quarantine the unpacked csurf directory like this:
cd <dir_where_you_unpacked>
sudo xattr -r -d com.apple.quarantine csurf
Here are convenient aliases for that 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, you can simply type:
unq csurf
-----------------------------
HOWTO Setup Data directories
-----------------------------
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 sh/bash/zsh or csh/tcsh:
[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 environment 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
Finally, here is how to start the csurf interface:
csurf
------------------------------------
HOWTO deal with Mac-specific issues
------------------------------------
On Mac, you must first install XQuartz, and unquarantine the new
csurf 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).
For Apple ARM silicon up until Tahoe, you can run the Intel-compiled
csurf ("-mac-" tarfile) using Rosetta 2, which works well. If
Rosetta 2 is not installed, you can install it with as follows (redo
OK):
softwareupdate --install-rosetta --agree-to-license
On MacOS 26 (Tahoe), Apple (hopefully temporarily) broke X11/GLX/OpenGL,
so I made a separate csurf release containing fixed mesa-25.4.3
X11/GL libraries that should be used for Apple ARM silicon machines
running Tahoe:
https://pages.ucsd.edu/~msereno/csurf0.8-arm-260622.tgz
An earlier X11 slowdown problem seems to have been fixed. Beginning
on MacOS 10.10 (Yosemite) until MacOS 10.15 (Catalina), an obscure
change to the window server (AppNap?) resulted in a massive (100x)
slowdown of X11 interfaces (incluing the tk-based X11 interfaces
for csurf/tksurfer/tkmedit). The slowdown can counterintuitively
be fixed simply (and inconveniently) 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]
Because that's not practical, I implemented a cover-and-uncover
window hack at tcl/tk panel startup, which makes things bearable.
I found the problem was resolved by MacOS 15 (Sequoia), on Apple
Silicon, so I turned off the uncover hack by default for MacOS 11
and above (I couldn't test on all of those systems). You can turn
it on (or off) in csurf -> Preferences -> Cover/Uncover Speedup
Hack.
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]
On updates to recent MacOS versions, another key symbolic link that
is required to make X11 binaries work is sometimes removed. Here
is how to re-make the link if it is removed (can also fix this by
just reinstalling X11):
cd /private/var/select
sudo ln -s /opt/X11 X11
------------------------------------
HOW Find Documentation and 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 Update csurf
-----------------------------------
If you have already installed csurf, the simplest way to update is
by selecting the csurf menu item:
csurf -> Preferences -> Update Csurf
and then restarting csurf to use the new one. The menu item runs
the update script 'update-csurf', which can also be run from the
command line.
The existing csurf directory will be moved aside (and dated) and
then the latest update will be downloaded and unpacked/installed
from https://pages.ucsd.edu
Once again, on Mac, you may need to run:
sudo xattr -r -d com.apple.quarantine csurf
on the new directory to remove the quarantine metadata attribute.
-----------------------------------------------------
HOWTO install CsurfMaps1 parcellation into fsaverage
-----------------------------------------------------
The easiest way to do this is to download a fixed fsaverage
subject from:
https://pages.ucsd.edu/~msereno/csurf/fsaverage.tgz
To see exactly what is going on, you can instead use the included
shell script on an existing fsaverage subject:
$CSURF_DIR/bin/noarch/update-fsaverage
This 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. Here is how to run it:
[if bash/zsh]
export SUBJECTS_DIR=<directory_containing_writable_fsaverage>
[if csh/tcsh]
setenv SUBJECTS_DIR <directory_containing_writable_fsaverage>
update-fsaverage go
Finally, to see how the artifactual large triangles at the 'poles'
of inflated_avg were fixed (so that update-fsaverage can install
them), see the script:
$CSURF_DIR/subjects/fsaverage-ADDITIONS/scripts/fixinflatedavg
-------------------------------------------------------------------
HOWTO shrink huge Gnome window title bars, stop auto-max (Linux-only)
-------------------------------------------------------------------
The Gnome window title bars in somewhat 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).
Since Apple is strongly suggesting that AppleScript will no longer
be supported, Csurf.app will probably not be able to be maintained
in the future.
---------------------------------------
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 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)