imodauto(1) General Commands Manual imodauto(1)
NAME
imodauto - creates a model from an mrc image stack.
SYNOPSIS
imodauto [options] MRC_image_file output_model_file
DESCRIPTION
imodauto creates an IMOD model from an MRC image stack using a simple
image thresholding. Both a low and a high threshold may be set; con-
tours are drawn around groups of pixels that are below the low thresh-
old and around pixels above the high threshold. Image data are read
from the file and scaled to values between 0 and 255, just as when
reading into 3dmod. The thresholds may be specified as values
either before or after this scaling. In addition, thresholds may be
specified as absolute values or as multiples of the mean image inten-
sity. The default behavior is for thresholds to be interpreted as
absolute values after scaling, in which case they will correspond to
thresholds set in the 3dmod autocontouring window.
Typically, you would enter either a low or a high threshold, but not
both. However, if your images have annular regions of pixels, you can
get contours drawn both inside and outside the regions by having the
same value for the low and the high threshold. The details of making
this work right are handled by the -n option. Using that option, you
would enter the threshold once, as either a low or a high threshold,
depending on whether the features of interest are dark or light. The
program will set the other threshold equal to the given one, and follow
diagonals (connect pixels touching only on their corners) and eliminate
contours touching edges as appropriate. For example, if you enter a
high threshold, then imodauto will follow diagonals when finding areas
above threshold, but not when finding areas below threshold. This sub-
tlety is needed to achieve sensible nested contours. In this example,
the program will also eliminate any contours touching the edges of the
image area when finding areas below threshold; otherwise a large con-
tour enclosing most of the image would be produced.
Imodauto can also be used to make contours around areas containing a
particular uniform value, regardless of the values of neighboring pix-
els. This feature is useful if an image volume has already been seg-
mented by other means to produce a volume in which different regions
are marked with one or more values. Use the -E option to specify an
exact value to generate contours around. The value may be a scaled
value, as read out of 3dmod, or it may be the actual value in the
file if the -u option is used. The -f option can be used to follow
diagonals, but 3 is the only meaningful value. Inside contours can be
found with the -n option. One problem with the model output is that it
will be appear jagged as it follows the edges of pixels, since the
interpolation method used with normal image data is assumed to be mean-
ingless and is not applied. There are three tools available for get-
ting a smoother model. 1) Use the -R option with a value of 0.5 to
remove all points within 0.5 pixel of the remaining lines. This method
will still leave some jaggedness but contours will still follow the
edges of the region fairly well. 2) Use Smoothsurf solely to smooth
the contours in 2D by entering parameters such as:
smoothsurf -nz 1 -dist 3 -cont 3
This may produce smoother output than the first method, but may deviate
more from the region at sharp corners. 3) Use the contour smoothing
option in Drawing Tools, available from the Special menu of 3dmod.
Check the option to "ALLOW POINTS TO BE MOVED" and reduce the "min dis-
tance to move" to 0.1. This may be the best method.
The program is parallelized with OpenMP by having multiple sections be
analyzed in parallel. This high level of parallelization requires mul-
tiple copies of several arrays as large as the image area being ana-
lyzed. For large images, the number of threads will be limited to keep
the memory usage under 2 GB.
OPTIONS
-l value
Specifies the low threshold level. Contours will be generated
around pixels that map to levels below the low threshold level.
The default value is 0, which will give no contours for areas
below threshold.
-h value
Specifies the high threshold level. Contours will be generated
around pixels that map to levels above the high threshold level.
The default value is 255, which will give no contours for areas
above threshold.
-E value
Specifies an exact value to generate contours around, regardless
of whether surrounding pixels are high or lower than this (see
description above). The -l, -h, and -d options may not be
entered together with this option.
-d value
Determines how the low and high threshold levels are computed.
The default value is d = 1, in which case the low and high val-
ues are used directly. When d = 2, the high and low values are
treated as factors to be applied to the mean of the image file
(after loading into the program). If an image file's mean value
is 50 and the low value is 0.5 then the low threshold will be
set to 25. When d = 3, the low and high values are factors
applied to the mean of each individual section.
-u Specifies that the entered threshold values are to be inter-
preted as unscaled, corresponding to the actual values in the
image file. By default, threshold values are instead inter-
preted as scaled values to be applied after the images are
scaled to the range of 0 to 255.
-f value
Determines whether diagonals are followed when finding groups of
connected pixels. The default value is 0, meaning that diago-
nals will not be followed. With a value of 3, diagonals will
always be followed. With 1 or 2 diagonals will be followed only
for areas above the high threshold or below the low threshold,
respectively.
-n Find inside contours in closed, annular regions. To use this
option, enter one threshold as appropriate for defining your
regions of interest.
-m value
Minimum area for each contour, in square pixels. Any values
less than 1 will be treated as 1. The default value is 10.
-M value
Maximum area for each contour, in square pixels. If this option
is not used, no maximum size will be enforced. Any value
entered should be greater than the minimum area specified by -m.
-e value
Criterion for eliminating contours based on the number of edges
of the image that they touch. Values from 1 to 4 are meaning-
ful; for example, a value of 2 will eliminate contours that
touch 2 or more edges. The default is zero, for no selection on
the basis of edges touched.
-r value
Resolution for point shaving, in which points are removed when
they are closer than the given distance apart. This method of
point removal will eliminate some detail and might be useful for
smoothing; otherwise, the -R option is preferable. The default
value is 0.0, which turns this feature off.
-R value
Resolution or tolerance for point reduction when generating the
final model. Points are eliminated if they are within this dis-
tance of the lines connecting the remaining points, just as with
the -R option in imodmesh and the resolution feature when
autocontouring in 3dmod. This method of point removal will
preserve detail as well as possible, unlike the -r option. Val-
ues in the range 0.25 to 0.5 are often useful. The default
value is 0.0, which turns this feature off.
-s min,max
Set the intensity scaling for the image data, so that min is
mapped to 0 and max is mapped to 255. The default for these
values are the minimum and maximum from the image file header.
-X min,max
Load and model a subset in X from min to max, where the coordi-
nates are numbered from 0.
-Y min,max
Load and model a subset in Y from min to max, where the coordi-
nates are numbered from 0. If the -e option is used with -X or
-Y, then decisions about contours are made based on the edges of
the loaded subset of the image, not of the full image.
-Z min,max
Load and model a subset in Z from min to max, where the coordi-
nates are numbered from 0.
-B filename
Specify a model with boundary contours around the region(s) to
be modeled. These contours should all be in one closed contour
object. More than one contour can be drawn on each section. By
default, when there are any boundary contours, each section will
use the contours on the nearest section; thus, only one or a few
contours may be needed. Use -e 1 to eliminate contours that
touch the boundaries. There is one flaw in this elimination if
inside contours are being found: inside contours may be produced
that are no longer surrounded by an outer contour, because the
outer contour was eliminated while the inner ones were retained.
-S Apply the boundary contours only on the same sections as they
are drawn; sections without boundary contours will be analyzed
in their entirety.
-O value
Specify the object number that contains boundary contours in the
boundary model. By default, the program will use the first
closed contour object in the model.
-k sigma
Smooth the data with a kernel filter whose Gaussian sigma is
given by the entered value. This filter is the same as the
smoothing filter in the 3dmod image processing window or in
Clip. Use a value of 0 to select the simple default filter
instead of the Gaussian kernel.
-z value
Set the zscale for the model. The zscale is a factor that com-
pensates for 3 dimensional data that is sampled at a different z
resolution than the x-y plane data. If the images have 25nm
pixels and 100nm z slice size then the z-scale factor would be
4.0.
-c r,g,b
Set the color of the model object by specifying red, green, blue
values separated by commas. The values can range from 0 to 1 or
from 0 to 255; i.e., 1.0,0.5,0 and 255,128,0 could both be used
to specify orange.
-x Expand areas by one pixel before enclosing them in contours,
just as in 3dmod autocontouring.
-i Shrink areas by one pixel before enclosing them in contours,
just as in 3dmod autocontouring.
-o Smooth areas before enclosing them in contours. As in 3dmod
autocontouring, this is implemented by expanding then shrinking.
-I file
Take the image coordinate reference information to be assigned
to the new model from the given image file instead of from the
input file being contoured. This option is useful if the input
file was created outside of IMOD and did not retain the header
information (pixel spacing, origin, and rotation) of the IMOD
image file from which it was derived. Supplying the latter file
to this option will make the model display correctly on that
file in 3dmod, provided that its pixels still correspond to
those of the input file (e.g., the two files are at the same
binning).
The segmentation used by imodauto is a simple threshold. Each pixel
lying between the low and high thresholds is thrown out. Then, the
program finds all of the separate areas lying below the low or above
the high threshold. Groups of pixels with area greater then the value
given by the -M option or area less then the value given by the -m
option are thrown out. Next, contours are drawn around each remaining
area.
If the -r option has a value greater than 0, then points are eliminated
from each contour if they are less than the given distance apart.
After that, if the -R option has a value greater than 0, points are
eliminated if they are within the given distance from the lines between
remaining points.
FILES
If the model file already exists, it becomes a backup file with ~ added
to its name.
AUTHORS
Jim Kremer and David Mastronarde
SEE ALSO
3dmod, 3dmodv, imodmesh, contourmod
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.0.2 imodauto(1)