MeshKernel.hh 17 KB
Newer Older
Jan Möbius's avatar
Jan Möbius committed
1
//=============================================================================
2 3 4 5 6
//
//                               OpenMesh
//      Copyright (C) 2001-2005 by Computer Graphics Group, RWTH Aachen
//                           www.openmesh.org
//
Jan Möbius's avatar
Jan Möbius committed
7
//-----------------------------------------------------------------------------
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
//
//                                License
//
//   This library is free software; you can redistribute it and/or modify it
//   under the terms of the GNU Library General Public License as published
//   by the Free Software Foundation, version 2.
//
//   This library is distributed in the hope that it will be useful, but
//   WITHOUT ANY WARRANTY; without even the implied warranty of
//   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
//   Library General Public License for more details.
//
//   You should have received a copy of the GNU Library General Public
//   License along with this library; if not, write to the Free Software
//   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
//
Jan Möbius's avatar
Jan Möbius committed
24
//-----------------------------------------------------------------------------
25
//
Jan Möbius's avatar
Jan Möbius committed
26 27
//   $Revision$
//   $Date$
28
//
Jan Möbius's avatar
Jan Möbius committed
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
//=============================================================================


//=============================================================================
//
//  Kernel Concept
//
//=============================================================================


#error this file is for documentation purposes only


//== NAMESPACES ===============================================================


