IMOD User's Guide for Version 4.11

University of Colorado, Boulder


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 shell script that can extract and install the programs.  For Windows and Mac, there is an executable installer than runs this script; for Linux you need to run the script yourself at the command line.  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 use the installers on Windows and Mac, and install on Linux simply by running the script, e.g.,
   sh imod_4.11.1_RHEL6.sh

(In this guide, the specific filenames with "4.11.1" are used as an example; you should always substitute the full name of the file that you are installing for the one shown here.) You cannot click on the .sh file to install it.  This command will not work on Windows unless the Cygwin toolkit is installed. The executable installer for Windows (with extension .exe) does work by clicking on it 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 method. 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.11.1_RHEL6.sh -dir /opt

Older versions will be renamed, and at the end the installation script will offer to remove them for you.

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.11.1_RHEL6.sh -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:
  sh imod_4.11.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.

1.1. Installing Java for Etomo.

To run Etomo, you need a Java run-time environment (JRE), version 1.7 or higher, installed and accessible to IMOD. You should use an OpenJDK version of Java. Most Linux distributions have an OpenJDK package available if not in the default install. On Ubuntu 18 and 20, OpenJDK java can be installed with
    sudo apt install default-jre

For Red Hat 8, the default install includes only a "headless" version and you will need to install a proper version with
    sudo yum install java-1.8.0-openjdk

where you could use java-11-openjdk instead.
For Windows, Mac, and other Linux distributions, you will need to download a package. A good source of the latest installer packages is Adoptium, where packages are referred to as "Eclipse Temurin". Oracle now requires a paid license for most Java packages and you are probably not eligible to run one of their installer packages for free. (You can use one for free if your institution has a license or you are not being paid to work with IMOD.) Their "open source" packages are free but currently are not installers, just compressed archives that do not make the program easily runnable. On a Mac, this means that when you try to run Etomo with no Java installed, if the OS puts up a message that takes you to the Oracle site, you should ignore it.

Download a JRE or JDK from the Adoptium releases page. If you start at the Adoptium home page, press the "Other platforms" button to get to this page; the "Latest Release" button on the home page downloads a Java software development kit (JDK) that is considerably larger and is not needed. You can choose the latest release or one of the releases marked as LTS (long term support); they are all compatible with Etomo and all are being maintained with security updates. Keep the default selection of the JVM, the HotSpot. Download a JRE for your operating system, or a JDK if a JRE is not available.

Windows. Click on the installer to run it and take the default options, in particular the one to put Java on the path.

Mac OS. Click on the installer to run it. It will install to  /Library/Java/JavaVirtualMachines. By some mysterious means, running /usr/bin/java should end up running the highest version in this directory (or the most recent installation, if there is both a JRE and a JDK of that version). To verify that it is running the intended version, enter
   java -version

In IMOD 4.11, the Etomo startup script in these packages will look for the latest directory in /Library/Java/JavaVirtualMachines and run the Java there. If this fails or is not running the right version, there are two options:

  1. Set the environment variable IMOD_JAVADIR to the directory in the package containing the bin directory, for example
       export IMOD_JAVADIR=/Library/Java/JavaVirtualMachines/adoptopenjdk-12.jre/Contents/Home

    To set this on a system-wide basis, you can make a file IMOD.sh in /usr/local/ImodCalib with this line; or you can add the line to /etc/profile and /etc/zprofile in the place where the IMOD environment is set.
  2. Put the bin directory in the package on your path, for example
       export PATH="/Library/Java/JavaVirtualMachines/adoptopenjdk-12.jre/Contents/Home/bin:$PATH"

    To do this on a system-wide basis, make either of the two changes described for option 2.

Linux. If your distribution does not provide OpenJDK packages, see if you can use the RPM or DEB install packages from AdoptOpenJDK and follow the instructions there for installation. Otherwise, you will need to get one of their .tar.gz packages and untar in a location of your choice. Then you have two options: set the environment variable IMOD_JAVADIR to the top Java directory; or add the bin directory that it contains to your PATH. To do either of these on a system-wide basis, you can put the appropriate line in files IMOD.sh and/or IMOD.csh in /usr/local/ImodCalib.

Java is notoriously insecure when run in browsers and requires frequent updating if a browser is enabled to run Java. The frequency of security vulnerabilities when using it just to run a program like Etomo is less clear; but it is a good idea to keep it up to date.

1.2. Setting Up a Linux PC to Run IMOD.

