WebSVN – gelsvn – Diff – /branches/cpp11-devel/doc/intro.tex

   Vec3f p2 = p0 + p1;
   p2 += p1; // Same as p2 = p2 + p1
 \end{verbatim}
 Thus both the normal form of \texttt{+} and the assignment form are supported for \texttt{Vec3f}. The same is true of the other arithmetic operators \texttt{-*/} and the operators are supported for most  CGLA entities including all matrix and vector types.
-Multiplication is also supported for matrix vector products:
+Multiplication is also supported for matrix vector products. Below an example with 4D double precision vector and matrix:
 \begin{verbatim}
-  Vec4d p0(1,1,0,1);
+  Vec4d x(1,1,0,1);
   Mat4x4d m = rotation_Mat4x4d(ZAXIS, 3.14);
-  Vec4d p1 = m * p0;
+  Vec4d y = m * x;
 \end{verbatim}
 but all vectors are column vectors, so only right multiplication is supported. We cannot multiply a vector on the left side of a matrix. However, there is, of course, a \texttt{dot} function which computes the dot product of two vectors.
 A very common operation is to compute the normal of a triangle from
                    [&](VertexID v){ p += m.pos(v); });
         return p / n;
 \end{verbatim}
 Here the function \texttt{circulate\_vertex\_ccw} takes three arguments. The \texttt{Manifold}, \texttt{m}, and the vertex, \texttt{v}, around which we circulate, and, finally, a function that accepts a \texttt{VertexID}. This function gets called for every vertex adjacent to \texttt{v}. In this example, the function is given as a so called \textit{lambda} function. This allows us to write things compactly and to have the body of the function where it is needed. We could also have passed a function which accepts a \texttt{FaceID} or a \texttt{HalfEdgeID} or a \texttt{Walker}. Thus, we can visit incident faces and edges during circulation if that is what we need, and if we need go get some entity other than adjacent vertices, edges, or faces, we can use the \texttt{Walker} option which is the most generic.
-To summarize there are three datatypes that we use to refer to mesh entitites.
+To sum up, there are two datatypes that we use to refer to mesh entitites.
 \begin{itemize}
 \item IDs \texttt{VertexID}, \texttt{HalfEdgeID}, and \texttt{FaceID} are simply indices. These types are what we use when calling functions that take arguments which refer to mesh entities.
-\item ID iterators \texttt{VertexIDIterator}, \texttt{HalfEdgeIDIterator}, and\\ \texttt{FaceIDIterator} as their names imply can be used to iterate over the entities of a mesh. As such they reflect how the mesh is stored in memory. Dereferencing an ID iterator will give an ID.
 \item \texttt{Walker} is used to walk from halfedge to halfedge on the mesh. It utilizes the references stored in halfedges to other halfedges in order to facilitate this traversal. Again, we can obtain an ID from a walker.
 \end{itemize}
-It might seem tiresome that you have to deal with three different methods for referring to mesh entities, but they do very different jobs. The IDs are simply indices (wrapped in a class) referring to mesh elements. The iterators combine this indices with a reference to the actual data structures. The walker contains functions that allow us to move from halfedge to halfedge and additionally keeps track of the starting point and number of steps taken.
+It might seem tiresome that you have to deal with two different methods for referring to mesh entities, but they do very different jobs. The IDs are simply indices (wrapped in a class) referring to mesh elements. The walker contains functions that allow us to move from halfedge to halfedge and additionally keeps track of the starting point and number of steps taken. In fact there are also three iterator classes, but we do not mention them, because the user does not need them; they are only a tool which allows for loops that visit all faces, edges, or vertices.
-We could have combined two or all three of these concepts, but would have led to rather bloated datatypes.
 \subsection{Attributes}
 Given a \texttt{VertexID},  \texttt{v}, and a \texttt{Manifold}, \texttt{m}, we can obtain the geometric position of the vertex with the method call \texttt{m.pos(v)}. If is fairly important to note that a reference to the position is returned. Thus, we can assign the position of a vertex:
 \begin{verbatim}
 Vec3d p;
 VertexAttributeVector<T> vertex_attrib_vector;
 FaceAttributeVector<T> face_ttrib_vector;
 HalfEdgeAttributeVector<T> halfedge_attrib_vector;
 \end{verbatim}
 where \texttt{T} is a typename. Attribute vectors are indexed with indices. Thus, a
