Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

BOXSTARTEND(1)							 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 volumes 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 in to a single file, an average will also be
  accumulated and saved in the file after the last extracted subvolume.  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.

  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 -):

 -image 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 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 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 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 number will be the same for
    all files so that they will list in order.

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

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

 -true OR -TruePieceList   File name
    Name of piece list file for viewing subvolumes in original positions

 -objects 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 contour object.

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

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

 -zminmax OR -ZMinAndMax   Two integers
    Minimum and maximum sections within which volumes must be contained 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 volume, not just the center point, must be contained
    with in the limits.  Sections are numbered from 0.

 -xforms OR -XformsToApply   File name
    File of transforms to apply to points before extracting.  The first
    transform in the file should correspond to the first section in the file.

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

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

 -param OR -ParameterFile   Parameter file
    Read parameter entries as keyword-value pairs from a parameter file.

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard 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