IMOD development for Linux is done on Red Hat Workstation 7 with NVIDIA cards, and computation on the graphics card is supported only for NVIDIA cards. For graphics (e.g., IMOD model display), AMD cards are a reasonable alternative. We actively maintain compatibility with Ubuntu, and deal with issues that come up on other Linux distributions as necessary.

NVIDIA installation. Installing NVIDIA drivers is 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 control which graphics device programs use. At least as of a few years ago, you could 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.

Java for Etomo. To check whether you have Java installed, run the command
   java -version

If there is no Java or it is not an OpenJDK version, see 1.1 Installing Java for Etomo..

Python on Ubuntu 18 and 20 and Red Hat 8. Ubuntu 18 and 20 and Red Hat 8 install 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/python3 to /usr/bin/python, or you can use the Python 3 just for the IMOD install, then install Python 2 explicitly if you want to use that for some reason. On Ubuntu you can do so with
   sudo apt install python
and if the IMOD installer made a link in /usr/bin, it will be replaced when you install Python 2. On Red Hat 8, you can install Python 2 with
   sudo yum install python2
but the executable is named python2, and if the IMOD installer made a link in /usr/bin, it will be removed. You will need to make a link yourself, with
   sudo ln -s /usr/bin/python2 /usr/bin/python

tcsh for Ubuntu, Fedora, or Red Hat 8. Only a few very specialized scripts in IMOD require tcsh, although you would need it to install very old versions of IMOD with package names ending in .csh instead of <.sh. The standard Red Hat 8, 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 or Red Hat 8 with:
   sudo yum install tcsh

1.3. 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 an Ubuntu version before 10 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 sh imod_4.11.1_RHEL7-64_CUDA8.0.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 /etc/profile, /etc/cshrc, /usr/local/etc/cshrc, or users' .bashrc, .bash_profile, or .cshrc 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 .bashrc or .bash_profile 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 .cshrc files of individual users of tcsh :

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 the users' .bashrc/.bash_profile or .cshrc, 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:
       sh imod_4.11.1_RHEL7-64_CUDA8.0 -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:

   export IMOD_DIR=`pwd`    (under bash, or)      setenv IMOD_DIR `pwd`   (under tcsh)
   source IMOD-linux.sh    (under bash, or)     source 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 -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.11.1_RHEL6.tar.gz /usr/local
  3.   cd /usr/local 
  4.   tar -xzf imod_4.11.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_4.7.15), then enter
      rm IMOD
    Otherwise, rename the existing directory, e.g.:
      mv IMOD oldIMOD
  7.   ln -s imod_4.11.1 IMOD
  8. Except on Ubuntu before version 10 and other Debian systems,
      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/bash.bashrc and /etc/csh.cshrc just like those given above for inserting in users' .bash_profile and .cshr files, respectively. 

1.4. Installing IMOD on a Macintosh running OS 10 - 12

Rosetta2 for M1 Macs. To install IMOD 4.11 on an M1-based Mac, Rosetta2 must be installed. IMOD 4.11 currently runs only through this emulator, but a package compiled for M1 is available in IMOD 4.12 beta.

Python for OS 12. The default installation in OS 12.3 no longer includes Python. You must install a Python first to install IMOD. The recommended option is a package from python.org; here is a Python 3.9.11 universal installer package that runs on Intel and M1 processors. Installed, this package takes about 180 MB if documentation is omitted. Another option is to install Python through homebrew. The third option is to install the Apple Developer Command Line Tools, which the system will offer to install if you enter "python3" at the command line. This package takes 2.2 GB. The IMOD installer will recognize all of these Pythons regardless of whether they are on the search path, and if you install some other Python, it needs to be on the search path and you will probably need to use the command-line self-installing package instead of the clickable installer.

Installing IMOD The clickable installer (ending in ".pkg") will install to /Applications and will place appropriate source commands in /etc/profile, /etc/zprofile, and /etc/csh.login. You will need administrative privileges to use this installer.

After installing on OS 11 or 12, the Launchpad (multiple icon display) will show IMOD with two tempting icons inside, 3dmod and Qt Assistant. It will not work to click on 3dmod or Qt Assistant.

The package built under OS 10.14 is fully signed and the system should not object when you try to install it in OS 10.14, 10.15 or 11.0. If for some reason you need to install a package built on an earlier OS, there are two options. You can click on the question mark in the upper right of the message that you get when you try to run the package; it will direct you to open the Settings - Security and Privacy - Private tab where you can confirm the installation after dismissing the installer message. Or, you can use the command-line package described next.

