Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells WARPVOL(1) WARPVOL(1) NAME warpvol - to warp one volume into alignment with another SYNOPSIS warpvol DESCRIPTION Warpvol will transform a volume using a series of general linear transformations. Its original use was to "warp" one tomogram from a two-axis tilt series so that it matches the other tomogram, but it is also used for volume flattening and for transforming adjacent, overlapping tomograms into alignment so that theycan be stitched together. For each position in the volume, it interpolates between adjacent transformations to find the transformation appropriate for that position. Any initial alignment transformation (from Solvematch) must be already contained in the transformations entered into this program; this combining of transformations is accomplished by Findwarp. It can work with either a 2-D matrix of transformations (varying in X and Z) or with a general 3-D matrix, as output by Findwarp. The program uses the same algorithm as Rotatevol for rotating large volumes. Warpvol uses the PIP package for input (see the manual page for pip) and can take input interactively for options that existed when it was converted, to maintain compatibility with old command files. 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 -InputFile File name Input image file to warp -output OR -OutputFile File name Output file for warped volume -xforms OR -TransformFile File name File with matrix of inverse transforms produced by Findwarp -scale OR -ScaleTransforms Floating point Factor by which to scale transforms, to account for the input image file having a different binning or scaling than the file on which transforms were derived. For example, if transforms were found on files binned by 2, enter 2 to apply the transforms to an unbinned file. -tempdir OR -TemporaryDirectory Text string Directory to use for temporary files. The default is that the temporary files will be placed in the current directory. -size OR -OutputSizeXYZ Three integers X, Y, Z dimensions of the output file (Default is Z, Y, X size of input file) -same OR -SameSizeAsInput Make default size of output file be same size as input file. One or more of the dimensions can be overridden by a value in a -size entry. -order OR -InterpolationOrder Integer Order of interpolation to use. Currently only quadratic (2) and linear (1) interpolation are available; the default is quadratic. -memory OR -MemoryLimit Integer Amount of memory to allocate for the major arrays needed by the program. This always includes memory for input images and may include memory for a plane of transformations or for a stack of output slices, depending on whether transformations rotate the data by 90 degrees. -verbose OR -VerboseOutput Integer 1 for diagnostic output; 2 for output as each slice is loaded -patch OR -PatchOutputFile File name Output text file for vectors representing the displacement produced by each transform. It can be converted to a model with patch2imod. The program will exit without making an output file if this option is given. -filled OR -FilledInOutputFile File name Output file for warping transforms after filling in empty positions. The program will exit without making an output image file if this option is given. -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. If the program is started with no command line arguments, it reverts to interactive input with the following entries: Name of the input file to be transformed Name of the output file for the transformed volume Path name of directory (for example, /usr/tmp) where temporary files can be placed, or Return to have files placed in the current directory X, Y, and Z dimensions of the output file, or / to accept the default values, which are NZ, NY, and NX of the input volume (a 90-degree rotation about the Y axis) Name of the file with the matrix of inverse transformations (produced by Findwarp) Format of Warping File The warping file can have three forms, determined by the number of entries on the first line of the file. If there are two entries on this line, they specify the number of positions in X and in Z. If there are three entries, they specify the number of positions in X, Y, and Z. In either of these two cases, there must be a transform in the file for every such location in the 2D or 3D array of positions. In the third form, not all transforms need to be present, and the header line contains 9 entries indicating the number of positions, the starting position, and the interval between positions in each dimension: #_in_X #_in_Y #_in_Z start_X start_Y start_Z delta_X delta_Y delta_Z For each position, there are four lines: centered_X centered_Y centered_Z a11 a12 a13 dx a21 a22 a23 dy a31 a32 a33 dz where the coordinates are relative to the center of the volume, and the next three lines specify an inverse transformation for getting from a location in the output volume to a location in the input volume: xi = a11 * xo + a12 * yo + a13 * zo + dx yi = a21 * xo + a22 * yo + a23 * zo + dy zi = a31 * xo + a32 * yo + a33 * zo + dz where (xo, yo, zo) are coordinates relative to the center of the output volume, and (xi, yi, xi) are coordinates relative to the center of the input volume. The center coordinates of the transforms are used to assign them to the regular array of positions, so transforms that are not located at these regular positions will be relocated and will not perform as expected. If there are missing transforms, the array will be filled in at each empty spot by taking a weighted average of the nearest defined transforms. Once the nearest existing transform is found to a particular spot, transforms are included from positions up to twice as far away as the nearest one, and their weights are proportional to the square of their distances from the position being filled in. The same approach is used to extend the transform array to cover all positions in the output volume being computed. HISTORY Written by David Mastronarde 11/15/96; modified for 3-D matrix of transformations, 7/23/97 Converted to PIP/autodoc 10/10/03 Changed the way transforms are filled in and extrapolated, 6/7/09 Converted to Fortran 95, parallelized with OpenMP, 6/14/09