IMOD User's Guide for Version 4.7

Boulder Laboratory for 3-D Electron Microscopy of Cells


Table of Contents

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.


1. Installation

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 C 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 script, e.g.,
   csh -f imod_4.7.1_RHEL6.csh

(In this guide, the specific filenames are used as an example; your copy may have higher version numbers.) You cannot click on the .csh 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 since IMOD 3.0.8, 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.,
  csh -f imod_4.7.1_RHEL6.csh -dir /opt

Older versions will be renamed, and at the end the installation script will offer to remove them for you.  People with special requirements not anticipated by the install script may need to work with the tar file instead.  It can be extracted with:
   csh -f imod_4.7.1_RHEL6.csh -extract

The gzipped tar file and the install script will be left in a subdirectory named IMODtempDir.  There are several other useful options: -script to install startup scripts to a different location, -skip to skip installing startup scripts, -name to have the IMOD directory be renamed to the given name.  Use:
  csh -f imod_4.7.1_RHEL6.csh -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.

1.1. Setting Up a Linux PC to Run IMOD.

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, 256 MB or higher cards preferred)
Minimum memory size: 2 GB
Minimum disk size: 50 GB
Operating System: Red Hat Workstation 5 or Fedora 6 or higher
Recent Nvidia Linux device drivers and OpenGL libraries from Nvidia

Nvidia installation. Installing Nvidia drivers is now straightforward on some systems, but here are some instructions that may be helpful for older Fedora (up to 16 or so) and Red Hat/Centos through version 6.  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 the 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.

Window manager settings. To keep 3dmod from bogging down when it is displaying complex models, some window managers can be set to display only the outline and not the contents of windows when they are moved or resized.  This cannot be done under Gnome but it can generally be done under KDE if you can find the "Window Behavior" control panel. For example, on RHEL5 you can run kcontrol at the command line to open the Control Center and selecting "Look and Feel" or "Desktop" (depending on KDE version), then "Window Behavior" then the "Moving" tab.  On Fedora 11, open System Settings from the main menu, select "Look and Feel" and "Window Behavior" and "Window Behavior" again, then the "Moving" tab.  Also, on the "Advanced" tab you should turn off "Hide utility windows for inactive applications" to keep undocked toolbars in 3dmod from disappearing.  Both 3dmod and eTomo have problems under Compiz, so you should disable this.  On older Ubuntu, open the menu entry System - Preferences - Visual Effects and select "No effects".

tcsh and libjpeg62 for Ubuntu. You must install tcsh even if you also have csh installed.  Things should work with both installed, but it would be safer to have only tcsh.  You can install tcsh through the Synaptic Package Manager or Ubuntu Software Manager or with:
   sudo apt-get install tcsh
You will also need 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

tcsh and libpng12 for Fedora. The standard Fedora install no longer includes tcsh, so you must install it before trying to install IMOD, with:
   sudo yum install tcsh
You will also need version 1.2 of the PNG libraries, which is not present on newer systems. The sign of needing this is an error message when trying run 3dmod: error while loading shared libraries: libpng12.so.0: cannot open shared object file: No such file or directory. Install a compatibility library with:
   sudo yum install libpng12

1.2. Installing IMOD on a Linux PC

The self-installing package will install to a directory named IMOD under /usr/local unless given an alternate location to /usr/local with the -dir option.  It will copy the startup scripts IMOD-linux.sh and IMOD-linux.csh to /etc/profile.d. unless given an alternate location with the -script option or told to skip this step with the -skip option, or unless you are running Ubuntu or give the -debian option.  It the latter cases, it will modify /etc/bash.bashrc and /etc/csh.cshrc to source the startup scripts from the IMOD directory, unless you give the -skip option.  To accomplish all of this, change directory to the place where the package is located and enter, for example:
     sudo csh -f imod_4.7.1_RHEL6.csh

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 /etc/cshrc, /usr/local/etc/cshrc, or users' .cshrc, .bashrc, or .bash_profile files.

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 the .cshrc files of individual users of tcsh (where <location of IMOD> is the absolute path to the IMOD directory):