The command-line self-installing package (ending in ".sh") will install to /Applications or to an alternate location with the -dir option.  The ".sh" file 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/profile, /etc/profile, and /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.11.1_osx10.11_CUDA8.0.sh

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

Fixing an IMOD Installation after a System Update. On OS 11 or 12, system updates may replace the files in /etc that source the IMOD environment-setting commands, and IMOD will stop working.  To recover from this without reinstalling IMOD, run the command
     sudo /Applications/IMOD/fixMacInstall
or if IMOD is installed elsewhere, run
     sudo pathToIMOD/fixMacInstall
where pathToIMOD is the full path to the IMOD directory. If this command fails with "Command not found", it is probably because there is no Python runnable as "python" on the path, in which case this should work:
     sudo /Applications/IMOD/pythonLink/python /Applications/IMOD/fixMacInstall

Setting Up Ability to Click on Files or Drag and Drop onto an Icon to Open them in 3dmod. Once you have verified that IMOD programs run from the terminal after installing them, you can associate files having desired extensions (e.g., .mrc or .rec) with a script that will open files in 3dmod. The steps are:

  1. Right click on a file with the desired extension
  2. Select Get Info
  3. Open the section "Open with" if it is closed
  4. Open the combo box and select Other
  5. Change Recommended Applications to All Applications
  6. Check Always Open With (maybe unneeded)
  7. Open /Applications/IMOD/bin in the chooser
  8. Scroll down to find openIn3dmod and select it (it has the same icon as 3dmod)
  9. Press Change All button in the Info window
  10. Press Continue that you are sure to change all similar documents
  11. Double click the initial file or another file with the same extension
  12. A dialog may come up the first time to confirm that you want to open the file with the script; do so and the file should open in 3dmod

You can also drag and drop a file onto openIn3dmod to open it. Open a Finder and find /Applications/IMOD/bin/openIn3dmod. Drag this to the dock if you want it there.

If you install IMOD in a location other than /Applications, you will need to be able to get to it in the file association chooser, or you will need to copy the openIn3dmod.app directory to another location that you can get to.

In general, you cannot run 3dmod by clicking on its icon ("3D") in /Applications/bin/IMOD. However, this is possible if you have installed an unsigned package built under an older OS (i.e., 10.11). In that case you can also make some links in /usr/local/lib to libraries in the IMOD directories that will allow you to start 3dmod by clicking on its icon. (This is not needed for the file association and drag-and-drop to work and does not work with a signed package.)  Run the linklibs-mac 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 run sudo $IMOD_DIR/linklibs-mac -u $IMOD_DIR before installing the new version then rerun with the -i option after installing.

Once the links are made, test that 3dmod will start by finding it in the IMOD/bin and clicking on it.

Installing Java.  To check whether you have Java installed, you can try to start Etomo by entering etomo, or just enter java -version in a terminal. If it is not installed, you will get a message from the operating system offering to take you to the Oracle site. Ignore this message and see 1.1 Installing Java for Etomo..

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.11.1_osx_intel64.tar.gz /Applications
  2.    cd /Applications
  3.    sudo tar xzf imod_4.11.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.11.1 IMOD

You also need to add some startup commands to the system files /etc/profile and /etc/csh.login , 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.profile to the end of both /etc/profile and /etc/zprofile, specifically the command
[ -r /Applications/IMOD/IMOD-mac.sh ] && source /Applications/IMOD/IMOD-mac.sh

Similarly, 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

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

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.  In the latter case, 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". In any case, you will need Java installed to run Etomo. ou See 1.1 Installing Java for Etomo both for instructions and for information on license restrictions with Oracle Java. To check whether you have Java installed, you can try to start Etomo by entering etomo, or just enter java -version in a terminal or Command Prompt window.

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 for the 32-bit version, or ~500 MB for the 64-bit version, 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 packages from January 2017 or December 2020 must be used on Windows 10. If you plan to upgrade or add to your installation, get the 64-bit one because only 64-bit is now supported.

 Date  Runs on
 December 2020    Windows 10    64-bit    Cygwin Installer     Cygwin Package     Matching Source  
 January 2017    Windows Vista -> 10    32-bit    Cygwin Installer     Cygwin Package     Matching Source  
 October 2014    Windows XP -> 8    32-bit    Cygwin Installer     Cygwin Package     Matching Source  

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 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, /bin/python.exe, recognizable to Windows (see below).

