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)