added documentation for cpp properties

docs/properties.rst

@@ -4,3 +4,64 @@ Properties
 **********
 
 TODO
+
+
+A Note to OpenFlipper Users
+###########################
+
+When using the OpenMesh Python Bindings within OpenFlipper, it is often
+necessary to pass data to one of the OpenFlipper plugins. Properties provide a
+straightforward way to do this. For example, we may wish to calculate a scalar
+vertex property using the python scripting interface and then visualize the
+result using OpenFlipper's PropertyVisualizer plugin.
+
+However, since all properties created using the mechanisms described above are
+stored as python objects, most existing OpenFlipper plugins will not know how to
+interpret them. To circumvent this problem, OpenFlipper users can create native
+C++ properties by calling :func:`~openmesh.TriMesh.add_vertex_cpp_property`,
+:func:`~openmesh.TriMesh.add_halfedge_cpp_property`,
+:func:`~openmesh.TriMesh.add_edge_cpp_property` and
+:func:`~openmesh.TriMesh.add_face_cpp_property` respectively.
+
+For example,
+
+.. code:: python
+
+	mesh.add_vertex_cpp_property("my_double_property", "double")
+
+will create a vertex property with the name "my_double_property" and type
+``double``. In addition to ``double``, the following C++ types are currently
+supported: ``bool``, ``int``, ``float``, ``double``, ``vec2f``, ``vec3f``,
+``vec4f``, ``vec2d``, ``vec3d``, ``vec4d``
+
+Native C++ properties can be set like any other property, i.e.
+
+.. code:: python
+
+	mesh.set_vertex_property("my_double_property", om.VertexHandle(0), 42.0)
+
+will attempt to set the property for vertex 0 by converting the given value
+(here 42.0) to a native ``double``. In case the conversion fails, a
+``ValueError`` exception is thrown. Similarly,
+
+.. code:: python
+
+	mesh.vertex_property("my_double_property", om.VertexHandle(0))
+
+will retrieve the property for vertex 0.
+
+As before, :func:`~openmesh.TriMesh.has_vertex_property`,
+:func:`~openmesh.TriMesh.has_halfedge_property`,
+:func:`~openmesh.TriMesh.has_edge_property` and
+:func:`~openmesh.TriMesh.has_face_property` can be used to check if a property
+with the given name already exists, while
+:func:`~openmesh.TriMesh.remove_vertex_property`,
+:func:`~openmesh.TriMesh.remove_halfedge_property`,
+:func:`~openmesh.TriMesh.remove_edge_property` and
+:func:`~openmesh.TriMesh.remove_face_property`
+can be used to remove a property.
+
+.. caution:: When using the OpenMesh Python Bindings within OpenFlipper,
+    internal properties such as ``v:points`` and ``v:normals``, which store the
+    vertex coordinates and normals respectively, are exposed to python. Do not
+    remove these properties!