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. ...@@ -13,18 +13,18 @@ Welcome to the %OpenVolumeMesh documentation.
meshes. Its concepts are closely related to OpenMesh (http://www.openmesh.org). In particular, 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 %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. 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 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 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 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, 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 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 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 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 adjacency relations have to be computed explicitly which 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 adjacency relations, the top-down and the bottom-up can be performed in linear time complexity. Both incidence relations, the top-down and the bottom-up
adjacencies, are used to provide a set of iterators and circulators that are comfortable in use. 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 As in OpenMesh, %OpenVolumeMesh provides an entirely generic underlying property system that allows
attaching properties of any kind to the entities. attaching properties of any kind to the entities.
......
...@@ -8,7 +8,7 @@ The concepts of %OpenVolumeMesh are closely related to those of %OpenMesh (http: ...@@ -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. 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 %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 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 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). 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. 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 ...@@ -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. set of polyhedra, %OpenVolumeMesh extends the set of entities by \e cells.
But unlike in the original idea of half-edge data structure, But unlike in the original idea of half-edge data structure,
in %OpenVolumeMesh all entities are stored in arrays (STL vectors) rather than 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 has the major advantage that the data structure can handle configurations that are
not three-manifold (since this is desired in some applications). 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 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. ...@@ -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." \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 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 (intrinsic) top-down incidences and
\li the bottom-up adjacencies. \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, 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 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 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 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. that address all adjacent lower-dimensional entities of a given reference entity.
Read more on iterators and circulators in Section \ref iterators_and_circulators. Read more on iterators and circulators in Section \ref iterators_and_circulators.
Figure 2 illustrates this hierarchy. Figure 2 illustrates this hierarchy.
\image html volume_mesh_hierarchy.png "Figure 2. Each entity is defined as a tuple of lower-dimensional entities." \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 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: following information for the respective entity type in additional caches:
\li \b Vertex: A list of all outgoing half-edges. \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-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. \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 These incidence relations are computed automatically for each affected entity
when adding/deleting it. In most cases these adjacencies are needed since many when adding/deleting it. In most cases these incidences are needed since many
iterators/circulators rely on them. Storing this additional information consumes iterators/circulators rely on them. Storing this additional information consumes
extra memory that scales linearly with the mesh's complexity. extra memory that scales linearly with the mesh's complexity.
However, in case these adjacency relations are not needed (e.g. in numerical analysis 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_adjacencies() 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 adjacencies and passing false as parameter. Also it is possible to enable bottom-up incidences
for single entity types, just call the following functions: for single entity types, just call the following functions:
\li TopologyKernel::enable_vertex_bottom_up_adjacencies() \li TopologyKernel::enable_vertex_bottom_up_incidences()
\li TopologyKernel::enable_edge_bottom_up_adjacencies() \li TopologyKernel::enable_edge_bottom_up_incidences()
\li TopologyKernel::enable_face_bottom_up_adjacencies() \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 while at the same time keeping the data structure as compact as possible
allocating only a minimum of storage overhead. 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 \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 ...@@ -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 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. overhead in cases where only topological information of a mesh is needed.
The topology kernel implements only a minimal set of (intrinsic) operations on 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 iterator objects. All other additional functions are provided by the so-called attribute classes
which are presented in the next section. which are presented in the next section.
......
...@@ -7,13 +7,12 @@ of an entity, %OpenVolumeMesh provides a set of iterators and circulators. These ...@@ -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 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: 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. be computed.
\li \b Bottom-Up \b Adjacency \b Dependent \b Iterators: Iterators that need bottom-up \li \b Bottom-Up \b Incidence \b Dependent \b Iterators: Iterators that need bottom-up
adjacencies to be computed before they can be used. incidences to be computed before they can be used.
For information on bottom-up adjacencies, refer to Section \ref concepts. Bottom-up For information on bottom-up incidences, refer to Section \ref concepts.
adjacencies can be computed by calling OpenVolumeMesh::PolyhedralMesh::update_adjacencies().
Note since %OpenVolumeMesh is an index-based data structure, the iterators encapsulate 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 \e handles to entities. Dereferencing an iterator thus never returns a reference to the
entity itself but only a handle to the entity. 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 ...@@ -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. 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 \subsection general_iterators Iterators for General Polyhedral Meshes
......
...@@ -28,9 +28,9 @@ for(OpenVolumeMesh::HalfEdgeIter he_it = myMesh.halfedges_begin(); ...@@ -28,9 +28,9 @@ for(OpenVolumeMesh::HalfEdgeIter he_it = myMesh.halfedges_begin();
\endcode \endcode
In the next example, we iterate over all incident outgoing half-edges of a given 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. 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 \code
// Instantiate a polyhedral mesh // Instantiate a polyhedral mesh
......
...@@ -63,7 +63,7 @@ void someFunction() { ...@@ -63,7 +63,7 @@ void someFunction() {
Function OpenVolumeMesh::IO::FileManager::readFile() expects a total of four parameters, 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 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. whether a topology check should be performed when adding faces and cells.
The two flags are turned on per default. 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