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                                4.12.61                       clipmodel(1)