There is also a Listing of All Programs that gives a one-line description of each IMOD program and a link to its man page.
All of the IMOD programs are available via the
IMOD Download Page. The distribution is bundled together using
the tar program with gzip compression, then placed in a file after a shell
script that can extract and install the programs. If you are willing to
install to the default location in the system and set up the IMOD environment
for all users in the default way, then you can install simply by running this
(In this guide, the specific filenames are used as an example; your copy may have higher version numbers.) You cannot click on the .sh file to install it. This command will not work on Windows unless the Cygwin toolkit is installed. There is an executable installer for Windows with extension .exe that you can click on to install (either with or without Cygwin). If you have followed our recommended installation procedures in the past, you will be able to upgrade using the same command. If you want to install to a location other than the default, you can specify the desired location inside of which the IMOD directory will be placed, e.g.,
sh imod_4.9.1_RHEL6.sh -dir /opt
Older versions will be renamed, and at the end the installation script will offer to remove them for you. If you are installing an older IMOD version with a package file that ends in
.csh, run it with
csh instead of
After installing for the first time, you will probably need to start a new terminal window to be able to run IMOD programs; on Ubuntu you will probably need to log out and log back in.
People with special requirements not
anticipated by the install script may need to work with the tar file
instead. It can be extracted with:
sh imod_4.9.1_RHEL6.sh -extract
The gzipped tar file and the install script will be left in a subdirectory
IMODtempDir. There are several other useful options:
-script to install startup scripts to a different location,
to skip installing startup scripts,
-name to have the IMOD
directory be renamed to the given name. Use:
sh imod_4.9.1_RHEL6.sh -help
to see all available options. The sections below on individual machine types describe what will be done by the default installation procedure. They also list the steps for doing a manual installation instead of using the self-installing package, but this should rarely be needed.
The recommended configuration for running the IMOD software is:
Processor: Almost any Intel or AMD processor from the last few years, or
medium- to high-end processors from the last 5 years, will run adequately
Video Card: any relatively modern Nvidia card (GeForce or Quadro, 512 MB or higher cards preferred)
Operating System: Red Hat Workstation 6, Centos 6, or Fedora equivalent or higher, Ubuntu 11 or higher
Recent Nvidia Linux device drivers and OpenGL libraries from Nvidia
Minimum memory and disk size depend on your application.
Nvidia installation. Installing Nvidia drivers is now
straightforward on some systems,
but here are some instructions that may be
helpful for older Fedora and for Red Hat/Centos through
version 7. The latest versions of the drivers change the Driver line in
/etc/X11/xorg.conf from "nv" to "nvidia" if you accept their offer to modify
the file. For recent Fedora, search for "Install NVIDIA drivers
Fedora xx", where xx is your version number, and study the
various instructions that you find.
On Ubuntu, the automatic installation through Synaptic Package
Manager or its current equivalent should be adequate. However, on
laptops, it is important to know whether the NVIDIA card has Optimus
technology for switching between the card and built-in graphics. If it
does, the regular methods will probably not work, but one solution is to
install bumblebee (search on bumblebee and the Linux distribution name
for specific instructions). Bumblebee allows you to direct a program
to access the NVIDIA graphics by starting it with a
optirun command. Thus, if you simply start a new
shell, e.g., with
optirun bash and run IMOD commands from
this shell, you should find that
3dmod uses the NVIDIA graphics and that the GPU is available for reconstruction.
libjpeg62 for Ubuntu.
You must install version 6.2 of the JPEG libraries, which is not
present on newer systems. The sign of needing this is an error message
when trying run 3dmod or some other programs: error while loading shared
libraries: libjpeg.so.62: cannot open shared object file: No such file or
directory. Before this, you should see a warning when you install
IMOD. Install the older JPEG library with:
sudo apt-get install libjpeg62
Python on Ubuntu 18.
Ubuntu 18 installs with Python 3 and not 2, and this Python runs
with the command
python3. IMOD scripts run fine with
Python 2 or 3, but rely on a program named
python being on
the search path. The IMOD installer will offer to make a link from
/usr/bin/python, or you
can use the Python 3 just for the IMOD install, then install Python 2
sudo apt-get install python
If you do make a link in
/usr/bin, it will be replaced
if you later install Python 2.
tcsh for Ubuntu or Fedora.
Only a few very specialized scripts in IMOD require
although you would need it to install older versions of IMOD.
The standard Fedora and Ubuntu installs do not include it. If you find
that you need it, you can install it on Ubuntu with:
sudo apt-get install tcsh
or on Fedora with:
sudo yum install tcsh
The self-installing package will install to a directory named
/usr/local unless given an alternate location to
-dir option. It will copy the startup scripts
given an alternate location with the
-script option or told to
skip this step with the
-skip option, or unless you are running
an Ubuntu version before 10 or give the
option. It the latter cases, it will
source the startup scripts from the IMOD directory, unless you give the
option. To accomplish all of this, change directory to the place where
the package is located and enter, for example:
sudo sh imod_4.9.1_RHEL6.sh
You will have to open a new window, or possibly even log out and log back in, for the installation to take effect.
If you are upgrading IMOD using the default procedures, and your previous
installation used another method for setting the environment variables for
users, be sure to remove whatever commands were used before. These might
have been placed in
You would skip the installation of the startup scripts if you do not want a
system wide installation, or if you are installing to a server to be accessed
by multiple workstations. In this case, you would place the following in
of individual users running the
bash shell (where
<location of IMOD> is the absolute path to the IMOD directory):
export IMOD_DIR=<location of IMOD>
if [ -e $IMOD_DIR/IMOD-linux.sh ] ; then source $IMOD_DIR/IMOD-linux.sh ; fi
or, place the following in the
files of individual users of
setenv IMOD_DIR <location of IMOD>
if (-e $IMOD_DIR/IMOD-linux.csh) source $IMOD_DIR/IMOD-linux.csh
Alternatively, if there are system-wide startup scripts sourced from
would place these commands in the system-wide startup scripts. You
should always source the startup script that comes with an IMOD
distribution, not make a copy of the startup script and incorporate it
into other scripts, because that is the easiest way to adapt to changes in
the startup script between versions.
If you want to run programs temporarily in a particular version of IMOD without
replacing your installed version, unpack the desired version in some logical
place with a command like:
sh imod_4.9.1_RHEL6.sh -dir
This will manage an installation of IMOD under the directory
offering to delete other versions there. To run with this IMOD, cd to
export IMOD_DIR=`pwd` (under bash,
setenv IMOD_DIR `pwd`
source IMOD-linux.sh (under bash,
IMOD-linux.csh (under tcsh)
Manual Install. To install manually from the tar file, do the
following steps after running the self-installing file with the
mv imod_4.9.1_RHEL6.tar.gz /usr/local
tar -xzf imod_4.9.1_RHEL6.tar.gz
IMOD -> imod_4.7.15), then enter
mv IMOD oldIMOD
ln -s imod_4.9.1 IMOD
cp IMOD/IMOD-linux.* /etc/profile.d
On early Ubuntu or Debian systems, when installing manually, instead of
step 8, you would insert commands into
/etc/csh.cshrc just like
those given above for inserting in users'
.cshr files, respectively.
Etomo is a Java application and thus requires a Java runtime environment (JRE) with a version of 1.6 or better to be installed. Recent Fedora, RedHat-based, and Ununtu systems have had usable native Java packages available or installed. Check your system with
openjdk-6-jreoffered by the Ubuntu Software Center seemed to work well. On Ubuntu 16 and 18, OpenJDK java can be installed with
sudo apt-get install default-jre
If you need to install a usable Java, get the latest Java Run-time
Environment from the Java
On most 64-bit systems, you will generally need a 64-bit version.
.tar.gz files are available; the instructions next are
for installing from a 64-bit
.tar.gz file, for example
To install the JRE for Linux first move the
Next change your working directory to
/usr/local and unpack
the file by entering
sudo tar -xzf jre-7u67-linux-x64.tar.gz
on the command line.
This will install the JRE in
/usr/local/jre1.7.0_67. The IMOD
startup scripts will assume that the JRE is in
java is not on your command path, so next create a link:
sudo ln -s jre1.7.0_67 java
If you upgrade to a different JRE, then you just need to change the link.
If you wish to use a different JRE than the one pointed to by
you must redefine the environment variable IMOD_JAVADIR to specify the
directory where the JRE you wish to use is installed. The best way to do
this is to make files
that set this environment variable, rather than modifying the
IMOD-linux.csh scripts in
/etc/profile.d (see Using
the ImodCalib Directory).
If you enable Java in your browser and it uses this Java, you MUST keep this Java updated to the latest version.
The self-installing package will install to /Applications or to an
alternate location with the
not work by clicking on it, only by running it at the command
line. It will place appropriate "source" commands for defining the user
/etc/csh.login. You need to be able to use sudo. Open a
terminal window (under Applications-Utilities), change directory to the place
where the package is located, and enter, e.g.:
sudo sh imod_4.9.1_osx_intel64.sh
You will need to exit and restart Terminal for these changes to take effect, or you can just source
/etc/profile (if you are
running bash) or
/etc/csh.login (if you are
running tcsh). If
you are upgrading IMOD with the default installation procedures and your
previous installation used another method of setting environment variables,
then you may need to remove "source" or other environment-setting commands from
various files, such as
Setting Up Ability to Click on Files to Open them in 3dmod. Once you have verified that IMOD programs run after installing them, you can make some links in
/usr/lib to libraries in the IMOD directories
that will allow you to start 3dmod by clicking on its icon and to open
files in 3dmod by clicking on them. Run the
script by entering:
sudo $IMOD_DIR/linklibs-mac -i $IMOD_DIR
If this creates problems, such as conflicts with other programs that supply
their own Qt libraries, you can remove the links with:
sudo $IMOD_DIR/linklibs-mac -u $IMOD_DIR
If you are upgrading IMOD and have done this before, you should
-u $IMOD_DIR before installing the new version then rerun with
-i option after installing.
Once the links are made, test that 3dmod will start by finding it in
IMOD/bin and clicking on it. If this works, then you can
proceed to associate files with desired extensions
.rec) by a script that will open
files in 3dmod. The steps are:
If you install IMOD in a location other
/Applications, you will need to be able to get to it in
the file association chooser, or you will need to copy
openIn3dmod.app directory to another location that you
can get to.
Java for OS X 10.7 and above. Java is not installed by default in OS X
10.7 and above. When you try
to run a Java program like Etomo, or just enter
-version in a terminal, the most recent OS versions will tell you
need to install Java, and might give you a
link from which you can get a Java to install.
The Apple Java that was available before OS X 10.12 has not been updated
to be secure, so we recommend installing the latest version of
Java from Oracle. This comes in
two forms, the JRE (Java Runtime Environment) and
the considerably larger JDK (Java Development Kit). On OS X 10.13, the
link that comes up when you run java
accesses an up-to-date Oracle version of the JRE that will install correctly.
However, until recently,
Oracle's installer for the JRE failed to set the links in the system
correctly, while the installer for the JDK does. If you run into this
problem, there are several solutions:
export PATH="/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin:$PATH"
/etc/profilefor a system-wide installation, or in the file
.bash_profilein your home directory for personal use. When running the
tcshshell the command is
setenv PATH "/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin:$PATH"
/etc/csh.loginfor a system-wide installation, or in the file
.cshrcin your home directory for personal use.
IMOD_JAVADIR. The command under
export IMOD_JAVADIR="/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home"
/etc/profileor your own
.bash_profile. The command under
setenv IMOD_JAVADIR "/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home"
/etc/csh.loginor your own
/usr/bin, which would require turning off System Integrity Protection in newer Mac versions. The commands would be:
sudo rm java
sudo ln -s "/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java" java
Using a 3-button Mouse. The
one-button mouse on the Mac can be used in
3dmod with some
keyboard modifiers, but this is painful. Just get a 3-button mouse.
It may just work when you plug it in, so try it in
before installing drivers. Installing Logitech and some other drivers may
actually make it stop working, and the solution is to uninstall the drivers.
Manual Install. To install manually from the tar file that you can
get by running the self-installing file with the
you have two alternatives. To do it from the command line, open a Terminal
sudo mv imod_4.9.1_osx_intel64.tar.gz /Applications
sudo tar xzf imod_4.9.1_osx_intel64.tar.gz
IMOD -> imod_3.1.6), then enter
sudo rm IMOD
sudo mv IMOD oldIMOD
sudo mv imod_4.9.1 IMOD
You also need to add some startup commands to the system
/etc/csh.login , unless they
are already there from a previous installation of IMOD. Use sudo to invoke
pico on these files, .e.g.:
sudo emacs /etc/csh.login
Copy the text in
IMOD/mac.bashrc to the end
/etc/profile, specifically the command
[ -r /Applications/IMOD/IMOD-mac.sh ] && source
Similarly, copy the text in
IMOD/mac.cshrc to the end of
specifically the command
if (-e /Applications/IMOD/IMOD-mac.csh) source
If you want to install at another location, change
the name of the top IMOD directory in
IMOD-mac.csh and in the
source commands placed in
If you are sure you are not going to install somewhere else in the future, you
can avoid modifying
defining IMOD_DIR before the source commands, i.e. with
before the source command in
/etc/profile, or with
setenv IMOD_DIR <Location_of_IMOD>
before the source command in
See the above instructions for Linux PC for other variations on installation procedures.
To use IMOD effectively under Windows, you need to install either a Unix-like environment called Cygwin or an appropriate version of Python. The option of just installing Python was new in IMOD 4.7 and had some problems that are resolved in IMOD 4.9. Everything in IMOD will work except a few specialized C-shell scripts, but subtomogram averaging with PEET will not work without Cygwin. If this is the route that you prefer, go to Setting Up a Windows PC and Installing IMOD without Cygwin. A third, less useful way of running IMOD on a Windows PC is described in Using IMOD under "Bash on Ubuntu on Windows".
This section deals with installing Cygwin. We have provided both a Cygwin package and a Cygwin installer to make the installation process simpler and more predictable. Use the installer when installing for the first time. This installation will occupy ~220 MB, all located under a single directory that can be removed easily. The installation will also create icons on the desktop and in the Start Menu, and make several simple entries to the Windows registry. To satisfy the terms of the Cygwin open source license, we also provide the source code matching the binaries in our package. The download links are in the table; the package from October 2014 must be used on Windows XP; the package from January 2017 must be used on Windows 10.
|January 2017||Windows Vista -> 10||Cygwin Installer||Cygwin Package||Matching Source|
|October 2014||Windows XP -> 8||Cygwin Installer||Cygwin Package||Matching Source|
Installing Cygwin creates a Unix-like directory tree (including directories
home) under its top
directory, which is
C:\cygwin by default. Terminal windows
and Cygwin programs such as the Unix tools will display and work with Unix-type
paths that are relative to the top Cygwin directory. For example, if you
install Cygwin in
C:\cygwin, then the location where IMOD will be
installed is referred to as
/usr/local/IMOD from within Cygwin and
will exist in the Windows file systems as
The Cygwin that you use must include Python, which is now
required for building tomograms. It is included in our packages.
If you use a current version of Cygwin from the Cygwin
website, you may need to make sure that there is a Python executable,
recognizable to Windows (see below).
Our Cygwin packages also include a superior terminal window called
a lightweight text editor,
nano (derived from
and similar to the editor in the
pine email program),
The primary advantage of the
mintty window is that you can copy and paste just like under Unix
(highlight with left mouse button, paste with middle mouse button). This
capability uses the Windows clipboard, so you can copy text in a Windows
program (Ctrl-C) and paste with the mouse in the
mintty window, or
highlight in the
mintty window and paste in a Windows program with
Ctrl-V. Another advantage is that you can resize the
horizontally as well as vertically.
Cygwin installation will work best if you are logged in as a user with Administrative privileges.
Use our Cygwin installer for a fresh installation of Cygwin. It performs all the steps described below. Simply click on it; it will unpack itself and launch the Cygwin setup program as well as show a page with some instructions. Note the following points:
cygwinas the directory name.
minttywindow running either a
.minttyrcthere that will give good starting properties for a
.minttyrcwill also be left in /usr/local for other users to copy.
In order to run Etomo, you also need to have Java installed. If you do not already have Java (most machines do now), get the latest Java Run-time Environment from the Java download site. Click on the file and take the defaults related to installing Java (and turn off any defaults to modify your search engine, add toolbars, or other make pernicious changes). When you are done, you can delete any Java icons from your desktop.
You can use our simpler Cygwin package instead to install Cygwin, but then you would have to do all the steps described below yourself. You can also use this package to upgrade a previous Cygwin installation. The rest of this section has steps for installing or upgrading Cygwin from this package:
setup.exeprogram and a
CygwinMasterfolder with all the packages.
C:\cygwinunless you want it on a different disk. Do not install under a directory with spaces in its name. In the rest of this document, C:\ is used in the examples, and you need to substitute your location if it is different.
CygwinMasterfolder as the Local Package Directory
After installation you will get an icon that will start up a shell under
bash. The first time that you run this, a home
directory is created in
C:\cygwin\home) and some
files are copied there.
CygwinMaster folder contains two shortcuts and a configuration
file that make it easy to use
mintty. To use mintty:
CygwinMasterto your desktop, depending on your preferred shell.
CygwinMasterto your Cygwin home directory.
.minttyrcwith the command
mv minttyrc .minttyrc(you cannot do this in Windows Explorer).
minttywindow. You can right-click in the title bar of the window and select Options to get a dialog for adjusting font size and style, colors, default window size, etc..
CygwinMasterfolder to some other place where the users can access them (such as
Occasionally you will get an annoying warning in a terminal window starting with cygwin warning: MS-DOS style path detected. To eliminate this, you need to define an environment variable in Windows with the name CYGWIN and the value "nodosfilewarning". To do so, right click Computer or My Computer on the Desktop, browser window or Start menu, select Properties, Advanced or Advanced System Properties, then press Environment Variables. Press "New" in the "User variables" or "System variables" section. Enter "CYGWIN" as the name and "nodosfilewarning" as the value (without the quotes).
If you want to customize your Cygwin installation instead of using our package,
go to www.cygwin.com, click on "Setup", and
follow the installation procedures. In addition to the
default installation, it is essential that you select
python from the
Python category. In addition, there must be a Python executable named
just a Cygwin link to an executable. The IMOD installer will take care
of creating such an executable, but if you upgrade Cygwin without re-installing
IMOD, you should do the following:
python2.7.exe(or whatever numbered executable shows up in the listing) with
cp /bin/python2.7.exe /bin/python.exe
For Windows, we provide an executable installer that works by clicking on it,
installs IMOD in
/usr/local, copies the startup scripts
/etc/profile.d, and takes care
of putting Cygwin on the system path and setting the environment variables
HOME as described below. Old versions of IMOD are
automatically deleted. If you need something besides this behavior, you
can still run a self-installing package (e.g., a
sh file like
at the command line, as described below.
To use the installer, just click on it and press buttons to confirm each step. There are no choices to make. Open a new Cygwin window and you should be able to run IMOD programs.
Here are some optional steps, whichever way you install IMOD:
C:\cygwin\usr\local\IMOD\bin) to the Windows path, in which case you will be able to run everything, including shell scripts, from a DOS window.
C:\Users, following the procedure described below in the paragraph To define an environment variable in Windows.
nda, mtk, mtoverlap), you can install ghostscript and gsview for Windows.
The rest of this section describes other ways of installing IMOD. If you run a
self-installing package at the command line instead (with filename ending in
it will install IMOD in /usr/local and copy
/etc/profile.d, unless given options telling it to do something
It will not work by
clicking on it, only
by executing it from the command line. To install or upgrade IMOD this way,
start a Cygwin terminal window, change to the directory where the package is
located, and enter, e.g.:
You will have to open a new Cygwin window for a new installation to take effect.
After installation at the command line, everything can be run from a
Cygwin window. In order to run from a Command Prompt window or
to run Etomo by clicking on a shortcut to
also need to define some environment variables inside Windows:
PATH, press "Edit", and add
C:\cygwin\bin;to the front of the path (the ";" is a separator).
Even if you are not running Etomo, if you installed to a drive other than C:,
you should define
IMOD_DIR as an environment variable in
Windows as described above, but with the appropriate letter instead of C, so
3dmod will be able to find help files if it is started by
clicking on an icon.
The steps for manually installing from the tar file instead are:
/usr/localeither from the command line or from an Explorer window, where the location will appear as
/usr/localand, if you have an existing IMOD installed, rename it.
mv IMOD oldIMOD
tar -xzf imod_4.9.1.tar.gz
mv imod_4.9.1 IMOD
cp IMOD/IMOD-cygwin.* /etc/profile.d
To install IMOD without Cygwin using our installer package, you need to have Administrator privileges on Windows versions past XP because, for now, the installation can go only in C:\Program Files.
You must have Python installed to use IMOD fully on Windows, as well as a module called psutil built for the same version of Python. The IMOD installer relies on the registry entries made by Windows Python packages from the Python download site to find Python, so a package from there is probably needed to use the installer. Some packages are provided here:
Unless you know or anticipate that other software will need Python 2.7, you might as well install Python 3. If you need to use a Python package other than the ones here, get a matching version of psutil from the psutil site; use the Download link to get to current versions and the Download tab to get to older versions.
Click on the downloaded file to install it; first Python, then psutil.
Python does not need to install in the default location that it offers;
you can put it in
C:\Program Files under the name of the version (e.g.,
set the install location to
Python installs without using "Run as Administrator", but on Windows
versions past XP, it appears to be necessary to install psutil by
right-clicking and selecting "Run as Administrator".
After Python is installed, click on the IMOD installer. It will
install IMOD in
C:\Program Files\IMOD, define the environment
HOME, and place both IMOD and the version of
Python that it finds on the path. For Windows Vista and higher, it will
In order to run Etomo, you also need to have Java installed. If you do not already have Java (most machines do now), get the latest Java Run-time Environment from the Java download site. Click on the file and take the defaults related to installing Java. When you are done, you can delete any Java icons from your desktop.
If you want to use a better terminal window than the Command Prompt
window, try getting the Console program from
program allows window resizing, font and color control, easy cutting and
pasting with mouse buttons, and multiple tabs.
Unzip the package wherever you want to; it will create a directory
"Console2" with Console.exe inside, to which you can create a shortcut on your
configuration file has some good initial settings. Make a folder
C:\Users\yourUserName\Application Data (or
C:\Documents and Setting\yourUserName\Application Data on
Windows XP) and place the file in that folder.
There is no
man command for viewing program manual pages,
imodhelp programName will open Qt Assistant to the
manual page for the given program. The program name can even be
If there will be multiple IMOD users of the system, they should add HOME
environment variables to point to their directories in
Without Cygwin, environment variables can be set only through a
Windows dialog that can be opened by various means, all described in the
section above, To define an environment variable
in Windows. There is no IMOD startup script, so ignore any
references to IMOD startup scripts below.
If you want to upgrade to a beta version after you have installed IMOD
from one of the executable installer packages, you should find and use an
executable installer on the beta download site. If not, or to install a
nightly build, you need to download the appropriate self-installing
package file, for example,
imod_4.8.50_win64.sh. Copy the
C:\Program Files\IMOD to
the same place that you put the package, which should NOT
C:\Program Files\IMOD. Open a Command Prompt window by
right-clicking on a shortcut and
selecting "Run as Administrator". In the terminal,
the folder with the files and enter (for this example file)
python installIMOD -skip imod_4.10.12_win64.sh
IMOD can be run under the "Bash on Ubuntu on Windows" environment in Windows 10, but this has several disadvantages. The many programs that use OpenMP to access multiple cores will only be able to use one core, and there is no access to hardware acceleration of model displays or to the GPU for computing. This environment is a way to run Ubuntu on a Windows PC, not a way to have Linux tools in the Windows environment. The Ubuntu installation is larger than Cygwin (~1100 MB), and to some extent, it would have to be maintained as a separate operating system. Although the Windows filesystem can be accessed, Windows programs, including the IMOD distributions for Windows, cannot be run. Nevertheless, if you wish to use IMOD under this environment, here are the things to know:
sudo apt-get install libjpeg62
sudo apt-get install default-jre
sudo apt-get install Xorg
Parallel processing is done in IMOD by dividing a job into multiple
parts and using Processchunks
to execute the chunks on multiple processors. Almost all parallel
processing is done through Etomo, which uses Processchunks.
The processors can be either all on one machine,
on multiple machines, or on a cluster queue. In the latter two cases,
the available machines need to be defined in a
cpu.adoc that is located in the directory
pointed to by the environment variable IMOD_CALIB_DIR (default
on Windows without Cygwin). See the example
the manual page for cpu.adoc for full
details on configuring this file.
For a single machine with multiple CPUs, there are three simple options for enabling the parallel processing through Etomo:
[Computer = localhost]
number = 4
export IMOD_PROCESSORS=4(for bash users)
setenv IMOD_PROCESSORS 4(for tcsh users)
Parallel processing on multiple machines requires two things in addition
cpu.adoc file: it must be possible to log
in to all machines via ssh without a password, and the data must be in a
shared file system accessible to all machines.
To set up ssh keys for access without passwords, simply run
ssh-keygen -t rsa
and type Enter for all of the queries. Then enter:
If necessary, distribute this authorized_keys file to the .ssh directories on other machines that do not have the same home directory. The three different kinds of platforms (Linux/Unix, Mac OSX, Windows with Cygwin) may require separately generated keys. If this seems to be the case, run ssh-keygen once on each type of machine then combine the .ssh/id_rsa.pub files from each into one authorized_keys file. Distribute this combined authorized_keys file to the .ssh directories.
Processchunks runs jobs via ssh by starting a non-interactive bash login shell
on the remote computer. Any programs to be run must be on your path when
logging in as a bash user. If you use only IMOD programs in the command file
and IMOD has been installed by the default method, there should be no
problem and nothing else to do. The exception is on Ubuntu with an
older version of IMOD installed. Before IMOD 4.9, the installer did not
copy the IMOD startup scripts to
/etc/profile.d, and the
the environment thus does not get set right for running commands
through ssh. The easiest remedy is to upgrade IMOD.
However, if you set up the IMOD environment in your own startup files instead
of in the default way, you need to make sure that the environment is defined
when running this bash shell. Specifically, you need to set the IMOD_DIR
environment variable then source
$IMOD_DIR/IMOD-mac.sh in your
and not just in your
~/.bashrc, since the latter is not run by the
non-interactive shell. Similarly, if you are running programs outside IMOD
whose environment is set up in your own startup files, you need to do
~/.bash_profile. However, we have found that in
other contexts it does not work to set environment only
~/.bash_profile. Thus, the recommended approach is to
set the environment in
~/.bashrc and source that file
To diagnose problems, there are a few tests that you can run by issuing the
same kind of command that Processchunks uses to run jobs, of the form:
ssh -x machine bash --login -c \'"command"\'
where the command can be relatively complex because of the quoting; but the quoting can be omitted for simple commands. Specifically, use
ssh -x machine bash --login -c \'"cd directory"\'
to test if you can change to the given directory. Use
ssh -x machine bash --login -c imodinfo
to test if the remote machine can run IMOD this way, and use
ssh -x machine bash --login -c env > env.out
to collect the environment if there is trouble running IMOD.
It is possible to have a user name as part of the machine name
(user@machine) in these ssh commands, in the
file, or in the machine names provided when running Processchunks
directly. However, although the user name may be different between
machines, it should be the same user in some sense (probably in terms of
the user ID on the systems).
With all IMOD 4.9 packages, you can use the graphics processing unit (GPU) of an NVIDIA graphics card to compute tomograms. The card must be of a kind that supports processing with a system called CUDA, and you also need to have NVIDIA drivers new enough to support CUDA. To see if your card can be used, check it in NVIDIA's lists . Most of the packages for IMOD 4.9 are built with CUDA version 6. A few packages are built for older CUDA versions. A package built with a particular version of CUDA will work with CUDA drivers of the same or a higher version. However, there is a significantly longer startup time using a package built with a version below 6 with CUDA 6 or higher, so you should use a package built with 6 (if available) if your drivers support that. Here are details for the three operating systems:
The easiest way to test whether the GPU is functioning and computing reliably
is to run the command:
This will unpack test data and do a one-minute test for reproducibility.
And optional argument can be added to set the length of the test in minutes; an
optional second argument can be used to specify the GPU number when there is
more than one. A few cards do give variable results, so it is important
to test for reproducible results initially, periodically thereafter, and
especially after upgrading the NVIDIA drivers or the operating system.
There is also a button on the Front Page of Etomo for running this test.
If the test fails, the file
gputtest.log will have some
diagnostic information, in particular a line like
CUDA version - driver: 6.050 runtime: 6.000
which would indicate a version problem if the driver is lower than the runtime.
The GPU can be enabled for use when making reconstructions in Etomo in one of two ways. If you have a cpu.adoc file to specify machines available for parallel processing, then you need to add a line
gpu = 1
to the section for each computer with a usable GPU. If you do not have a
cpu.adoc file, then select Settings from the Options menu
of Etomo. In the box User Level Enhanced Processing, check Enable
graphics processing. However, if there is more than one gpu in
your computer, the only way to access this is by providing
cpu.adoc with a line like
gpu.device = 1,2,3
See the cpu.adoc help file for details
and the example
cpu.adoc file in
If you want to know how much speed improvement your system has, get
from our benchmark
directory and follow
the instructions in the
README file there. More extensive
benchmarks are available in the file
On Linux, permissions on the files
/dev/nvidia* can prevent the
GPU from being used by someone ssh'd into the computer while someone else is
logged in to the workstation. In RHEL5 and related systems, this is
solved by editing
changing the entries on the line for <dri> from 0600 to 0666, i.e.,
<console> 0666 <dri> 0666 root
Several parts of IMOD look for data and configuration files in a separate
location, pointed to by the environment variable IMOD_CALIB_DIR. These files
cpu.adoc file for enabling parallel processing,
distortion correction files, noise files for microscope CTF correction, and
local startup files. The default value for IMOD_CALIB_DIR is
on all platforms except Windows without Cygwin, where it is set to
C:\ProgramData\IMOD on Windows Vista and higher. It is set
in the IMOD startup scripts if it is not already defined. We have designed
this directory as a place for local files
that should not be replaced when IMOD is upgraded. Minimally, then, you may
want to create this directory and place a
cpu.adoc there defining
the number of processors on one or more machines. In addition, the IMOD startup
scripts will try to source local startup scripts in this directory:
$IMOD_CALIB_DIR/IMOD.sh. You can use these startup scripts
for customizations, such as redefining
IMOD_JAVADIR, instead of
modifying the startup scripts that come with IMOD and get replaced with each
new version. However, if you are going to take advantage of this mechanism and
want to redefine
IMOD_CALIB_DIR to point to a different location,
your startup must set this environment variable before sourcing the IMOD
You will want to go through the Introduction to 3dmod
3dmod is the central graphical tool of the IMOD
package. If you are doing tomography, you should start with the
Etomo tutorial. This Etomo tutorial is also available in video
form on our YouTube channel.
If you are doing reconstructions from serial images such as serial thin
sections or serial block face images, you should work through the
Serial Section Alignment guide, which
will take you through the steps needed to align the images in Etomo.
For access to the complete IMOD documentation, just enter
at the command line to open it in the Qt Assistant, where it can be browsed and
Aside from learning to use the major tools, your initial problem may be getting data into a format usable by the IMOD programs. If you are having problems getting your data into a format usable by IMOD contact us for help.
All of the IMOD programs read and produce files in
the MRC image file format.
They can also read TIFF files and files in several specialized
image formats compatible with MRC: DigitalMicrograph, PIF files from
Bsoft, EM, and Hanspeter Winkler's NFF. New in IMOD 4.9 is the ability
to read and write HDF files in a format compatible with EMAN2; files
from UCSF Chimera can also be read.
In addition to those formats,
3dmod can read some other common
formats like JPEG, PNG, and BMP,
and it has a dialog box and options for specifying how to read raw
In IMOD 4.9, programs write MRC files in byte mode as signed by default (values of -128 to 127), which is a change from previous behavior to conform with a clarification of the MRC standards. Such files will not be read correctly by IMOD versions before 4.3, and you may encounter other software that has difficulty with signed byte files. Two programs have command-line options to produce unsigned output files (values 0-255): newstack (option "-byte 0") and clip (option "-m ubyte"). In addition, you can make all programs write unsigned bytes by setting the environment variable WRITE_MODE0_SIGNED to 0. As of September 2017, ImageJ does not read signed byte files correctly unless you import them through the Bioformats tool. Please inform the IMOD developers if you run into other up-to-date software that does not read signed bytes correctly.
Even though IMOD programs can read multiple file types, you will generally want to convert your data to a stack of images in MRC format, because most programs are designed to operate on a stack of images in a single file rather than on a set of single-image files. Thus, we have utility programs available for converting TIFF files and raw data into the MRC file format and combining single-image files into a stack.
Use the program tif2mrc to convert a series
of TIFF image files into a single MRC image file. The
has an option for converting 24-bit color to 8-bit grayscale images, and
options for dealing with unsigned 16 bit images, which are a potential problem
because the standard MRC format supports only signed 16-bit images. The
following example entry will create a MRC file from a list of TIFF files
(cell01.tif, cell02.tif ...).
tif2mrc cell*.tif cell.mrc
The files must be in the current directory of the terminal where you
enter the command. See the tif2mrc
manual page for more information on how to
Use the program dm2mrc to convert a series of
DigitalMicrograph image files into a single MRC image file. The following
example will create a MRC file from a list of DigitalMicrograph files
(cell01.dm3, cell02.dm3....; note that dm2 and dm4 files are also
dm2mrc cell*.dm3 cell.mrc
If you have a series of MRC files, with one image per file, you can
combine them into a single stack easily with the program newstack.
For example, enter
newstack cell*.mrc cell.st
You can also use
newstack to stack TIFF and
DigitalMicrograph files, provided that no special conversion options are
The program raw2mrc is used to convert raw
image data into the mrc format. This program can take a file of 8, 16,or 32 bit
integers, IEEE float values, or 24-bit RGB triplets and convert them into an
MRC image file. In MRC files, the data start in the lower left hand corner of
the image, with the data stored in rows. To use
raw2mrc, you need
to know the size of the images, the type of data, and the size of any header
information preceding the image. For example, if you have a set of files
(cell01.em, cell02.em, ...) with 1024 x 1024 images of signed 16-bit integers,
and a header of 512 bytes, use:
raw2mrc -t short -x 1024 -y 1024 -o 512 cell*.em cell.mrc
If the data need to have their bytes swapped because they come from a machine with the opposite byte ordering (e.g. PPC Mac versus Intel), use the -s option. If you do not know something about the image, such as the header size or whether the data are unsigned or need swapping, you may be able to figure it out just by trying different options for data types and swapping. If you do not know the header size, convert one file without the -o option, load it into 3dmod, and try to see where the image data start. If the final MRC image is upside down use the -f option in the initial conversion or use the program clip to flip the image back.
When a 3dmod is started with an image file that
it does not recognize, it brings up a dialog that allows you to specify the
image and header size and the data type. Alternatively, you can specify
these features with options at the command line, which could be the most
convenient way to experiment and find the right values. For example, the
files in the previous command could be displayed with:
3dmod -r 1024,1024,1 -H 512 -t 1 cell*.em
If you already have a 3-D model and wish to view it within the IMOD model
3dmodv, you will need to convert the file into
the IMOD format. See the IMOD model file format ASCII
and binary specifications if you wish to write
your own conversion program.
The IMOD model format can be either binary or ASCII.
use of the ASCII format would be to access the data for analysis or conversion
by other programs. To convert a binary IMOD file (binary.imod) to an ASCII IMOD
file (ascii.imod) use the imodinfo command:
imodinfo -a binary.imod > ascii.imod
imodinfo -a -f ascii.imod binary.imod
will both create an ASCII model file from the binary.imod model. The ASCII format preserves many but not all possible features in the model. It is moderately complex and may not be the most convenient format to use for exporting or importing data. There are also two programs, model2point and point2model, that can be used to convert an IMOD model to or from a simple list of point coordinates.
In order to get accurate information the fields in the model header have to be set properly. See the Introduction to 3dmod for an explanation of how to do this. Selecting the Edit->Contour->Info menu item from the 3dmod Information Window will cause some quantitative information to be printed out in the bottom panel of the window.
Use the imodinfo command to get basic
information from a model and print it out to a terminal or file. For example:
# MODEL cell.imod
# NAME A little cell
# PIX SCALE: x = 1
# y = 1
# z = 9.17
# PIX SIZE = 0.00654
# UNITS: um
NAME: spindle pole
object uses closed contours.
color (red, green, blue) = (0, 1, 1)
CONTOUR #1,2,0 16 points, length = 0.464513, area = 0.0134249
CONTOUR #2,2,0 14 points, length = 0.458311, area = 0.0125642
CONTOUR #3,2,0 8 points, length = 0.200755, area = 0.00277481
CONTOUR #4,2,0 13 points, length = 0.313501, area = 0.00664029
CONTOUR #5,2,0 9 points, length = 0.232374, area = 0.00272134
Total volume = 0.00228646
Total contour cylinder surface area = 0.10012.
Total mesh surface area = 0.0349499.
There are several useful command line options for imodinfo to extract lengths of contours into a single column output, print surface and point size information, and compute volumes and mesh areas. A text file can be created using the -f option.
IMOD models can be converted to a few other 3rd party formats. The formats and the programs used to convert to them are listed below.
See also: Manual pages for 3dmodv, imodmesh, and imodinfo.
This list shows only the most important of the many documents in
IMOD. A complete set of links to all of the documention can be found in
Index file with links to all files in the current set of documentation being viewed.
Web page section with links to all documentation in either the current stable release or beta version of IMOD, as well as links for downloading tutorial data sets.