MESH scene graph API

Introduction

The MESH scene graph is the re-ordered version of the X3D scene graph. Indeed it arranges topology informations in a more usable form. The MESH scene graph is based on winged-edge nodes. MESH nodes inherit the scene graph API of which description can be found here.

Moreover the scene graph is templated by the datas stored per vertex, edge, face and mesh, ensuring a fully customizable structure. We present here the form of a classical MESH scene graph and the interface of the different entities of a Mesh node.

The two important nodes of a MESH scene graph are X3DTK::MESH::Mesh and X3DTK::MESH::Vertex. They are container of the base entities: vertices, edges and faces.

An example of MESH scene graph

X3DandMESHSceneGraph.gif

fig 1: on the left, a typical X3D scene graph, on the right the translation into the MESH scene graph.

The translation of an X3D scene graph into a MESH scene graph conserves the global structure, but some differences are introduced. the X3DTK::X3D::IndexedFaceSet node is replaced by a template winged-edge node, X3DTK::MESH::Mesh, X3DTK::X3D::Coordinate is replaced by another template node: X3DTK::MESH::Vertex. The list of node attributes like X3DTK::X3D::Normal is removed, the information is placed into the template nodes.

Concerning the X3DTK::X3D::Appearance, the X3D sub-graph is cloned without translating it into a MESH node.

Notice that there is a difference between the X3DTK::X3D::Coordinate node and the X3DTK::MESH::Vertex. The former stores coordinates, the latter stores vertices. Indeed same 3D coordinates can lead to several vertices.

Base entities

The winged-edge structure is based on interdependant entities: vertex, edge and face. These entities are templated by datas that can be chosen by the user. Nevertheless each entity contains topological links with the neighboor entities.

Access

You can access a vertex object and its index:
// Default vertex (with default template datas) X3DTK::MESH::SFVertex *v; // User data vertex X3DTK::MESH::SFTemplateVertex<MyVertexData, MyEdgeData, MyFaceData, true> *gv; unsigned int i = v->getIndex();

The index is the same index present in the X3DTK::X3D::IndexedFaceSet. Template datas are explained later.

Topological part

Letīs see what kind of topological requests can be made. Here is an example of mesh:
faces_topology.gif
A face is made up of oriented edges which are defined by a from vertex and a to vertex. Here, the face f contains the edge e (counter-clock wise), of which from vertex is u and to vertex is v. When a face is created, new edges are created if they do not already exist. If a face is defined by the vertex list: A, B and C, then the oriented edges AB, BA, BC, CB, CA and AC exist. Nevertheless if you ask for the list of edges from the face, you will get AB, BC and CA.

From a vertex:

X3DTK::MESH::SFVertex *v; // Getting the rounding edges const typename X3DTK::MESH::SFVertex::MFEdge &me = v->getEdges();
faces_topology_v.gif
// Getting the rounding faces const typename X3DTK::MESH::SFVertex::MFFace &mf = v->getFaces();
faces_topology_f.gif
From an edge:
X3DTK::MESH::SFEdge *e; // Getting the symetric edge X3DTK::MESH::SFEdge *s = e->getSymetric();
faces_topology_s.gif
// Getting the from vertex X3DTK::MESH::SFVertex *from = e->getFromVertex(); // Getting the to vertex X3DTK::MESH::SFVertex *to = e->getToVertex();
faces_topology_fromto.gif
// Getting the right faces const typename X3DTK::MESH::SFEdge::MFFace &mf = e->getRightFaces();
faces_topology_r.gif
// Getting the left faces const typename X3DTK::MESH::SFEdge::MFFace &mf = e->getLeftFaces();
faces_topology_l.gif
// Getting all the faces. The method is inefficient and it is better to access // successively the left faces and the right faces. typename X3DTK::MESH::SFEdge::MFFace af = e->getFaces();
faces_topology_af.gif
From a face:
X3DTK::MESH::SFFace *f; // Getting the edges of the face const typename X3DTK::MESH::SFFace::MFEdge &me = f->getEdges();
faces_topology_ef.gif
// Getting the vertices of the face. This method is inefficient. typename X3DTK::MESH::SFFace::MFVertex vertices = f->getVertices(); // Getting the vertices of the face by getting the edges. Prefer this method. const typename X3DTK::MESH::SFFace::MFEdge &me = f->getEdges(); for (typename X3DTK::MESH::SFFace::MFEdge::const_iterator e = me.begin(); e != me.end(); ++e) { X3DTK::MESH::SFVertex *v = (*e)->getFromVertex(); ... }
faces_topology_vf.gif

