imodchopconts(1)            General Commands Manual           imodchopconts(1)



NAME
       imodchopconts - Chop up contours in IMOD model based on length or color

SYNOPSIS
       imodchopconts  [options]  input_model  output_model

DESCRIPTION
       This program will chop contours into pieces in two different ways.  In
       one mode, it will produce contours with equal numbers of points, and
       with a specified amount of overlap between the pieces.  This mode of
       operation has two main uses: 1) Breaking up the contours produced by
       patch tracking with Tiltxcorr into overlapping pieces, which can
       give a better fit in Tiltalign.  2) Splitting up scattered point
       contours so that there is one point per contour.  However, it could
       also be used to split up contours into other lengths, with or without
       overlap.  In its other mode of operation, the program will break con-
       tours apart at fine-grained color changes between points, and put the
       new contours into separate surfaces or separate objects.  Whole con-
       tours that are a different color because of a fine-grained contour
       color property will also be sorted into different surfaces or objects.
       The color can thus be changed at the surface or object level for all
       contour segments of the same color, which is otherwise difficult.
       Breaking contours apart in this way also allows quantitative analysis
       to be done on separately colored segments by programs that do not take
       account of fine-grained color changes.

       Specifying positive numbers for the -length and -overlap options here
       has exactly the same effect as providing those two numbers to the
       -length option of Tiltxcorr.

       When doing length-base chopping, fine grained information at the point
       level will be preserved in the newly created contours.  Fine-grained
       information for an individual contour will be transferred to each of
       the new contours derived from it.  Surface-level fine-grained informa-
       tion will also be preserved unless the -surfaces option is given.

       When doing color-based chopping, all line segments will be appear with
       their original colors for open or closed contour objects.  This
       requires a duplication of points at the contour endpoints.  However,
       there is no such duplication of points for scattered point objects.

       Fine grained information will be preserved during color-based chopping
       to the extent that it makes sense.  Specifically, fine-grained proper-
       ties at all three levels (point, contour, or surface) will be preserved
       in the new contours, except for color.  The color is not lost, but is
       incorporated into the surface or object to which the derived contours
       are assigned and is thus removed as a fine-grained property.  Contour
       level fine-grained properties are transferred from the original contour
       to each contour derived from it.  Surface level information is trans-
       ferred differently depending on whether contours are assigned to sur-
       faces or objects.  In the latter case, the derived contours have the
       same surface number as the original one, and all non-color surface
       information is copied to each new object.  When derived contours are
       assigned to new surfaces, surface information that applies to the orig-
       inal contour is duplicated for the new surfaces.

       If for some reason your model has surface-level fine-grained data, it
       will probably be preferable to split contours into new objects, to
       avoid a proliferation of surfaces.

OPTIONS
       Imodchopconts uses the PIP package for input (see the manual page for
       pip).  Options can be specified either as command line arguments
       (with the -) or one per line in a command file (without the -).
       Options can be abbreviated to unique letters; the currently valid
       abbreviations for short names are shown in parentheses.

       -input (-i) OR -InputModel     File name
              Name of input model file.  If this option is not entered, the
              first non-option argument will be taken as the input file.

       -output (-ou) OR -OutputModel       File name
              Name of output model file.  If this option is not entered, the
              second non-option argument will be taken as the output file.

       -length (-l) OR -LengthOfPieces     Integer
              The length of the new contours, i.e., the number of points to
              put in each.  The actual length can be affected by the entry for
              -overlap.  If -1 is entered, the length will be the default for
              breaking up contours from patch tracking in Etomo, which is the
              Z size in the model divided by 5, but no less than 16.  The
              default if neither this option nor -number is entered is to
              leave contours as they are.  This option cannot be entered with
              -number.

       -overlap (-ov) OR -MinimumOverlap   Integer
              The minimum number of points overlapping between pieces.  If the
              minimum overlap is 0 or positive, then all new contours will be
              given the same number of points, but both the overlap and the
              number of contours will vary depending on the length of the
              original contour.  Enter -1 to enforce zero overlap between con-
              tours and have the contours broken into variable lengths, typi-
              cally less than the specified length.  The default is 4, unless
              1 is entered for -length, in which case the default is 0.

       -number (-n) OR -NumberOfPieces     Integer
              This option provides an alternative way to specify how to chop
              up contours.  The maximum number of points in any contour to be
              processed will be divided by the given number to determine the
              number of points to require in each new contour.  This option
              cannot be entered with -length.

       -surfaces (-s) OR -AssignSurfaces
              Give each new contour a surface number equal to the number of
              the contour from which it came.  This will replace any existing
              surface numbers and invalidate any fine-grained information that
              applies to surfaces.

       -colors (-c) OR -BreakAtColors      Integer
              Break contours at fine-grained color changes, assigning them to
              new surfaces or new objects with the appropriate color if 1 or 2
              is entered, respectively.  None of the options related to
              length-based chopping (-length, -overlap, -number, or -surfaces)
              may be entered with this option.  See above for details.

       -objects (-ob) OR -ObjectsToDo      List of integer ranges
              List of objects to chop up, a comma-separate list of ranges.
              The default is to chop up all objects.

       -help (-h) OR -usage
              Print help output

       -StandardInput
              Read parameter entries from standard input


AUTHOR
       David Mastronarde

SEE ALSO
       tiltxcorr

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                4.10.10                   imodchopconts(1)