updated tutorial on reading and writing meshes with python bindings (Alexander Dielen)

git-svn-id: http://www.openmesh.org/svnrepo/OpenMesh/trunk@1217 fdac6126-5c0c-442c-9429-916003d36597

Doc/Examples/python_tutorial.py

@@ -130,3 +130,29 @@ for vh in mesh.vertices():
         prop_man[vh] += mesh.point(neighbor)
         valence += 1
     prop_man[vh] /= valence
+
+
+##################################################
+# I/O
+##################################################
+
+mesh = TriMesh()
+
+read_mesh(mesh, "bunny.obj")
+# modify mesh ...
+write_mesh(mesh, "bunny.obj")
+
+
+mesh = TriMesh()
+mesh.request_halfedge_normals()
+mesh.request_vertex_normals()
+
+options = Options()
+options += Options.VertexNormal
+
+result = read_mesh(mesh, "bunny.obj", options)
+
+if result:
+	print "everything worked"
+else:
+	print "something went wrong"

Doc/python_tutorial.docu

@@ -8,6 +8,7 @@ Bindings. We will cover the following topics:
 \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
+\li How to read and write meshes from files
 
 In addition, we will briefly discuss some of the differences between the Python
 Bindings and the original C++ implementation of %OpenMesh.
@@ -21,7 +22,8 @@ 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.
+\note Make sure that your Boost Python and Python versions match, i.e. that
+Boost Python was linked against the correct Python version.
 
 The Python Bindings are automatically build with %OpenMesh. For more information
 on how to build %OpenMesh see \ref compiling.
@@ -184,6 +186,62 @@ manager is garbage collected).
 
 
 
+\section python_io Read and write meshes from files
+
+You can read and write meshes from files using the read_mesh() and write_mesh()
+functions:
+
+\skipline mesh
+\until write_mesh(mesh, "bunny.obj")
+
+The file type is automatically deduced from the file extension. %OpenMesh
+currently supports four file types: .off, .obj, .stl and .om
+
+The behaviour of the I/O functions can be controlled by passing an instance of
+the Options class to either read_mesh() or write_mesh(). The class controls the
+behaviour of the I/O functions by means of enabled/disabled bits in a bitset:
+
+\skipline mesh
+\until print "something went wrong"
+
+Other available option bits include:
+
+-# mode bits - control binary reading/writing
+ - Options.Binary
+ - Options.MSB
+ - Options.LSB
+ - Options.Swap (MSB|LSB)
+-# property bits - controls which standard properties to read/write
+ - Options.VertexNormal
+ - Options.VertexTexCoord
+ - Options.VertexColor
+ - Options.FaceNormal
+ - Options.FaceColor
+ - Options.ColorAlpha
+ - Options.ColorFloat
+
+\note You have to pass an instance of the Options class to the I/O functions,
+i.e. you cannot directly pass one of the option bits. For example, directly
+passing Options.Binary to either one of the functions will cause an error.
+
+When reading a file the options are used as hints, i.e. depending on the format
+we can help the reader to interpret the data correctly.
+
+\note If you want to read a property from a file the property must have been
+requested prior to reading the file.
+
+When writing the mesh the mode bits control whether to use the binary variant of
+the respective file format and the desired byte-ordering.
+
+
+
+\section python_examples Additional Code Examples
+
+You can use our unit tests to learn more about the %OpenMesh Python Bindings.
+They are located in the src/Python/Unittests subdirectory.
+
+
+
 \section python_cpp Python and C++
 
 The interface of the Python Bindings is to a large extent identical to the