matchvol(1)                 General Commands Manual                matchvol(1)



NAME
       matchvol - transform a volume to match another with a general linear
                      transformation

SYNOPSIS
       matchvol  [options  input_file  output_file

DESCRIPTION
       Matchvol will transform a volume using a general linear transformation.
       Its main use is to transform one tomogram from a two-axis tilt series
       so that it matches the other tomogram.  To do so, it can combine an
       initial alignment transformation and any number of successive refining
       transformations.  The program uses the same algorithm as Rotatevol for
       rotating large volumes.

       The format of the 3D transform when stored in a file is to consist of 3
       lines:
           a11  a12  a13  dx
           a21  a22  a23  dy
           a31  a32  a33  dz
       which specify a transformation for getting from a location in the input
       volume to a location in the output volume:
           xo = a11 * xi + a12 * yi + a13 * zi + dx
           yo = a21 * xi + a22 * yi + a23 * zi + dy
           zo = a31 * xi + a32 * yi + a33 * zi + 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.

OPTIONS
       Matchvol 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 (with-
       out the -).  Options can be abbreviated to unique letters; the cur-
       rently valid abbreviations for short names are shown in parentheses.

       -input (-inp) OR -InputFile    File name
              Input image file to transform

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

       -inverse (-inv) OR -InverseFile     File name
              Output file in which to write the inverse of the combined trans-
              formation.  This output is optional.

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

       -center (-ce) OR -CenterXYZ    Three floats
              X, Y, Z index coordinates of the center of the region to trans-
              form (Default is center of input file).  Coordinates are num-
              bered from zero.

       -xffile (-x) OR -TransformFile      File name
              Name of file with 3D transform to apply.  Multiple transforms
              are applied in the order that they are entered, and before any
              3DTransform entries.  (Successive entries accumulate)

       -3dxform (-3) OR -3DTransform       Multiple floats
              A 3D transform to apply, consisting of 12 values on one line
              (a11, a12, a13, dx, a21, a22, a23, dy, a31, a32, a33, dz).  Mul-
              tiple transforms are applied in the order that they are entered,
              and after any TransformFile entries.  (Successive entries accu-
              mulate)

       -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 (-ch) 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 stack of output slices,
              depending on the orientation of the output.  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

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

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

       Number of successive transformations to combine and apply

       For each transformation, either enter the name of a file with
          the transformation, or enter a Return, then enter the 12-element
          transformation directly.  Transform files need not all occur before
          direct entries.

       Name of a file in which to place the inverse of the combined
          transformation, or Return for no such output

HISTORY
       Written by David Mastronarde, 1995
       Converted to PIP/autodoc 10/10/03
       Converted to Fortran 95, parallelized with OpenMP, 6/14/09

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                4.11.0                         matchvol(1)