setenv IMOD_DIR <location of IMOD>
if (-e $IMOD_DIR/IMOD-linux.csh) source $IMOD_DIR/IMOD-linux.csh

or, place the following in the .bashrc or .bash_profile of  individual users under bash:

export IMOD_DIR=<location of IMOD>
if [ -e $IMOD_DIR/IMOD-linux.sh ] ; then source $IMOD_DIR/IMOD-linux.sh ; fi

Alternatively, if there are system-wide startup scripts sourced from the users' .cshrc or .basrc/.bash_profile, you 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:
       csh -f imod_4.7.1_RHEL6.csh -dir testIMOD -skip

This will manage an installation of IMOD under the directory testIMOD, offering to delete other versions there.  To run with this IMOD, cd to testIMOD/IMOD and enter:

   setenv IMOD_DIR `pwd`    (under tcsh, or)      export IMOD_DIR=`pwd`   (under bash)
   source IMOD-linux.csh    (under tcsh, or)     source IMOD-linux.sh   (under bash)

Manual Install.  To install manually from the tar file, do the following steps after running the self-installing file with the -extract option:

  1. Log in as root or do all of these commands with sudo
  2. cd to the directory where you downloaded IMOD, and
      mv imod_4.7.1_RHEL6.tar.gz /usr/local
  3.   cd /usr/local 
  4.   tar -xzf imod_4.7.1_RHEL6.tar.gz
  5. To see if you already have a /usr/local/IMOD,
      ls -l
  6. If you do have a /usr/local/IMOD and it is a link (e.g., it shows up as IMOD -> imod_2.7.6), then enter
      rm IMOD
    Otherwise, rename the existing directory, e.g.:
      mv IMOD oldIMOD
  7.   ln -s imod_4.7.1 IMOD
  8. Except on Ubuntu and other Debian systems,
      cp IMOD/IMOD-linux.* /etc/profile.d

On Ubuntu when installing manually, instead of step 8, you would insert commands into /etc/csh.cshrc and /etc/bash.bashrc just like those given above for inserting in users' .cshrc and .bash_profile files, respectively. 

1.3. Installing Java on a Linux PC

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 and RedHat-based systems have had usable native Java packages available or installed.  Check your system with
    java -version
If you see Java(TM) (as on RHEL5 and RHEL6) or OpenJDK (as on Centos 5 and recent Fedora) then the installed java should work.  Otherwise, you will need to install a Sun/Oracle version.  Sun/Oracle's JRE version 1.6.0_20 is available here for 32-bit Linux and here for 64-bit Linux.  On most newer 64-bit systems you will generally need a 64-bit version. 

On older versions of Ubuntu, the sun-java6-jre package available in the Synaptic Package Manager seemed to work well, while openjdk-6-jre gave display problems. On Ubuntu 11, the openjdk-6-jre offered by the Ubuntu Software Center seems to work well.

If you are installing a 64-bit system, modify all the commands given next appropriately.  To install the JRE for Linux first move the jre-6u20-linux-i586.bin file to /usr/local
   sudo mv jre-6u20-linux-i586.bin /usr/local

Next change your working directory to /usr/local and  execute the bin by entering
   cd /usr/local
   sudo sh jre-6u20-linux-i586.bin

on the command line.  

This will install the JRE in /usr/local/jre1.6.0_20.  The IMOD startup scripts will assume that the JRE is in /usr/local/java if java is not on your command path, so next create a link:
   sudo ln -s jre1.6.0_20 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 /usr/local/java, 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 IMOD.csh and IMOD.sh in /usr/local/ImodCalib that set this environment variable, rather than modifying the IMOD-linux.sh and IMOD-linux.csh scripts in /etc/profile.d (see Using the ImodCalib Directory).

1.4. Installing IMOD on a Macintosh running OS X

