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 5.0.2 boxstartend(1)