tilt(1) General Commands Manual tilt(1)
NAME
tilt - calculates 3-D tomographic reconstruction from a tilt series
SYNOPSIS
tilt [options] [input_file] [output_file]
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 varia-
tions from this scheme.
The program uses a number of different numerical strategies depending
on the complexity of the alignments needed to reconstruct the volume
and on whether the computation is being done by the central processing
unit (CPU) or the graphical processing unit (GPU). If there are no
local alignments being applied, then for processing on the CPU, the
program will do a preliminary stretching of each input line by the
cosine of the tilt angle. This stretching speeds up the direct back-
projection because each stretched input line is in register with the
lines of the output planes. The stretching will not be used if the
maximum tilt angle is over 80 degrees, if the option "COSINTERP 0" is
entered, or in the unlikely event that there is insufficient memory for
the stretched data. When computing on the GPU, the program does not
use cosine stretching, thus avoiding the consequences of interpolating
the data twice.
If there is no X-axis tilt being imposed, then each output plane is
derived from one line of the input data; i.e., data all at one Y value
in the input images. With a fixed tilt around the X axis, each output
slice derives from several lines of input data. However, as long as
there are no "Z-factors", it is still possible to compute a slice prior
to the tilting from a single line of input. Thus, the program will
compute such untilted slices, one per input line, and interpolate an
output slice from the relevant untilted slices. If the option "XTILT-
INTERP 0" is entered, or in the unlikely event that there is insuffi-
cient 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.
With output of perpendicular slices, the header of the output file will
set up a coordinate system congruent with that of the original views.
This represents a 90 degree rotation about X but no change in handed-
ness. When these X/Z planes are viewed in 3dmod without rotation,
we are looking down the positive Y axis towards an X/Z slice with the Z
axis pointing down. Higher Z in such slices corresponds to more nega-
tive Z in true tomogram coordinates. A positive (counterclockwise)
tilt around the Y axis swings points on the right higher in the viewed
slice and thus to more negative Z; this direction also corresponds to
higher underfocus (see Ctfplotter man page).
With parallel slice output using PARALLEL, the handedness is inverted;
whereas parallel slice output with the "RotateBy90" option retains the
handedness.
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 reprojec-
tions 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 back-
projection 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 backpro-
jection, 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.
Using a GPU
The program can use the GPU of an NVIDIA graphics card for all kinds of
reconstructions and reprojections from an existing reconstruction file.
The card must be capable of supporting computations with CUDA, and you
must have a version of NVIDIA graphics drivers installed that supports
the particular version of CUDA against which your version of Tilt was
compiled.
The amount of memory required in the GPU is relatively modest unless
local alignments or Z factors are being used. In those cases, the mem-
ory requirement depends on how many planes of input data need to be
loaded to reconstruct one plane of output data, where a plane refers to
a set of horizontal projection lines or a tomogram slice. That need
will be determined by thickness, amount of X-axis tilt, and the degree
of distortion imposed by the local alignments. When there is insuffi-
cient memory to do an operation on the GPU, the program will issue a
message to this effect that refers to "current parameters"; these are
the relevant parameters. Reducing the thickness or the X-axis tilt
should allow the operation to proceed.
SIRT and a SIRT-like Filter
The program can compute multiple iterations of the Simultaneous Itera-
tive Reconstruction Technique (SIRT) internally for the situation where
a reconstruction slice backprojects from, and reprojects to, a single
set of lines in the projection images. This option is thus not avail-
able when the reconstruction involves the Z factors produced when solv-
ing for linear stretch in Tiltalign, a variable X-axis tilt produced
when correcting for beam tilt, or local alignments. It also requires
that the reconstruction be the same size as the aligned stack in X and
Y (i.e., no SLICE or WIDTH entries) and that the tilt axis be in the
center of the aligned images. The procedure starts with a slice com-
puted with no or reduced R-weighting, or read in from prevous itera-
tions. The slice is reprojected, the difference is formed between the
reprojections and the original projections, and this difference is
backprojected with a weighting that distributes the error in difference
among the pixels along a projection ray. The backprojected difference
is then subtracted from the starting slice, and the procedure is ready
to be iterated. The program carries each slice through the full set of
iterations before writing it out and going on to the next slice. Fur-
ther details are given under the SIRTIterations option.
A fast alternative to SIRT is provided by the FakeSirtIterations
option, which simply modifies the radial weighting function applied to
each line of input data so that it is theoretically equivalent to a
certain number of iterations of SIRT. Instead of being proportional to
frequency, the equivalent filter would be proportional to:
freq * (1 - (1 - alpha / freq)^iter)
where "freq" is frequency, "iter" is the number of SIRT iterations
being matched, "alpha" is a constant, and "^" is exponentiation (Zeng,
G.L., 2012, "A filtered backprojection algorithm with characteristics
of the iterative landweber algorithm", Med. Phys. 39: 603-607). This
program uses the equation
freq * (1 - (1 - 0.00195 / freq)^(fakeIter + 0.3))
where the value of "fakeIter" is:
iter for 1 <= iter <= 15
15 + 0.4 * (iter - 15) for 15 < iter <= 30
27 + 0.6 * (iter - 30) for iter > 30
The alpha value and modification of the iteration number were deter-
mined empirically by computing back-projections with different values
for the iteration parameter then matching one of those tomograms with a
SIRT reconstruction for a series of different SIRT iterations. This
was done with a cryo-tomogram of virus particles, where the SIRT and
modified backprojection were remarkably similar. The evaluation was
also done with two tomograms of stained, embedded material. SIRT and
the modified backprojection matched reasonably well in terms of the
visibility of fine detail, but overall appearance was different because
of some differences in very low frequencies and a possible non-linear
relationship between intensities in the two reconstructions. The match
between iteration numbers was quite different in the two cases, so some
experimentation with iteration number is needed to find the desired
value. Note that this same filter can be applied to a tomogram still in
its original orientation with Mtffilter. That program would be a
more efficient way to assess different iteration numbers than running
this program multiple times.
Backprojection works with angles up to and beyond 90 degrees on both
the CPU and GPU. Both reprojection and internal SIRT should work for
such data sets provided that local alignments are not used.
Super-sampled backprojection
Super-sampling refers to computing the back projection in a slice
larger by an integer factor in each dimension, which is done here in
one of two ways: by interpolating the projection data at smaller inter-
vals during backprojection, or by expanding the input lines by the fac-
tor using sync interpolation (padding in Fourier space). Super-sam-
pling will reduce the rays along the projection angles that appear to
reflect from the edges of a Fourier transform of an X/Z slice. These
rays result from back-projecting into discrete pixels and represent
inappropriate information generated by the transitions between succes-
sive pixels along a backprojection ray. Super-sampling by 2 will
remove most of these rays, especially oblique ones. The additional
benefit (amount of change in the image) of going from 2 to 3 is about
10% as large as that of super-sampling by 2; it is about 3% going from
3 to 4 and 1.5% going from 4 to 8 (the highest allowed value). The
super-sampled slice is reduced to the original resolution by cropping
its Fourier transform. Super-sampling alone with the first method does
not reduce the rays in the corners of the Fourier transform past 0.5
cycle/pixel. These rays are also inappropriate since they originate
from lower-frequency information in the projection images, so they are
removed from the cropped Fourier transform before inverting it. This
removal has an added benefit about 1/3 as large as the benefit from
supersampling by 2. The effect of these removals is a subtle change in
the noise, and a benefit may show up only with subvolume averaging.
The additional effect of expanding the input lines is to avoid attenu-
ating frequencies past half Nyquist (0.25/pixel) any more than is
achieved with the falloff of the radial filter. This will be notice-
able in a tomogram and would be particularly helpful if setting the
radial filter cutoff higher than the default for subvolume averaging.
For both methods of supersampling, computation time with a CPU is
essentially proportional to the square of the super-sampling factor.
With a GPU, the overhead from steps besides backprojection makes the
increase in total time much less, so super-sampling by 3 may take about
3 times as long overall. The increase in memory requirements is modest
for the first method since only a single reconstructed slice needs to
be stored at the square of the normal size. However, expanding input
lines will increase the storage needed for all lines loaded into the
program by the given factor on both the CPU and the GPU; this may be
problematic in situations where a large number of input lines are
needed to reconstruct a slice.
Super-sampling can be used for back-projection with all kinds of align-
ment information, but it is not available when doing SIRT or reprojec-
tions from a tomogram.
OPTIONS
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-insensi-
tive and can be entered in upper, lower, or mixed case. While Tilt can
take such variants, options used in command files and scripts should
always have the case shown below, because various IMOD scripts recog-
nize only those forms. 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 (with-
out the -). Options can be abbreviated to unique letters (but must be
unique when all option names are converted to the same case); the cur-
rently valid abbreviations for short names are shown in parentheses.
General Reconstruction-Related File Options
These options specify input and output files for ordinary reconstruc-
tions.
-input (-inp) 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 (-o) 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.
-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.
-XTILTFILE File name
Use this entry to specify a file containing a list of tilts to
be applied around the X axis for the individual views. A global
tilt specified by the XAXISTILT entry, if any, will be sub-
tracted from these tilts. If this file contains all zeros, the
program runs the same as if the file was not entered.
-ZFACTORFILE File name
Use this entry to specify a file containing factors for adjust-
ing 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.
-LOCALFILE File name
File containing local tilt alignment information. See Tiltal-
ign(1) for a description of the format and contents of this
file.
-BoundaryInfoFile File name
File with information about boundary locations and files when
directly writing in parallel to a single output file.
-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 fac-
tors may be one per line or many per line. These weights are
ignored if the log is being taken of the data.
Geometry-Related Options
These options control the size, location, and angles of the recon-
struction.
-WIDTH Integer
The width of the output image; the default is the width of the
input image.
-SLICE Multiple integers
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,
must be positive, and defaults to 1 when omitted.
-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 pro-
gram 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.
-THICKNESS Integer
Thickness in Z of reconstructed volume, in pixels
-OFFSET Multiple floats
This entry can contain two numbers, DELANG and DELXX. An offset
of DELANG degrees will be applied to all tilt angles. DELANG
positive rotates reconstructed sections anticlockwise. A DELXX
entry indicates that the tilt axis would be offset in a stack of
full-sized projection images, cutting the X-axis at NX/2. +
DELXX instead of NX/2. 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. If the projec-
tion images are a non-centered subset with the tilt axis cen-
tered in them, then using this entry together with SUBSETSTART
and FULLIMAGE should produce a correct result.
-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.
-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)
-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).
-COMPFRACTION Floating point
If the compression measured by TILTALIGN occurred over only a
fraction of the distance between the fiducials, enter the frac-
tion 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)
-FULLIMAGE Two integers
Use this entry to specify the full size in X and Y of the origi-
nal 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.
-SUBSETSTART Two integers
If the aligned stack contains a subset of the area in the origi-
nal 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.
-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, THICK-
NESS, WIDTH, FULLIMAGESIZE, SLICE, and SUBSETSTART will be
scaled. These entries thus do not need to be changed when the
input binning is changed.
-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. With-
out 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.
Reconstruction Control Options
These options control various other aspects of the reconstruction
process.
-LOG Floating point
This entry allows one to generate a reconstruction using the
logarithm of the densities in the input file, with the entered
value added before taking the logarithm.
-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 determined by the
second value. The sigma (or standard deviation) of the Gaussian
is the second value times 0.707, unless the option -Falloff-
IsTrueSigma is entered, in which case the second value is used
directly as the sigma. If the cutoff is greater than 1 the dis-
tances are interpreted as pixels in Fourier space; otherwise
they are treated as frequencies in cycles/pixel, which range
from 0 to 0.5. Use a cutoff of 0.5 for no low-pass filtering.
-FalloffIsTrueSigma
Use the falloff value entered with the -RADIAL option directly
as the sigma of the Gaussian filter instead of using a sigma
that is 0.707 times the entered value. This option was added
for IMOD 4.8.58, when the incorrect scaling of the falloff value
was discovered in the code, so that newer command files could
show the true sigma value while older command files without the
option would still produce the same result.
-MultiplyByGaussian
Multiply the radial weighting function by the Gaussian specified
with the -RADIAL option instead of replacing the remainder of
the ramp filter with the Gaussian.
-HammingLikeFilter Floating point
Cutoff radius for multiplying by a Gaussian that falls to ~0.06
at the Nyquist frequency (0.5 cycles/pixel). This function is
very close to the Hamming window applied in the tomo3d program
from Agulleiro and Fernandez. The sigma value of the Gaussian
is 0.438 * (0.5 - cutoff). This option cannot be entered with
-RADIAL as it replaces the function specified by that entry.
-DENSWEIGHT Multiple floats
Use this entry to control the weighting of each view propor-
tional 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 num-
ber of weights to be applied in averaging the adjacent incre-
ments (the default is equal weighting).
-ExactFilterSize Integer
"Object size", in unbinned pixels, controlling the shape of the
"exact filter" functions of Harauz and van Heel, 1986. With
this option, these filters will be used in place of standard R-
weighting. Such filters start from a slighty higher point at
low frequencies and rise nearly linearly. Their shape is con-
trolled by a mostly arbitrary parameter referred to as the
"object size". For large enough sizes, the filters will rise
much more rapidly than R-weighted filters and reach a plateau at
some intermediate frequency. This effectively attenuates some
of the higher frequencies, relative to an R-weighted reconstruc-
tion. For low-contrast reconstructions, these filters will
increase low-frequency contrast, partly because of the higher
value at low frequency, but primarily because of the plateau
effect with large "object sizes". The program will output a
line indicating the mean frequency at which the plateau is
reached. Spatial frequencies above this point will not be
present at the right amplitude, on average, relative to the
lower frequencies. This feature arguably makes these filters
unsuitable for making a reconstruction to be used for subvolume
averaging. This entry is ignored if -FlatFilterFraction is
entered. The Gaussian filter specified with the options above
is applied at the high-frequency end of these filters.
-FakeSIRTiterations Integer
Modify the radial filter to produce a reconstruction equivalent
to the one produced by the given number of iterations of SIRT.
See description above. The Gaussian filter specified with the
options above is applied at the high-frequency end of the fil-
ter.
-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)
-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)
-COSINTERP Multiple integers
Interpolation order and sampling factor 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 back-
projection.
-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.
-SuperSampleFactor Integer
This entry makes the program compute the back projection in a
slice larger by the given factor in each dimension, by interpo-
lating the projection data at smaller intervals ("super-sam-
pling"). See description above.
-ExpandInputLines
Expand projection lines by Fourier padding (sync interpolation)
when super-sampling, which will preserve higher frequencies bet-
ter but increase memory needed. See description above.
-UseGPU Integer
Use the GPU (graphical processing unit) for computations if pos-
sible; enter 0 to use the best GPU on the system, or the number
of a specific GPU (numbered from 1). The GPU can be used for
all types of operations as long as there is sufficient memory.
-ActionIfGPUFails Two integers
The action to take when the GPU cannot be used after being
requested: 0 to take no action, 1 to issue a warning prefixed
with MESSAGE:, and 2 to exit with an error. Enter 2 numbers:
the first for the action when the GPU is requested by the UseGPU
option; the second for the action when the GPU is requested only
by the environment variable IMOD_USE_GPU, or by the variable
IMOD_USE_GPU2. The default is 0,0.
Output Control Options
These options control various aspects of the output from reconstruc-
tion.
-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.
-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.
-MASK Integer
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. The entered value
specifies the number of extra pixels to mask out in this way; a
negative value can be used to set the mask farther out. Inside
the masked area, densities are smoothly tapered from the value
of a pixel at the edge of the area down to the mean value at the
edge. This masking is needed to prevent artifacts from building
up at the edges of the slice during iterations with SIRT.
-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 and allows efficient computation of chunks
in parallel.
-PARALLEL
Output slices parallel to the plane of the zero tilt projection.
This option cannot be used with direct writing of data to a sin-
gle output file from parallelized Tilt runs. It inverts the
handedness of the reconstruction.
-RotateBy90
Output slices parallel to the plane of the zero tilt projection,
but in the proper order to avoid inverting handedness. This
option cannot be used with direct writing of data to a single
output file from parallelized Tilt runs.
-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 PERPENDICU-
LAR 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 -ori-
gin 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.
-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".
Options for Incremental Reconstruction
These options allow reconstructions from a subset of view to be added
to or subtracted from an existing reconstruction.
-BaseRecFile File name
Previous reconstruction file to add views to or subtract views
from. One use for this option is to compute a series of recon-
structions 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 (unless -1 is entered for Subtract-
FromBase). 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 sub-
tracted, then you should also use the MinMaxMean option to keep
fill values constant.
-BaseNumViews Integer
When adding or subtracting views from a base reconstruction,
this option must be entered with the number of views in the pre-
vious reconstruction. However, if the SubtractFromBase option
is entered with a -1 to indicate that a reconstruction is to be
subtracted from a base file for SIRT, this option should not be
entered.
-SubtractFromBase List of integer ranges
Views to subtract from the previous reconstruction specified by
BaseRecFile. Without this entry, all views are added. Enter
the list of specific views to subtract, 0 to have all included
views subtracted, or -1 to have all views subtracted for a SIRT
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.
Options for Reprojection
These options activate and control reprojection from a reconstruc-
tion.
-REPROJECT Multiple floats
With this entry, the program will output one or more reprojec-
tions of the reconstructed slices at the given angles. If Rec-
FileToReproject 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 pro-
duce. (Successive entries accumulate)
-ViewsToReproject List of integer ranges
List of views to reproject from a reconstruction file, numbered
from 1. 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.
-recfile (-r) OR -RecFileToReproject File name
Reconstruction file to reproject or run SIRT with. When using
this option, all of the entries to the program used when build-
ing this reconstruction should be included as well.
-xminmax (-x) 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.
-yminmax (-y) OR -YMinAndMaxReproj Two integers
Starting and ending Y index coordinates of region to reproject
from a reconstruction file (numbered from 0). Y is the thick-
ness dimension. The default is the whole extent in Y.
-zminmax (-z) 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.
-threshold (-th) OR -ThresholdedReproj Three floats
This option enables a rapid, discrete reprojection only of vox-
els in a volume that are beyond a threshold. The first two val-
ues are the threshold, and 1 to pick voxels above threshold or
-1 to pick ones below threshold. The third value controls how
the pixels being projected to are filled. With a value of 1 or
more, the program will form a sum in the reprojection. For each
voxel beyond threshold, a fixed value well be apportioned among
the 4 pixels projected to by the voxel by their respective
interpolation fractions and added into the pixels. A value less
than 1 is a criterion for binary marking of pixels; each of the
4 pixels with an interpolation fraction above the criterion is
marked with a fixed value, and the resulting reprojection will
have only two values in it.
SIRT-Related Options
These options activate, control, or are used in reconstructions with
SIRT.
-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 fil-
ter and a flat filter, which will greatly overemphasize low fre-
quencies. The entered value is the fraction for the flat fil-
ter. 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 compo-
nent at the lowest non-zero frequency. If the value is greater
than one, a filter suitable for Simultaneous Iterative Recon-
struction (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.
-SIRTIterations Integer
This entry directs the program to compute a SIRT reconstruction
internally for the given number of iterations, as described
above. If the RecFileToReproject option is given, then the pro-
gram will read in slices from the existing reconstruction,
interpolating between them to make vertical slices if there is a
fixed X-axis tilt. Each read-in slice or vertical slice is then
used for reprojection and modified by a backprojection of the
difference between the reprojection and the original projection
image. In this case, the FlatFilterFraction option is not
needed, as the appropriate filter is used automatically. If no
existing reconstruction is given, then the program generates an
initial reconstruction with a flat filter fraction of 1.0 unless
a value is supplied with the FlatFilterFraction option.
-SIRTSubtraction
Subtract reprojections from original projections to produce a
reprojection difference for SIRT. The width of the reprojection
must match the width of the input data.
-StartingIteration Integer
Starting SIRT iteration number, in order to obtain reports of
the mean and standard deviation of a difference reconstruction
in a SIRT procedure. These values are computed for slices in
the middle 80% of the slice range, in the middle 80% of the
width in X, and in the middle half of the height in Y. When
running SIRT internally, the statistics are computed as each
difference slice is computed. Otherwise, they are computed just
before subtracting the difference reconstruction from read-in
slices. A summary is printed when the program finishes.
-VertBoundaryFile File name
File with information about boundaries and temporary files when
writing a vertical slice output file and running multiple chunks
in parallel.
-VertSliceOutputFile File name
File for saving internally produced vertical slices at the last
iteration when running SIRT internally. When such a file is
saved, SIRT can be resumed with it and the vertical slices will
not be degraded by being interpolated on output and input.
-VertForSIRTInput
The file to be reprojected when resuming internal SIRT is a ver-
tical slice file, specified by VertSliceOutputFile on the previ-
ous run. When such a file is provided, the program will use its
slices directly instead of having to interpolate from the slices
of the reconstruction file.
-ConstrainSign Integer
Enter -1 or 1 to constrain the result to negative or positive
when subtracting a reconstruction from a base reconstruction, or
when subtracting an error reconstruction from the current slice
with SIRT internally.
Model Projection Options
These options are used when reprojecting a model from a reconstruc-
tion onto the input projections.
-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.
-SkipTurnedOffPoints
Skip points with contour values below threshold when projecting
the model if they are not visible in 3dmod, namely if "Turn off
below threshold" is set in the Bead Fixer, or "Turn off Low" is
set in the Values panel of the Model View Object Edit dialog.
-AngleOutputFile File name
Output file in which to write projection angles when reproject-
ing a model. The output contains one line per point in the pro-
jected model, with contour number, point number, view number
(all numbered from 1), X-axis tilt, tilt angle, and rotation in
the plane of the projection image, (all in degrees). At the end
of the line will be either a 0 or, if the -DefocusFile option is
entered, the defocus in nanometers. The rotation will be rela-
tive to the aligned projection image (and zero if there are no
local alignments) unless a file of alignment transforms is
entered with the AlignTransformFile option. In that case, the
rotation will be relative to the raw tilt series image. The
angles have the same meaning and order as in the Tiltalign
alignment model: the specimen is tilted around X, then tilted
around Y, then rotated around Z in order for its projection to
match the image in the aligned stack, where angles are counter-
clockwise positive looking down each axis from the positive
direction.
-AlignTransformFile File name
File of linear transformations used to align the projection
images. When making an output file with projection angles, this
file is needed to produce rotation angles relative to the
unaligned projection images.
-DefocusFile File name
File with defocus values in nanometers (underfocus positive) for
each view, one per line. When making an output file with pro-
jection angles, this entry allows the program to include the
defocus at each position as well.
-PixelForDefocus Two floats
Pixel size for computing defocus when making a file of projec-
tion angles, and 1 to invert tilt angles for this computation or
0 not to. The default is to use the pixel size of the input
projections and assume no inversion.
Obsolete, Test, and General Options
These miscellaneous options are obsolete, provide test output, or are
general PIP options.
-DONE The entry is equivalent to EndInput, and lines of input follow-
ing it will be ignored. This option is provided for compatibil-
ity with old command files, but Etomo does not handle it prop-
erly, so it should not be used.
-FBPINTERP Integer
This option was discontinued in IMOD 4.0.20
-REPLICATE Two floats
This option was discontinued in IMOD 4.0.21 (Successive entries
accumulate)
-debug (-d) OR -DebugOutput
Print output for debugging
-internal (-int) OR -InternalSIRTSlices Two integers
Output reprojections or reconstruction slices held internally on
the last iteration of SIRT. The first value is the type of
reprojection: 0 for none, 1 for actual reprojection, or 2 for
difference between reprojection and input data. The second
value is for type of slice: 0 for none, 1 for backprojection of
difference lines, 2 for final vertical slice, 3 for slice pro-
duced on iteration 0, and 4 for vertical slice decomposed from
input. Output files are sirttst.prj and sirttst.drec, respec-
tively.
-texture (-te) OR -TextureType Integer
Type of texture to use on GPU: 0 for 2D, -1 for 2D layered, 1
for 3D. The type of texture is chosen automatically depending
on the capability of the graphics card and what texture types
are available for a particular type of alignment. In making
this choice, 3D textures are preferred if the data sizes allow
it; otherwise 2D layered, otherwise 2D. This entry overrides
that choice, except in the case of single slice computations
with no X-axis tilt in the back- or reprojection and no Z-fac-
tors or local alignments, where 2D textures are used. All three
types are available for back-projection with local alignments or
reprojections involving multiple slices; 3D textures are not
available for back-projections with X axis tilt and/or Z factors
but no local alignments. The program will exit with an error if
a non-available type is specified by this entry; but if a type
is chosen that does not fit within the card's texture size lim-
its, the program will just not use the GPU.
-param (-p) OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter
file.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
HISTORY
The program was originally written by Mike Lawrence and has been modified
vastly and repeatedly by David Mastronarde.
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 4.11.0 tilt(1)