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 5.0.2 imodcurvature(1)