imodcurvature(1)            General Commands Manual           imodcurvature(1)



NAME
       imodcurvature - Measures radius of curvature of model objects

SYNOPSIS
       imodcurvature  options  input_model output_model

DESCRIPTION
       This program will compute the local radius of curvature of objects in a
       model and encode that value into the model as a color or a 2D or 3D
       point size.  It can compute either a 2D or a 3D radius of curvature by
       fitting circles or spheres to contours; it can also fit cylinders.  For
       fitting in 2D, it computes the radius of curvature at each point in a
       contour by fitting to a segment of the contour centered on the point;
       the length of this segment is set by a parameter called the window
       length.  This parameter should be varied to explore the tradeoff
       between averaging over larger areas and having a less noisy result.
       This 2D fitting should be very reliable because the search for the cen-
       ter and radius of the circle is initialized by an explicit solution for
       the circle through three widely spaced points along the contour.   How-
       ever, the 2D fitting will produce a gradient of curvatures in a spheri-
       cal object because the radius of cross-sections decreases away from the
       equator.

       The 3D fitting is activated by specifying a parameter for the range in
       Z over which to fit.  The objects to be fit must contain a mesh (pro-
       duced by Imodmesh) so that connections between contours can be
       deduced.  This mesh should connect all contours rather than skipping Z
       levels; otherwise the contours that are not on the Z levels included in
       the meshing cannot be analyzed.  For 3D fitting, the program computes
       the radius for each point by sampling points from contours above and
       below the point in Z.  The fit of 4 parameters to these sample points
       may be somewhat less reliable because it is still initialized by the
       explicit solution for a circle fit to the central contour.  No fit is
       done to a point unless there is at least one contour above and one con-
       tour below the point in Z.  Here one may need to explore the effects of
       varying both the window length and the Z range.

       Fitting to cylinders instead of spheres is activated by specifying an
       angular increment for searching different orientations.  At each possi-
       ble orientation for the cylinder axis, the sampled points are projected
       into a plane and then a circle is fit to those points.  Cylinder fits
       thus involve finding 5 parameters, so they may be even less reliable
       than spherical fits.  Nevertheless, they will give more meaningful val-
       ues for tubular regions, which have a high curvature around the tube
       and a low curvature along its length.  A limitation here is that the
       fit will not generally include points from both sides of a long contour
       and will not be possible for some portions of the tops and bottoms of
       structures.  The exhaustive orientation search is computationally inef-
       ficient and will make the program run much longer than for spherical
       fits.  However, the program is parallelized in OpenMP and has shown
       high parallel efficiency for these searches, even using up to 32 cores,
       so run this operation on as powerful a computer as possible.

       If contours are in arbitrary planes rather than in Z planes, the 2D
       curvature can be determined, but only if they are individually rotated
       into the best-fitting plane, using the -ro option.

       A radius of curvature is encoded into the model only if it falls within
       the range of the lower and upper criteria set with the -rc option.  In
       addition, a criterion for the root mean square error of the fit may be
       set with the -fc option, in which case a radius is encoded only if the
       fit gave an error less than this criterion.

       The radius value can be used to set a color, a 3D point size, or a 2D
       symbol size for each individual point that meets the criteria.  One or
       a few colors can be specified with the -co option, or a full false-
       color palette can be used with the -pa option.  In addition, the curva-
       ture values can be stored directly in the model, in which case 3dmod
       will display the values in false color by default.  This method allows
       dynamic control over the display.  With either method for color dis-
       play, the model needs to be remeshed to see the colors in the model
       view of 3dmod.  Stored values can be seen for individual points by
       opening the Fine Grain dialog in 3dmod. With 3D points, you can see
       the values of the radius by opening the Surface/Contour/Point dialog in
       3dmod.  3D points could also be useful for visualizing the fit in
       the 3dmod Zap window, provided that one selects the option in the
       Edit Object dialog to show the spheres only on their central section.
       These spheres will impair the display in the model view window, how-
       ever.  An alternative is to encode the radius as circular symbols; how-
       ever, they will only have the right size at the particular zoom speci-
       fied with the -sy option.

