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