Our Cygwin packages also include a superior terminal window called mintty, a lightweight text editor, nano, and the vi editor. 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 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:

Sometimes there are permission problems that might prevent the installer from copying some files at the end of the installation, or that result in errors or prevent the creation of some files during tomogram setup in Etomo. If this happens, try editing the file /etc/fstab within Cygwin with one of the provided editors. This line determines how all drives should be mounted (including permissions):

      'none /cygdrive cygdrive binary,posix=0,user 0 0'
    

The line should be edited to:
      'none /cygdrive cygdrive binary,noacl,posix=0,user 0 0
    

This setting makes Cygwin ignore the windows Access Control List and prevents these permission errors.

In order to run Etomo, you also need to have Java installed.  Again, see 1.1 Installing Java for Etomo.

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, on the line labeled "All", click the drop-down arrow next to "Default" and select "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).

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 /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, first try entering
       fixCygPython.sh.
  2. If that does not work (the script was not in the IMOD/bin before IMOD 4.11.1), next enter
       /usr/local/IMOD/fixCygPython.sh.
  3. If this command does not work either (the script is only present there after installing with the executable installer), next enter
       ls /bin/python*
    to see if there is a python.exe
  4. If there is not, or if it is older than the numbered executable in the listing, then copy python2.7.exe (or whatever numbered executable shows up in the listing) with
       ln -f /bin/python2.7.exe /bin/python.exe

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 sh file like imod_4.11.1_win32.sh) at the command line, as described below.

To use the installer, just click on it.  If you get a message from Defender SmartScreen that "Windows protected your PC", press More info instead of Don't run, then press Run anyway.  If you then get a message from User Account Control asking if you want this app to make changes to your device, press Yes.  When the installer finally starts, 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 there will be multiple IMOD users of the system, they should add HOME environment variables to point to their directories in C:\Users, following the procedure described below in the paragraph To define an environment variable in Windows.
  3. 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 .sh), 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.:
    sh imod_4.11.1_win.sh

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 etomo.cmd, you also need to define some environment variables inside Windows:

  1. To define an environment variable in Windows: Right click Computer or My Computer or This PC on the Desktop, in a browser window or in the Start menu. Select Properties. In whatever window comes up, select Advanced or Advanced System Properties, then Environment Variables. If your privileges do not give you access to the dialog in this way, you can still access your user variables in two other ways: 1) Open the Control Panel and select User Accounts, then User Accounts again if you were viewing the control panel by category, then select Change My Environment Variables. 2) In a terminal window or Command Prompt window, enter
       rundll32 sysdm.cpl,EditEnvironmentVariables
  2. Define all of these paths in Windows format as illustrated in the following steps. Press "New" to define a variable.
  3. Under "System variables", define IMOD_DIR to be C:\cygwin\usr\local\IMOD
  4. Under "User variables for username", define HOME to be C:\cygwin\home\username
  5. 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.11.1.tar.gz
       mv imod_4.11.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. There is no need to upgrade if you already have a Python installed that works for IMOD; for the purposes of running IMOD, there is no benefit to having a newer Python. 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 the various versions.

For older Python, click on the downloaded Python file to install it; it installs without using "Run as Administrator". For Python 3.8, right click on the file and select "Run as Administrator".  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.3). Check the option to add Python to the PATH if one is present, and you might as well let it disable the path length limit if that is offered. If you customize the installation to leave out unneeded components (e.g., Documentation, tcl/tk, and the test suite), be sure to keep PIP if that is listed.

Next install psutil. For older version such as those for Python 2.7 and 3.3 in the links above, right click on the file and select "Run as Administrator". Newer versions, like the one for Python 3.8 above, come in a ".whl" file that installs with the Python package installer pip. Open a Command Prompt window as Administrator by right clicking on its icon and selecting "Run as Administrator".  (One way to run it is to open the Start menu and type "cmd"; Windows should offer Command Prompt as the best match and you can right-click on that.)  Then cd to the location of the psutil file (e.g., cd C:\Users\username\Downloads where "username" is your account name). Finally enter, for example,
    pip install psutil-5.7.3-cp38-cp38-win_amd64.whl
(You can type the Tab key after "psutil" and it will complete the name.)  You can ignore the warning that a newer version of pip is available unless you plan to install more packages.