namespace OpenMesh {
namespace Concepts {


//== CLASS DEFINITION =========================================================


/** \ingroup mesh_concepts_group
53
    This class describes the minimum interface a mesh kernel
Jan Möbius's avatar
Jan Möbius committed
54 55 56 57 58 59 60 61 62 63 64 65 66
    has to implement (because the resulting mesh will rely on
    this interface).

    This is the template class the actually holds the mesh kernel
    implementation. All functions marked as internal should only be used
    by the mesh class (that inherits the kernel). The mesh may then
    provide wrapper functions that provide the same functionality.

    \todo Check, if the member list is complete.
*/
template <class FinalMeshItems> class KernelT
{
public:
67

Jan Möbius's avatar
Jan Möbius committed
68 69 70 71 72 73 74 75 76 77 78 79 80
  /// \name Mesh Items
  //@{

  /// Derive this type from the FinalMeshItems
  typedef typename FinalMeshItems::Vertex             Vertex;
  typedef typename FinalMeshItems::Halfedge           Halfedge;
  typedef typename FinalMeshItems::Edge               Edge;
  typedef typename FinalMeshItems::Face               Face;
  typedef typename FinalMeshItems::Point              Point;
  typedef typename FinalMeshItems::Scalar             Scalar;
  typedef typename FinalMeshItems::Normal             Normal;
  typedef typename FinalMeshItems::Color              Color;
  typedef typename FinalMeshItems::TexCoord           TexCoord;
81 82 83 84
  typedef typename FinalMeshItems::VertexHandle       VertexHandle;
  typedef typename FinalMeshItems::HalfedgeHandle     HalfedgeHandle;
  typedef typename FinalMeshItems::EdgeHandle         EdgeHandle;
  typedef typename FinalMeshItems::FaceHandle         FaceHandle;
Jan Möbius's avatar
Jan Möbius committed
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112

  //@}


  /// \name Kernel Iterators
  //@{
  /// This type depends on the container type in use.
  typedef SomeIterator KernelVertexIter;
  typedef SomeIterator KernelConstVertexIter;
  typedef SomeIterator KernelEdgeIter;
  typedef SomeIterator KernelConstEdgeIter;
  typedef SomeIterator KernelFaceIter;
  typedef SomeIterator KernelConstFaceIter;
  //@}

  /// \name Constructor/Destructor
  //@{
  /// Default constructor
  KernelT() {}

  /// Destructor
  ~KernelT();
  //@}

  /// Assignment operator
  KernelT& operator=(const KernelT& _rhs);


113
  /** Reserve memory for vertices, edges, faces.
Jan Möbius's avatar
Jan Möbius committed
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
   *
   *  Reserve memory for the mesh items vertices, edges, faces.  Use
   *  this method if you can estimate the memory consumption, for
   *  instance in algorithm expanding the mesh. Depending on the
   *  underlying array type you might be better of using this method,
   *  then letting the array type decide when to increase the
   *  capacity. For instance the STL vector class \c std::vector (used
   *  in the supplied ArrayKernelT) doubles the capacity if it is
   *  exhausted. This might lead to an memory allocation exception,
   *  though an smaller increment would be enough.
   */
  void reserve( unsigned int _n_vertices,
		unsigned int _n_edges,
		unsigned int _n_faces );

129 130

  /// \name Handle -> Item.
Jan Möbius's avatar
Jan Möbius committed
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
  //@{
  /// Translate handle to item (see also OpenMesh::PolyMeshT::deref())
  const Vertex& vertex(VertexHandle _h) const { return deref(_h); }
  Vertex& vertex(VertexHandle _h) { return deref(_h); }
  const Halfedge& halfedge(HalfedgeHandle _h) const { return deref(_h); }
  Halfedge& halfedge(HalfedgeHandle _h) { return deref(_h); }
  const Edge& edge(EdgeHandle _h) const { return deref(_h); }
  Edge& edge(EdgeHandle _h) { return deref(_h); }
  const Face& face(FaceHandle _h) const { return deref(_h); }
  Face& face(FaceHandle _h) { return deref(_h); }
  //@}


  /// \name Item -> Handle
  //@{
  /// Translate item to handle
  VertexHandle handle(const Vertex& _v) const;
  HalfedgeHandle handle(const Halfedge& _he) const;
  EdgeHandle handle(const Edge& _e) const;
  FaceHandle handle(const Face& _f) const;
  //@}


  /// \name Get the i'th item
  //@{
  /// Get the i'th item
  VertexHandle   vertex_handle(unsigned int _i) const;
  HalfedgeHandle halfedge_handle(unsigned int _i) const;
  EdgeHandle     edge_handle(unsigned int _i) const;
  FaceHandle     face_handle(unsigned int _i) const;
  //@}


  /// \name Delete items
  //@{
  /// Delete all items, i.e. clear all item containers.
  void clear();
  /** Remove all items that are marked as deleted from the
      corresponding containers.
      \note Needs the Attributes::Status attribute
      \note This function may not be implemented for all kernels.
  */
  void garbage_collection();

  /** Remove the last vertex imidiately, i.e. call pop_back() for the
176
      VertexContainer.
Jan Möbius's avatar
Jan Möbius committed
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
  */
  void remove_last_vertex() { vertices_.pop_back(); }
  /** Remove the last edge imidiately, i.e. call pop_back() for the
      EdgeContainer. Used e.g. by the add_face() method of PolyMeshT
  */
  void remove_last_edge()   { edges_.pop_back();    }
  /** Remove the last face imidiately, i.e. call pop_back() for the
      FaceContainer. Used e.g. by the add_face() method of PolyMeshT
  */
  void remove_last_face()   { faces_.pop_back();    }

  //@}




  /// \name Number of elements
  //@{
  /// Returns number of vertices
  unsigned int n_vertices() const;
  /// Returns number of halfedges (should be 2*n_edges())
  unsigned int n_halfedges() const;
  /// Returns number of edges
  unsigned int n_edges() const;
  /// Returns number of faces
  unsigned int n_faces() const;
  /// Is the vertex container empty?
  bool vertices_empty() const;
  /// Is the halfedge container empty (should be the same as edges_empty()).
  bool halfedges_empty() const;
  /// Is the edge container empty?
  bool edges_empty() const;
  /// Is the face container empty?
  bool faces_empty() const;
  //@}



  /// \name Vertex connectivity
  //@{
  /// Get an outgoing halfedge of a given vertex
  HalfedgeHandle halfedge_handle(VertexHandle _vh) const;
  /// Set the outgoing halfedge handle of a given vertex
  void set_halfedge_handle(VertexHandle _vh, HalfedgeHandle _heh);
  /// Get the coordinate of a vertex
  const Point& point(VertexHandle _vh) const;
  /// Get the coordinate of a vertex
  const Point& point(const Vertex& _v) const;
  /// Set the coordinate of a vertex
  void set_point(VertexHandle _vh, const Point& _p);
  /// Set the coordinate of a vertex
  void set_point(Vertex& _v, const Point& _p);
  //@}
230

Jan Möbius's avatar
Jan Möbius committed
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295



  /// \name Halfedge connectivity
  //@{
  /// Get the vertex the halfedge points to
  VertexHandle to_vertex_handle(HalfedgeHandle _heh) const;
  /** Get the vertex the halfedge starts from (implemented as to-handle
      of the opposite halfedge, provided for convenience) */
  VertexHandle from_vertex_handle(HalfedgeHandle _heh) const;
  /// Set the to-vertex-handle of the halfedge
  void set_vertex_handle(HalfedgeHandle _heh, VertexHandle _vh);
  /** Get the face the halfedge belongs to.
      \note The handle is invalid if the halfedge is a boundary halfedge */
  FaceHandle face_handle(HalfedgeHandle _heh) const;
  /// Set the face the halfedge belongs to
  void set_face_handle(HalfedgeHandle _heh, FaceHandle _fh);
  /// Get the next halfedge handle
  HalfedgeHandle next_halfedge_handle(HalfedgeHandle _heh) const;
  /** Set the next halfedge handle.  \note If the previous halfedge is
      also stored (see OpenMesh::Attributes::PrevHalfedge) then this
      method also has to set this link) */
  void set_next_halfedge_handle(HalfedgeHandle _heh, HalfedgeHandle _nheh);
  /** Get the previous halfedge of the given halfedge. The
      implementation should take care of an existing
      OpenMesh::Attributes::PrevHalfedge attribute. */
  HalfedgeHandle prev_halfedge_handle(HalfedgeHandle _heh) const;
  /// Get the opposite halfedge
  HalfedgeHandle opposite_halfedge_handle(HalfedgeHandle _heh) const;
  /// Counter-clockwise rotate the given halfedge around its from vertex
  HalfedgeHandle ccw_rotated_halfedge_handle(HalfedgeHandle _heh) const;
  /// Clockwise rotate the given halfedge around its from vertex
  HalfedgeHandle cw_rotated_halfedge_handle(HalfedgeHandle _heh) const;
  /// Get the edge the current halfedge it contained in
  EdgeHandle edge_handle(HalfedgeHandle _heh) const;
  //@}



  /// \name Edge connectivity
  //@{
  /// Get the first or second halfedge of the given edge
  HalfedgeHandle halfedge_handle(EdgeHandle _eh, unsigned int _i) const;
  //@}



  /// \name Face connectivity
  //@{
  /// Get a halfedge belonging to the face
  HalfedgeHandle halfedge_handle(FaceHandle _fh) const;
  /// Set one halfedge of the face
  void set_halfedge_handle(FaceHandle _fh, HalfedgeHandle _heh);
  //@}


public: // Standard Property Management

  /// \name set/get value of a standard property
  //@{

  // vertex
  const Point& point(VertexHandle _vh) const; ///< Get position
  void set_point(VertexHandle _vh, const Point& _p); ///< Set position
  Point& point(VertexHandle _vh); ///< Convenience function
296

Jan Möbius's avatar
Jan Möbius committed
297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333
  const Normal& normal(VertexHandle _vh) const; ///< Get normal
  void set_normal(VertexHandle _vh, const Normal& _n); ///< Set normal

  const Color& color(VertexHandle _vh) const; ///< Get color
  void set_color(VertexHandle _vh, const Color& _c) ///< Set color

  const TexCoord& texcoord(VertexHandle _vh) const; ///< Get texture coordinate.
  void set_texcoord(VertexHandle _vh, const TexCoord& _t); ///< Set texture coordinate.

  const StatusInfo& status(VertexHandle _vh) const; ///< Get status
  StatusInfo& status(VertexHandle _vh); ///< Get status

  // halfedge
  const StatusInfo& status(HalfedgeHandle _vh) const; ///< Get status
  StatusInfo& status(HalfedgeHandle _vh); ///< Get status

  // edge
  const StatusInfo& status(EdgeHandle _vh) const; ///< Get status
  StatusInfo& status(EdgeHandle _vh); ///< Get status

  // face
  const Normal& normal(FaceHandle _fh) const; ///< Get normal
  void set_normal(FaceHandle _fh, const Normal& _n); ///< Set normal

  const Color& color(FaceHandle _fh) const; ///< Get color
  void set_color(FaceHandle _fh, const Color& _c); ///< Set color

  const StatusInfo& status(FaceHandle _vh) const; ///< Get status
  StatusInfo& status(FaceHandle _vh); ///< Get status

  //@}

  /// \name Dynamically add standard properties
  //@{
  /// Request property
  void request_vertex_normals();
  void request_vertex_colors();
334 335 336
  void request_vertex_texcoords1D();
  void request_vertex_texcoords2D();
  void request_vertex_texcoords3D();
Jan Möbius's avatar
Jan Möbius committed
337 338 339
  void request_vertex_status();

  void request_halfedge_status();
340 341 342
  void request_halfedge_texcoords1D();
  void request_halfedge_texcoords2D();
  void request_halfedge_texcoords3D();
Jan Möbius's avatar
Jan Möbius committed
343 344

  void request_edge_status();
345
  void request_edge_colors();
Jan Möbius's avatar
Jan Möbius committed
346 347 348 349

  void request_face_normals();
  void request_face_colors();
  void request_face_status();
350
  void request_face_texture_index();
Jan Möbius's avatar
Jan Möbius committed
351 352 353 354 355 356 357
  //@}

  /// \name Remove standard properties
  //@{
  /// Remove property
  void release_vertex_normals();
  void release_vertex_colors();
358 359 360
  void release_vertex_texcoords1D();
  void release_vertex_texcoords2D();
  void release_vertex_texcoords3D();
Jan Möbius's avatar
Jan Möbius committed
361 362 363
  void release_vertex_status();

  void release_halfedge_status();
364 365 366
  void release_halfedge_texcoords1D();
  void release_halfedge_texcoords2D();
  void release_halfedge_texcoords3D();
Jan Möbius's avatar
Jan Möbius committed
367 368

  void release_edge_status();
369
  void release_edge_colors();
Jan Möbius's avatar
Jan Möbius committed
370 371 372 373

  void release_face_normals();
  void release_face_colors();
  void release_face_status();
374
  void release_face_texture_index();
Jan Möbius's avatar
Jan Möbius committed
375 376 377 378 379
  //@}

  /// \name Check availability of standard properties
  //@{
  /// Is property available?
380 381 382 383 384 385 386 387 388 389 390 391 392
  bool has_vertex_normals() const;
  bool has_vertex_colors() const;
  bool has_vertex_texcoords1D() const;
  bool has_vertex_texcoords2D() const;
  bool has_vertex_texcoords3D() const;
  bool has_vertex_status() const;

  bool has_halfedge_status() const;
  bool has_halfedge_texcoords1D() const;
  bool has_halfedge_texcoords2D() const;
  bool has_halfedge_texcoords3D() const;

  bool has_edge_status() const;
393
  bool has_edge_colors() const;
394 395 396 397 398

  bool has_face_normals() const;
  bool has_face_colors() const;
  bool has_face_status() const;
  bool has_face_texture_index() const;
Jan Möbius's avatar
Jan Möbius committed
399 400 401 402 403 404 405 406 407 408
  //@}

public: // Property Management

  /// \anchor concepts_kernelt_property_management

  /// \name Property management - add property
  //@{
  /// Add property.
  /// @copydoc OpenMesh::BaseKernel::add_property()
409
  template <typename T> bool add_property( [VEHFM]PropHandleT<T>& _ph,
Jan Möbius's avatar
Jan Möbius committed
410 411 412 413 414 415 416 417 418 419
                                           const std::string& _name = "" );
  //@}

  /// \name Property management - remove property
  //@{
  /// Remove property
  template <typename T> void remove_property( [VEHFM]PropHandleT<T>& );
  //@}

  /// \name Property management - get property by name
420
  //@{
Jan Möbius's avatar
Jan Möbius committed
421
  /// Get property handle by name
422
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438
  bool get_property_handle( [VEHFM]PropHandleT<T>& ph, const std::string& _n ) const;
  //@}

  /// \name Property management - get property
  //@{
  /// Get property
  template <typename T> PropertyT<T>& property( [VEHF]PropHandleT<T> _ph );
  template <typename T> const PropertyT<T>& property( [VEHF]PropHandleT<T> _ph ) const;
  template <typename T> PropertyT<T>& mproperty( MPropHandleT<T> _ph );
  template <typename T> const PropertyT<T>& mproperty( MPropHandleT<T> _ph ) const;
  //@}

  /// \name Property management - get property value for an item
  //@{

  /// Get value for item represented by the handle.
439
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
440
  T& property( VPropHandleT<T> _ph, VertexHandle _vh );
441
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
442 443
  const T& property( VPropHandleT<T> _ph, VertexHandle _vh ) const;

444
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
445
  T& property( EPropHandleT<T> _ph, EdgeHandle _vh );
446
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
447 448
  const T& property( EPropHandleT<T> _ph, EdgeHandle _vh ) const;

449
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
450
  T& property( HPropHandleT<T> _ph, HalfedgeHandle _vh );
451
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
452 453
  const T& property( HPropHandleT<T> _ph, HalfedgeHandle _vh ) const;

454
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
455
  T& property( FPropHandleT<T> _ph, FaceHandle _vh );
456
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
457 458
  const T& property( FPropHandleT<T> _ph, FaceHandle _vh ) const;

459
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
460
  T& property( MPropHandleT<T> _ph );
461
  template <typename T>
Jan Möbius's avatar
Jan Möbius committed
462 463 464 465 466 467 468 469 470 471 472 473
  const T& property( MPropHandleT<T> _ph ) const;

  //@}

public:


  /// \name Low-level adding new items
  //@{
  /** Add a new (default) vertex.
      \internal */
  VertexHandle new_vertex();
474
  /** Add a new vertex with a given point coordinate.
Jan Möbius's avatar
Jan Möbius committed
475 476
      \internal */
  VertexHandle new_vertex(const Point& _p);
477
  /** Add a new vertex (copied from the given one).
Jan Möbius's avatar
Jan Möbius committed
478 479 480 481 482 483 484
      \internal */
  VertexHandle new_vertex(const Vertex& _v);
  /** Add a new edge from \c _start_vertex_handle to \c _end_vertex_handle.
      This method should add an edge (i.e. two opposite halfedges) and set
      the corresponding vertex handles of these halfedges.
      \internal
   */
485
  HalfedgeHandle new_edge(VertexHandle _start_vertex_handle,
Jan Möbius's avatar
Jan Möbius committed
486 487
			  VertexHandle _end_vertex_handle);

488
  /** Adding a new face
Jan Möbius's avatar
Jan Möbius committed
489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534
      \internal
  */
  FaceHandle new_face();
  /** Adding a new face (copied from a \c _f).
      \internal */
  FaceHandle new_face(const Face& _f);
  //@}


  // --- iterators ---

  /// \name Kernel item iterators
  //@{
  /** Kernel item iterator
      \internal */
  KernelVertexIter vertices_begin();
  KernelConstVertexIter vertices_begin() const;
  KernelVertexIter vertices_end();
  KernelConstVertexIter vertices_end() const;
  KernelEdgeIter edges_begin();
  KernelConstEdgeIter edges_begin() const;
  KernelEdgeIter edges_end();
  KernelConstEdgeIter edges_end() const;
  KernelFaceIter faces_begin();
  KernelConstFaceIter faces_begin() const;
  KernelFaceIter faces_end();
  KernelConstFaceIter faces_end() const;
  //@}



private:


  // --- private functions ---

  /// copy constructor: not used
  KernelT(const KernelT& _rhs);
};
};


//=============================================================================
} // namespace Concepts
} // namespace OpenMesh
//=============================================================================