Template datas

The MESH scene graph offers a special and innovative use of template datas per entity. Thus in our case, the template parameters represent datas stored per vertex, per edge or per face. A special framework based on atomic data aggregation by type list is developed.

Letīs take the example of vertex. A standard X3D file defines at most, a coordinate, a normal, a color and a texture coordinate per vertex. However you are a user of the library and you need to code an algorithm that only requires coordinates and normals. Colors and texture coordinates are useless and take overload memory. You want that vertices only store coordinate and normal information. The MESH scene graph is customizable and allows you to choose which information are stored per entity. Furthermore you can also define your own information per vertex, by adding a weight property for instance.

Using color, normal and weight:

// Defining a new information per vertex typedef clist<tlist<VertexPointData, tlist<VertexNormalData, tlist<VertexWeightData> > > > MyVertexData; // Using the template type X3DTK::MESH::SFTemplateVertex<MyVertexData, EdgeData, FaceData, true> *v; // Accessing the information MyVertexData &data = v->data(); // Accessing optionally the content of v inside a template function template<class MData, class VData, class EData, class FData, bool readOnly> void MyProcessor<MData, VData, EData, FData, readOnly>::enterVertex(TemplateVertex<VData, EData, FData, readOnly> *V) { SFTemplateVertex<VData, EData, FData, readOnly> *v; if (VData::template find<VertexWeightData>()) { VertexWeightData &w = v->template ogetData<MESH::VertexWeightData>(); // using w... } }

For a description of the default template datas, refer to the Default MESH entity data page.

Using the X3DTK::MESH::Mesh and X3DTK::MESH::Vertex nodes

X3DTK::MESH::Vertex

X3DTK::MESH::Vertex is the node containing a set of vertices and edges. These vertices and edges are used by X3DTK::MESH::Mesh to define faces.

You can access the list of vertices:

// Default Vertex node X3DTK::MESH::Vertex *V; // User data Vertex node X3DTK::MESH::TemplateVertex<MyVertexData, MyEdgeData, MyFaceData, true> *U; // Getting the vertices const Vertex::MFVertex &mv = V->getVertices(); const typename TemplateVertex<MyVertexData, MyEdgeData, MyFaceData, true>::MFVertex &mu = U->getVertices();

You can create a vertex entity:

// Default Vertex node X3DTK::MESH::Vertex *V; // Default vertex entity managed by the Vertex node X3DTK::MESH::SFVertex *v = V->createVertex(); // Setting attributes v->data().setPoint(SFVec3f(1.0f, -2.3f, 1.2f)); // Removing the vertex V->removeVertex(v);

X3DTK::MESH::Mesh

X3DTK::MESH::Mesh is the node defining a winged-edge. It contains a set of faces and oriented-edges.

You can access the list of faces and edges:

// Default Mesh X3DTK::MESH::Mesh *M; // Getting the faces const Mesh::MFVertex &mv = M->getFaces(); // Getting the edges const Mesh::MFEdge &me = M->getEdges();

You can create a face of vertices at index 0, 12 and 14 of the Vertex node:

// Default Mesh X3DTK::MESH::Mesh *M; MFInt32 mi; mi.push_back(0); mi.push_back(12); mi.push_back(14); X3DTK::MESH::SFFace *f = M->createFace(mi); // Removing the face M->removeFace(f);
You can see the meshCreation example, for the creation and deletion of faces.

Using X3DTK::MESH::Mesh and X3DTK::MESH::Vertex

An X3DTK::MESH::Vertex node can be shared by several X3DTK::MESH::Mesh nodes.

connectedCom.gif
V0 and V1 are shared by two X3DTK::MESH::Mesh nodes. It implies that when you traverse the first Mesh, iterate over its faces and ask for their neighbour faces, you will get F1 and F2 for F0. That is a property of the MESH scene graph: two X3DTK::MESH::Mesh nodes can be part of the same connected component and share vertices.

Examples

Here is the list of the examples where the MESH scene graph is used:
Generated on Fri Aug 27 13:16:25 2004 for X3DToolKit by doxygen 1.3.6