Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells
TILT(1) TILT(1)
NAME
tilt - calculates 3-D tomographic reconstruction from a tilt series
SYNOPSIS
tilt [options] [input filename] [output filename]
DESCRIPTION
Tilt is a program for reconstructing a three-dimensional object from a
series of two-dimensional projections. The projections are assumed to arise
from rotation about a fixed tilt axis, subject to minor variations from this
scheme.
The program uses a number of different numerical strategies depending on
whether the reconstructed volume is rotated around the X axis and depending
on the amount of memory available. If there is no X-axis tilt being
imposed, then each output plane is derived from one line of the input data.
The program tries first to use the fast backprojection algorithm developed
by Sandberg and Beylkin, if there is a license. If there is insufficient
memory for this, or if other preconditions are not satisfied, it then tries
to use preliminary stretching of each input line by the cosine of the tilt
angle, which speeds up the direct backprojection. If there is not enough
memory for this method either, the program falls back to direct
backprojection from the unstretched input lines.
When a tilt around the X axis is specified, then each output slice derives
from several lines of input data. The program tries to do this first by
computing untilted slices, one per input line, and interpolating an output
slice from the relevant untilted slices. It uses fast backprojection if
possible; if not, it tries to use cosine stretching if possible, or falls
back to direct computation. If there is insufficient memory for this
approach, the program reverts to "old-style" X-axis tilting, in which the
output slice is computed directly from the various input slices. In this
case,it also tries to use cosine stretching if memory is available.
The user can disable various strategies by specifying an interpolation order
of 0: cosine stretching by entering "COSINTERP 0", fast backprojection by
entering "FBPINTERP 0", or the new style of X-axis tilting by entering
"XTILTINTERP 0". There are some cases where the fast backprojection is
slower than the conventional approach (e.g., few input views). The program
attempts to detect these cases and use conventional summation instead. If
you use "FBPINTERP 1", you can bypass this checking and force the program to
use fast backprojection as long as other conditions are met.
With perpendicular slices, the header of the output file will set up a
coordinate system congruent with that of the original views. If slices are
output in order of increasing slice number, this represents a 90 degree
rotation about X, so the slices are inverted about their new Z axis (by
using the negative of the tilt angles). If slices are output in inverted
order (IDELSLICE < 0), this represents a -90 degree rotation about X; slices
are not inverted in this case.
The program can do two different kinds of reprojections. First, it can
compute each tomogram slice as usual then, instead of writing the slice to
the output file, it outputs a reprojection of that slice at selected
angles. This reprojection should match what xyzproj would produce by
reprojecting from the tomogram, but it will not match the input images if
the reconstruction is computed with a fixed or variable X axis tilt, Z
factors, or local alignments. Getting a reprojection that matches input
images in any of these cases requires multiple slices of reconstruction to
get one line of reprojection. Thus, these reprojections are obtained by
first computing the full reconstruction, then providing this file as input
to the program on a second run. On that run, the program needs to know
about all the parameters used to make the reconstruction, as well as about
the original projection file.
The scaling of data by the backprojection is somewhat unpredictable. If the
radial filter were scaled to go from 0 at zero frequency to 1 at 0.5
cycle/pixel, then the backprojection would produce numbers that correspond
approximately to the underlying densities; i.e., their reprojection by
summation would give numbers comparable to those in the input projections.
Unfortunately, the radial filter goes from 0 to NX / 2, where NX is the X
dimension of the input data. This means that in order to get output
that would reproject to give values comparable to the input, you would need
to: a) not take the log of the data; and b) set the scaling factor in the
SCALE entry to 2/NX.
The scaling of data in the reprojection from a tomogram takes the
backprojection scaling into account. Specifically, the program first undoes
the output scaling that was specified by the SCALE entry, then it multiplies
by 2.2 / NX. The reprojection is computed by summing these unscaled
values. If the log was not being taken in the backprojection, these sums
are then divided by the weighting factors entered with WeightFile, if any,
and output. If the log was taken, the sums are adjusted by adding an amount
that should give a constant mean level, then the exponential is taken.
Tilt uses the PIP package for input (see the manual page for pip) but
it has several special features to maintain compatibility with the old
input method and old command files. 1) Options are case-insensitive and can
be entered in upper, lower, or mixed case. 2) If the program is started
with no command line arguments, it behaves as if -StandardInput were given
and takes lines from standard input. 3) The first two lines taken from
standard input can be the input and output filenames, without their
respective keywords. This will not work if the filenames match a subset
of any of the option strings.
The following options can be specified either as command line arguments
(with the -) or one per line in a command file or parameter file (without
the -):
-input OR -InputProjections File name
Input image file with aligned projections. If this option is not entered,
the first non-option argument is taken as the input name.
-output OR -OutputFile File name
Output file for reconstruction or reprojection. If this option is not
entered, the second non-option argument is taken as the output name.
-recfile OR -RecFileToReproject File name
Reconstruction file to reproject. When using this option, all of the
entries to the program used when building this reconstruction should be
included as well.
-ProjectModel File name
Model file with point positions to reproject onto the projection images.
The output file will be a model. All of the other parameter entries
should be the same as were used for generating the tomogram upon which the
model was built. Points will be output only for the views included in
that tomogram. The model header will be set so that the model will
display properly on both the aligned stack used to generate the tomogram
and on aligned stacks at other binnings.
-BaseRecFile File name
Previous reconstruction file to add views to or subtract views from. One
use for this option is to compute a series reconstructions quickly with
different views left out. The BaseNumViews option must also be entered in
order for the right scaling to be set up when reading in the existing
reconstruction and writing out the new one. If the WeightAngleFile option
is also used, then incremental reconstructions computed in this way should
match reconstructions computed de novo very closely. If the input
projection file contains only the views being added or subtracted, then
you should also use the MinMaxMean option to keep fill values constant.
-AdjustOrigin
Adjust origin for shifts with the SHIFT option and size changes with WIDTH
and SLICES, and base the origin on that of the aligned stack. With this
option, reconstructions in PERPENDICULAR mode of different size and
location will have congruent coordinate systems and will load models
interchangeably. In addition, reconstructions from different sized
projection stacks will have congruent coordinates provided that the origin
was adjusted when making the projection stack (e.g., with the -origin
option to Newstack). The default is to produce legacy origin values
that are not adjusted for these operations, with the origin in X and Y in
the center of the volume.
-ANGLES Multiple floats
Use this entry to specify the tilt angles of the views if they are not in
a separate file. You must enter one tilt angle for each view. Use more
than one ANGLES entry if necessary. This information will override tilt
angles specified in the file header. If you enter angles in this way, the
file header need not contain tilt information.
(Successive entries accumulate)
-BaseNumViews Integer
Number of views in previous reconstruction
-COMPFRACTION Floating point
If the compression measured by TILTALIGN occurred over only a fraction of
the distance between the fiducials, enter the fraction with this option.
-COMPRESS Multiple floats
With this entry, the program will assume that the section has compressed
in Z by the amount given by the amount given for each view. The
compressions would be taken directly from the output of TILTALIGN for
incremental compression. A value must be entered for each view.
(Successive entries accumulate)
-COSINTERP Multiple integers
Interpolation order and sampling factor for cosine stretching for cosine
stretching of the input data. The order can be 1 for linear, 2 for
quadratic, 3 for cubic, or 0 to disable cosine stretching. The default is
linear to provide some smoothing of the data; higher orders are
appropriate if data are relatively noise-free. The factor is optional;
the default is 2, which prevents further smoothing when the stretched data
are linearly interpolated during backprojection.
-DENSWEIGHT Multiple floats
Use this entry to control the weighting of each view proportional to the
local average tilt increment between views. The first value specifies the
number of intervals on EACH side of a view to consider; the default is 2,
and a value of 0 disables weighting. Optionally, this value may be
followed by that number of weights to be applied in averaging the adjacent
increments (the default is equal weighting).
-DONE
The entry is equivalent to EndInput, and lines of input following it will
be ignored. This option is provided for compatibility with old command
files.
-EXCLUDELIST2 List of integer ranges
List of views to be excluded from the reconstruction, numbered from 1.
The list can consist of individual view numbers, or of ranges (e.g., 1-4),
separated by commas or spaces. The EXCLUDE and EXCLUDELIST entries
available in old versions of the program are treated as this option. You
may have any number of entries with exclude lists, but they cannot be
combined with INCLUDE entries.
(Successive entries accumulate)
-FlatFilterFraction Floating point
With a value entered between 0 and 1, the radial filter will be set up as
a linear combination of the standard R-weighting filter and a flat filter,
which will greatly overemphasize low frequencies. The entered value is
the fraction for the flat filter. The flat filter is scaled to give
output densities roughly comparable to those obtained with the R-weighting
filter. The zero-frequency component of each filter is 0.2 times the
component at the lowest non-zero frequency. If the value is greater than
one, a filter suitable for Simultaneous Iterative Reconstruction (SIRT) is
set up, scaled so as to distribute input values equally along each ray.
The zero-frequency component is the same as the other components in this
case.
-FBPINTERP Integer
The interpolation order for the fast backprojection algorithm: 1 for
linear interpolation (the default), 3 for cubic spline interpolation,
which will low-pass filter the input data more, or 0 to disable fast
backprojection. Entering a value with this option will also force the
program to use fast backprojection even if the width, thickness, and
number of views are small enough so that fast backprojection will run
slower than direct summation.
-FULLIMAGE Two integers
Use this entry to specify the full size in X and Y of the original stack
of tilted views, so that a subset of the aligned stack can be handled
properly when using a global X-axis tilt or local alignments.
-IMAGEBINNED Integer
If the input images have been binned, this entry can be entered to specify
the binning and have various other dimensions scaled down by this factor.
Values entered with SHIFT, OFFSET, THICKNESS, WIDTH, FULLIMAGESIZE, SLICE,
and SUBSETSTART will be scaled. These entries thus do not need to be
changed when the input binning is changed.
-INCLUDE List of integer ranges
A subset of views to be used for the reconstruction, numbered from 1. The
values can be individual view numbers or ranges, separated by spaces or
commas. Use more than one INCLUDE entry if the numbers do not all fit on
one line.
(Successive entries accumulate)
-SubtractFromBase List of integer ranges
Views to subtract from the previous reconstruction specified by
BaseRecFile. Without this entry, all views are added. Enter 0 to have
all included views subtracted, or the list of specific views to subtract.
-LOCALFILE File name
File containing local tilt alignment information.
-LOCALSCALE Floating point
If local tilt alignments were obtained from unreduced data, but the
aligned stack was reduced by binning or transforming, use this entry to
specify the factor by which the data were scaled, so that the local
alignment information can be adjusted. Without this entry, the program
will use the ratio of the pixel size at which local alignments were
computed to the pixel size of the aligned images, which should be correct
if data were binned.
-LOG Floating point
This entry allows one to generate a reconstruction using the logarithm of
the densities in the input file, with the value BASE added before taking
the logarithm.
-MASK Floating point
This entry allows a mask to be applied so as to exclude from the
reconstructed volume those parts which lie outside the volume for which
the projection data are complete. This volume is a cylinder whose axis
lies along the tilt axis. Grid points outside this volume will be set to
the given value. For thick sections, this option saves a little execution
time but produces sharp edges in the reconstruction.
-MinMaxMean Three integers
Min, max, and mean densities to use instead of values in the input
projection file. Use this entry to keep the fill value used for back
projecting from outside the data constant when doing incremental
reconstruction with a projection file that contains only the views being
added or subtracted.
-MODE Integer
This entry allows one to specify the data mode of the output file, which
is 2 by default. Be sure to use an appropriate SCALE entry so that data
will be scaled to the proper range.
-OFFSET Multiple floats
This entry allows an offset of DELANG degrees to be applied to all tilt
angles and indicates that the tilt axis is offset in the projection
images, cutting the X-axis at NX/2. + DELXX instead of NX/2. DELANG
positive rotates reconstructed sections anticlockwise. The DELXX entry is
optional and defaults to 0 when omitted. If the tilt axis is offset from
the center because the projection images are a non-centered subset of the
full images, use the SUBSETSTART entry instead.
-PARALLEL
Output slices parallel to the plane of the zero tilt projection. This
option cannot be used with direct writing of data to a single output file
from parallel Tilt runs. It inverts the handedness of the reconstruction.
-PERPENDICULAR
Output slices perpendicular to the plane of the specimen. This output is
the default since it corresponds to the way in which slices are computed.
-RADIAL Two floats
This entry controls low-pass filtering with the radial weighting function.
The radial weighting function is linear away from the origin out to the
distance in reciprocal space specified by the first value, followed by a
Gaussian fall-off with a s.d. (sigma) given by the second value. If the
cutoff is great than 1 the distances are interpreted as pixels in Fourier
space; otherwise they are treated as frequencies in cycles/pixel, which
range from 0 to 0.5.
-REPLICATE Two floats
With this entry, the input views will be replicated the number of times
given by the first value, with an increment given by the second value in
degrees added to the original angles for each replication. For example,
if you can assume 9-fold symmetry, enter REPLICATE 8 40.
(Successive entries accumulate)
-REPROJECT Multiple floats
With this entry, the program will output one or more reprojections of the
reconstructed slices at the given angles. If RecFileToReproject is
entered, then the reprojections should match the input projections;
otherwise the reprojections will be of the computed slices and should
match what Xyzproj would produce.
(Successive entries accumulate)
-SCALE Two floats
With this entry, the values in the reconstruction will be scaled by adding
the first value then multiplying by the second one. The default is 0,1.
After the reconstruction is complete, the program will output the scale
values that would make the data range from 10 to 245.
-SHIFT Multiple floats
This entry allows one to shift the reconstructed slice in X or Z before it
is output. If the X shift is positive, the slice will be shifted to the
right, and the output will contain the left part of the whole potentially
reconstructable area. If the Z shift is positive, the slice is shifted
upward. The Z entry is optional and defaults to 0 when omitted.
-SLICE Multiple floats
Starting and ending slice number to reconstruct, and interval between
slices. The numbers refer to slices in the X/Z plane and correspond to Y
coordinates in the projection images. Slices are numbered from 0. The
interval entry is optional and defaults to 1 when omitted.
-SUBSETSTART Two integers
If the aligned stack contains a subset of the area in the original images,
and this area is not centered in X or a global X-axis tilt or local
alignments are being used, use this entry to enter the X and Y index
coordinates (numbered from 0) of the lower left corner of the subset
within the original images. A FULLIMAGE entry must also be included. If
the aligned stack is larger than the original images, use negative values.
-THICKNESS Integer
Thickness in Z of reconstructed volume, in pixels
-TILTFILE File name
Use this entry to specify a file containing a list of all tilt angles.
The angles may be one per line or many per line.
-TITLE Text string
An alphanumeric string giving the title for the job, which will be added
to the output map. Limit 50 characters. This entry is optional; the
default is "Tomographic reconstruction".
-TOTALSLICES Two integers
This entry is used to allow multiple runs of Tilt to compute a subset of
slices and place them into the same output file. The values specify the
first and last slice to be reconstructed in the whole volume, numbered
from 0. When this entry is present, the behavior of the program depends
on the SLICE entry (or the ZMinAndMax entry when reprojecting from a
tomogram). The program should be run initially with SLICE -1 -1 (or
ZMinAndMax -1 -1 when reprojecting), which will cause it to create the
output file and write its header. On successive runs with SLICE or
ZMinAndMax indicating a real range of slices, the program will open the
existing file, write only those slices, and not write the header when it
is done.
-ViewsToReproject List of integer ranges
List of views to reproject from a reconstruction file, numbered from 0.
The default is to project just the views that were included in the
reconstruction. To project all views in the input projection file, enter
0.
-WeightAngleFile File name
File with a list of tilt angles to be used for computing the relative
weighting of the views. Use this entry to keep the weightings applied to
each view constant across reconstructions from subsets of views,
regardless of which views are actually included in a particular
reconstruction. For example, when leaving one view out, the two adjacent
views would receive higher weights without this entry, but with this entry
they would have the same weights as with the view included.
-WeightFile File name
Name of a file containing a list of weighting factors to be applied to the
views, such as for mass normalization. The factors may be one per line or
many per line. These weights are ignored if the log is being taken of the
data.
-WIDTH Integer
The width of the output image; the default is the width of the input
image.
-XAXISTILT Floating point
This entry allows one to rotate the reconstruction around the X axis, so
that a section that appears to be tilted around the X axis can be made
flat to fit into a smaller volume. The angle should be the tilt of the
section relative to the X-Y plane in an unrotated reconstruction. For
example, if the reconstruction extends 500 slices, and the section is 5
pixels below the middle in the first slice and 5 pixels above the middle
in the last slice, the angle should be 1.1 (the arc sine of 10/500).
-xminmax OR -XMinAndMaxReproj Two integers
Starting and ending X index coordinates of region to reproject from a
reconstruction file (numbered from 0). The default is the whole extent in
X.
-XTILTFILE File name
Use this entry to specify a file containing a list of tilts around the X
axis for the individual views. A global tilt specified by the XAXISTILT
entry, if any, will be added to these tilts. If this file contains all
zeros, the program runs the same as if the file was not entered.
-XTILTINTERP Integer
This entry controls the order for interpolating an output slice tilted
around the X axis from vertical, untilted slices each computed from a
single line of input data. Set the order to 1 for linear, 2 for
quadratic, 3 for cubic, or 0 to disable this method of X-axis tilting and
revert to computing the output slice directly from input data. The
default is 1; higher orders are appropriate if data are particularly
noise-free.
-yminmax OR -YMinAndMaxReproj Two integers
Starting and ending Y index coordinates of region to reproject from a
reconstruction file (numbered from 0). Y is the thickness dimension. The
default is the whole extent in Y.
-ZFACTORFILE File name
Use this entry to specify a file containing factors for adjusting the
backprojection position in each image as a function of Z height in the
output slice. These factors are necessary when input images have been
transformed to correct for an apparent specimen stretch. If this entry is
absent, Z factors in a local alignment file will not be applied.
-zminmax OR -ZMinAndMaxReproj Two integers
Starting and ending Z index coordinates of region to reproject from a
reconstruction file (numbered from 0). Z is the the dimension along the
tilt axis. The default is the whole extent in Z.
-param OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter file.
-help OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
HISTORY
Originally written by Mike Lawrence. Storage of tilt angle data
altered by Guy Vigers; angles can be stored in image stack header by
the program ALTERHEADER.
David Mastronarde added ability to output slices at selected
intervals and in inverse direction, and setting of header
information so that coordinates correspond between output file and
tilt data set. Also added ability to specify a subset of views to
use or exclude, control of output mode, abilities to take log,
replicate views, enter specific tilt angles or read in angles from a
file, adjust for compression, set width of output, and shift the
output. Implemented weighting by local tilt increment and padding
before filtering. Added ability to adjust for tilt around the X axis
and to use local alignments. Implemented subroutine calls for the
inner loops so that assembly code could be adjusted to minimize very
slow steps on the PC. Implemented cosine stretching of the input
data as an alternative solution to this problem that is faster on
all machines. Incorporated the fast backprojection code developed by
Kristian Sandberg and Gregory Beylkin. Implemented X-axis tilting
by interpolation from untilted slices, so that the fast
backprojection could be used with X-axis tilting.