Commit 44f514b4 authored by Mike Kremer's avatar Mike Kremer

Updated documentation.

git-svn-id: http://www.openvolumemesh.org/svnrepo/OpenVolumeMesh/trunk@207 66977474-1d4b-4f09-8fe9-267525286df2
parent 2ea4c6f9
......@@ -13,18 +13,18 @@ Welcome to the %OpenVolumeMesh documentation.
meshes. Its concepts are closely related to OpenMesh (http://www.openmesh.org). In particular,
%OpenVolumeMesh carries the general idea of storing edges as so-called (directed) half-edges over
to the face definitions. So, faces are split up into so-called half-faces having opposing orientations.
But unlike in the original concept of half-edges, local adjacency information is not stored on a per
But unlike in the original concept of half-edges, local incidence information is not stored on a per
half-edge basis. Instead, all entities are arranged in arrays, which makes %OpenVolumeMesh an
index-based data structure where the access to entities via handles is accomplished in constant
time complexity. By making the data structure index-based, we alleviate the major drawback of
the half-edge data structure of only being capable to represent manifold meshes. In our concept,
each entity of dimension \f$n\f$ only stores an (ordered) tuple of handles (or indices) pointing to the
incident entities of dimension \f$(n-1)\f$. These adjacency relations are called the top-down adjacencies.
incident entities of dimension \f$(n-1)\f$. These incidence relations are called the top-down incidences.
They are intrinsic to the implemented concept of volumentric meshes. One can additionally compute
bottom-up adjacencies, which means that for each entity of dimension \f$n\f$, we also store handles to
adjacent entities of dimension \f$(n+1)\f$. These adjacency relations have to be computed explicitly which
can be performed in linear time complexity. Both adjacency relations, the top-down and the bottom-up
adjacencies, are used to provide a set of iterators and circulators that are comfortable in use.
bottom-up incidences, which means that for each entity of dimension \f$n\f$, we also store handles to
adjacent entities of dimension \f$(n+1)\f$. These incidence relations have to be computed explicitly which
can be performed in linear time complexity. Both incidence relations, the top-down and the bottom-up
incidences, are used to provide a set of iterators and circulators that are comfortable in use.
As in OpenMesh, %OpenVolumeMesh provides an entirely generic underlying property system that allows
attaching properties of any kind to the entities.
......
......@@ -8,7 +8,7 @@ The concepts of %OpenVolumeMesh are closely related to those of %OpenMesh (http:
For further reading on the concepts of %OpenMesh, refer to \cite Botsch02OpenMesh.
%OpenMesh is used to handle two-manifold geometric meshes. For this purpose, it distinguishes
between \e vertices, \e edges, and \e faces. The main idea in %OpenMesh is to represent the
edges as a pair of so-called half-edges that have opposing orientations. Additional local adjacency
edges as a pair of so-called half-edges that have opposing orientations. Additional local incidence
information is stored for each half-edge such that the navigation on the mesh can be completely
accomplished by using only these local links to adjacent structures (similar to e.g. a linked list).
This, of course, assumes the surface mesh to be two-manifold.
......@@ -18,7 +18,7 @@ The main concept of %OpenVolumeMesh is slightly different but shares some of its
set of polyhedra, %OpenVolumeMesh extends the set of entities by \e cells.
But unlike in the original idea of half-edge data structure,
in %OpenVolumeMesh all entities are stored in arrays (STL vectors) rather than
in adjacency linked lists. This is why %OpenVolumeMesh is index-based which
in incidence linked lists. This is why %OpenVolumeMesh is index-based which
has the major advantage that the data structure can handle configurations that are
not three-manifold (since this is desired in some applications).
For example, a set of vertices or just a two-manifold surface can be respresented by
......@@ -32,57 +32,57 @@ by its incident half-edges. See Figure 1 for an illustration of this concept.
\image html halfedge_halfface.png "Figure 1. Left: Two half-edges as in OpenMesh. Right: A face split into two half-faces."
\section adjacencies Adjacency Relations
\section incidences Incidence Relations
The entities in %OpenVolumeMesh are arranged hierarchically and we distinguish between
two adjacency relations:
two incidence relations:
\li The (intrinsic) top-down adjacencies and
\li the bottom-up adjacencies.
\li The (intrinsic) top-down incidences and
\li the bottom-up incidences.
\subsection top_down The Top-Down Adjacency Relation
\subsection top_down The Top-Down Incidence Relation
Each entity of dimension n is defined as a tuple of entities of dimension n-1,
except for the vertices. So, edges are defined as a pair of vertices, (half-)faces are defined as
a j-tuple of (half-)edges, where j is the valence of the face, and cells are defined
as a k-tuple of (half-)faces, where k is the valence of the cell. This adjacency
as a k-tuple of (half-)faces, where k is the valence of the cell. This incidence
relation is intrinsically given by definition. %OpenVolumeMesh can use these
adjacencies in order to provide \e top-down circulators, that is circulators
incidences in order to provide \e top-down circulators, that is circulators
that address all adjacent lower-dimensional entities of a given reference entity.
Read more on iterators and circulators in Section \ref iterators_and_circulators.
Figure 2 illustrates this hierarchy.
\image html volume_mesh_hierarchy.png "Figure 2. Each entity is defined as a tuple of lower-dimensional entities."
\subsection bottom_up The Bottom-Up Adjacency Relation
\subsection bottom_up The Bottom-Up Incidence Relation
In many cases, the adjacency list to higher dimensional entities for a given entity is
In many cases, the incidence list to higher dimensional entities for a given entity is
required. Therefore, %OpenVolumeMesh offers the opportunity to explicitly compute
the so-called \e bottom-up adjacencies. For this, %OpenVolumeMesh stores the
the so-called \e bottom-up incidences. For this, %OpenVolumeMesh stores the
following information for the respective entity type in additional caches:
\li \b Vertex: A list of all outgoing half-edges.
\li \b Half-Edge: An (ordered) list of all incident half-faces.
\li \b Half-Face: The handle to an incident cell or none if it is a boundary half-face.
These adjacency relations are computed automatically for each affected entity
when adding/deleting it. In most cases these adjacencies are needed since many
These incidence relations are computed automatically for each affected entity
when adding/deleting it. In most cases these incidences are needed since many
iterators/circulators rely on them. Storing this additional information consumes
extra memory that scales linearly with the mesh's complexity.
However, in case these adjacency relations are not needed (e.g. in numerical analysis
applications, etc.), they can be disabled by calling TopologyKernel::enable_bottom_up_adjacencies()
and passing false as parameter. Also it is possible to enable bottom-up adjacencies
However, in case these incidence relations are not needed (e.g. in numerical analysis
applications, etc.), they can be disabled by calling TopologyKernel::enable_bottom_up_incidences()
and passing false as parameter. Also it is possible to enable bottom-up incidences
for single entity types, just call the following functions:
\li TopologyKernel::enable_vertex_bottom_up_adjacencies()
\li TopologyKernel::enable_edge_bottom_up_adjacencies()
\li TopologyKernel::enable_face_bottom_up_adjacencies()
\li TopologyKernel::enable_vertex_bottom_up_incidences()
\li TopologyKernel::enable_edge_bottom_up_incidences()
\li TopologyKernel::enable_face_bottom_up_incidences()
This is useful in cases where only a subset of these adjacency relations is required
This is useful in cases where only a subset of these incidence relations is required
while at the same time keeping the data structure as compact as possible
allocating only a minimum of storage overhead.
\note Note that most of the iterators and circulators rely on these adjacency lists, so, many of them do not work if bottom-up adjacencies are disabled.
\note Note that most of the iterators and circulators rely on these incidence lists, so, many of them do not work if bottom-up incidences are disabled.
\section modularity Modularity - Take only what you need
......@@ -98,7 +98,7 @@ between the geometry and topology of a mesh, such that the choice of whether a m
a geometric embedding or not is up to the user. This may save a lot of unnecessary memory
overhead in cases where only topological information of a mesh is needed.
The topology kernel implements only a minimal set of (intrinsic) operations on
a mesh such as adding/deleting entities, computing adjacency relations and instantiate
a mesh such as adding/deleting entities, computing incidence relations and instantiate
iterator objects. All other additional functions are provided by the so-called attribute classes
which are presented in the next section.
......
......@@ -7,13 +7,12 @@ of an entity, %OpenVolumeMesh provides a set of iterators and circulators. These
are entirely STL-compatible and can as such be used in all algorithms of the C++ standard
template library. We distinguish between two different kinds of iterators:
\li \b Intrinsic \b Iterators: Iterators that do not require bottom-up adjacencies to
\li \b Intrinsic \b Iterators: Iterators that do not require bottom-up incidences to
be computed.
\li \b Bottom-Up \b Adjacency \b Dependent \b Iterators: Iterators that need bottom-up
adjacencies to be computed before they can be used.
\li \b Bottom-Up \b Incidence \b Dependent \b Iterators: Iterators that need bottom-up
incidences to be computed before they can be used.
For information on bottom-up adjacencies, refer to Section \ref concepts. Bottom-up
adjacencies can be computed by calling OpenVolumeMesh::PolyhedralMesh::update_adjacencies().
For information on bottom-up incidences, refer to Section \ref concepts.
Note since %OpenVolumeMesh is an index-based data structure, the iterators encapsulate
\e handles to entities. Dereferencing an iterator thus never returns a reference to the
entity itself but only a handle to the entity.
......@@ -39,7 +38,7 @@ The following sections provide a concise overview of the iterators that come alo
Iterate over all vertices of a given cell.
\section adjacency_depending_iterators Bottom-Up Adjacency Dependent Iterators and Circulators
\section incidence_depending_iterators Bottom-Up Incidence Dependent Iterators and Circulators
\subsection general_iterators Iterators for General Polyhedral Meshes
......
......@@ -28,9 +28,9 @@ for(OpenVolumeMesh::HalfEdgeIter he_it = myMesh.halfedges_begin();
\endcode
In the next example, we iterate over all incident outgoing half-edges of a given
vertex. Note that this iterator needs bottom-up adjacencies which are
vertex. Note that this iterator needs bottom-up incidences which are
computed automatically per default. Otherwise, the iterator would not be valid.
See Section \ref bottom_up for information on the bottom-up adjacencies.
See Section \ref bottom_up for information on the bottom-up incidences.
\code
// Instantiate a polyhedral mesh
......
......@@ -63,7 +63,7 @@ void someFunction() {
Function OpenVolumeMesh::IO::FileManager::readFile() expects a total of four parameters,
two of which are mandatory (file name and mesh reference). The other two parameters
are optional flags that control whether bottom-up adjacencies should be computed automatically and
are optional flags that control whether bottom-up incidences should be computed automatically and
whether a topology check should be performed when adding faces and cells.
The two flags are turned on per default.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment