protomo user’s guide
version 2.2

Hanspeter Winkler

Table of Contents


1 Introduction

protomo is a software package used in electron tomography for marker-free alignment and 3D reconstruction of tilt series. The marker-free alignment is based on cross-correlation methods and projection matching. It also includes the refinement of geometric parameters of the tilt series. 3D reconstruction is carried out by weighted backprojection with general weighting functions that allow varying tilt angle increments [1]. The software was originally developed for thin sections of insect flight muscle and paracrystalline protein arrays [2], but has since been successfully applied to various specimens in cryo-electron tomography.

2 Installation

2.1 Requirements

Recent versions of the following software packages should be installed:
  • TIFF library ( (mandatory)
  • Fourier transform libraries, optional but recommended. If they are not installed, the fall-back are the built-in FFTPACK routines (
    • FFTW2 (; only version 2 is supported, compiled for single precision with type prefix (configure options: –enable-shared –enable-float –enable-type-prefix)
    • djbfft (
  • GTK+, the GIMP toolkit (
  • GtkGLExt, OpenGL Extension to GTK+ (
  • GNU plotutils (
  • A postscript viewer
    • GNU “gv” (
    • ImageMagick’s “display” (
  • EMAN2 (
Note: If some of the above packages or libraries are not present at runtime, the corresponding functionality will be disabled in the Python tomography extension module. Tilt series alignment will not be affected.

2.2 Linux installation

Currently, protomo is available for Linux on 32-bit and 64-bit architectures (Intel i686, AMD64) only. The software can be installed anywhere in the file system, including a user’s home directory. The programs do not need superuser privileges to run, however “root” may be required to install the software in directories that are typically writable for root only, such as /usr/local. The software is unpacked by typing the following commands at the shell prompt:
cd /usr/local
tar -xjf /path/to/protomo-2.2.x.tar.bz2
where /path/to/ is the absolute path where the tar file was stored, and x is the release number. This will create a new subdirectory protomo-2.2.x in /usr/local. The bash shell script must be adapted to the installation. The environment variable I3ROOT must point to the installation directory, in our case /usr/local/protomo-2.2.x, and the variable I3DEPLIB must point to the location of the third-party libraries, that are distributed separately. If these libraries are already provided by the system, it is recommended to make a symbolic link to the actual library in the I3DEPLIB directory. Similarly, the EMAN2DIR variable must point to the EMAN2 installation. Other variables should not be changed. The setup script must be “sourced” before the first protomo session or program invocation in the current shell, or alternatively, the source command can be executed at login by putting it in the shell startup files .profile or .bash_profile. To make sure that the correct versions of executables and libraries are loaded, the environment variables PATH and LD_LIBRARY_PATH should be examined. Library dependencies can be printed with the Linux system utility “ldd”.

3 Concepts and conventions

3.1 Tilt Geometry

3.1.1 Coordinate systems

We define a Cartesian coordinate system S = { Os, s1,  s2,  s3 } which is fixed with respect to the specimen, a coordinate system M = { Om,  m1,  m2,  m3} which is the microscope coordinate system, and finally, for each projection image a coordinate system P i = { O  ip,  p i1,  p i2 }, where i = 1…n, and n is the number of images in the tilt series. P i is defined by the pixel raster, and the origin O  ip is usually located at the bottom left of the image. We assume that the two origins Om and Os are identical, and the two planes spanned by the vector pairs m1,  m2 and p i1,  p i2 (the projection plane) are parallel. m3 is the projection direction. The projection of Os onto the image plane is denoted as O i. Os is implicitly defined by choosing one of the projection images as a reference image, usually the projection of the untilted specimen.

Figure 1 Tilt geometry
The tilt azimuth angle ψ measured anti-clockwise from the m1 axis, indicates the direction of the tilt axis t, and the angles ϑi are the specimen tilt angles corresponding to the ith image. The in-plane rotation angles αi align the projected tilt axes ti in each of the images to a common axis. The green plane corresponds to the grid supporting the specimen, which in its untilted state coincides with the pink plane. The rotation R0 from the green plane to the yellow plane is the specimen orientation relative to the grid (see figure 1↑).

3.1.2 Geometric transformations

All geometric transformations are specified as transformations of coordinate axes. For example, the total specimen tilt is

R i = R0R it

where R it is the rotation matrix of a rotation about the tilt axis t with the angle ϑi, for the ith projection. The matrix R i is the transformation of the coordinate system M to S:

sj = 3⎲⎳k = 1rjijkmk ; j = 1…3
In the software, the matrix elements riiijk are specified in the order of increasing indices on the command line or in parameter files. Note, that the transformations also require an origin which can be defined anywhere in an image. By default it is the center of the image.

3.2 Input/output

3.2.1 Image file formats

protomo supports the following file formats: CCP4, EM, FFF, IMAGIC, MRC, SPIDER, SUPRIM, and TIFF. It can read these formats transparently, and the automatic format detection is based on the file contents rather than file name suffixes. Map files are written as CCP4 files and diagnostic output files are written in the native FFF format [3]. While the default output file format can be changed to any of the supported formats, it is not recommended to do so, because not all of the image formats can store the necessary metadata required by the software. In particular, a coordinate system must be associated with each image. In the FFF format, the coordinates of the lower left corner are stored for this purpose, and cropping images with protomo utilities preserves this information.

3.2.2 Tilt series metadata

The geometry information (see below, section “Geometry files”) and alignment information is stored in a binary database for each tilt series. These geometry metadata files have a file name suffix of “.i3t” and are generated by importing a text file. For diagnostic purposes the data can be reexported in text form.

3.3 Fourier transforms

Several Fourier transform algorithms are available:
  • FFTPACK (, Fortran subroutines for complex and real sequences, developed by Paul Swarztrauber.
  • GSL FFT, (, part of the GNU scientific library. This is a reimplementation of FFTPACK. In protomo, it performs slightly worse than FFTPACK and is therefore not recommended.
  • FFTW (, the “Fastest Fourier Transform in the West”.
  • djbfft (, an extremely fast FFT implementation that provides powers of 2 complex and real FFTs. In protomo, it beats FFTW in speed.
Fourier transform modules are loaded during program startup and a fall-back sequence can be defined to select the optimal algorithm (default sequence is djbfft, FFTW, FFTPACK), in case the particular transform type is missing in an implementation, for instance calls for transform lengths that are not a power of two would skip djbfft and use the FFTW algorithm.

3.4 Specifying parameters

3.4.1 Command line parameters

Programs that accept command line parameters are invoked at the shell prompt like other Unix commands by specifying the name of the executable first, followed by options and then file name(s). Options are prefixed by a “-” sign and can have zero or more parameters, which are all separated by spaces. To indicate the end of the option part on the command line, an optional double “–” is used before the first file name. For specific examples, see appendix.

3.4.2 Parameter files

Parameter files are simple text files in a free format. Keywords and numbers are separated by “white space”, i. e. any number of consecutive characters such as spaces, tabs, new line, etc. Parameters for a particular application are specified in sections which consist of a section name followed by the section body enclosed in braces. For instance
tiltseries { sampling: 2 }
is a section that declares a parameter “sampling”. A section can contain nested subsections, and parameters with the same name declared within different subsections represent distinct values. Parameters are grouped in subsections according to various processing functions. The protomo software only uses parameters defined in the section named “tiltseries” and ignores all other sections. When read, the entire parameter file is parsed though, and all section and parameter specifications must therefore be syntactically correct. Comments can be included as follows and they can be nested and span multiple lines:
(* this is a comment *)
Parameters are declared with a parameter name, followed by a colon, followed by the parameter value. The parameter values can be of type boolean, integer, floating point and string. Boolean values are designated by the keywords true or false, strings are enclosed in double quotes. A list of two or more values is enclosed in braces, the values are separated by commas. Variables can be defined with the text sequence “variable name”, “equal sign”, “value” and simple arithmetic operations can be performed: addition (+), subtraction (-), multiplication (*), and division (/).
In the following example, a window is defined and reduced in size according to the specified sampling factor:
tiltseries {
  N = { 512, 512 } (* window size *)
  S = 2            (* sampling factor *)
  suffix: “.tiff”
  sampling: S
  binning: true
  window { size: N / S }
If parameters need to be specified on a command line, the section names are concatenated and separated by dots. The top level name (tiltseries) can be omitted in protomo applications. The name of the size parameter in the above example would therefore be specified as “window.size”.

3.4.3 Geometry files

Like parameter files, the geometry files are text files using a free format, i. e. keywords, identifiers and numbers can be separated by any amount of white space. All definitions are enclosed by keywords as follows:
TILT SERIES identifier
where identifier is an alphanumeric text string. definitions is a list of subsections and each subsection can be either a tilt axis definition, a specimen orientation definition, a reference definition, or an image parameter definition. Text in angle brackets is optional, and if left unspecified, the corresponding parameter is assumed to be zero:
  < TILT ELEVATION angle >
  < PSI angle >
  < THETA angle >
  < PHI angle >
number is a non-negative integer number. The AXIS subsection defines the two angles ψ and φ (figure 1↑), and the ORIENTATION subsection the rotation R0.
An image parameter definition begins with the keyword IMAGE:
IMAGE number
and is followed by one or more parameter definitions:
FILE name or FILE name[index]
ORIGIN [ x y ]
SCALE factor

name is a file identifier, the actual file name is constructed as explained in the next section by prepending a file path and appending a suffix. The first variant of the file definition assumes a 2D image, the second one a stack of 2D images, a “pseudo-3D” image, and index refers to the section within the stack. x and y are the coordinates of point O i, where the index i corresponds to number. The angles theta and alpha are denoted as ϑi and αi in figure 1↑. factoris an isotropic scale factor applied to the image.

4 The alignment process

4.1 Common parameters

4.1.1 General parameters

These parameters control the input and output of image data, diagnostic terminal output, and the sampling of the input images (Table 1↓) and are specified within a top level section called tiltseries. When a tilt series is processed, the raw images are first located by file name. File names are constructed from the identifiers specified in the geometry file by appending a suffix defined in the parameter file. If a path list was also defined, the files are searched in the directories given in the list. The images are first preprocessed (see below) if requested, and stored in a cache file. If the parameter cachedir is defined, the cache files will be created in that directory, otherwise the current working directory is used. If binning is requested and the sampling factor is greater or equal to two, the raw or preprocessed images are binned and stored in an additional cache file. The binning factor is the sampling factor truncated to an integer value. All cache files can be deleted anytime and will be automatically regenerated when needed. By default, other output files are created in the directory defined by the parameter outdir or the current working directory if the parameter is undefined. The selection and exclusion parameters have the effect of effectively removing images in the tilt series. The format of a selection specification is a comma-separated list of image numbers or image number ranges. It is a string and must therefore be enclosed in double quotes. By default, all images are being selected. If both parameters are present, selection takes place before exclusion.

Parameter name Parameter type Parameter description
prefix string Prefix for input and output files, with the exception of raw image files, which are defined in the geometry file.
suffix string Suffix for raw image files.
pathlist string Colon-separated list of directories to search for raw image files.
cachedir string Directory where cache files are stored.
outdir string Directory where other output files are stored.
preprocessing bool Enable preprocessing of raw image files.
binning bool Binning of raw image files.
sampling real  ≥ 1 Sampling factor.
select selection Select specific images in the tilt series.
exclude selection Exclude images from the tilt series.
logging bool Enable diagnostic terminal output.
Table 1 General parameters

4.1.2 Preprocessing

The preprocessing is carried out in one or two passes. In each pass, image statistics are first computed from the whole image or a region thereof reduced by a border of fixed width. Optionally a linear density gradient can be subtracted and/or densities can be thresholded below and above a specified multiple of the density standard deviation. Additionally, a median or Gaussian filter can be applied. All preprocessing parameters are specified in a subsection called preprocess (Table 2↓). If a subsection mask is present within the preprocess section, then the first pass generates a binary mask that indicates which pixels are set to a locally computed mean value in the second pass, otherwise only one pass is carried out. Preprocessing can be turned off without removing the preprocess subsection (see parameter preprocessing under general parameters).

Parameter name Parameter type Parameter description
clip real, real Lower and upper threshold, specified in multiples of the standard deviation.
thr real, real Lower and upper threshold, specified as density value.
gradient bool Enable linear gradient subtraction.
iter bool Iterate gradient subtraction once.
filter string “median” or “gauss”
kernel int, int Filter window size.
radius real, real Widths of the Gaussian function.
grow int > 0 Grow the selected regions in the binary mask by the specified number of pixels.
logging bool Enable diagnostic terminal output.
Table 2 Preprocessing parameters

4.1.3 Region of interest

When a tilt series is aligned, three subsections are relevant for specifying parameters. These are window, reference, and align. First, a window is extracted by applying the stored geometric parameters under the consideration of the preprocessing and resampling parameters by linear interpolation, and its resulting size is specified with the size parameter in the window subsection. If binning was selected, the window is extracted from the cached, binned data, otherwise it is extracted from the preprocessed or raw data. In the former case, the sampling factor used in the linear interpolation is automatically adjusted to take into account the binning factor, so that the overall sampling factor remains as specified by the parameters. After extraction, the windowed image is masked, Fourier transformed, and filtered. The parameters that apply to these steps are listed in tables 3↓ and 4↓.

Parameter name Parameter type Parameter description
size int, int > 0 Size of extracted and resampled window.
area real Fraction of area that must be covered by source image.
mask section See table 4↓
lowpass section See table 4↓
highpass section See table 4↓
Table 3 Window parameters

Parameter name Parameter type Parameter description
width real, real  ≥ 0 Rectangular mask widths.
diameter real, real  ≥ 0 Ellipsoidal mask, principal axes.
sigma real, real  ≥ 0 Gaussian mask width.
apodization real, real  ≥ 0 Apodization for rectangular and ellipsoidal masks.
inv bool Mask interior instead of exterior region.
Table 4 Mask parameters

4.1.4 Reference

The alignment reference construction is controlled by the subsection reference. The presence of the parameter body indicates that the reference is to be calculated by reprojecting a preliminary backprojection map, based on already aligned images in the tilt series. The reprojection is carried out with the geometric parameters of the image that will be aligned. If no backprojection options are present, the nearest neighbor image is selected as a reference. The selection and exclusion parameters within the reference subsection define which images in the tilt series contribute to the reference construction. The format is the same as explained in “General options”.

Parameter name Parameter type Parameter description
body real Backprojection body size.
select selection Select images of the tilt series.
exclude selection Exclude images from tilt series.
Table 5 Reconstruction parameters

4.1.5 Cross-correlation

Several cross-correlation methods are available: the conventional cross-correlation “xcf”, the mutual correlation “mcf”, phase only correlation “pcf”, and phase doubled correlation “dbl”. For diagnostic purposes, an image stack with the cross-correlation function can be written. The size parameter specifies the image window that is extracted and written to a file. It does not affect the correlation calculation nor the peak search described below, which always use the image window size defined in the window subsection.

Parameter name Parameter type Parameter description
mode string Correlation mode: “xcf”, “mcf”, “pcf”, or “dbl”.
size int, int > 0 Size of output image with correlation peaks.
Table 6 Cross-correlation parameters
By default the whole cross-correlation function is searched for a maximum. The radius parameter restricts the search for the highest correlation peak to a smaller ellipsoidal or circular area. The two required values define the principal axes. If cmdiameter is also present, a refined value (center of mass) of the peak position and height is calculated within an area centered at the maximum obtained by the preceding search.

Parameter name Parameter type Parameter description
radius real, real > 0 Defines peak search area.
cmdiameter real, real > 0 Area for center of mass calculation.
Table 7 Peak search parameters

4.2 Alignment

A coarse alignment can be carried out interactively with the graphical tool described in section “Standalone graphical tools”. It is primarily used to correct misaligned images or do an initial alignment of a raw tilt series if large shifts occurred during data collection. Individual images can be aligned manually or a whole series can be aligned automatically. The automated alignment function performs a simple, sequential cross-correlation between neighboring image pairs and differences in the foreshortening are accounted for. Area matching is implemented in the Python module (see section “Python classes for tomography”).
Area matching operates on whole tilt series and starts with the image defined as reference in the geometry parameter file as the first alignment reference. It aligns the neighboring images with the next lower and higher tilt angle to this reference. After successful completion of the alignment, the two aligned images are incorporated into the new reference, and the next neighbors are aligned. This process is repeated until all images are aligned, or one of the termination criteria listed in table 8↓ is met. Dual axis or multiple axis tilt series can be aligned in two ways, either separately or simultaneously. For the first variant, the images are grouped by tilt axis first and the groups are aligned one after another. For the second variant, when the parameter startangle is set, all images are aligned in the order of increasing tilt angle magnitude, alternating between the axis groups. If startangle is greater than zero, the images up to startangle are aligned according to the first variant, at which point the alignment mode switches to the second variant. Area matching computes updated transformation matrices:
Ai = R i C i
where R i are the input transformations, and C i the corrections applied. To interpret the corrections, we compute the singular value decomposition:
C i = U SVT
The singular values of the diagonal matrix S indicate a stretch/compression correction in two orthogonal directions with an orientation angle given by the orthogonal matrix V . U indicates a correction of the in-plane rotation.

Parameter name Parameter type Parameter description
estimate bool Estimate geometric parameters instead of using stored values.
norotations bool Set in-plane rotations to zero instead of using stored values.
area real Fraction of area that must be covered by source image.
mask section Mask parameters for aligned image, see table 4↑
correlation section See table 6↑.
peaksearch section See table 7↑.
maxcorrection real Terminate alignment if correction exceeds specified value.
maxcorrchange real Terminate alignment if change of the correction value is greater than the specified value.
maxshift real Terminate alignment if translational shift exceeds specified value.
startangle real Start alternating alignment at specified tilt angle.
maxtilt real Align images only up to |angle| ≤ maxtilt.
include selection Include image in alignment by image number.
exclude selection Exclude images from alignment.
logging bool Enable diagnostic terminal output.
Table 8 Area matching parameters

4.3 Geometry refinement

The geometry refinement tries to approximate matrix C if to a unit matrix in the equation Ai = R if C if. The matrices Ai were obtained by area matching, and R if are the new, refined alignment transformations.

Parameter name Parameter type Parameter description
orientation bool Include orientation angles in refinement.
azimuth bool Include tilt azimuth in refinement.
elevation bool Include tilt axis elevation in refinement.
rotation bool Include in-plane rotations in refinement.
scale bool Include scale factors (magnification) in refinement.
include selection Select images by image number.
exclude selection Exclude images.
logging bool Enable diagnostic terminal output.
Table 9 Geometry refinement parameters

4.4 3D reconstruction

3D reconstruction is carried out by weighted backprojection with general weighting functions. The backprojection parameters have the same meaning as in the reference construction. Additionally, a low-pass filter is applied to filter out the signal beyond the resolution limit imposed by the angular sampling.

Parameter name Parameter type Parameter description
size int, int, int > 0 Size of computed map.
identifier See table 5↑
lowpass section See table 4↑.
logging bool Enable diagnostic terminal output.
Table 10 Map computation parameters


5 Processing a tilt series

Tilt series alignment is carried out at the Python command level in SPARX. SPARX is a Python and EMAN2 based environment for image processing. The protomo software package provides a Python extension module that integrates with SPARX/EMAN2 and provides the functionality needed for tilt series alignment and 3D reconstruction.

5.1 Python classes for tomography

The protomo Python extension module is loaded with the following command at the Python or SPARX command prompt:
import protomo
It makes four classes available: protomo.param for processing parameters, protomo.geom for geometric parameters, protomo.series for alignment, and protomo.image for image manipulation. The methods provided by these classes are listed in tables 11↓, 12↓, 13↓, and 14↓.

Method Return value Description
protomo.param(file) parameter object Create a parameter object from a parameter text file specified by the string file.
.list() none List all parameters.
.set(par,value) none Change the parameter with the name par to value.
Table 11 Parameter object methods

Method Return value Description
protomo.geom(file) geometry object Create a geometry object from a geometry text file specified by the string file.
.write(file) none Write a geometry text file specified by the string file.
Table 12 Geometry object methods
A typical alignment session first creates a parameter and geometry object from which a series object is then created that keeps track of the alignment parameters and the alignment status. The geometry and parameter objects are stored in memory and are not persistent between SPARX sessions. The series object however, is backed by the geometry metadata file which keeps track of the alignment status, so that a session can be restarted. If the metadata file exists at startup, the geometry object is no longer needed to create the series object, since all the relevant data is stored in the metadata file.

The actual alignment is carried out with the align method. If interrupted, it can be restarted. At least a few images of the tilt series must be aligned before the geometry can be re-evaluated with the fit method. The re-evaluation can be carried out multiple times with different parameters and previous results are overwritten with each invocation. The new, re-evaluated geometry will not be effective and will be lost unless the updatemethod is called.

Method Return value Description
series object Create a series object. p is a parameter object, g is a geometry object. The first variant reopens a series, the second variant creates a new series.
.align() none Align the tilt series with area matching.
.area() image object Determine the maximal usable area.
.corr() none Writes correction data to a text file.
.filter(img) image object Computes filtered image number img.
.fit() none Re-evaluates geometry parameters.
.geom() geometry object Returns a copy of the geometry.
.image(img) image object Resamples image number img.
.map() image object Computes a tomogram.
.mapfile(file) none Writes a tomogram to an image file with name file. If file is omitted, a name is generated automatically.
.param(p) none Replaces the current parameters with object p.
.plot() none Displays a graph of the stretch/compression factors.
.preprocess(img) image object Preprocess image number img.
.setparam(par,value) none Change the parameter with the name par to value.
.transform(img) image object Computes transform of image number img.
.update() none Replaces the current geometry with the re-evaluated geometry.
.window() image object Computes a stack of resampled images.
Table 13 Series object methods

Method Return value Description
protomo.image(img) image object Create an image object. If img is a string, read the image from a file with the name img. If img is an EMdata object, convert it to an image object.
.write(file) none Write the image to the file with the name file.
.stat() none Print image statistics.
.fft() image object Compute the Fourier transform.
.display() none Display the image. See also below, section “Image display”
.emdata() EMdata object Convert the image to an EMdata object.
Table 14 Image object methods

5.2 Standalone graphical tools

5.2.1 Image display

The program “i3display” is a command line front end equivalent to the display method of an image object, and is invoked at the shell prompt as follows:
i3display [-r min max] image
It displays the image with the file name image, and if the option -r is given, thresholds the densities below min and above max. If the option is absent, it first scans the image to find the minimal and maximal densities and uses these to scale the densities for display. It recognizes the key/buttons listed in table 15↓. Stacks of 3D images cannot be displayed directly. Use the program “i3montage” to create a montage first, and display the montage.

Key/button Action
up arrow Display next lower section.
down arrow Display next higher section.
left mouse Print coordinates.
left mouse + drag Pan.
middle mouse + drag Zoom.
Table 15 i3display: key/button press actions

5.2.2 Tilt series alignment

The program “tomoalign-gui” is used for manual alignment of tilt series, or for displaying and saving animated sequences of tilt series:
tomoalign-gui [-log] [-zoom fac] [-r min max] [-tlt geom] param
If the -log option is present, diagnostic information is printed to the terminal. Option -zoom sets the initial zoom factor, and -r the density scaling as in the program “i3display”. If this is a new tilt series and the geometry metadata file does not exist yet, the option -tlt to specify the geometry parameter file is mandatory. Key/button actions are listed in table 16↓.

Key/button Action
left mouse Print coordinates.
left mouse + drag Align image manually.
A a Align image manually.
I i Toggle image display.
R r Reset alignment.
Zoom out.
+ Zoom in.
Table 16 tomoalign: key/button press actions
On startup, or when the overlay mode is selected from the menu, this program displays two images, a reference image in red, and the image to be aligned in green. The superposition of the two colors results in a more or less grey tone if the two images are in register. To align manually, the green image can be dragged to the aligned position by holding down the left mouse button. The automatic alignment function, selected from the menu, performs a cross-correlation alignment. The differences in foreshortening of the images is compensated, but the reference construction scheme used in area matching is not applied, the two images are simply cross-correlated and the displacement calculated according to the correlation maximum.

5.3 Command line utilities

The program tomoinit can be used to create the geometry metadata file (“.i3t”) from the geometry parameter file (“.tlt”):
tomoinit -tlt geom param

geom is a geometry parameter file, and param a processing parameter file. The parameter files can be parsed to check for correctness with the programs “tomotilt”, or “tomoparam” respectively.