tutorial_05.docu 6.15 KB
 Jan Möbius committed Feb 06, 2009 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 /** \page tutorial_05 Using standard properties This example shows: - How to add and remove a standard property, - How to get and set the value of a standard property. As we already have seen, we can bind additional data to the mesh entities by means of properties. %OpenMesh provides a set of so-called standard properties. Unlike the custom properties these have some special features and a different interface, which are the matter in this tutorial. The following table lists all available standard properties and the suitable entity for which it can be used.
Vertex Face Edge Halfedge
Color X XX
Normal X X  X
Position (*) X
Status X X X X
TexCoord X    X
 Mike Kremer committed Jan 21, 2010 29   Jan Möbius committed Feb 06, 2009 30 31 32 33 34 35 36   Jan Möbius committed Jan 20, 2012 37   Jan Möbius committed Feb 06, 2009 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57   Jan Möbius committed Jan 20, 2012 58   Jan Möbius committed Feb 06, 2009 59 60 61 62  To add a standard property to an entity simply use the appropriate  63 request method, e.g. \c request_face_normals(). The only exception is  Jan Möbius committed Feb 06, 2009 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 the position (*). It cannot be added because it is permanently available, hence it cannot be removed as well. In this example we -# add vertex normals to a mesh object -# load a file -# check if the file provides vertex normals and calculate them if not -# move every vertex one unit length along its normal direction -# print the resulting positions to std::cout Let's start with adding vertex normals to the mesh: \dontinclude 05-std_properties/properties.cc \skipline request_vertex_normals In a similar manner we can request the other standard properties. For example the face normals: \skipline request_face_normals We need them to calculate the vertex normals with \c update_normals(), if the file didn't provide any. But we can do more with standard properties. We can verify if the mesh has already the property vertex normals \dontinclude 05-std_properties/properties.cc \skipline has_vertex_normals \until } And after usage we remove them again \skipline release_vertex_normals But, what happens if for example the vertex status property has been requested twice? Then the first release does nothing, but the second one will remove it. The standard properties have a reference counter, which is incremented by one for each request and decremented by one for each release. If the counter reaches 0 the property will be removed from memory.  105 106 107 108 109 110 As we have seen in the table above, we have 9 dynamically requestable properties. The request functions as defined in OpenMesh::Concepts::KernelT are:
• request_edge_status()
•  Mike Kremer committed Jan 21, 2010 111 
• request_edge_colors()
•  112 113 114 
• request_face_colors()
• request_face_normals()
• request_face_status()
•  Mike Kremer committed Jul 28, 2009 115 
• request_face_texture_index()
•  116 
• request_halfedge_status()
•  Jan Möbius committed Jan 20, 2012 117 
• request_halfedge_normals()
•  Mike Kremer committed Jul 28, 2009 118 119 120 
• request_halfedge_texcoords1D()
• request_halfedge_texcoords2D()
• request_halfedge_texcoords3D()
•  121 122 123 
• request_vertex_colors()
• request_vertex_normals()
• request_vertex_status()
•  Mike Kremer committed Jul 28, 2009 124 125 126 
• request_vertex_texcoords1D()
• request_vertex_texcoords2D()
• request_vertex_texcoords3D()
•  127 128 129 130 131 132 
Added properties can be released by the following functions:
• release_edge_status()
•  Mike Kremer committed Jan 21, 2010 133 
• release_edge_colors()
•  134 135 136 
• release_face_colors()
• release_face_normals()
• release_face_status()
•  Mike Kremer committed Jul 28, 2009 137 
• release_face_texture_index()
•  138 
• release_halfedge_status()
•  Jan Möbius committed Jan 20, 2012 139 
• release_halfedge_normals()
•  Mike Kremer committed Jul 28, 2009 140 141 142 
• release_halfedge_texcoords1D()
• release_halfedge_texcoords2D()
• release_halfedge_texcoords3D()
•  143 144 145 
• release_vertex_colors()
• release_vertex_normals()
• release_vertex_status()
•  Mike Kremer committed Jul 28, 2009 146 147 148 
• release_vertex_texcoords1D()
• release_vertex_texcoords2D()
• release_vertex_texcoords3D()
•  149 150 
 Mike Kremer committed Jul 28, 2009 151 A property's existance can be tested with  152 153 154 
• has_edge_status()
•  Mike Kremer committed Jan 21, 2010 155 
• has_edge_colors()
•  156 157 158 
• has_face_colors()
• has_face_normals()
• has_face_status()
•  Mike Kremer committed Jul 28, 2009 159 
• has_face_texture_index()
•  160 
• has_halfedge_status()
•  Jan Möbius committed Jan 20, 2012 161 
• has_halfedge_normals()
•  Mike Kremer committed Jul 28, 2009 162 163 164 
• has_halfedge_texcoords1D()
• has_halfedge_texcoords2D()
• has_halfedge_texcoords3D()
•  165 166 167 
• has_vertex_colors()
• has_vertex_normals()
• has_vertex_status()
•  Mike Kremer committed Jul 28, 2009 168 169 170 
• has_vertex_texcoords1D()
• has_vertex_texcoords2D()
• has_vertex_texcoords3D()
•  171 172 173 174 175 176 177 
which return true if a property has been requested before and is available. The status property is used for marking geometry elements i.e. as selected or deleted. See \ref tutorial_07b for further information.  Jan Möbius committed Feb 06, 2009 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 Now we know how to add and remove standard properties, but how do we access them? Again we need the mesh object. Unlike the custom properties, where we accessed one with the mesh member function \c property(), for each standard property the mesh provides a get and a set method. We have used one pair of get/set methods already in the previous three tutorials, where we computed a new location for the vertex position. Here we move all vertices a unit length along their normal direction: \dontinclude 05-std_properties/properties.cc \skipline MyMesh::VertexIter \until { \skipline mesh.set_point \skipline } The get-methods take an entity handle and return the value of the desired property, and the set-methods require an additional parameter to pass the new value to the property. According to the table not every pair of get/set-methods apply to every entity. For example a face has normally no texture coordinates, hence a call to \c  Jan Möbius committed Jul 15, 2010 198 mesh.texcoord2D( _face_handle ) will result in an error when compiling  Jan Möbius committed Feb 06, 2009 199 200 201 202 203 204 205 206 207 208 the code. Since we know how to add/remove/access standard properties, one further question remains. What data types do they have? And are there more hidden secrets? The next tutorial (\ref tutorial_06) will give the answer. The complete source looks like this: \include 05-std_properties/properties.cc  Mike Kremer committed Jan 21, 2010 209 */