Be sure to install the right package for the processor type: _osx_intel for an Intel processor or _osx_ppc for a PowerPC (G4, G5, etc).  The self-installing package will install to /Applications or to an alternate location with the -dir option.  It will not work by clicking on it, only by running it at the command line.  It will place appropriate "source" commands for defining the user environment in /etc/csh.login and /etc/profile. 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 csh -f imod_4.7.1_osx_intel64.csh

 You will need to exit and restart Terminal for these changes to take effect, or you can just source /etc/csh.login (if you are running tcsh) or /etc/profile (if you are running bash). 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 /etc/csh.login, /etc/profile, or users' .cshrc, .bashrc, or .profile files.

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.  Run the linklibs-mac script by entering:
   sudo $IMOD_DIR/linklibs-mac -i

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

If you are upgrading IMOD and have done this before, you should run $IMOD_DIR/linklibs-mac -u before installing the new version.

Java for OS X 10.7 - 10.9.  Java is not installed by default in OS X 10.7 and above.  The system will offer to install it for you the first time you run a Java program.  To check the status of Java and get it installed, in the terminal, enter
   java -version

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 3dmod 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 -extract option, you have two alternatives. To do it from the command line, open a Terminal window and:

  1. cd to the directory where you downloaded IMOD, and
       sudo mv imod_4.7.1_osx_intel64.tar.gz /Applications
  2.    cd /Applications
  3.    sudo tar xzf imod_4.7.1_osx_intel64.tar.gz
  4. To see if you already have a /Applications/IMOD,
       ls -l
  5. If you do have a /Applications/IMOD and it is a link (e.g., it shows up as IMOD -> imod_3.1.6), then enter
       sudo rm IMOD
    Otherwise, rename the existing directory, e.g.:
       sudo mv IMOD oldIMOD
  6.    sudo mv imod_4.7.1 IMOD

If you are on a single user-machine or have administrative privileges from the desktop, you can use the following alternative approach:

  1. Click on the downloaded file to unpack it with Stuffit Expander and create the IMOD folder, e.g. imod_4.7.1
  2. Drag this folder into the /Applications folder.
  3. If you already have an IMOD folder in /Applications, rename it or move it elsewhere.
  4. Rename the new distribution to IMOD.

Whichever approach you use, you need to add some startup commands to the system files /etc/csh.login and /etc/profile, unless they are already there from a previous installation of IMOD. Use sudo to invoke emacs or pico on these files, .e.g.:
   sudo emacs /etc/csh.login
 Copy the text in IMOD/mac.cshrc to the end of /etc/csh.login, specifically the command
if (-e /Applications/IMOD/IMOD-mac.csh) source /Applications/IMOD/IMOD-mac.csh

Similarly, copy the text in IMOD/mac.bashrc to the end of /etc/profile, specifically the command
[ -r /Applications/IMOD/IMOD-mac.sh ] && source /Applications/IMOD/IMOD-mac.sh

If you want to install at another location, change /Applications/IMOD to the name of the top IMOD directory in IMOD-mac.cshand IMOD-mac.shand in the source commands placed in /etc/csh.login and /etc/profile. If you are sure you are not going to install somewhere else in the future, you can avoid modifying IMOD-mac.csh and IMOD-mac.sh by defining IMOD_DIR before the source commands, i.e. with
   setenv IMOD_DIR <Location_of_IMOD>
before the source command in /etc/csh.login, or with
   export IMOD_DIR=<Location_of_IMOD>
before the source command in /etc/profile .

See the above instructions for Linux PC for other variations on installation procedures.

1.5. Setting Up a Windows PC to Run IMOD with Cygwin

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 is new for IMOD 4.7; 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

This section deals with installing Cygwin. We have provided both a Cygwin package and a Cygwin installer (from March 2010) to make this process simpler and more predictable.  This installation will occupy ~100 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.