After Python and psutil are installed, click on the IMOD installer.  If you get a message from Defender SmartScreen that "Windows protected your PC", press More info instead of Don't run, then press Run anyway.  If you then get a message from User Account Control asking if you want this app to make changes to your device, press Yes.  When the installer finally starts, press buttons to confirm each step; there are no options. It will install IMOD in C:\Program Files\IMOD, define the environment variables IMOD_DIR, IMOD_PLUGIN_DIR, and HOME, and place both IMOD and the version of Python that it finds on the path. For Windows Vista and higher, it will also define IMOD_CALIB_DIR to be C:\ProgramData\IMOD.

In order to run Etomo, you also need to have Java installed.  Again, see 1.1 Installing Java for Etomo.

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\AppData\Roaming (on Window 10) or C:\Users\yourUserName\Application Data (on Windows 7) 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 there will be multiple IMOD users of the system, they should add HOME environment variables to point to their directories in C:\Users. 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.12.12_win64_NoCUDA.sh. Copy the file installIMOD from C:\Program Files\IMOD to the same place that you put the package, which should NOT be C:\Program Files\IMOD. Open a Command Prompt window by right-clicking on a shortcut and selecting "Run as Administrator". In the terminal, cd to the folder with the files and enter (for this example file)

    python installIMOD -skip imod_4.12.12_win64_NoCUDA.sh

1.8 Using IMOD under "Bash on Ubuntu on Windows"

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:

1.9 Setting up Parallel Processing in IMOD

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. (See the Queuechunk man page for the definitive list of supported cluster types.) Multiple machines or a cluster need to be defined in a file cpu.adoc that is located in the directory pointed to by the environment variable IMOD_CALIB_DIR (default /usr/local/ImodCalib, or C:\ProgramData\IMOD on Windows without Cygwin). See the example cpu.adoc file in $IMOD_DIR/autodoc and 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:

  1. In Etomo, open the Settings dialog from the Options menu, check "Enable Parallel processing" and enter the number of processors.
  2. Make a file /usr/local/ImodCalib/cpu.adoc with these two lines:
        [Computer = localhost]
        number = 4
    where the number should be set to the number of processors.
  3. set the environment variable IMOD_PROCESSORS to the number of processors, e.g.,
        export IMOD_PROCESSORS=4 (for bash users)
        setenv IMOD_PROCESSORS 4 (for tcsh users)

We recommend using only the number of physical cores on the system when there is hyperthreading available. For the computational tasks in IMOD, using more than the number of physical cores is usually of little benefit at best, and using all of the hypercores will make jobs take longer overall. To determine the number of physical cores, you can enter
    imodqtassist -t

Parallel processing on multiple machines requires two things in addition to a 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:
    cp $HOME/.ssh/id_rsa.pub $HOME/.ssh/authorized_keys
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-linux.sh or $IMOD_DIR/IMOD-mac.sh in your ~/.bash_profile 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 that in ~/.bash_profile. However, we have found that in other contexts it does not work to set environment only in ~/.bash_profile. Thus, the recommended approach is to set the environment in ~/.bashrc and source that file from ~/.bash_profile.

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 cpu.adoc 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).

1.10. Using a GPU for Tomography

With most versions of the IMOD 4.11 packages, you can use the graphics processing unit (GPU) of an NVIDIA graphics card to compute tomograms, correct for microscope CTF, and align camera movie frames.  This works with any recent NVIDIA card, but you also need to have NVIDIA drivers new enough to support the version of CUDA that IMOD was built with.  To see if your card can be used, check it in NVIDIA's lists .  Some of the packages for IMOD 4.11 are built with CUDA version 8.  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.  Always use a package built with the highest version number supported by your drivers, because there may be a significantly longer startup time using a package built with a lower version (this is the case for CUDA 6). 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:
   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.  Some years ago, a few cards gave variable results, so it may be 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 a 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 IMOD/autodoc.

If you want to know how much speed improvement your system has, get tilttimers.tar.gz from our benchmark directory and follow the instructions in the README file there. More extensive benchmarks are available in the file gputests.tar.gz.

1.11. 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 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-...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.

1.12. Running a Test or Private Copy of IMOD

To unpack a copy of IMOD for test purposes and run it in parallel with an installed copy, follow these steps except on Windows without Cygwin:

  1. Download a self-installing package file (one ending in .sh), for example imod_4.12.10_win64_CUDA8.0.sh.
  2. cd to the directory where you want this copy of IMOD to be located and move the package file there.
  3. To place this copy in a directory named testIMOD, run
       sh imod_4.12.10_win64_CUDA8.0.sh -skip -dir . -name testIMOD
  4. If running the bash shell, run these commands in a terminal any time you want to run this copy instead of the installed one:
       unset IMOD_DIR
       unset IMOD_PLUGIN_DIR
       source testIMOD/IMOD-*.sh

