imodmesh(1) imodmesh(1)
NAME
imodmesh - create a triangle mesh from IMOD contour data.
SYNOPSIS
imodmesh [options] <model files...>
DESCRIPTION
imodmesh is used to create mesh data in an IMOD model file from closed
or open contours. Each contour is connected to contours directly above
and below by an algorithm that minimizes the total area of the trian-
gles used to connect the contours. Branches in a volume are handled by
combining contours in the same plane with additional points. Contours
contained totally within other contours are considered to represent
inside surfaces and will be connected to the outer surface where appro-
priate.
Open and Closed Contours
Open contours can be used instead of closed ones to represent extended
sheets, or objects that are cut open on one side. If you do so, you
must model all of the contours in the same direction so that the skin
will face outward in the proper direction along the whole surface. If
you are facing the surface from the side that you want to be brightly
lit, contours should progress (point number should increase) from left
to right. If a few contours are going the wrong way, you can correct
them individually in 3dmod with Edit-Contour-Invert. If the entire
surface is facing the wrong way, you can invert the polarity of the
surface at the level of the whole object; use Edit-Object-Type to
define the "Front Surface" as being "Inside" rather than "Outside".
When meshing open contour objects, imodmesh will attempt to connect all
contours between sections, regardless of proximity, because it cannot
use overlapping areas to assess whether contours should be joined. It
will pair up the closest contours first, which should lead to correct
results in most cases. If incorrect connections occur, contours can be
assigned to different surfaces in 3dmod, and the -S option can be used
to mesh only contours within each surface.
If only some of the contours in an object need to be open, such as if
the object is only partially cut open, then individual contours in a
closed-contour object can be defined as open with the Edit-Contour-Type
window in 3dmod. Imodmesh will properly join these open contours to
each other and to the closed contours in the same object. The inside
of one of these open contours is defined in the same way as if the con-
tour were closed, and overlap of enclosed area is used to assess
whether such contours should be connected, so using open contours in a
closed-contour object may give superior results to using open-contour
objects. Two cautions should be noted when using open contours in
closed-contour objects. First, when there is a branch involving an
open contour, the open contour will be joined with one or more closed
contours on the same section to form a merged open contour that pre-
serves the open ends; but if such branching requires two open contours
on the same section to be joined, the surface will not be meshed cor-
rectly. Second, if the line connecting the start and end of an open
contour would intersect the rest of the contour, difficulties may arise
if that contour has to be joined with another on the same section.
Caps
A cap is used to close off a surface at a place where a contour is not
connected to another contour on the adjacent section. Imodmesh will
create such caps when you use the -c or -C option. If the unconnected
contour is relatively round, imodmesh inserts a single point above or
below the contour, and connects that point to all of the points in the
contour. If the contour is more than twice as long as it is wide, the
program will insert two or more points along the long axis of the con-
tour and connect them appropriately. There are several situations in
which you may want to create your own caps by hand, such as if only
some of the unconnected contours on a section should be capped, or if
the cap created by imodmesh is inadequate. To create a simple cap by
hand, just create a contour with one or two points either directly
above or directly below the one you want capped. To create a complex
cap, for example to cap off a U-shaped contour, create a contour on the
adjacent section with as many points as needed to describe the cap,
then use Edit-Contour-Loopback to make the contour be a complex cap
that encloses no area.
Inside Contours
A contour that is completely contained inside another contour of the
same object is assumed to describe a surface that faces in the opposite
direction. Typically, this means that an inner contour is assumed to
face inward rather than outward. In fact, contours may be nested to
any level, with the outermost contour facing outward, the next one in
facing inward, the next one in facing outward, etc. Connections will
be made appropriately, i.e., only between contours that are facing the
same direction. In addition, three kinds of transitions can be han-
dled. First, if there is a transition from an annulus (one contour
inside another) to a single, simple contour that encloses all of the
area covered by the inside contour on the adjacent section, then the
inside surface is assumed to end and will be capped, if caps are being
made. Second, if there is a transition from an annulus to a single
contour that is shaped like a horseshoe, and does not enclose the area
over the inside contour, then the horseshoe-shaped contour will be
divided into an inside and an outside contour for the purpose of con-
necting to the two contours on the adjacent section. This transition
is tricky and may not be handled correctly, especially if more than one
inside contour is involved in the transition, or if two such transi-
tions occur in close proximity. If problems arise, try to avoid having
more than one transition occur across a given pair of sections, and
make the points at the tip of the horseshoe (where the contour will be
divided into two) be close together. Finally, a branch may emerge from
the inside of an inside contour just as it may from a normal, outside
contour.
Fine-grained display information
Imodmesh will encoded some fine-grained display information into the
mesh, specifically, color, transparency, 3D width changes, and stored
values. Contour-specific and point-specific properties will always be
encoded into the mesh. This means that you cannot see changes in these
properties without remeshing the model. The treatment of surface-spe-
cific properties depends on whether the -S option is entered to connect
contours only within surfaces. If this option is not given, then sur-
face-specific properties are encoded in the mesh as well, and changes
in these properties will not be seen unless the model is remeshed. If
the option is given, then the surface-specific properties are not
included in the mesh but are applied during display and can be changed
dynamically.
Connection numbers can be assigned to either points or contours and
Imodmesh will use these numbers when making the mesh. Point connection
numbers can be used to force the mesh to join particular pairs of
points between two contours. See the Fine Grain dialog help for more
details. To force a connection between two contours that do not over-
lap, give them both the same connection number. To prevent a connec-
tion between contours that do overlap, give them different connection
numbers. If only one of a pair of contours has a connection number it
will be ignored when deciding whether to join them.
Tilted contours
The program's meshing routines assume that contours are flat in the X/Y
plane and located at integer steps in Z. However, it will first ana-
lyze the contours of an object to find out if they deviate from flat-
ness. If they do, it will find an average orientation of the contours
in each surface and rotate the contours into the X/Y plane. It then
meshes the rotated contours and rotates the mesh back to the original
orientation to fit the contours. In order for this to work, two rules
must be followed. First, all the contours in a surface must have very
nearly the same orientation. An object can have contours in different
orientations as long as they are assigned to different surfaces. Sec-
ond, the average spacing between contours must be at least one pixel in
the direction perpendicular to the plane of the contours. This spacing
will be maintained when you model in the slicer window with the Lock
button on and step between slices with the PageUp and PageDown keys.
Stored parameters
All of the parameters used to mesh an object are stored in the object.
Most of these stored values are presented in the Remesh panel of the
3dmod Model View Object Edit window, where they can be modified and
used to remesh the object. By default, the stored parameters will be
ignored and replaced when you mesh with Imodmesh. However, with the -u
option, you can use the stored parameters instead of having to enter
the options specifying them. When you do use stored parameters, any
option entries that you make will override specific stored values. In
addition, a set of "-no" options are available for turning off options
selected in the stored parameters.
Options
-u Use parameters stored in each object to set options for meshing.
-c This option will cap off the ends of objects at their extreme
limits in Z.
-C This option will cap off all unconnected contours.
-D <list of Z-values>
This option can be used with the -C option to keep caps from
being made on certain sections. The list of Z-values (a comma-
separated list of ranges) should specify the Z-values at which
contours are missing for whatever reason. An unconnected con-
tour on an adjacent section will not be capped.
-p <value>
Don't make connections unless a given percentage of the contour
overlaps with contours above and below. The valid range is 0 to
100. The default is 0, which means that any amount of overlap
will cause a connection to be made. This option is ignored dur-
ing the -f option's second pass through the data.
-s Normally connections are only made to adjacent sections in the
image data. This option allows connections through sections
containing no data. Note that with this option alone, the sec-
tions must contain either no data or whatever is considered to
be a full amount of data.
-P <value>
Do the given number of passes through the contours, connecting
contours that are progressively farther apart in Z on each pass.
In the simplest case, contours up to 2 sections apart will be
connected with 2 passes, etc. However, when the -s option is
also given, the program will connect contours across gaps with
no data at all on the first pass, then connect contours that are
even farther apart in Z on the next pass, etc. To avoid gener-
ating unintended connections, use both -s and -P and use the
minimum number of passes needed to make the desired connections.
-S This will forbid contours with different surface numbers from
being connected. Contours with the same surface number sections
will be connected, but ones with different surface numbers will
not. Thus, if you use surface numbers at all, you must make all
of the contours that belong in one meshed entity have the same
surface number. Contour connection numbers would be an easier
way to control a small number of misconnections.
-I Ignore time values and connect contours at different times. By
default, a model drawn on multiple image files (referred to as
different times in 3dmod) will be meshed by connecting only con-
tours with the same time values. This option can be used to
override this behavior, in case the contours contain inappropri-
ate time information.
-f Force more connections. Do a final pass through the contour
data and make any leftover connections with no requirement for
contour overlap. This pass occurs after any multiple passes
selected with the -P option. Only contours on sections that
would ordinarily be connected without the -P option will be con-
nected. If this option makes undesirable connections, use con-
tour connection numbers.
-t list
Open contours are by default connected together in a mesh if
possible. This option causes a tube-like mesh of diameter given
by the line width to be created instead, for objects in the list
(comma-separated list of ranges). Closed contour objects
included in the list will be meshed as usual.
-d <diameter>
Override the default diameter used for making tubes with the -t
option. The diameter is given in pixels, the default value is
the line width of the current object.
-E Cap the ends of tubes made with the -t option. This is only way
to get tubes capped and is independent of the -c and -C options.
-T Do more time consuming calculations by searching exhaustively
through all possible sets of connections instead of guessing at
one initial connection. This may help reduce artifacts in some
cases. This flag can cause the computation to take an order of
magnitude more time.
-o <list of object #'s>
Do operations only on objects in the list of numbers. The list
can consist of comma-separated ranges (e.g., 1,7-11,13-17,19).
Without this option, all objects are scanned for skinning.
-R <value>
Tolerance value for point reduction, given in pixels. With this
option, the number of points is reduced by removing ones which
are less than a certain distance from the remaining line seg-
ments. This will remove points selectively from relatively
straight segments and not from tight corners. A tolerance value
of about 0.25 can substantially reduce the number of points with
little perceptible change in the model; larger values could be
used to get models that mesh and display faster.
-i <value>
Form a mesh between contours at z-values that are a multiple of
the given z-increment.
-z <minimum>,<maximum>,[increment]
Filters which contours will be considered while meshing. Con-
tours less then the minimum value and greater then the maximum
value will be skipped. An optional increment value will cause
only z-values that are a multiple of the given increment to be
meshed.
-x <minimum>,<maximum>
-y <minimum>,<maximum> Exclude triangles from the mesh if they
are outside the given limits in X or in Y. This is an alterna-
tive to using clipping planes to chop off surfaces at the edge
of the data set, although the result will be more ragged than
using a clipping plane.
-l Form a low resolution mesh. Any new mesh data created by this
run of the program will be marked as low resolution mesh.
Existing low resolution mesh will be replaced but existing high
resolution mesh will be retained. If tolerance and z-increment
values are not entered with the -R, -i, or -z options, rela-
tively large default values are used to generate a coarse mesh.
The low resolution mesh can be toggled on and off in the 3dmod
Model View window with the View-Low Res menu entry or the "R"
hot key.
-F <value>
This option sets the criterion Z difference for deciding whether
contours are flat enough to mesh without rotating. If the value
is nonzero, the program will determine the maximum Z extent of
all contours in the object. If the Z difference is greater than
the criterion, it will mesh each surface separately after find-
ing the best rotation angles for it. The default value is 1.5.
-a Append the mesh data to objects, replacing only the existing
mesh in the given range instead of replacing the entire mesh.
This option would be used to "edit" a mesh that has problems, by
skinning only a few Z planes with the -T option.
-e Erase all mesh data instead of creating new data. Other options
besides -l and -o are ignored.
-n Recompute the normals in the existing mesh, without computing a
new mesh from contours. Other options besides -l and -o are
ignored.
-n Rescale the normals in the existing mesh by the value given in
the -Z option.
-Z <scale>
A scaling multiplier applied to the z values of normals. The
default value is 1.0.
-noc
-noC
-nos
-noS
-noI
-nof
-noE
-noT Turn off the corresponding option when using stored parameters.
-noD Remove any restrictions on Z values to cap to when using stored
parameters.
-not Do not mesh open objects as tubes when using stored parameters.
-nox
-noy
-noz Remove any limits on X, Y, or Z coordinates when using stored
parameters.
-B Make mesh output backward-compatible to IMOD before 3.6.14 if
possible. Regardless of this option, if a mesh contains fine-
grained display changes, then it will be encoded in a new-style
mesh, which results in a 20% smaller model file. This option
can be set automatically for all runs of imodmesh by setting the
environment variable IMODMESH_OLDMESH.
FILES
A backup file of the original model is created with the ~ extension.
AUTHORS
Jim Kremer and David Mastronarde <mast at colorado dot edu>
SEE ALSO
3dmod, 3dmodv, reducecont
The algorithm in imodmesh is based on:
Fuchs, H., Kedem, Z.M., and Uselton, S.P. 1977. Optimal surface recon-
struction from planar contours. Graphics and Image Processing, 20:
693-702.
Shantz, M. 1981. Surface definition for branching, contour-defined
objects. Computer Graphics, 15: 242-267.
BUGS
The algorithm for finding the set of triangles with minimum area is
currently quadratic; that is, execution time is proportional to the
square of the number of points in the contours being connected.
imodmesh can bog down badly if there are too many points; point reduc-
tion with the -R option will solve this for now.
Here are some things that will create strange-looking meshes:
Contours on the same section that overlap. There is now a function
that eliminates modest amounts of overlap before meshing.
Two unconnected branches that overlap in the next section. Setting a
threshold for percentage overlap with the -p option may keep them from
being connected incorrectly.
Two overlapping horseshoes that open in different places. The program
would need to recognize this situation and split both into inside and
outside contours before trying to join them.
BL3DEMC 3.11.2 imodmesh(1)