trimvol(1) General Commands Manual trimvol(1)
NAME
trimvol - Trim a volume and optionally rotate or scale to bytes or
integers
SYNOPSIS
trimvol [options] input_file output_file
DESCRIPTION
Trimvol provides an interface to the program Newstack for trimming
out, scaling, and rotating a selected portion of an MRC image volume.
There are options for specifying the volume to be extracted, and for
controlling the scaling. By default, coordinates are numbered from 1.
Scaling can be specified in several different ways. The -c option
specifies a scaling to bytes given black and white contrast settings
from 3dmod. The -mm option will scale the minimum and maximum of
the file to the specified values, converting to integers by default or
to a data mode entered with -mode. Other scaling involves analyzing a
region of the volume in one of two ways. One way is to run Findcon-
trast(1), which chooses a scaling that saturates the intensities of one
pixel per slice, on average, at the dark and the light end. The other
way is to run Densmatch to find the scaling to a specified mean and
standard deviation. The latter method is invoked by the -meansd option
and can be used to scale to bytes or to a specified mode. If -meansd
is not entered, scaling with Findcontrast is invoked by entering the
-sz option, and scaling must be to bytes.
When computing a scaling, by default, regions within 10% of the lateral
borders of each section are omitted, but a different region can be set
with -sx and -sy. The coordinates specified with these options and -sz
will be treated as coming from a flipped volume only if the -f option
is entered.
By default, the origin of the output file will be adjusted so that a
model built on the input volume will display correctly on the output
file. This will even work for a volume rotated with -rx but not for
one flipped with -yz. This adjustment can be turned off with the -k
option.
OPTIONS
You can enter only one of -c, -mm, or a combination of -sz and -meansd.
Similarly, you cannot enter both -x and -nx, both -y and -ny, or both
-z and -nz. You can also enter only one of -yz and -rx.
It is possible to enter limits for -x, -y, or -z that are outside the
range of the volumes, provided that the specified volume includes some
pixels within range for in each dimension. Regions in X and Y out of
range will be filled with the mean value, and blank slices will be put
for Z values out of range.
Trimvol uses the PIP package for input (see the manual page for
pip). Options can be specified either as command line arguments
(with the -) or one per line in a command file (without the -).
Options can be abbreviated to unique letters; the currently valid
abbreviations for short names are shown in parentheses.
-x OR -XStartAndEnd Two integers
Starting and ending X coordinate of region to cut out
-y OR -YStartAndEnd Two integers
Starting and ending Y coordinate of region to cut out
-z OR -ZStartAndEnd Two integers
Starting and ending Z coordinate of region to cut out
-nx OR -XSize Integer
Number of pixels to cut out in X, centered on the middle in X
-ny OR -YSize Integer
Number of pixels to cut out in Y, centered on the middle in Y
-nz OR -ZSize Integer
Number of slices to cut out in Z, centered on the middle in Z
-sz OR -ZFindStartAndEnd Two integers
Scale to bytes, or to another mode specified by -mode, by ana-
lyzing intensities from sections between the two given numbers,
inclusive. Coordinates are treated as coming from a flipped
volume only if the "-f" option is given. Slices are numbered
from 1 regardless of whether the "-i" option is used. If the
-meansd option is entered, scaling will be found by running
Densmatch and can be to any mode; if -meansd is not entered,
scaling will be determined by running Findcontrast and must
be to bytes.
-sx OR -XFindStartAndEnd Two integers
Analyze the region between this starting and ending coordinate
in X to determine the scaling invoked by either --sz or -meansd.
The default is to use 80% of the range in X.
-sy OR -YFindStartAndEnd Two integers
Analyze the region between this starting and ending coordinate
in Y to determine the scaling invoked by either --sz or -meansd.
The default is to use 80% of the range in Y.
-c OR -ContrastBlackWhite Two integers
Scale to bytes, with relative intensities between the two
entered numbers (representing black and white values on a scale
of 0 to 255) stretched to occupy the full range of byte values.
-meansd (-me) OR -ScaleToMeanAndSD Two floats
Scale the image intensities to the given mean and standard devi-
ation, then convert values to bytes (mode 0) unless the -modeop-
tion is entered with a different mode.
-mm OR -IntegerMinMax Two floats
Scale image intensities so that the minimum and maximum of the
file become the given values of minimum and maximum, then con-
vert values to integers (mode 1) unless the -modeoption is
entered with a different mode. Newstack is run with the
-scale option and the entered values. This option has this name
because it was originally used only to scale to integers.
-mode (-mo) OR -ModeToOutput Integer
The storage mode of the output file; 0 for byte, 1 for 16-bit
signed integer, 6 for 16-bit unsigned integer, 2 for 32-bit
floating point, or 12 for 16-bit floats. This option can be used
to modify the output mode for the -mm and -meansd options or
when not applying any scaling at all, but cannot be used with
the scaling to bytes invoked by the -sz or -c options. Mode 12
is allowed only if the output format is MRC.
-rx (-r) OR -RotateX
Rotate the output volume by -90 degrees around the X axis, by
first creating a temporary trimmed volume with newstack then
running "clip rotx" on this volume to create the final output
file. The slices will look the same as with the "-yz" option
but rotating instead of flipping will preserve the handedness of
structures.
-yz OR -FlipYZ
Flip Y and Z in the output volume by first creating a temporary
trimmed volume with newstack then running "clip flipyz" on this
volume to create the final output file. Do not use this option
unless you intend to invert handedness.
-format (-fo) OR -FormatOfOutputFile Text string
Set output file format to MRC, TIFF, or HDF by entering MRC,
TIF, TIFF, HDF, or any lower case form of these. This entry
overrides a default format set with the environment variable
IMOD_OUTPUT_FORMAT.
-i OR -IndexCoordinates
Interpret "-x", "-y", "-z", "-sx", and "-sy" entries as index
coordinates numbered from 0, rather than as 3dmod coordinates
numbered from 1.
-f OR -FlippedCoordinates
Interpret "-y", "-z", "-ny", "-nz", "-sy", and "-sz" entries as
referring to a volume viewed in flipped orientation in 3dmod,
with Y and Z sizes swapped. This option allows you to enter the
coordinates as they appear in 3dmod when the volume is loaded
with flipping (the -Y option). The program assumes that flip-
ping occurred by rotating around the X axis, unless the "-old"
option is given.
-old (-o) OR -OldFlippedCoordinates Integer
This option indicates that Z coordinates were obtained by load-
ing the volume with the -Y option into a version of 3dmod prior
to 4.6.18, where flipping was done by exchanging the Y and Y
axes instead of rotating around X. Enter the sum of 1 if the
"-z" entry is based on such flipping and 2 if the "-sz" entry is
based on such flipping.
-k OR -KeepOrigin
Keep the origin the same in the output from Newstack instead
of passing it the -origin option to adjust the origin for the
location of the subvolume being created. This option can be
used to reproduce a volume created with earlier versions of
IMOD.
-PID Print process ID
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input
FILES
If the output file already exists a backup image of the original is
created with the ~ extension. The temporary file needed when flipping
or rotating is created in the current directory with ".tmp.nnn" added
to the input filename, where "nnn" is the process ID.
AUTHOR
David Mastronarde <mast at colorado dot edu>
SEE ALSO
newstack, findcontrast
IMOD 5.0.2 trimvol(1)