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