Tomography Guide for IMOD Version 4.7

Boulder Laboratory for 3-D Electron Microscopy of Cells

Table of Contents


This section lists significant changes or additions to this guide from the 4.5 version.


This is a guide to building single and dual axis tomograms with IMOD using the eTomo interface. It contains sufficient detail to serve as a reference guide, which makes it less suitable when starting out. The recommended approach is to work through our tutorial with a sample data set before trying to use this guide to process your own data.

1.1. Program Names

In this document, program names are capitalized. However, their true names are all lower case, and they must be run by entering these names in lower case.

1.2. Command Files

eTomo works with a set of command files that contain all of the lines needed for running one or more programs. These files have the extension .com, and when a command file is run, program output is recorded in a log file with the extension .log. When you open the panel for a particular step, eTomo reads the existing contents of a command file to set the parameters and settings that appear in the panel. When you run an operation, it writes the current parameters into the command file. eTomo also makes sure that the command file matches your entries when you leave a panel by pressing Done or Postpone or simply by selecting another panel with a button on the left.

You can run a command file at the command line with "subm", which is either an alias or a script depending on your operating system. For example, if you enter "subm track", a file named will be executed in the background, a log file will be created called track.log, and a message will appear when the command file is completed. For more information on the format of command files and how to run them, see Command Files in the Advanced Topics section. If you want to make or edit command files, or if you want to run programs at the command line, see also the section on Entries to Programs.

1.3. Numbering System

Sections or views in the image files are consistently numbered from 1 within the graphical interface programs, eTomo, 3dmod, and Midas. However, many other programs in the IMOD package number coordinates from 0, which was the original convention for MRC files. If you work exclusively within eTomo, you need not be concerned about this; but if you run other programs in the package you need to be aware of this problem. When a program refers to "view numbers", these are always numbered from 1; but when a program refers to "section numbers" or "Z values", there is a good chance that they are numbered from 0. The most important example is the program Newstack, which is often used for rearranging or extracting sections from a stack. It has an option "-fromone" that allows you to enter section values numbered from 1 instead of 0.

1.4. Backup Files

Nearly every program that you run will create a backup file if an output file already exists, rather than simply deleting the old version of the output file. The existing file is renamed by adding a "~" at the end. This can lead to some large unneeded files if commands are run more than once. It is helpful to have an alias for purging backup files in your .cshrc if you are using tcsh or your .bashrc if you are using bash:
alias purge '\rm *~' OR alias purge="\rm *~"
With this alias, "purge" will delete all backup files without asking for confirmation.

1.5. File Format and Naming Conventions

All of the operations that you run through eTomo will produce new image files in the MRC format. The starting tilt series is not required to be an MRC file; programs can also read TIFF files and files in a few MRC-like formats, the most notable being DigitalMicrograph files and files in the PIF format used by Bsoft.

In order for the processing sequence to work, however, the names of your starting files must follow several conventions. The raw image stacks must have an extension of either ".st" or ".mrc"; so for a single axis tilt series the name should be or dataSetName.mrc. For a dual axis data set, the two filenames must end in "a" and "b" before the extension, e.g., and Etomo will rename files ending in ".mrc" to end in ".st" so that the rest of the processing can proceed with the expected names. These names are just conventions and do not correspond to a separate file format. In fact, if a file is not in the MRC format, it still needs to be renamed to have one of these two extensions to be processed in eTomo.