OPTIONS
       Imodcurvature 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.

       -in (-i) OR -InputFile    File name
              Name of input model file.  If it is not entered with this option
              it must be entered with the first non-option argument.

       -OutputFile     File name
              Name of output model file.  If it is not entered with this
              option it must be entered with the second non-option argument.

       -wl (-w) OR -WindowLength      Floating point
              Length in pixels over which to fit a circle to the contour data
              around a point.  The default is the sum of the lower and upper
              radius criteria (i.e., the mean diameter) if the -rc option is
              entered, otherwise 100.  By default, this entry also sets the
              minimum window length, but the minimum can be set to a lower
              value with the -min option.  The radius will not be determined
              in contours less than this minimum length for closed contour
              objects, or less than half this length for open contour objects.
              For points near the end of an open contour, the fit will be to
              half of this minimum length on the side away from the end and to
              whatever length is available on the side toward the end.

       -min (-mi) OR -MinimumWindowLength       Floating point
              Minimum length in pixels over which to fit a circle to the con-
              tour data around a point.  This entry can be used to fit small
              contours while using a larger window length for more averaged,
              less noisy measurements over larger contours. The default is to
              use the window length.

       -zr (-z) OR -ZRangeToFit       Floating point
              Range of contours in Z to include for fitting to a sphere.  The
              value should specify the actual distance in Z after Z-scaling,
              if any.  The default is 0 to fit just one contour at a time to a
              circle.

       -cy OR -CylinderSearchAngle    Floating point
              If this option is entered, points will be fit to a cylinder
              instead of a sphere by doing an exhaustive search of all possi-
              ble orientations.  The value entered is the angular increment
              for this search.  Increments of 5 to 10 degrees are useful.
              Computation time will increase inversely with the square of this
              increment.  A value of 10 is recommended for initial testing,
              and a value of 5 for final computations.

       -rc OR -RadiusCriterion   Two floats
              Lower and upper criteria for radius of curvature, in pixels.
              When the radius at a point is within this range, it will be
              encoded into the model.  The default is 0,0, which makes it
              apply no criteria and encode for all points.  However, a pair of
              positive criteria must be entered if this radius range is being
              subdivided to assign colors; i.e., when using either the -pa
              option or the -co and -di options.

       -fc (-f) OR -FitCriterion      Floating point
              Criterion for root mean squared error of the local fit to a cir-
              cle, in pixels.  If a non-zero value is entered, then the RMS
              error must be less than the given value for a radius of curva-
              ture to be encoded at that point.  With the default value of 0,
              the curvature will be encoded regardless of the error of the
              fit.

       -ob (-o) OR -ObjectsToDo       List of integer ranges
              List of objects to encode

       -ro OR -RotateToXYPlane
              Rotate contours that are not all in one X/Y plane into the best-
              fitting X/Y plane.  Circles will be fit to the rotated contour.
              This option cannot be used with the -zr option for spherical
              fitting.

       -st OR -StoreValues
              Store the radius of curvature values directly in the model.
              They can then be visualized as intensity variations or in false
              color by activating the option to "Show stored values" in the
              Values panel of the model view Object Edit window of 3dmod.
              This option allows dynamic adjustment of the displayed colors.
              These radius values will be scaled by the pixel size defined in
              the model, unlike all other radius values, which are in pixels.
              The units of radius are the same as those in which the pixel
              size of the model is defined, thus nanometers if the pixel size
              is in nm.

       -kappa (-k) OR -KappaValues
              Store curvature values, which are the inverse of the radius of
              curvature, in the model.  This curvature is commonly referred to
              as kappa.  To keep values from becoming too small, they will be
              multiplied by 1000 if the pixel size is greater than 0.05.
              Thus, for typical pixel sizes in nanometers, the curvatures will
              be in reciprocal microns.  This measure could be advantageous if
              you are interested in seeing the values for regions with little
              or no curvature while still seeing distinctions among regions
              with moderate curvature.  The curvature value goes to zero,
              while radius of curvature becomes very large and compresses the
              dynamic range.  Also, the mean and standard deviation estimates
              can be badly skewed if the distribution of values includes
              regions with very low curvature.

       -ps OR -PointSize
              Use spherical point size to encode radius of curvature.  Each
              point that meets the criterion will be given a point size equal
              to the radius of curvature; other points will have individual
              point sizes set to 0.

       -sy OR -SymbolZoom   Floating point
              Use circular symbols to encode radius of curvature, where the
              circles will have the right size when the image is displayed
              with the given zoom factor.

       -co OR -Color   Three integers
              Use this entry to specify one or more colors to change points to
              when their radius of curvature meets the criteria.  Enter r,g,b
              values between 0 and 255.  When multiple colors are entered, the
              behavior is controlled by the -di option.  (Successive entries
              accumulate)

       -di (-d) OR -DivideRange
              When multiple colors are entered, by default they will be
              applied to successive objects being analyzed.  If this option is
              entered, then the range of radii between the low and high crite-
              rion will be subdivided by the number of colors, and points
              within each subrange will be assigned to a different color.

       -pa OR -UsePalette   File name
              Use a 256-color false color palette for the colors.  Enter a
              filename to read a color table from a file, or "s", "standard",
              or any abbreviation thereof for the standard palette from 3dmod,
              or "i", "inverted", or any abbreviation thereof for an inverted
              palette from 3dmod.  This option will automatically subdivide
              the radius range into 256 levels.  A color table file can have
              one of two forms.  One form starts with a line with 256, then
              has 256 lines with red, green, and blue values from 0-255.  The
              other form starts with the number of lines to follow; then each
              following line has a red, green, and blue value (0-255) plus an
              arbitrary integer indicating the relative location of that value
              along the 256-color range.  These location values must be in
              order.  If the colors being specified are to be equally spaced,
              the location values can simply be sequential values.

       -sa OR -SampleSpacing     Floating point
              Spacing of sample points along contour for fitting (default 2)

       -me OR -MeanStored   Integer
              Use this option to get an output of the mean value stored in the
              model for each object (1) or for each contour (2).

       -ve (-v) OR -Verbose
              The verbose output will show the number of points being fit, the
              center and radius, and the root mean squared error for each
              point being fit.  It could be useful for getting a sense of the
              RMS errors.

       -tc OR -TestCircleFits
              Test circle fitting by fitting a circle to each contour in
              object 1 and putting a point with the given location and radius
              in a new object.

       -ts OR -TestSphereFits    Two integers
              Test sphere fitting by making a new object with the points being
              fit to and the fitted sphere for the given contour and point
              number.  If cylinder fitting is being done instead, 3 spheres
              will be shown along the axis of the fitted cyclinder, and the
              results for each search angle will be printed.  If the -ve
              option is given, the program will also output the projection
              points at each search angle.

       -si OR -SignedValues      Text string
              If "+", radii and curvatures will be stored as positive values
              when the contour follows a locally clockwise path as viewed from
              the +z axis, and negative for counterclockwise. If "-", these
              signs will be reversed.  SignedValues are not allowed in combi-
              nation with ZRangeToFit (-zr) or CylinderSearchAngles (-cy) .

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

       -StandardInput
              Read parameter entries from standard input


AUTHOR
       David Mastronarde

SEE ALSO
       3dmod, imodmesh

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                4.12.61                   imodcurvature(1)