-\texttt{VertexAttributeVector} is indexed with a \texttt{VertexID} and likewise for the other types. To give a simple example of how this is used consider smoothing a mesh. The simplest way of smoothing is to replace the vertex with the average of its neighbors. However, if we copy the average value back before the average value for some neighbor has been computed, then we clearly use one average to compute another average and thereby introduce an unfortunate dependence on the ordering of the vertices. Consequently, we need to first compute all of the averages and then update the original vertices. The code looks as follows:
+\texttt{VertexAttributeVector} is indexed with a \texttt{VertexID} and likewise for the other types.
 \begin{verbatim}
+VertexAttributeVector<Vec3d> my_attrib;
+VertexID v;
+// assign some vertex ID to v
+my_attrib[v] = Vec3d(1,2,3);
+\end{verbatim}
-void smooth(Manifold& m, float t)
+To give a simple example of how this is used consider smoothing a mesh. The simplest way of smoothing is to replace the vertex with the average of its neighbors. However, if we copy the average value back before the average value for some neighbor has been computed, then we clearly use one average to compute another average and thereby introduce an unfortunate dependence on the ordering of the vertices. Consequently, we need to first compute all of the averages and then update the original vertices. What we do is to copy \textit{all} vertex positions to a new attribute vector. Then we compute a new position for each vertex storing it in the new attribute vector. Finally, we copy the positions back. Some complexity is due to the treatment of boundaries. Boundary vertices are not smoothed in this example. However, since we have copied the old vertex positions to the new attribute vector this means that boundary vertices are simply left where they are. The code looks as follows:
+\begin{verbatim}
+void laplacian_smooth_example(Manifold& m)
-    {
+{
-        VertexAttributeVector<Vec3f> pos(m.total_vertices());
+    VertexAttributeVector<Vec3d> new_pos =
+        m.positions_attribute_vector();
-        for(VertexIDIterator v = m.vertices_begin();
+    for(VertexID v : m.vertices())
-              v != m.vertices_end(); ++v)
+        if(!boundary(m, v))
+        {
-            if(!boundary(m, *v))
-            {
-          Vec3f avg_pos(0);
+            Vec3d L(0);
-          Walker w = m.walker(v)
-            for(; !w.full_circle(); w = w.circulate_vertex_cw())
+            int n = circulate_vertex_ccw(m,v,
-                avg_pos += m.pos(w.vertex());
+                [&](VertexID v){
-                pos[*v] =  avg_pos / w.no_steps();
+                    L += m.pos(v);
-             }
+            });
-        }
-        for(VertexIDIterator v = m.vertices_begin();
-              v != m.vertices_end(); ++v){
-            if(!boundary(m, *v))
-                m.pos(*v) = pos[*v];
+            new_pos[v] = L/n;
+        }
+   m.positions_attribute_vector() = new_pos;
-    }
+}
 \end{verbatim}
-In the smoothing example the \texttt{VertexAttributeVector} containing the new positions is initialized to a size equal to the actual number of vertices. That is not strictly necessary since the attribute vectors automatically resize if the index stored in the ID is out of bounds. Thus, we never explicitly need to increase the size of an attribute vector. What if there are suddenly fewer vertices? In that case, we can clean up the attribute vector. However, we also need to clean up the manifold. The procedure looks as follows:
+What if we were to write to a position in the attribute vector which did not contain a value? For instance, what happens if we add vertices to the mesh, somehow, and then assign attribute values to the added vertices. One would hope that the attribute vector is resized automatically, and that is the case, fortunately. Thus, we never explicitly need to increase the size of an attribute vector. What if there are suddenly fewer vertices? In that case, we can clean up the attribute vector. However, we also need to clean up the manifold. The procedure looks as follows:
 \begin{verbatim}
 VertexAttributeVector<T> vertex_attrib_vector;
 Manifold m;
 // ....
 vertex_attrib_vector.cleanup(remap);
 \end{verbatim}
 Calling \texttt{cleanup} on the \texttt{Manifold} removes unused mesh entities, resizes, and resize the vectors containing these entities. When we subsequently call cleanup on the attribute vector, the same reorganization is carried out on the attribute vector keeping it in sync. Strictly speaking cleanup is rarely needed, but it removes unused memory which can be a performance advantage.
 \subsection{Extended Example: Edge Flipping}
-The following example demonstrates how to create a \texttt{Manifold} and add polygons (in this case triangles) and finally how to flip edges of a manifold. First, let us define some vertices
+The following example demonstrates how to create a \texttt{Manifold} and add polygons (in this case triangles) and finally how to flip edges of a manifold. First, let us define some vertices. This is just a vector of 3D points:
 \begin{verbatim}
   vector<Vec3f> vertices(3);
   vertices[0] = p1;
   vertices[1] = p2;
   vertices[2] = p3;

Subversion Repositories gelsvn

(root)/branches/cpp11-devel/doc/intro.tex @ 633 – Rev 633 → 635