The data set name can contain ".", "-", and "_" as separators but must not contain spaces or other characters that could confuse a Unix shell or the IMOD processing tools. Specifically, the following characters are known to give problems:

   ` ' " ! # $ % & * ( ) { } [ ; < > / ? \ |
It appears that all of these characters can be used safely in filenames (although colon is not allowed in Windows):
~ @ ^ _ - = + ] , . :

If you are supplying your own file of raw tilt angles, they must be named with the data set name followed by ".rawtlt" (or "a.rawtlt" and "b.rawtlt" for a dual axis tilt series.)

1.6. Using Temporary or Insecure Storage

It is possible to have your small working files automatically saved to another directory every time that you run a command file. This will provide backup protection if you build tomograms in a disk area that is not regularly backed up. To use this feature, first be sure that the directory where you will do your work and the directory where files should be saved both exist. If you choose to copy your raw stacks to the working directory, which you might want to do if this gives significantly faster access, then you can proceed as described below. If you want to leave the raw stacks in the backed up location, then eTomo can create links to them for you, but this will work best if you start eTomo from the directory where you will build the tomogram.

After every command file is run, the script "savework" will be run automatically, copying files over to the source directory. You can also run "savework" yourself at any time (for example, after working on a fiducial model for a while).

1.7. Problems with Intensities in 3dmod

X-rays and other artifacts from the CCD camera can produce extreme intensity values in the raw tilt series. These effects can result in the images looking terrible when loaded into 3dmod in the default way, with the data stored internally as bytes. When the image features of interest occupy a very small fraction of the whole dynamic range of the data, there are only a few gray levels left to represent them out of the 256 levels. Successful removal of these artifacts will solve this problem (see PRE-PROCESSING: REMOVING X-RAYS). Before the artifacts are removed, one can use the "-I 1" option when starting 3dmod to make it load the data as integers. It will then provide four rather than two sliders for contrast control, so that the small part of the dynamic range occupied by true image features can be displayed with good intensity resolution (many gray levels).

The tilt series will automatically be loaded as integers when opened with the View Raw Image Stack button on the eTomo Tomogram Setup page, or with the View X-Ray Model button in the PreProcessing page. Thereafter, if you still have contrast problems, you can open 3dmod with the Startup dialog by right clicking on the viewing button, and then selecting Load non-byte data as 16-bit integers. You can make 3dmod load data as integers by default by selecting the menu entry Edit-Options, opening the Behavior tab, and turning on Load non-byte data into program as 16-bit integers. You should do this only if you are confident that you will not run out of computer memory when processing tilt series.

There is another procedure available if you do not want to reopen 3dmod with the integer loading option, or do not have enough memory to do so. Use the Auto button or adjust the Black and White sliders until the image features are visible in an appropriate contrast range. Then use the menu entry Edit-Image-Reload to open a dialog for rescaling the data. Press Apply and the data will be reloaded with the scaling indicated in the Lower limit and Upper limit text boxes, and the Black and White sliders will be set to values that allow the contrast to be decreased as well as increased. Now that you can see the images better, you can repeat this process if necessary - adjust the contrast again, then press Calc then Apply.

Finally, if you can not get good dynamic range even after removing X-rays, you should prevent the coarse aligned stack from being converted to bytes. Go to Advanced mode in the Newstack section of the Coarse Alignment panel in eTomo and uncheck Convert to bytes.


2.1. Image Scaling and Contrast Polarity

The default parameters for reconstruction assume that the numbers in your images are linearly related to the number of transmitted electrons caught by the detector. This is the case if images are recorded directly by CCD camera or if film is digitized in optical density units. The logarithm of such values should then be proportional to projected mass density for imaging dominated by amplitude (aperture) contrast. Because of this, the backprojection program, Tilt, has an option to take the logarithm of the numbers after adding a base value (originally designed to specify the fog level of film but also useful if the data are offset from zero). The default is to take logarithms with a zero base value. If your images are already mass-normalized, you should turn off the taking of logarithms in the Tomogram Generation Panel; if your images are in arbitrarily scaled units, you may need to turn off the logarithms or at least adjust the offset value that is added so that all values will be positive before taking the logarithm. You may also want to turn off the logarithms for predominantly phase contrast (cryoEM) data. When the logarithm is turned off, a separate set of factors is used to scale the backprojection data for output, so you do not need to change the scaling yourself.

If your data were derived from unsigned 16-bit integers and have had 32768 subtracted from them for storage as signed integers in the MRC file, the programs will try to detect this and set the base to 32768.

If electron density appears as white in your images, Beadtrack will fail to track your fiducials properly with the default settings. Simply check Light fiducial markers in Advanced mode in the Fiducial Model Generation Panel. Also, check Light in the Bead Fixer when making the seed model or fixing gaps.

2.2. Tilt Series Taken in Two Directions from a Starting Angle

A tilt series taken by tilting in two directions from zero tilt or another angle often shows a discontinuity in the aligned stack at the transition between the two halves of the series. Usually this reflects either an irregular tilt increment due to backlash in the goniometer, or changes in the specimen during the first half of the series. Because of these effects, you should always identify such tilt series as bidirectional in the Setup Tomogram panel. Doing so will identify the first half of the series as a separate group in the Separate view groups fields on the Fiducial Model Generation and Fine Alignment panels. These entries will prevent the programs from assigning the same or similar values for alignment variables to views that are not in the same half of the tilt series. For example, if the discontinuity occurs between views 71 and 72, the Separate view groups fields will be filled with "1-71".

For plastic section tilt series, sometimes the shrinkage in the first half of the series makes it hard to track gold beads across the discontinuity. An option is available in the Fine Alignment panel to find a magnification (size) change at one or more views. When you identify the series as bidirectional during the setup, this option will appear in Basic mode, with the correct view number filled in, but it will not be turned on.

In some cases there appears to be a change in the X-axis tilt of the specimen between the two directions of tilting. It is possible to correct for this effect by solving for a single change in X-axis tilt in Tiltalign; see Correcting for X-axis Tilt in Bidirectional Tilt Series in the Extra Topics section.

2.3. Unknown Tilt Axis Rotation Angle

A starting estimate for the angle of the tilt axis in the images is required for processing, and if this information is not contained in the header of your tilt series, you will have to supply an estimate yourself. For the initial coarse alignment with cross-correlation, this angle needs to be accurate to within about 5-10 degrees, depending on the highest tilt angle. The fine alignment with fiducials will solve for the actual angle and can work with more inaccurate estimates; it will also warn you if your starting angle is significantly off. For a given microscope, this angle is essentially fixed for each magnification and will usually be nearly constant over some ranges of magnifications. Thus, if you can a good fine alignment on one data set, you will have a very good value to use for comparable future data sets.

If you have no information about the nominal tilt axis angle in your tilt series, open the raw stack in 3dmod and step or riffle through some of the views until you can get an impression of structures rotating around an axis. You may have to go up to a tilt angle of ~20-30 degrees to see the axis of tilting clearly. The axis may be more apparent in the coarse aligned stack, so you may have to start the data set with a very rough estimate and refine that estimate with the coarse aligned stack. The rotation angle is the angle from the vertical to the axis of tilting, where counterclockwise is positive.

The problem with the approach just described is that it cannot resolve the ambiguity between the true angle and an angle 180 degrees away; and the latter angle will invert the handedness of the reconstruction. This is a difficult issue; see Reorienting the Volume for some ways to approach it. Properly configured tilt series acquisition software (e.g., SerialEM, FEI software) should provide a true angle that will give appropriate handedness.

2.4. Image Reduction with Antialiasing

When making both the initial coarsely aligned stack and the final aligned stack, you can reduce the size of the data by an integral factor. In both cases, there is an option the apply an antialiasing filter during image reduction. Aliasing occurs when information in the original image at spatial frequencies past the Nyquist frequency of the reduced image (i.e., the highest frequency that can be represented in that image) is mapped into lower frequencies. That mapping essentially produces noise in the reduced image. Simple binning does alias some information. An antialiasing filter removes the high frequencies before subsampling the image. Using this filter will increase signal-to-noise significantly ratio in the reduced image for an electron counting camera (e.g., the Gatan K2 camera in electron counting mode) because of the very high response of these cameras at high frequencies. Antialiasing may also be helpful for other direct electron detection cameras that have good high-frequency performance, but is unlikely to make a difference for data from fiber-optically coupled CCD cameras.


To work on a new data set, start eTomo and fill in the entries in the Setup Panel that appears. You need not start eTomo from the directory where the files are located.

Once you have made all of these entries, push the button to Create Com Scripts. eTomo will run the Copytomocoms script to produce command files for processing the data. For a data set consisting of single frames, the files are as follows:

Each ".com" file generates a corresponding ".log" file when it is run. In eTomo, you can examine a log file by clicking the right mouse button over free space within a panel; the menu that pops up will show the relevant log files for that panel.

If you have a two-axis tilt series, you will get one copy for each series, with names "" and "". For convenience, most command files will be referred to below by a name without an "a" or "b" (e.g.,, but in practice you will always be running an "a" or "b" version when you have a dual tilt series.

The man pages for the programs run by these command files give full details on their operation and on the meaning of the entries to each. Consult them for any questions on the options available in these programs.

If you find that you need to run Copytomocoms by hand, see Getting Command Files in the Advanced Topics section for more details.

3.1. Command Files when Montaging

For a montaged data set, some command files and programs are different, as follows:


As mentioned above, X-rays and other flaws in CCD camera images can produce extreme low or high values that ruin the contrast when you view the images in 3dmod, and they can also give undesirable artifacts in the reconstruction. These defects can be wiped out with Ccderaser, which finds X-rays in two ways. It looks for "peaks", or pixels whose intensity deviate from the surrounding pixels by a certain number of standard deviations, which is specified in the Peak criterion text box. It also looks for pixel-to-pixel differences that exceed background by a certain number of SDs, specified in the Difference criterion text box. The ones found by these two criteria have to be smaller than the size set in the Maximum radius text box. However, particularly strong artifacts larger than this size will also be removed if they satisfy other criteria, the principal one being a criterion for pixel-to-pixel differences shown in Extra-large difference criterion

When Ccderaser runs, it produces an IMOD model marking the pixels that were found. Press the View X-ray Model button to see this model. Points are sorted into different objects based on how much they exceeded a criterion (less than 1 SD for object 1, 1-2 SDs for object 2, etc.). You will probably be surprised at how many points are marked, possibly on the order of 100 points per image for a 2K by 2K camera. In our experience, the default criteria are conservative for unbinned images and all of these points are indeed X-rays. However, in binned images, the difference criterion may pick up some pixels on the edge of gold particles used as fiducials. If you see this happen, you can prevent it by raising the difference criterion to 10 or more.

If you want see the effects of changing criteria, you can save time by running in trial mode, using the Find X-rays button. The program will analyze images and produce a model without writing an output image stack.

When you press the Create Fixed Stack button, Ccderaser writes the corrected images into a file named "". If you are satisfied with the result, press the Use Fixed Stack button to rename the original file to "" and replace it with the fixed stack.

If you find that some X-rays or other artifacts are too large to be removed with the default parameters, there are two avenues to pursue. If the artifacts are particularly strong, you can try reducing the Extra-large difference criterion, but make sure that this does not cause gold particles to be erased. Otherwise, increase the Maximum radius to encompass these large X-rays and try again. If the larger radius causes inappropriate points to be corrected, then do the removal in two stages. First create a fixed stack with the smaller radius, and press Use Fixed Stack. Then increase both the radius and the criterion so that only the large X-rays are removed, and rerun the removal. Press Use Fixed Stack again if you are satisfied with the result.

You can see the minimum and maximum values and their locations for each view by pressing Show Min/Max for Raw Stack or Show Min/Max for Fixed Stack. You will see the statistics output from the clip program both in a graph showing minimum and maximum values, and in a log window. In the latter, views with locally extreme values of the minimum or maximum will be marked by stars and listed at the bottom. This marking of outliers is of limited value with the raw stack because all views generally have X-rays that increase the maximum; but with the fixed stack this listing will often reveal the subset of views that still have sizable uncorrected X-rays. If you have trouble finding a position, you can type the X and Y coordinates into the spin boxes in the 3dmod Info Window then toggle the centering button in the Zap window toolbar on then off to center on the position that you typed in.

If your images have other features that do not get corrected by the automatic X-ray removal, you can specify the pixels to erase in a model file. Press the A button next to Manual Pixel Region Replacement to reveal the controls for this option, and see the man page for Ccderaser for details on how to construct the model file. By default, model objects are assumed to have contours consisting of a single point on each pixel to be erased. If you want to erase pixels along lines, list objects with such line contours in the Line replacement list text box. If you want to draw contours as boundaries around large patches to be replaced, list objects with such contours in the Boundary replacement list text box.

With a montaged data set, when you view the X-ray model or the fixed stack, the images will be loaded into 3dmod with no overlap and spaced apart by a few pixels, so that all parts of every frame can be viewed. The statistics outputs will list the minimum and maximum for each piece in the stack, but their locations will be translated into coordinates on the relevant view so that you can find them in the display. A manual replacement model is also drawn on a montaged display with no overlap; Ccderaser will translate the coordinates from this display into coordinates in the appropriate frame in the file. A feature to be replaced on all sections needs to be modeled on only one piece in the montage (any piece).


The main purpose of this step is to get the images aligned well enough for the automatic tracking of fiducials to work. For the purposes of this basic alignment, there are only a few options to be aware of. First, if you identified the tilt series as bidirectional during tomogram setup, the option to find a magnification change at the discontinuity in the series will appear in Basic mode, and you can turn this on to adjust for shrinkage in the first half of the series. Second, it is possible for the alignment to fail if there is inadequate gain normalization of the images, because a fixed pattern present in the images may make them correlate best at zero shift. To handle this, switch to Advanced mode in the Tiltxcorr section and turn on Exclude central peak due to fixed pattern noise. (This option used to be problematic but was enhanced to be useful in IMOD 4.7.) Other than this, there are generally no parameters to adjust, so you proceed by pushing the top three buttons in sequence.

Press Fix Alignment with Midas only if you need to adjust some of the alignments. This will start Midas on the raw image stack, with the alignment transformations determined on the first step. Go to the pairs of views that showed problems, and use the left mouse button to translate each pair of images into alignment. When you toggle between a pair of images, you should see the section appear to tilt around an axis in the middle. The tilt axis should appear to be vertical because Midas applies a global rotation to the images, starting with the value in the Tilt axis rotation text box on the Coarse Alignment panel. If you have a big magnification change, you could also correct for this using the right mouse button while holding the Shift key down. (Alternatively, you can rerun the correlations after turning on the option to find a magnification change at this view, switch to Advanced mode if necessary to see this option.)

After fixing and saving transformations, you must generate a new coarse aligned stack.

The coarse aligned stack will be used for tracking the fiducial model, and there might be cases where you want to work with binned images for this procedure. You can set a binning for this stack by pressing the Advanced button then adjusting the entry for Coarse aligned image stack binning before generating the stack. also note the option to Reduce size with antialiasing filter; see Image Reduction with Antialiasing for an explanation of when this is helpful. If you change your mind about binning after starting to work on a fiducial model, you can go back to this panel, change the binning, and generate a new prealigned stack. The existing model will load correctly onto the stack with the new binning; just be sure to save the model after doing this and eventually run the fine alignment, which will synchronize all information about the pixel size.

5.1 Making a Quick Tomogram with Correlation Alignment

It is possible to generate a tomogram using only the coarse alignment from cross-correlation. This could be used to get a tomogram quickly to see whether it is worth doing the fiducial alignment, or if the tilt series was just for scanning purposes, or if there are no fiducials. This section describes a simple procedure for getting a tomogram quickly; for more detail on how to get as good a tomogram as possible from this procedure, see Making a Tomogram with Correlation Alignment in the Extra Topics section.

  1. Press Calculate cross-correlation.
  2. Check Fiducialless alignment
  3. Press Done. There is no need to make a coarse aligned stack in this panel because its tilt axis is not vertical.
  4. Press Done on the Tomogram Positioning panel to get to the Final Aligned Stack panel.
  5. Adjust the Tilt axis rotation if it does not match the values that you usually get for rotation angle in a fiducial alignment solution at this magnification.
  6. Select an appropriate binning, then press Generate Full Aligned Stack. The speed of tomogram computation is roughly proportional to the cube of the binning.
  7. Press View Full Aligned Stack and check the alignment. If something needs to be fixed, press Coarse Alignment, then Fix Alignment with Midas. After fixing the alignment, come back to the Final Aligned Stack panel and rebuild the aligned stack.
  8. Press Done on the Final Aligned Stack panel to get to the Tomogram Generation panel.
  9. Set an appropriate Tomogram thickness in Z. Thickness is specified in unbinned pixels so that its value is independent of the selected binning.
  10. Press Generate Tomogram.

If you need to set the position of a tomogram built with fiducialless alignment, see the Advanced Topics section. It is recommended that you NOT do this if you plan to go back and do the fiducial alignment procedure.

5.2. Fixing Montage Edges

For a montaged data set, the Coarse Alignment panel also provides controls for fixing errors in the displacements between frames. Blendmont analyzes the overlap regions between adjacent pieces and determines how to shift the pieces into registration. Sometimes this analysis fails and a few of the shifts are wrong. It is important to fix these errors before going on to build the fiducial model, because when the displacements are changed, image positions in the blended image change as well. There are two ways to tell if there are shifts that need fixing.

  1. For a montage with more than one piece in each direction, Blendmont computes a remaining displacement (error) between each pair of adjacent pieces after shifting all the pieces into registration, and reports a mean and maximum error for each view. After calculating initial cross-correlations, eTomo pops up a graph of these errors. The errors should be small and smoothly varying with tilt angle. If magnification gradients are not large or have been corrected for, the error is usually less than 0.5 pixels. Otherwise, the error may increase gradually from a fraction of a pixel at low tilt to several pixels at high tilt. If you see errors that are abnormally high relative to the nearby views, open the xcorr.log file to determine the view number. The beginning part of this file shows the output from Blendmont. For each section in the file, you will see a line giving the "mean, max error before ... after ...". The last two numbers on each line are the ones in the graph. Note which sections need to be fixed and add 1, since sections are numbered from 0 in this output but from 1 in Midas.
  2. You can also see edge displacement errors by building a coarse aligned stack and looking at it carefully while riffling through the views. If there is an error, you should see one frame of a picture shift out of alignment with the corresponding frame in the adjacent views. This is the only way to detect errors when your montage consists of a single row or a single column.

To fix displacements, press Fix Edges With Midas. If you are correcting for magnification gradients or image distortion fields, you will first have to press Make Distortion Corrected Stack. This step is necessary because you need to visualize overlaps in the same images that Blendmont is analyzing, namely distortion-corrected images.

When Midas starts, enter the view number of a section with a large error in the Current Section text box. The control panel has push-buttons for the four edges with the worst errors; use these to select the edge with the worst error. Toggle between the two pieces to visualize the registration in the overlap zone. If it looks bad, shift the Current piece into alignment (the Apply Leave-out Error button can be a useful shortcut if this is the only piece with an error -- see the Midas man page for explanation.) If the overlap looks fine, simply go on to another edge; you will probably find the error there. This potentially confusing situation may be quite frequent, because whenever a bad edge involves a corner piece of the montage, its error is spread equally between the two edges of that piece. It will thus look like there are two equally bad edges when only one is bad.

After you correct the displacement at an edge, the push-buttons will rearrange and show new maximum errors. Once the maximum error is down to 0.3, you can go on to another section. When you are done, save the edge correlation displacement file and exit. Your corrected displacements will automatically be used when Blendmont is run again, and Blendmont will build new edge functions on its next run, because the edge functions depend partly on the displacements that you just modified.


There are several ways to get a model that can be used to align the tilt series. The first involves starting with a collection of gold beads on the zero-degree view, referred to as a seed model, and using Beadtrack to find their locations in the rest of the tilt series. The seed points can be marked manually or selected automatically. The second method involves tracking small patches of the image through the series by cross-correlating each patch from one view to the next with Tiltxcorr. The third method involves using RAPTOR to find beads automatically.

6.1. Generating a Seed Model Automatically

A seed model can be generated automatically by Autofidseed, which aims to select a well-distributed set of fiducials of a desired number. If this procedure does not succeed in giving a good seed model, for small data sets you would probably just proceed to make or finish the seed model manually. When larger numbers of fiducials are needed, however, it is worth trying to get Autofidseed to make a usable seed model by accessing the various problem-solving features provided in the interface. Here is what you need to know about automatic seed-finding to use it effectively in more difficult cases:

The basic use of Autofidseed involves a small number of parameter choices:

Press Generate Seed Model to run the operation. If you have the project log open, you will see the two most informative lines from the Autofidseed log file, a line showing the number of beads available and how many were considered clustered or elongated, and a line showing the total number of beads chosen and their distribution on two surfaces, if any.

Press View Seed Model to see the result. If you chose to have beads found on two surfaces, the ones on the bottom will appear as green, and the ones on the top as magenta, although they are all in one model object.

6.2. Solving Problems with Automatic Seed Generation

You need to switch to Advanced mode to see the controls for problem-solving, but two buttons present in Basic mode can help you assess the problems first. Open Initial Bead Model will show you whether Imodfindbeads succeeded in finding gold beads and distinguishing them from other features. If not, you need to adjust some parameters for running that first step. If you chose to find beads on two surfaces, Open Sorted 3D Models is available for opening the models of 3D positions derived from all of the Beadtrack runs in 3dmodv. This display will reveal whether the sorting into two surfaces failed for one or more runs, or whether there are too few beads on one surface. Use the 9 and 0 hot keys to step between the models.

A variety of problems can be addressed by the Advanced controls: