From 4613850d8e24b6358e5fbf40013abc5d5c89fe4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20M=C3=B6bius?= Date: Tue, 16 Sep 2014 11:15:01 +0000 Subject: [PATCH] Python Docu git-svn-id: http://www.openmesh.org/svnrepo/OpenMesh/trunk@1170 fdac6126-5c0c-442c-9429-916003d36597 --- Doc/python_tutorial.docu | 212 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 Doc/python_tutorial.docu diff --git a/Doc/python_tutorial.docu b/Doc/python_tutorial.docu new file mode 100644 index 00000000..055acc0d --- /dev/null +++ b/Doc/python_tutorial.docu @@ -0,0 +1,212 @@ +/** \page python_tutorial Python Tutorial + +This tutorial will introduce the basic concepts behind the %OpenMesh Python +Bindings. We will cover the following topics: + +\li How to build the Python Bindings +\li How to create an empty mesh +\li How to add vertices and faces to a mesh +\li How to navigate on a mesh using iterators and circulators +\li How to add and remove custom properties + +In addition, we will briefly discuss some of the differences between the Python +Bindings and the original C++ implementation of %OpenMesh. + + + +\section python_build Building the Python Bindings + +The Python Bindings depend on the following libraries: + +\li Python (2.7 or later) +\li Boost Python (1.54.0 or later) + +\note Make sure that your Python and Boost Python versions match. + +The Python Bindings are automatically build with %OpenMesh. For more information +on how to build %OpenMesh see \ref compiling. + + + +\section python_start Getting Started + +To use the %OpenMesh Python Bindings we first need to import the openmesh module: + +\dontinclude python_tutorial.py +\skipline from + +The module provides two mesh classes: One for polygonal meshes (PolyMesh) and +one for triangle meshes (TriMesh). You should use triangle meshes whenever +possible, since they are usually more efficient. In addition, some algorithms +are only implemented for triangle meshes while triangle meshes inherit the full +functionality of polygonal meshes. + +The following code creates a new triangle mesh: + +\skipline mesh + + + +\section python_add Adding Items to a Mesh + +We can add a new vertex to the mesh by calling the add_vertex() member function. +This function gets a coordinate and returns a handle to the newly inserted +vertex. + +\skipline vh0 +\until vh4 + +To add a new face to the mesh we have to call add_face(). This function gets the +handles of the vertices that make up the new face and returns a handle to the +newly inserted face: + +\skipline fh0 +\until fh2 + +We can also use a Python list to add a face to the mesh: + +\skipline vh_list +\until fh3 + + + +\section python_iterators Iterators and Circulators + +Now that we have added a couple of vertices to the mesh, we can iterate over +them and print out their indices: + +\skipline for +\until vh.idx() + +We can also iterate over halfedges, edges and faces by calling mesh.halfedges(), +mesh.edges() and mesh.faces() respectively: + +\skipline iterate +\until fh.idx() + +To iterate over the items adjacent to another item we can use one of the +circulator functions. For example, to iterate over the vertices adjacent to +another vertex we can call mesh.vv() and pass the handle of the center vertex: + +\skipline for +\until vh.idx() + +We can also iterate over the adjacent halfedges, edges and faces: + +\skipline iterate +\until fh.idx() + +To iterate over the items adjacent to a face we can use the following functions: + +\skipline iterate +\until fh.idx() + + + +\section python_props Properties + +%OpenMesh allows us to dynamically add custom properties to a mesh. We can add +properties to vertices, halfedges, edges, faces and the mesh itself. To +add a property to a mesh (and later access its value) we have to use a property +handle of the appropriate type: + +\li VPropHandle (for vertex properties) +\li HPropHandle (for halfedge properties) +\li EPropHandle (for edge properties) +\li FPropHandle (for face properties) +\li MPropHandle (for mesh properties) + +The following code shows how to add a vertex property to a mesh: + +\skipline prop_handle +\until mesh + +The second parameter of the function add_property() is optional. The parameter +is used to specify a name for the new property. This name can later be used +to retrieve a handle to the property using the get_property_handle() member +function. + +Now that we have added a vertex property to the mesh we can set and get its +value. Here we will use the property to store the center of gravity of each +vertex' neighborhood: + +\skipline for +\until mesh.set_property + +Properties use Python's type system. This means that we can use the same +property to store values of different types (e.g. store both strings and +integers using the same vertex property). Properties are initialized to the +Python built-in constant None. + +To remove a property we have to call remove_property() with the appropriate +property handle: + +\skipline mesh.remove_property + + + +\section python_propman Property Managers + +Another way to add and remove a property is to use a property manager. A +Property manager encapsulates a property and manages its lifecycle. A Property +manager also provides a number of convenience functions to access the enclosed +property. + +There are four different types of property managers. One for each type of mesh +item: + +\li VPropertyManager (for vertex properties) +\li HPropertyManager (for halfedge properties) +\li EPropertyManager (for edge properties) +\li FPropertyManager (for face properties) + +Property managers automatically add a new property to a mesh when they are +initialized. Thus the following code not only creates a new vertex property +manager, but also adds a new vertex property to the mesh: + +\skipline prop_man + +Property managers allow us to conveniently set the property value for an entire +range of mesh items: + +\skipline prop_man + +They also allow us to use the subscript operator to set and get property values. +Here we will once again use a property to store the center of gravity of each +vertex' neighborhood: + +\skipline for +\until prop_man[vh] /= valence + +Properties that are encapsulated by a property manager are automatically removed +from the mesh when the property manager goes out of scope (i.e. the property +manager is garbage collected). + + + +\section python_cpp Python and C++ + +The interface of the Python Bindings is to a large extent identical to the +interface of the original C++ implementation of %OpenMesh. You should therefore +be able to use the C++ documentation as a reference for the Python Bindings. In +particular, the classes KernelT, PolyMeshT and TriMeshT provide a good overview +of the available mesh member functions. That being said, there are a number of +small differences. For example, whenever the C++ implementation returns a +reference to an object that is managed by %OpenMesh, the Python Bindings will +return a copy of that object. This is due to the fact that Python does not have +a language feature that is analogous to C++ references. One example of such a +function is the point() member function of the PolyMesh and TriMesh classes. +Unlike its C++ counterpart, the function does not return a reference to the +requested point. It instead returns a copy of the point. This implies that you +have to use the set_point() member function to change the value of a point. The +same applies to the following functions: normal(), color(), property(), +status(), etc. + + + +
The complete source looks like this: + +\include python_tutorial.py + + +**/