warpvol(1)                  General Commands Manual                 warpvol(1)



NAME
       warpvol - to warp one volume into alignment with another

SYNOPSIS
       warpvol  [options]  input_file  output_file

DESCRIPTION
       Warpvol will transform a volume using a series of general linear trans-
       formations. 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 tomo-
       grams into alignment so that theycan be stitched together.  For each
       position in the volume, it interpolates between adjacent transforma-
       tions to find the transformation appropriate for that position.  Any
       initial alignment transformation (from Solvematch) must be already con-
       tained 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.

OPTIONS
       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 fol-
       lowing options can be specified either as command line arguments (with
       the -) or one per line in a command file or parameter file (without the
       -).  Options can be abbreviated to unique letters; the currently valid
       abbreviations for short names are shown in parentheses.

       -input (-i) OR -InputFile      File name
              Input image file to warp

       -output (-ou) OR -OutputFile   File name
              Output file for warped volume

       -xforms (-x) OR -TransformFile      File name
              File with matrix of inverse transforms produced by Findwarp

       -scale (-sc) 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 (-t) 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 (-si) OR -OutputSizeXYZ       Three integers
              X, Y, Z dimensions of the output file (Default is Z, Y, X size
              of input file)

       -same (-sa) 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) OR -InterpolationOrder      Integer
              Order of interpolation to use.  Currently only quadratic (2) and
              linear (1) interpolation are available; the default is quadrat-
              ic.

       -chunk (-c) OR -ChunkSizesForHDF    Three integers
              Size of chunks in X, Y, and Z for output to an HDF file orga-
              nized in chunks.  Storing data this way will prevent the need to
              output cubes of transformed data to scratch files and read them
              back in to make the final output, when the volume is too large
              to fit in the allowed memory.  Enter 0,0,0 for the default size,
              which is for chunks the same size as the cubes that would ordi-
              narily be written to scratch files, and for no chunks at all if
              data are being handled in one cube per layer.  If a specific
              size is entered for one or more axes, then the program will
              first determine the division into cubes, and then make the chunk
              size be the minimum of the cube size and the specified value for
              each axis.  When using chunks, the memory is limited to 15000
              megabytes even if a larger value is entered.

       -memory (-m) OR -MemoryLimit   Integer
              Amount of memory to allocate for the major arrays needed by the
              program, in megabytes.  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 transforma-
              tions rotate the data by 90 degrees.  The default is the minimum
              of system memory minus 1 GB, 60% of system memory, and 12 GB for
              system memory up to 30 GB, and 40% of system memory above 30 GB,
              but at least 768 MB.

       -verbose (-v) OR -VerboseOutput     Integer
              1 for diagnostic output; 2 for output as each slice is loaded

       -patch (-pat) OR -PatchOutputFile   File name
              Output text file for vectors representing the displacement pro-
              duced 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 (-f) OR -FilledInOutputFile      File name
              Output file for warping transforms after filling in empty posi-
              tions.  The program will exit without making an output image
              file if this option is given.

       -param (-par) 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.

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

   Additional Notes
       Format of Warping File: The warping file can have three forms, deter-
       mined 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 posi-
       tions 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 posi-
       tions, 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.

       Missing Transforms: If there are missing transforms, the array will be
       filled in at each empty spot by taking a weighted average of the near-
       est 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 propor-
       tional 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

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                4.11.0                          warpvol(1)