Installing Cygwin creates a Unix-like directory tree (including directories bin, etc, usr, and 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 C:\cygwin\usr\local\IMOD.

The Cygwin that you use must include Python, which is now required for building tomograms.  Our last two Cygwin packages have included Python.  If you use a current version of Cygwin from the Cygwin website, you may need to make sure that there is a Python executable, /bin/python.exe, recognizable to Windows (see below).

Our Cygwin packages also include a superior terminal window called mintty and a lightweight text editor, nano (derived from pico and similar to the editor in the pine email program).  We used to include rxvt and have now switched to mintty because it has a better interface and because rxvt is no longer supported and has developed problems in this Cygwin release. 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 mintty window horizontally as well as vertically.

Cygwin installation will work best if you are logged in as a user with Administrative privileges.

Use our 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:

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 Java download site.  Click on the file and take the defaults to install Java. 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:

  1. Click on the package to extract it. Press "Browse" and select a folder to unzip to that is conveniently accessed (the Desktop will do).  You will get the setup.exe program and a cygwinMaster folder with all the packages.
  2. Click on setup.exe
  3. Select install from a Local Directory
  4. Set the root drive to C:\cygwin unless 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.
    Take the default for the other selection: install for all users.
  5. Select the cygwinMaster folder as the Local Package Directory
  6. On the Select Packages page, click on the circular double arrow next to "All" to switch from "Default" to "Install"
  7. Proceed with the installation, and take the defaults to create icons on the desktop and start menu.

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 /home (C:\cygwin\home) and some bash startup files are copied there.

The cygwinMaster folder contains two shortcuts and a configuration file that make it easy to use mintty. To use mintty:

  1. Copy one of Cygwin-bash.lnk or Cygwin-tcsh.lnk from cygwinMaster to your desktop, depending on your preferred shell.
  2. Copy minttyrc from cygwinMaster to your Cygwin home directory.
  3. In a Cygwin window, rename minttyrc to .minttyrc with the command mv minttyrc .minttyrc (you cannot do this in Windows Explorer). 
  4. Click on the shortcut that you copied to get a mintty window.  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..
  5. Delete the existing Cygwin shortcut on your desktop and rename the Cygwin-bash or Cygwin-tcsh shortcut to Cygwin.
  6. If there are other users of Cygwin on your system, copy the shortcuts and minttyrc from the cygwinMaster folder to some other place where the users can access them (such as /usr/local).

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 tcsh from the Shells category and python from the Python category.  In addition, there must be a Python executable named /bin/python.exe, not 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:

  1. In a terminal window, enter
       ls /bin/python*
    to see if there is a python.exe
  2. If there is not, copy python2.7.exe (or whatever numbered executable shows up in the listing) with
       cp /bin/python2.7.exe /bin/python.exe
If you upgrade Cygwin and you DO reinstall IMOD, it will fail if there is an old python.exe from Python 2.6. In that case, you can just remove python.exe and run the installer again, or you can do the copy just described.

1.6. Installing IMOD on a Windows PC with Cygwin

For Windows, we provide an executable installer that works by clicking on it, installs IMOD in /usr/local, copies the startup scripts IMOD-cygwin.sh and IMOD-cygwin.csh to /etc/profile.d, and takes care of putting Cygwin on the system path and setting the environment variables IMOD_DIR and 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 csh file like imod_4.7.1_win.csh) 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:

  1. You can add the location of the IMOD bin directory (e.g., 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.
  2. If you want to be able to display and print Postscript graphs from the Fortran graphics programs (e.g., 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 .csh), it will install IMOD in /usr/local and copy IMOD-cygwin.sh and IMOD-cygwin.csh to /etc/profile.d, unless given options telling it to do something else. 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.:
    csh -f imod_4.7.1_win.csh

You will have to open a new Cygwin window for a new installation to take effect.

After installation, everything can be run from a Cygwin window.  In order to run eTomo, you also need to define some environment variables inside Windows:

  1. Right click My Computer, select Properties, Advanced, Environment Variables. Define all of these paths in Windows format as illustrated in the following steps. Press "New" to define a variable.
  2. Under "System variables", define IMOD_DIR to be C:\cygwin\usr\local\IMOD
  3. Under "User variables for username", define HOME to be C:\cygwin\home\username
  4. You also need to add the Cygwin bin to the system path, e.g., under "System variables", select 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 that 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:

  1. Start a Cygwin terminal window.
  2. Move your copy of the IMOD distribution to /usr/local either from the command line or from an Explorer window, where the location will appear as C:\cygwin\usr\local.
  3. Change directory to /usr/local and, if you have an existing IMOD installed, rename it.
       cd /usr/local
       mv IMOD oldIMOD
  4.  Unpack the tar file, rename it to IMOD, and copy startup files:
       tar -xzf imod_4.7.1.tar.gz
       mv imod_4.7.1 IMOD
       cp IMOD/IMOD-cygwin.* /etc/profile.d

1.7. Setting Up a Windows PC and Installing IMOD without Cygwin

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 C:\Program Files\Python3.2). 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 variables IMOD_DIR, IMOD_CALIB_DIR, and IMOD_PLUGIN_DIR, and place both IMOD and the version of Python that it finds on the path.

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 to install 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 sourceforge. This 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 desktop. This configuration file has some good initial settings. Make a folder named Console inside 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, but imodhelp programName will open Qt Assistant to the manual page for the given program. The program name can even be abbreviated.

