Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

ROTATEVOL(1)							ROTATEVOL(1)

NAME
  rotatevol - to rotate 3-dimensional data to arbitrary angles

SYNOPSIS
  rotatevol

DESCRIPTION
  This program will rotate all or part of a three-dimension volume
  of data.  The rotations may be by any angles about the three axes.
  Tilt angles and origin information in the header are properly
  maintained so that the new data stack will have a coordinate system
  congruent with the old one.
  
  Before running the program, examine the data set to determine
  what rotations you desire.  The overall rotation of the data set is
  specified by tilt angles for three successive rotations about the
  the 3 axes, with rotation first around Z, then around Y, then around
  X.  Positive angles give counterclockwise rotations (looking down
  an axis toward the origin).  This is the same way that angles are
  specified and acted on in the Slicer window of 3dmod, so you can use
  the Slicer to determine your desired angles, as long as the data volume
  is not being viewed with Y and Z flipped.  If you only want part of the
  data set, determine the center of the region that you want to extract.
  This region is specified by the index coordinates of that point in the
  input file.

  Rotatevol 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 rotate

 -output OR -OutputFile   File name
    Output file for rotated volume

 -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 size of input file)

 -center OR -RotationCenterXYZ   Three floats
    X, Y, Z index coordinates of the center of the region to be rotated
    (Default is center of input file).  This location will be placed in the
    center of the output volume.  Coordinates are numbered from zero.

 -angles OR -RotationAnglesZYX   Three floats
    Angles to rotate about Z, Y, and X axes.  Rotations will be applied in
    that order; first around Z, then Y, then X.

 -order OR -InterpolationOrder   Integer
    Order of interpolation to use.  Currently only quadratic (2) and linear
    (1) interpolation are available; the default is quadratic.

 -query OR -QuerySizeNeeded
    With this entry, the program will compute the size of the output volume
    needed to contain the whole original volume after rotation.  It will just
    print the sizes in X, Y, and Z then exit.

 -fill OR -FillValue   Floating point
    Value to fill regions without image data (default is file mean)

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

 -verbose OR -VerboseOutput   Integer
    1 for diagnostic output

 -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 with data to be rotated

  Name of the output file for rotated data

  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
  
  Index coordinates of the center of the region to be rotated in the
  .  input file, or / to use the coordinates of the center of the file
  
  Rotations around the Z, Y, and X axes
  
  The program can work on an arbitrarily large volume.  It reconstructs a
  series of rectangular sub-regions of the output volume.  For each region, it
  reads into memory a rectangular region from the input volume that contains
  all of the image area that rotates into that region of output volume.  It
  then uses linear or triquadratic interpolation to find each pixel of the
  output subvolume, and writes the subvolume to a scratch file if necessary.
  When all of the regions in one layer are done, it reads back data from the
  scratch files and assembles each section in that layer.
 	  
HISTORY
  Written by David Mastronarde 7/25/91
  Converted to PIP/autodoc 10/10/03
  Converted to Fortran 95, parallelized with OpenMP, 6/14/09