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
  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 backprojection 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 "XTILTINTERP 0" is entered, or in the unlikely event
  that 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.

  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 handedness.  With
  parallel slice output, the handedness is inverted.

  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.

  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.  Typically
  this will be CUDA 2.1, supported by drivers 180.22 and higher in Linux, or
  181.20 and higher in Windows.  Not all IMOD packages can be used with a GPU;
  ones that do will have cudart and cufft libraries in either IMOD/bin,
  IMOD/lib or IMOD/qtlib.

  The program can compute multiple iterations of the Simultaneous Iterative
  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 available when the
  reconstruction involves the Z factors produced when solving 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 computed with no or reduced R-weighting, or
  read in from prevous iterations.  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.  Further
  details are given under the SIRTIterations 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-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 or run SIRT with.  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 (unless -1 is entered for
    SubtractFromBase).  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.

 -ActionIfGPUFails   Two integers
    The action to take when the GPU cannot be used after being requested: 0 to
    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.

 -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
    When adding or subtracting views from a base reconstruction, this option
    must be entered with the number of views in the previous 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.

 -BoundaryInfoFile   File name
    File with information about boundary locations and files when directly
    writing in parallel to a single output file.

 -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)

 -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.

 -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 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, but eTomo does not handle it properly, so it should not be used.

 -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
    This option was discontinued in IMOD 4.0.20

 -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)

 -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 entered value added before
    taking the logarithm.

 -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.

 -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 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 projection images
    are a non-centered subset with the tilt axis centered in them, then using
    this entry together with SUBSETSTART and FULLIMAGE should produce a
    correct result.

 -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
    This option was discontinued in IMOD 4.0.21
    (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.

 -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 program 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.

 -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, must be positive, and defaults to 1 when
    omitted.

 -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.

 -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.

 -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.

 -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.

 -UseGPU   Integer
    Use the GPU (graphical processing unit) for computations if possible;
    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.

 -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.

 -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 vertical slice
    file, specified by VertSliceOutputFile on the previous 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.

 -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 to be applied
    around the X axis for the individual views.  A global tilt specified by
    the XAXISTILT entry, if any, will be subtracted from 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.

 -debug OR -DebugOutput
    Print output for debugging

 -internal 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 produced on iteration 0, and 4 for vertical slice decomposed from
    input.  Output files are sirttst.prj and sirttst.drec, respectively.

 -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

  The program was originally written by Mike Lawrence and has been modified
  vastly and repeatedly by David Mastronarde.