If you want to upgrade to a beta version after you have installed IMOD from one of the executable installer packages, you need to download the appropriate self-installing package file from the beta download site, for example, imod_4.8.10_win64.csh. Copy the file installIMOD from C:\Program Files\IMOD to the same place that you put the package. In a terminal, cd to that folder and enter (for this example file)

    installIMOD -skip imod_4.8.10_win64.csh

1.8. Using a GPU for Tomography

With all IMOD 4.7 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.7 are built with CUDA version 4.1.  A few packages are built with CUDA 2 or with CUDA 3.  When there are two packages for a particular operating system, the one not built with CUDA 4 has CUDA and the version number in its name.  A package built with a particular version of CUDA will work with CUDA drivers of the same or a higher version.  Here are details for the three operating systems:

The GPU can be enabled for use through 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

The easiest way to test whether the GPU is functioning and computing reliably is to run the command:
   gputilttest

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 you want to know how much speed improvement your system has, get tilttimers.tar.gz from our ftp site and follow the instructions in the README file there.

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 /etc/security/console.perms.d/50-default.perms and changing the entries on the line for <dri> from 0600 to 0666, i.e.,

<console> 0666 <dri> 0666 root

1.9. Using the ImodCalib directory

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 include the 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 /usr/local/ImodCalib on all platforms, and 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-...csh will source $IMOD_CALIB_DIR/IMOD.csh and IMOD-...sh will source $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 startup scripts.

2. Getting Started

You will want to go through the Introduction to 3dmod because 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 imodhelp at the command line to open it in the Qt Assistant, where it can be browsed and searched. 

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.

2.1. The Image Data Format and File Conversion

All of the IMOD programs read and produce files in the MRC image file format. As of IMOD 4.7, 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. 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 data.

As of IMOD 4.7, programs will 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.

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 tif2mrc program 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

See the tif2mrc manual page for more information on how to use tif2mrc.

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 supported.)
      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 
With the new file-reading capabilities in IMOD 4.7, you can also use newstack to stack TIFF and DigitalMicrograph files, provided that no special conversion options are needed.

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

2.2. The Model Format

If you already have a 3-D model and wish to view it within the IMOD model viewing program, 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. Model files from the HVEM3D program can be converted to the IMOD model format using the rec2imod program.

The IMOD model format can be either binary or ASCII. Currently supported machines can all read and write binary model files interchangeably, so the main 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
or
    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.

3. Getting Quantitative Information

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:
   imodinfo cell.imod

# MODEL cell.imod
# NAME A little cell
# PIX SCALE: x = 1
# y = 1
# z = 9.17
# PIX SIZE = 0.00654
# UNITS: um

OBJECT 1
NAME: spindle pole
5 contours
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.

4. Output to Other Model Formats

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.

 

5. Help on Specific Topics


Last updated: February 2, 2014 [IMOD Home Page] [BL3DEMC Home Page]