boxstartend(1)              General Commands Manual             boxstartend(1)



NAME
       boxstartend - to clip out portions of a volume around contour points

SYNOPSIS
       boxstartend  [options]  input_image  input_model  [output_file]

DESCRIPTION
       Boxstartend will extract subvolumes centered on the starting or ending
       points of model contours, or on all points in a model contour.  It can
       place each volume into a separate file, or stack all the extracted vol-
       umes into a single output file.  In the latter case, the program can
       generate two lists of piece coordinates to allow the volumes to be
       examined in two different ways in 3dmod.  One list will assemble all
       of the volumes into a single square array, with the extracted starting
       or ending points all appearing on the same section.  The other list
       will display each piece in its true position in the original volume of
       images.

       When all subvolumes are stacked into a single file, an average will
       also be accumulated and saved in the file after the last extracted sub-
       volume.  This average will show up as the rightmost item in the top row
       when viewing the square array in 3dmod.  If there is insufficient
       memory, the average will not be computed.

       The coordinates in the model are scaled to fit the current volume.
       This means that you can model points in a binned-down volume and use
       that model directly to extract boxes from the full-sized volume.  You
       can also model points on a volume loaded into 3dmod with flipping.
       However, all of the entries to the program referring to X, Y, and Z or
       slices must correspond to the actual X, Y, and Z coordinates in the
       unflipped volume, not to the coordinates as visualized in 3dmod.

       When each volume is placed in a separate file, the origin of each out-
       put file is adjusted for its position in the input volume, so that a
       model built on an extracted file should display at the correct position
       in the full volume, and vice versa.

       Image data is simply extracted, not interpolated to be exactly centered
       on the modeled point.  If the box size is even in a given dimension,
       then the extracted image would need to be shifted by round(C) - C to be
       centered in that dimension, where C is the coordinate in that dimension
       and "round" means rounding to the nearest integer.  If the box size is
       odd, the needed shift is round(C + 0.5) - (C + 0.5).

       By default, points will be used from all open and scattered point
       objects in the model, but closed contour objects will be skipped.  Use
       the -objects option to specify which objects to use or to include
       closed contour objects.

       Blank images are put out for points far enough outside the image area;
       no points are skipped.

