tutorial_05.docu 6.15 KB
Newer Older
Jan Möbius's avatar
Jan Möbius committed
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.

<table>
  <tr>
    <td>&nbsp;</td>
    <td>Vertex</td>
    <td>Face</td>
    <td>Edge</td>
    <td>Halfedge</td>
  </tr>
  <tr>
    <td>Color</td>
    <td>X</td>
    <td>X</td>
29
    <td>X</td>
Jan Möbius's avatar
Jan Möbius committed
30
31
32
33
34
35
36
    <td>&nbsp;</td>
  </tr>
  <tr>
    <td>Normal</td>
    <td>X</td>
    <td>X</td>
    <td>&nbsp;</td>
37
    <td>X</td>
Jan Möbius's avatar
Jan Möbius committed
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
  </tr>
  <tr>
    <td>Position <sup> (*) </sup> </td>
    <td>X</td>
    <td>&nbsp;</td>
    <td>&nbsp;</td>
    <td>&nbsp;</td>
  </tr>
  <tr>
    <td>Status</td>
    <td>X</td>
    <td>X</td>
    <td>X</td>
    <td>X</td>
  </tr>
  <tr>
    <td>TexCoord</td>
    <td>X</td>
    <td>&nbsp;</td>
    <td>&nbsp;</td>
58
    <td>X</td>
Jan Möbius's avatar
Jan Möbius committed
59
60
61
62
  </tr>
</table>

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's avatar
Jan Möbius committed
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 <sup>(*)</sup>. 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:

<ul>
<li>request_edge_status()</li>
111
<li>request_edge_colors()</li>
112
113
114
<li>request_face_colors()</li>
<li>request_face_normals()</li>
<li>request_face_status()</li>
115
<li>request_face_texture_index()</li>
116
<li>request_halfedge_status()</li>
117
<li>request_halfedge_normals()</li>
118
119
120
<li>request_halfedge_texcoords1D()</li>
<li>request_halfedge_texcoords2D()</li>
<li>request_halfedge_texcoords3D()</li>
121
122
123
<li>request_vertex_colors()</li>
<li>request_vertex_normals()</li>
<li>request_vertex_status()</li>
124
125
126
<li>request_vertex_texcoords1D()</li>
<li>request_vertex_texcoords2D()</li>
<li>request_vertex_texcoords3D()</li>
127
128
129
130
131
132
</ul>

Added properties can be released by the following functions:

<ul>
<li>release_edge_status()</li>
133
<li>release_edge_colors()</li>
134
135
136
<li>release_face_colors()</li>
<li>release_face_normals()</li>
<li>release_face_status()</li>
137
<li>release_face_texture_index()</li>
138
<li>release_halfedge_status()</li>
139
<li>release_halfedge_normals()</li>
140
141
142
<li>release_halfedge_texcoords1D()</li>
<li>release_halfedge_texcoords2D()</li>
<li>release_halfedge_texcoords3D()</li>
143
144
145
<li>release_vertex_colors()</li>
<li>release_vertex_normals()</li>
<li>release_vertex_status()</li>
146
147
148
<li>release_vertex_texcoords1D()</li>
<li>release_vertex_texcoords2D()</li>
<li>release_vertex_texcoords3D()</li>
149
150
</ul>

Mike Kremer's avatar
Mike Kremer committed
151
A property's existance can be tested with
152
153
154

<ul>
<li>has_edge_status()</li>
155
<li>has_edge_colors()</li>
156
157
158
<li>has_face_colors()</li>
<li>has_face_normals()</li>
<li>has_face_status()</li>
159
<li>has_face_texture_index()</li>
160
<li>has_halfedge_status()</li>
161
<li>has_halfedge_normals()</li>
162
163
164
<li>has_halfedge_texcoords1D()</li>
<li>has_halfedge_texcoords2D()</li>
<li>has_halfedge_texcoords3D()</li>
165
166
167
<li>has_vertex_colors()</li>
<li>has_vertex_normals()</li>
<li>has_vertex_status()</li>
168
169
170
<li>has_vertex_texcoords1D()</li>
<li>has_vertex_texcoords2D()</li>
<li>has_vertex_texcoords3D()</li>
171
172
173
174
175
176
177
</ul>

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's avatar
Jan Möbius committed
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's avatar
Jan Möbius committed
198
mesh.texcoord2D( _face_handle ) will result in an error when compiling
Jan Möbius's avatar
Jan Möbius committed
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

209
*/