There is also a reference guide that gives a description of each IMOD program and a link to its man page.
All of the IMOD programs are available via the
IMOD Download Page. The distribution is bundled together using
the tar program with gzip compression, then placed in a file after a 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.5.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. There is an executable installer for Windows with extension .exe
that you can click on. 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.5.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.5.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.5.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.
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, but here are some instructions that may be helpful. 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. On Ubuntu, the automatic installation through Synaptic Package Manager should be adequate.
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 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
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.5.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.4.5_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
Manual Install. To install manually from the tar file, do the
following steps after running the self-installing file with the -extract
option:
mv imod_4.5.1_RHEL6.tar.gz /usr/local
cd /usr/local
tar -xzf imod_4.5.1_RHEL6.tar.gz
ls -l
IMOD
-> imod_2.7.6
), then enter
rm IMOD
mv IMOD oldIMOD
ln -s imod_4.5.1 IMOD
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.
Etomo is a Java 2 application and thus requires a Java runtime environment (JRE) with a version of 1.5 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
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).
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.5.1_osx_intel64.csh
/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./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. Java is not installed by default in OS X
10.7. 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:
sudo mv imod_4.5.1_osx_intel64.tar.gz /Applications
cd /Applications
sudo tar xzf imod_4.5.1_osx_intel64.tar.gz
ls -l
IMOD
-> imod_3.1.6
), then enter
sudo rm IMOD
sudo mv IMOD oldIMOD
sudo mv imod_4.5.1 IMOD
If you are on a single user-machine or have administrative privileges from the desktop, you can use the following alternative approach:
imod_4.5.1
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.csh
and
IMOD-mac.sh
and 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.
For complete IMOD functionality under Windows, including the ability to run shell scripts and to build tomograms, you need to install a Unix-like environment called 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:
cygwin
as the directory name.
mintty
window running either a bash
or a tcsh
shell.
.minttyrc
there that
will give good starting properties for a mintty
window.
.minttyrc
will also be left in
/usr/local for other users to copy.In order to run eTomo, you also need to have Java installed. If you do not already have Java (most machines do now), get the latest Java Run-time Environment from Sun/Oracle or use the version provided here. 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:
setup.exe
program and a cygwinMaster
folder with all the packages.
setup.exe
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.cygwinMaster
folder as the Local Package Directory
After installation you will get an icon that will start up a shell under
bash. The first time that you run this, a home directory is created
in /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:
Cygwin-bash.lnk
or Cygwin-tcsh.lnk
from
cygwinMaster
to your desktop, depending on your preferred shell.
minttyrc
from cygwinMaster
to your Cygwin home directory.
minttyrc
to .minttyrc
with
the command mv minttyrc .minttyrc
(you cannot do this in Windows Explorer).
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..
Cygwin-bash
or Cygwin-tcsh
shortcut to Cygwin.
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:
ls /bin/python*
python.exe
python2.6.exe
(or whatever numbered
executable shows up in the listing) withcp /bin/python2.6.exe /bin/python.exe
For Windows, we provide an executable installer that works by clicking on it,
installs IMOD in /usr/local
, copies the startup scripts 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.5.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:
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.
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.5.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:
IMOD_DIR
to be C:\cygwin\usr\local\IMOD
HOME
to be C:\cygwin\home\username
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:
/usr/local
either from
the command line or from an Explorer window, where the location will appear as
C:\cygwin\usr\local
.
/usr/local
and, if you have an existing IMOD
installed, rename it. cd /usr/local
mv IMOD oldIMOD
tar -xzf imod_4.5.1.tar.gz
mv imod_4.5.1 IMOD
cp IMOD/IMOD-cygwin.* /etc/profile.d
Finally, if you do not want to install Cygwin, you can still use most of the
programs in IMOD (but not eTomo). In this case, get the .tar.gz
distribution instead of the self-installing distribution and use
Winzip to unpack it somewhere, (e.g., C:\Program Files
),
rename the top directory to IMOD, and add the IMOD\bin
directory
(e.g., C:\Program Files\IMOD\bin
) to your path in Windows, as
described above.
With this version of IMOD, 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.5 are built with CUDA version 3. A few packages are built with CUDA 2 or with CUDA 4. When there are two packages for a particular operating system, the one not built with CUDA 3 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 and after upgrading the NVIDIA drivers or the operating system.
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
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.
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.
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. Beyond this, your initial problem may be getting data into a
format usable by the IMOD programs. If you are having problems getting
your data into a format usable by IMOD contact us for help.
All of the IMOD programs use the MRC image file format.
We have utility programs available for converting TIFF files and raw data into
the MRC file format. In addition, 3dmod
can read some common
formats like JPEG, TIFF, PNG, and BMP; it recognizes several specialized image
formats (DigitalMicrograph, EM, Hanspeter Winkler's NFF, PIF files from Bsoft);
and it has a dialog box and options for specifying how to read raw data.
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
digital micrograph 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 already 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
The program raw2mrc is used to convert raw
image data into the mrc format. This program can take a file of 8, 16,or 32 bit
integers, IEEE float values, or 24-bit RGB triplets and convert them into an
MRC image file. In MRC files, the data start in the lower left hand corner of
the image, with the data stored in rows. To use raw2mrc
, you need
to know the size of the images, the type of data, and the size of any header
information preceding the image. For example, if you have a set of files
(cell01.em, cell02.em, ...) with 1024 x 1024 images of signed 16-bit integers,
and a header of 512 bytes, use:
raw2mrc -t short -x 1024 -y 1024 -o 512 cell*.em cell.mrc
If the data need to have their bytes swapped because they come from a machine with the opposite byte ordering (e.g. PPC Mac versus Intel), use the -s option. If you do not know something about the image, such as the header size or whether the data are unsigned or need swapping, you may be able to figure it out just by trying different options for data types and swapping. If you do not know the header size, convert one file without the -o option, load it into 3dmod, and try to see where the image data start. If the final MRC image is upside down use the -f option in the initial conversion or use the program clip to flip the image back.
When a 3dmod is started with an image file that
it does not recognize, it brings up a dialog that allows you to specify the
image and header size and the data type. Alternatively, you can specify
these features with options at the command line, which could be the most
convenient way to experiment and find the right values. For example, the
files in the previous command could be displayed with:
3dmod -r 1024,1024,1 -H 512 -t 1 cell*.em
If you already have a 3-D model and wish to view it within the IMOD model
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.
There are several tools available in IMOD for aligning serial section images. The procedures are most commonly used for aligning serial, EM thin sections for 3D reconstruction. For more background and explanation of the topics in this section, see the guide to serial section alignment.
Sometimes images in a data set are not in register with one another. When this happens, a series of transforms will need to be found that will align the whole stack of images. This series of transformations is obtained in two stages. First, each successive pair of images is considered separately, and a transform is found that aligns the images when applied to the second image in the pair. This procedure yields a list of transforms that align each image to the previous image; the programs consistently refer to this as a list of "f" transforms. If you think about it, you will realize that simply applying these f transforms to all of the images in the stack will not help, because each section would be aligned to the previous one only if that previous one were not itself transformed. A second stage is thus necessary: one must obtain the transforms for each image that will produce an aligned stack when actually applied to the images. This list is consistently referred to as a list of "g" transforms. In summary, "f" transforms align each section to the preceding one; "g" transforms align each section to the whole stack. Finally, the program newstack will apply the "g" transforms to the images to create an aligned stack. Note that newstack and some of the other programs will not work with 24-bit color images. Use the "-g" option to tif2mrc to convert to gray scale when making the MRC stack. If you do need to preserve the color information, then you can split the color into three separate byte-mode files with the clip program, determine the alignment with one color channel, apply the trasnformations to each of the 3 files separately, then merge the data again with clip.
The procedures described here are appropriate for aligning images of successive
slices through a structure, but not for aligning tilt series images for
tomography. The latter operation is done with the eTomo
program.
Conversely, the tilt series alignment procedures in eTomo cannot be
used to align serial thin section images.
There are three general methods for obtaining alignment transforms: automated search for the best fit between two images, manual adjustment of transformation parameters, and solving for a transform from a set of fiducial points that correspond between two sections.
Several programs are used for automated image alignment. The programs
used are
xfalign,
xftoxg,
midas and
newstack.
Xfalign
is a Python script that generates a "f" transform list using the
xfsimplex
program. It can prefilter images in several different ways.
It also has an option to get an initial alignment of the images by
cross-correlation, in case images are not already roughly aligned.
Steps and programs used in automatic image alignment:
xfalign cell.mrc cell.xf
xftoxg
to create a global "g" transform list from the "f" transform list:
xftoxg cell.xf
newstack -xform cell.xg cell.mrc newcell.mrc
If the automatic alignment is not always correct, it can be adjusted
with the
midas
program. Start the program with:
midas cell.mrc cell.xf
A window will open up and you can view the alignment between any given pair of
adjacent images. After making adjustments for any sections that are out of
alignment, save the transforms and exit the program. Then rerun the xftoxg
and newstack
commands shown above.
The program midas is used for manual alignment
or manual adjustments to automated alignment of images. Midas
can
be used to create a transform list or to edit an existing list; it can work
with either "f" or "g" transform lists. To get a "g" transform list from an "f"
transform list use the xftoxg program. xftoxg
has options to leave long term trends in the data, which are invoked by default
when you run the program with command-line arguments.
Steps and programs used for manual image alignment
midas
: Assess and adjust the alignment between pairs of images.
There are interactive controls for adjusting translation, rotation,
magnification and stretch along an axis. Save as a "f" transform file.
xftoxg
: Creates a "g" transform list, leaving in long term trends in the data.
newstack
: Applies the transforms creating an aligned image stack.The program xfmodel will create a list of xf transforms from a model containing fiducial points. See the Introduction to 3dmod to see how to make models.
Steps and programs used in fiducial marker alignment.
3dmod
: Creates a model in which points in each contour are placed on adjacent
sections that mark the same area on both sections. Note that a single contour
corresponds to a single fiducial marker, and the contour contains a point on
each of the sections where the marker appears. These are contours that pass
between sections rather than being confined to a single section.
xfmodel
: Creates a "f" transform list.
xftoxg
: Creates a "g" transform list, leaving in long term trends in the data.
newstack
: Creates an aligned image stack.
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.
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.