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