clipmodel(1) General Commands Manual clipmodel(1)
NAME
clipmodel - to clip a MT model by location or object number
SYNOPSIS
clipmodel [options] input_file output_file
DESCRIPTION
Clipmodel will clip out a portion of a model and output either a new
model file, or a simple list of point coordinates. It can either
include only points within a defined rectangular block of 3- dimen-
sional coordinate space, or exclude points within such a block. This
process of inclusion or exclusion may be invoked repeatedly. The pro-
gram can also eliminate an entire IMOD object.
To specify a rectangular block of coordinate space, one enters the min-
imum and maximum X, Y and Z coordinates of the block. The default val-
ues for the minimum and maximum X and Y coordinates are very large num-
bers, so one can select the default if one wants no limitation on
either the X, the Y, or both coordinates. A point on the edge of the
block (i.e. with one coordinate exactly equal to one of the lower or
upper limits) is treated as if it is inside the block. The Z limits
are extended by 0.005 to help this work as expected even if Z values
differ slightly from integers; for example, limits of 117,117 will
retain the point at Z = 117.
The coordinates that you enter should correspond to the index coordi-
nates in the image display from which the model was last saved. If you
last saved the model from an 3dmod display of a subset of the image
stack, then you need to refer to coordinates within that subset. If
this is a problem, reload the model onto the full image stack (or a
subset starting at 0,0,0) and save it again. Index coordinates are num-
bered from zero, so your Z values should be 1 less than the section
number shown in 3dmod.
The program does not create new contours. This limitation means that
if there is more than one segment of a contour inside a block being
included (or more than one segment outside a block being excluded), you
have two options. The program either can truncate the contour to be
the longest such segment, discarding any other segments, or it can clip
all of the points out of the contour that are in the region being
excluded, connecting the remaining segments with straight lines.
If an object consists of scattered points, then all points in the
region being included will be included, regardless of which clipping
option you choose for clipping contours.
When you choose to retain all segments in the region being included,
the program will sum and report the total length of cut edges, so that
the cut surface can be subtracted from a computed surface area. For
objects consisting of closed contours, this total will include an edge
between the starting and ending points of a clipped contour, if points
were clipped off at those ends of the contour. For open contour
objects, this edge will not be included.
OPTIONS
Clipmodel uses the PIP package for input (see the manual page for
pip) and can still take input interactively if a sequence of opera-
tions is needed that cannot be achieved with the PIP options. The fol-
lowing 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.
-input (-i) OR -InputFile File name
Input model file to be clipped
-output (-ou) OR -OutputFile File name
Name of output file, which can be either an IMOD model file or
text file with a list of point coordinates.
-point (-po) OR -PointOutput Integer
Enter 1 to make a point output file instead of a model output
file. Nearest integer coordinates will be output; use
Model2point to get more flexible point list output. Enter -1
to get a point list with corner points added each time a new Z
value is encountered; in this case -xminmax and -yminmax must be
entered.
-xminmax (-x) OR -XMinAndMax Two floats
Starting and ending X index coordinates to include or exclude,
numbered from 0. Enter a / to take the default, which is to
have no selection based on X coordinate. (Successive entries
accumulate)
-yminmax (-y) OR -YMinAndMax Two floats
Starting and ending Y index coordinates to include or exclude,
numbered from 0. Enter a / to take the default, which is to
have no selection based on Y coordinate. (Successive entries
accumulate)
-zminmax (-z) OR -ZMinAndMax Two floats
Starting and ending Z coordinates to include or exclude, num-
bered from 0. Enter a / to take the default, which is to have
no selection based on Z coordinate. Starting and ending will be
adjusted down and up by 0.005, respectively, so whole numbers
can be entered; e.g., 16,18 will clip out sections 16 through
18. (Successive entries accumulate)
-bound (-b) OR -BoundaryObjects List of integer ranges
List of model objects with contours enclosing a volume to
include or exclude. If coordinate limits are also entered, then
the intersection of the regions inside those limits and the
interior of the contours will be used as the volume to include
or exclude. Objects must be closed contour objects. There can
be more than one contour on each section, and contours do not
need to be drawn on every section included in the volume.
Points are tested for whether they are inside the boundary con-
tours on the nearest section with such contours, unless the
-coplanar option is given. Points beyond the minimum and maxi-
mum Z values of the boundary contours are considered outside the
volume. The listed objects will be excluded from the clipping
operations; not even coordinate limits are applied to them. If
multiple operations are specified, the boundary contours are
applied only on the first operation.
-coplanar (-c) OR -CoplanarBoundary
Boundary contours apply only on the planes where they are drawn;
thus, to be considered inside the volume, a point must be on the
same plane as, and inside, some boundary contour.
-exclude (-ex) OR -ExcludeOrInclude Multiple integers
1 to exclude or 0 to include points within specified coordinate
block. Multiple values can be entered for a sequence of opera-
tions. The number of -xminmax, -yminmax, and -zminmax entries
must each be equal to the number of values entered here, unless
an option is not entered at all for that dimension. If any
coordinate limits are entered, the default for this entry is a
single 0; in other words, you can omit this entry if you are
just clipping out coordinates inside one coordinate block.
-longest (-l) OR -LongestContourSegment
Retain only the longest segment of a contour that is within the
volume being included, instead of all segments.
-keep (-k) OR -KeepEmptyContours
Keep contours that have no points, so that contours have their
original numbers in the output model. This was the behavior
before IMOD 4.6.18. The default is now to remove empty con-
tours.
-objects (-ob) OR -ObjectList List of integer ranges
List of model objects to remove or clip endpoints from. This
option cannot be entered together with any of the options for
clipping by coordinates. If -ends is entered, points will be
removed from endpoints of contours; otherwise whole objects will
be removed.
-ends (-en) OR -ClipFromStartAndEnd Two integers
Number of points to clip from start and end of contours for the
objects specified by -objects; the latter must be entered.
-values (-v) OR -ValuesInOrOutOfRange Integer
Use this option to delete contours or points that have stored
values inside of or outside of a defined range. Enter 1 or -1
to delete contours, 2 or -2 to delete points, or 3 or -3 to
delete both, with a positive or negative number to delete if
values are inside or outside the range, respectively. For exam-
ple, if a model is produced by Imodfindbeads with the default
storage option, contours with values below threshold can be
removed with "clipmodel -values 1 input_file output_file".
-range (-r) OR -RangeForValues Two floats
When deleting points or contours with the -values option, use
this option to enter the lower and upper values of the range
used to decide whether a point or contour is to be deleted. If
this option is not entered, the default range for each object is
all values below the lower threshold stored in the model by
Imodfindbeads, Findbeads3d, 3dmod, or other programs.
In 3dmod, this threshold appears in the Bead Fixer dialog and
also as the Black slider setting in the Values panel of the
Edit-Objects dialog of the Model View window. When deleting
closed contours by area with the -areas option, use this option
to enter the lower and upper areas of the range.
-update (-up) OR -UpdateObjectMinMax
Update the stored minimum and maximum values of each object
based on the stored values of all contours and points in the
object. These minimum and maximum values determine the range of
the Black/White sliders in the Values panel of the Edit-Objects
dialog of the Model View window. This option cannot be used
together with -keep.
-areas (-a) OR -AreasInOrOutOfRange Integer
Use this option to delete contours in closed contour objects
with areas inside or outside of a range specified with the
-range option, which must be entered as well. Enter a positive
value to delete inside the range or a negative one to delete
outside the range. Enter -1 or 1 if the area limits entered
with -fBrange are in pixels, -2 or +2 if they are in square
nanometers, or -3 or 3 if they are in square microns. This
option cannot be entered with -values.
-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
In interactive mode, entries to the program are:
Name of input model file
Name of output file for clipped model
0 to output a model file, 1 to output a file with a simple list of
integer point coordinates, or -1 to output such a point list with
two additional corner points preceding the points on any given
section. Such a file could be used as a set of teaching points
for MTTEACH and MTDETECT; but beware of the need for each "zone"
to be contained within a single piece in a montaged image file.
0 to retain only the longest segment of a contour included in a
volume (if the contour passes through the volume more than once),
or 1 to retain all segments included in the volume.
0 to include points in the rectangular coordinate block to be
specified next, or 1 to exclude points in such a block, or -1 to
exclude whole IMOD objects, or -2 to clip points off of one end
of all contours in selected IMOD objects.
IF you entered 0 or 1, next specify the coordinates as follows:
Minimum and maximum X, minimum and maximum Y coordinates of the
block. / selects the defaults of no limits
Minimum and maximum Z of the block
BUT IF you entered -1, enter instead a list of the numbers of the
objects to be excluded. For data from a WIMP model file, use
256 minus the WIMP object color (e.g. 1 for color 255), or the
negative of this value to refer to WIMP objects that are turned
off. Ranges may be entered (e.g. 1-3,6).
OR IF you entered -2, enter the number of points to clip off of the
start, and the number of points to clip off of the end, of
contours in selected objects. Next enter a list of the numbers of
the objects to be clipped in this fashion, where WIMP objects may
again be referred to by 256 minus their color, or the negative of
this value if they are turned off. Ranges may be entered.
0 to store the current result, or 1 to loop back and specify a new
block to include or exclude (or objects to exclude or clip)
HISTORY
Written by David Mastronarde, 1/11/90
Modified for IMOD 4/24/97
Compute cut edges and handle coordinates better, 10/24/00
Converted to PIP input, July 2012.
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 clipmodel(1)