If running the tcsh shell, use unsetenv and source the .csh file instead.

On Windows without Cygwin, follow these steps (which only work with an installIMOD from an installed version of 4.9.11 or 4.10.21, or higher):

  1. Download a self-installing package file, not the executable installer, i.e., one ending in .sh instead of .exe, for example imod_4.12.10_win64_CUDA8.0.sh.
  2. In a command prompt or other terminal window, cd to the directory where you want this copy of IMOD to be located and move the package file there, for example, C:\Users\myname\Documents.
  3. To place this copy in a directory named testIMOD, run
       python %IMOD_DIR%\installIMOD -skip -dir . -name testIMOD imod_4.12.10_win64_CUDA8.0.sh
  4. Run these commands in a terminal any time you want to run this copy instead of the installed one (substituting the actual directory in the first commmand):
       set IMOD_DIR=C:\Users\myname\Documents\testIMOD
       PATH=%IMOD_DIR%\bin;%PATH
       set IMOD_PLUGIN_DIR=%IMOD_DIR%\lib\imodplug

1.13 Support for High-DPI Monitors in IMOD

High-DPI (high-resolution) monitors are supported to varying extents in the three graphical programs in IMOD based on the Qt toolkit: 3dmod, midas, and ctfplotter. This support relies on the solutions provided by Qt, which are imperfect and vary between operating systems. They are only available in IMOD packages built with Qt 5: currently RHEL7 in Linux, packages for CUDA6.5 and CUDA 8.0 on Windows, and the osx10.11 package on Mac. On Windows and Mac, the support is dynamic: programs can detect when a window is moved between monitors with different DPI and adjust the font size and spacing in dialogs. On Linux, the scaling for DPI only works properly when set before program startup, so problems will be encountered when using monitors with different DPIs. These points may be helpful when using a high-DPI monitor:

1.14 Support for 16-bit Floating Point

Support for 16-bit floating point values in MRC files, such as those used in Relion and available in numpy, was added in IMOD 4.12.17. A new mode for these values, 12, is now part of the MRC standard, but other software may not support it yet. Numbers in this format have a precision of 10 bits, or 0.1%, down to values of 0.00006. From this value down to 6x10e-9 (the lowest non-zero value), there are 1023 values with a precision of 6x10e-9, i.e., they occur in steps of that size. The lowest and highest possible values are -65504 and 65504. This is adequate for many uses in EM.

All programs except one can read files in this mode. All of the programs that have an option to explicitly set the mode can produce output in this mode. Otherwise, the output mode will be 32-bit floats (mode 2) whenever the input is 16-bit floats. However, and environment variable, IMOD_WRITE_FLOATS_16BIT, can be set nonzero to make the default floating point output for all programs be 16-bit. This default will fully govern the behavior of programs without an option to set the output mode. For the programs with an option, the default is overridden by whatever mode is specified with the option.


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.  All but one can read and produce files in an HDF image file format compatible with EMAN2; HDF files from UCSF Chimera can also be read. Programs can also read and write TIFF image stacks and single-image JPEG files, and can read files in several specialized image formats compatible with MRC: DigitalMicrograph, PIF files from Bsoft, EM, Hanspeter Winkler's NFF, and FEI/TFS raw files. In addition to those formats, 3dmod can read some other common formats like PNG and BMP, and it has a dialog box and options for specifying how to read raw data.

As of IMOD 4.9, programs write MRC files in byte mode as signed by default (values of -128 to 127), which was 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 still 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. At least as of version 2.1.0/1.53g, 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 or HDF 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. 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 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 
You can also use newstack to stack TIFF and DigitalMicrograph files, provided that no special conversion options are needed.  newstack and another program clip, have options for specifying that the output should be in HDF format; other programs can be made to do so by setting an environment variable, IMOD_OUTPUT_FORMAT (see the page on environment variables).

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 very old machine with the opposite byte ordering, 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.

The IMOD model format can be either binary or ASCII. 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. Perhaps the only one currently useful is Virtual Reality Modeling Language: imod2vrml converts to VRML 1.0; and imod2vrml2 converts to VRML 2. VRML has been superceded by X3D.

See also: Manual pages for 3dmodv, imodmesh, and imodinfo.

 

5. Help on Specific Topics

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 two places:
     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.


Last updated: December 1, 2020 [IMOD Home Page]