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, or 2 for 32-bit
              floating point.  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.

       -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

       -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                                4.10.10                         trimvol(1)