OPTIONS
       Boxstartend uses the PIP package for input (see the manual page for
       pip) and can also still take input interactively.  The following
       options can be specified either as command line arguments (with the -)
       or one per line in a command file or parameter file (without the -).
       Options can be abbreviated to unique letters; the currently valid
       abbreviations for short names are shown in parentheses.

       -image (-i) OR -InputImageFile      File name
              Input file with volume to be extracted from.  If this option is
              not entered, the first non-option argument will be used for this
              input file.

       -model (-m) OR -ModelFile      File name
              Name of model file with points to be extracted.  If this option
              is not entered, the second non-option argument will be used for
              this input file.

       -output (-ou) OR -OutputFile   File name
              Output file for single stack of all extracted subvolumes.  If
              this option is not entered, the third non-option argument will
              be used for this output file.  Either an output file or a root
              name for a series of files must be entered.

       -series (-se) OR -SeriesRootName    Text string
              Root name to use for series of numbered files, one per point
              being extracted.  A dot and the number will be appended to the
              root name for each file.  The number of digits used for the num-
              ber will be the same for all files so that they will list in
              order.

       -piece (-pi) OR -PieceListFile      File name
              Name of input piece list file if image is montaged or out of
              sequence

       -array (-a) OR -ArrayPieceList      File name
              Name of piece list file for viewing extracted volumes in an
              array

       -true (-tr) OR -TruePieceList       File name
              Name of piece list file for viewing subvolumes in original posi-
              tions

       -objects (-ob) OR -ObjectsToUse     List of integer ranges
              List of model objects with points to extract (comma-separated
              ranges allowed).  The default is to use all open contour or
              scattered point objects.  This option can be used to select a
              subset of objects in the model or force the use of a closed con-
              tour object.

       -box (-bo) OR -BoxSizeXY       Integer
              Size of square box to extract in X/Y plane.  If you want to
              extract a rectangular box, use the -volume option instead.
              Either -box or -volume must be entered.

       -volume (-v) OR -VolumeSizeXYZ      Three integers
              Size of subvolume to extract in X, Y, and Z.  The Z entry is
              irrelevant if -slices is entered as well.

       -slices (-sl) OR -SlicesBelowAndAbove    Two integers
              Number of slices to extract below and above points in Z.  If
              this option is not entered, the Z size is taken from the size
              entered with -box (thus giving a cube), or from the Z size
              entered with -volume.  In these cases, the program extracts an
              equal number of slices below and above for an odd Z size, and
              one more slice below than above for an even Z size.

       -which (-w) OR -WhichPointsToExtract     Integer
              Which points to extract from each contour: 0 for starting
              points, 1 for ending points, or -1 for all points.  The default
              is -1.

       -xminmax (-xm) OR -XMinAndMax       Two integers
              Minimum and maximum coordinates in X for points to extract.  The
              default is to extract for any point contained within the full
              volume and to fill areas outside the volume with the mean inten-
              sity.

       -yminmax (-y) OR -YMinAndMax   Two integers
              Minimum and maximum coordinates in Y for points to extract

       -zminmax (-z) OR -ZMinAndMax   Two integers
              Minimum and maximum sections within which volumes must be con-
              tained in order to be extracted.  The default is to extract a
              volume for any point contained within the full volume, which
              will lead to blank slices for points vey near the top or bottom
              of the volume.  If this limit is set, the whole extracted vol-
              ume, not just the center point, must be contained with in the
              limits.  Sections are numbered from 0.

       -xforms (-xf) OR -XformsToApply     File name
              File of transforms to apply to points before extracting.  The
              first transform in the file should correspond to the first sec-
              tion in the file.

       -back (-ba) OR -BackTransform
              Back-transform the points with the inverse of the transforms
              entered with -xforms.  These options could be used to take coor-
              dinates from an aligned model and extract images from unaligned
              images.

       -taper (-ta) OR -TaperAtFill   Two integers
              Use this option to taper the image in boxes that fall partially
              outside the input volume.  Enter the number of pixels over which
              to taper the image, and a 0 for tapering outside or 1 for taper-
              ing inside the border of the real image data.  Tapering is to
              the value that was used to fill the non-existent image area.
              This value is the mean of the existing image if only one slice
              is being extracted at each point and the input file is not a
              montage, otherwise it is the mean of the input image file.
              Boxes will be tapered in Z as well as in X and Y.

       -blank (-bl) OR -BlankBetweenImages      Integer
              Pixels of blank space between images in array piece list
              (default 5)

       -param (-pa) 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
       For compatibility with older command files, the program will also
       accept input interactively if started with no command line arguments.
       The interactive entries to the program are:

       Image file name Piece list file name, if image file is a montage Model
       file name

       0 to take the coordinates in the model as they are, or 1 to transform
           the coordinates by a set of transformations, or -1 to
           back-transform the coordinates.  The latter would be used to
           take coordinates from an aligned model and extract images from
           unaligned images.

       IF you entered -1 or 1 for transformed coordinates, next enter the
          name of the file with the transforms.  The first transform in the
          file should correspond to the first section in the file.

       Minimum and maximum X, and minimum and maximum Y index coordinates
          within which starting or ending points must be contained in order
          for them to be extracted, or / for no limits on coordinates

       Minimum and maximum section numbers within which the extracted
          volumes must be contained, or / for no limits on section number

       List of numbers of objects containing contours whose endpoints
          should be selected, or Return for all objects.  Ranges may be
          entered, e.g. 1-3,6.

       0 to extract starting points, or 1 to extract ending points, or -1
          to extract all points.

       Size of box, in pixels

       Number of sections before endpoint to extract, and number of
          sections after endpoint to extract

       0 to output all images into a single file, or 1 to output each
          box into a separate, numbered file

       IF you entered 1 for separate files, next enter the root name for the
          numbered files.  This is then the last entry.  IF you entered 0
          for a single file, then make the following additional entries:

       Name of output file for images

       Name of output file in which to place a list of piece coordinates in
          order to view the pieces in a square array, or Return for no
          file of such coordinates

       IF you specify a file name, next enter the amount of blank space to
          leave between adjacent pieces, in pixels

       Name of output file in which to place a list of the true, original
          coordinates of each piece, or Return for no such file

HISTORY
       Written by David Mastronarde, 4/23/90 - revised 1/19/93, for IMOD 4/24/97
       Modified for separate files and all point output 10/26/99
       Converted to PIP and made so practically any volume can be extracted,
          12/4/07

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                4.11.0                      boxstartend(1)