trimvol(1)                                                          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 a command-line interface to the programs Findcon-
       trast(1) and Newstack, for copying a selected portion of an MRC
       image volume into a new file, with automatic scaling to bytes.  There
       are options for specifying the volume to be extracted, and for control-
       ling the scaling to bytes.  There is also an option to scale floating
       point numbers to integers.  By default, coordinates are numbered from
       1.

       If you use the -sz option, then Findcontrast will be run on the
       specified sections.  By default, regions within 10% of the lateral bor-
       ders of each section are omitted, but a different region can be set
       with -sx and -sy.  A scaling is chosen which saturates the intensities
       of one pixel per slice, on average, at the dark and the light end.  If
       you use -sz The coordinates specified with these options 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, -sz or -mm.  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, determining the optimal scaling to bytes 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.

       -sx OR -XFindStartAndEnd       Two integers
              Analyze the region between this starting and ending coordinate
              in X to determine the scaling to bytes.  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 to bytes.  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.

       -mm (-m) OR -IntegerMinMax     Two integers
              Scale to integers (mode 1), so that the current minimum and max-
              imum of the file would be scaled to the given values of minimum
              and maximum.  Newstack is run with the -scale option and the
              entered values.  This option would be used to scale from mode 2
              (floating point) to mode 1.

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

       -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

       -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



BL3DEMC                              4.7.3                          trimvol(1)