rotatevol(1)                General Commands Manual               rotatevol(1)



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

SYNOPSIS
       rotatevol  [options]  input_file  output_file

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 speci-
       fied by tilt angles for three successive rotations about the the 3
       axes, with rotation first around Z, then around Y, then around X.  Pos-
       itive 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.

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

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

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

       -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 -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 (-a) 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.

       -back (-b) OR -BackRotate
              Back-transform the volume by using the inverse of the transfor-
              mation specified by the entered angles.

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

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

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

       -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 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 sec-
       tion 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

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                4.12.61                       rotatevol(1)