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.
       Specifically, the X and Z origins are derived from the X and Y origins
       of the aligned stack, respectively, adjusting for whatever subarea is
       reconstructed in those dimensions.  The Y origin is set to give a 0
       coordinate at the middle of a volume that is not shifted in Y, so that
       the coordinate system will be congruent in the depth dimension for
       reconstructions of different thicknesses or different Y shifts.  All of
       this is set up so that IMOD models will load properly on different
       reconstructions from the same tilt images with the same alignment.

       The perpendicular slice output represents a 90 degree rotation about X
       but no change in handedness.  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 negative 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)

       -XSubsetLoadRatio    Floating point
              This entry enables the loading of a subset of each line in X by
              specifying the ratio of the length being loaded to the length
              actually needed for reconstructing a subset in X.  Since the
              same range in X will be loaded for all views, it will usually be
              much longer than is required for a given view, so not much addi-
              tional padding is required to avoid edge effects.  A value of
              1.2 should be sufficient.  When raw projections are being used
              and they are rotated by 90 degrees from the aligned ones, the
              subset is in Y in the raw stack and this option will prevent the
              need to access all lines of the input file to make the recon-
              struction.

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

       -ExpandedByFactor    Floating point
              Value of ExpandByFactor used in Newstack when making aligned
              stack.  Values entered with SHIFT, OFFSET, THICKNESS, WIDTH,
              FULLIMAGESIZE, SLICE, and SUBSETSTART will be scaled just as
              when the aligned stack is binned.  However, if Tilt is being run
              in parallel, the entries for SLICE and TOTALSLICES are assumed
              to be corrected already by this factor; Splittilt does this
              correction.  This feature is intended to be used with factors
              relatively near 1, such as to make a tomogram whose pixel size
              matches that of another with no additional interpolation steps.
              This option cannot be used with -RecFileToReproject or -UseU-
              nalignedImages.

       -ReferenceSDofScaling     Floating point
              Standard deviation of the unbinned input images, which will be
              used to adjust scaling when not taking the logarithm of the
              input.  When this option is entered, scaling is linear, and bin-
              ning of input images is greater than 1, the program will find
              the SD in a region up to 1K by 1K in the center of the middle
              input image, and change the scaling to adjust for the change in
              SD caused by binning.

       -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
              and/or modified with ExpandByFactor.

   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.

       -FiltersInFile       File name
              Image file with radial filter values to be used in place of the
              standard ramp function.  The file should have dimensions in Y
              and Z of 1 and the number of views being included in the recon-
              struction (i.e, omitting excluded views). The size in X needs to
              be an integer multiple of half the padded size used in the pro-
              gram for radial filtering, or such a multiple plus 1. The pro-
              gram's error message when this requirement is not met will show
              the needed size.  This padded size can be determined
                 pad  IS  min(50, 2 * max(8, nxProj / 20))
                 evenSize  IS   2 * ((nxProj + pad) / 2)
                 padSize  IS  output from running "goodframe -n evenSize"
              Filters will be scaled to match the standard ramp in magnitude.
              If a Gaussian cutoff is specified, the filter will fall from its
              value at this point, as usual.  This option cannot be entered
              with -FakeSIRTiterations, -ExactFilterSize, -HammingLikeFilter,
              -MultiplyByGaussian, -FlatFilterFraction, or -RecFileToRepro-
              ject.

       -ray (-ra) OR -UseRayIntersections
              Use areas of intersection between projection rays and recon-
              struction pixels instead of interpolation when computing back-
              projection and reprojection from a reconstruction file.  Each
              ray has the width of one pixel and is aligned to pixel in the
              projection images.  This option cannot be used with X-axis tilt,
              Z-factors, local alignments, cosine stretching (-COSINTERP must
              be 0), or a GPU.  This method was implemented for experimenting
              with SIRT and is much slower than regular interpolation.

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

       -UseUnalignedImages
              Use the raw stack instead of an aligned stack to make a recon-
              struction.  The transforms for making an aligned stack must be
              entered with the -AlignTransformFile option.  These transforms
              are stored and used as local alignment information and they are
              combined with local alignments if they are also being used.
              Super-sampling can be used in the back projection, but not
              expansion of input lines (expansion would avoid only half of the
              loss from interpolation because there is inevitably some inter-
              polation between lines ).  SIRT reconstructions and reprojection
              from a reconstruction file cannot be used with this option.  The
              program may take significantly more memory and operate somewhat
              slower with this option.  Depending on the angle of the tilt
              axis, large amounts of input data may be needed to reconstruct a
              single slice.. Also, radial filtering needs to be done in two
              dimensions instead of one and the area filtered has to have a
              minimum aspect ratio to avoid low frequency artifacts; this
              operation is more efficient with more data lines instead of pad-
              ding in that area.

       -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 floating point by default.  Modes are 0 for byte,
              1 for 16-bit signed integer, 6 for 16-bit unsigned integer, 2
              for 32-bit floating point, or 12 for 16-bit floating point.  The
              default mode of floating point output for MRC files is governed
              by the value of environment variable IMOD_WRITE_FLOATS_16BIT.
              Mode 12 is allowed only if the output format is MRC.  For modes
              other than 2, be sure to use an appropriate SCALE entry so that
              data will be scaled to the proper range.  The range for mode 12
              is -65504 to 65504; values are stored with 11-bit precision down
              to 6.1e-5 and 10-bit precision down to 6.0e-8.

       -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 (-re) 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.  The file also needed to make a
              reconstruction from raw stack 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.

       -border (-b) OR -BorderForSuperSample    Floating point
              Border size to compute on each edge of slice when super-sam-
              pling, in final pixels, i.e. not scaled by the super-sampling
              factor.  This border is needed so that the worst oscillations
              that occur at the edges of the image after Fourier reduction are
              removed when the slice is cropped to its final size.  The
              default is 40, which reduces the oscillations to about 0.1% of
              the SD with high-contrast reconstructions.

       -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                                 5.0.1                             tilt(1)