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 5.0.2 rotatevol(1)