Topological Map

Introduction

Chapters  and are concerned with subdivisions of the plane induced by collections of curves. In this chapter we introduce the topological map. The topological map (Topological_map) is a combinatorial structure with no geometric information. Therefore, it can be used as a base class for deriving geometric subdivisions (e.g, 2D planar maps) with different geometries (e.g, on a sphere or torus). The Planar_map_2 (Chapter ) is derived from the Topological_map on the Euclidean plane. In this section we briefly review the concepts underlying the data structures described in the following sections.

Figure:  A face, an edge, and a vertex

Topological Map, Vertex, Edge, Face:  A topological map is a graph which consists of vertices V, edges E, faces F and an incidence relation on them. Each edge is represented by two halfedges with opposite orientations. A face of the topological map is defined by the ordered circular sequences (inner and outer) of halfedges along its boundary.

Incidence:  If a vertex $$v is an endpoint of an edge $$e, then we say that $$v and $$e are incident to one another. Similarly, a face and an edge on its boundary are incident, and a face and a vertex on its boundary are incident (including edges and vertices which are not connected to the outer boundary - see below).

Halfedge, Twin, Source, Target:  We consider each edge $$e to be two-sided, representing it by two directed halfedges $$e and $$Twin(e) (in other places the twin halfedge is called $$Opposite). A halfedge $$e is an ordered pair $$(u,v) of its endpoints, and it is directed from $$u, the source, to $$v, the target (there is no need to store both in each halfedge since $$Target(e) Source(Twin(e)).) We consider each halfedge to lie on the boundary of a single face.

Connected Component of the Boundary (CCB):  Each connected component of the boundary of a face is defined by a circular list of halfedges. For a face $$f of a topological map, we call each connected component of the boundary of $$f a CCB. A bounded face has a unique CCB that is defined to be it's outer-CCB. An unbounded face does not have an outer boundary. In the topological map we have one unbounded face. Except for the outer-CCB, any other connected component of the boundary of $$f is called a hole (or inner CCB), every face can have none or several holes. We say that the holes are contained inside the face.

Edges Around Vertex :  Every maximal set of halfedges that share the same target can be viewed as a circular list of halfedges ordered around their target vertex. It should be noted that the orientation of the edges around a vertex is opposite to that of the halfedges around a face, i.e., if edge $$e2 succeeds edge $$e1 in the order given around vertex $$v, then $$e1 succeeds $$e2 in the order given around the incident face $$f. Unlike the convention we adopt for the planar map in Chapter  where the halfedges are oriented counterclockwise around a face and clockwise around a vertex, in the topological map the users are free to choose any other convention.

Figure:  Source and target vertices, and twin halfedges

Doubly Connected Edge List (DCEL):  For a topological map, its DCEL representation consists of a connected list of halfedges for every CCB of every face in the subdivision, with additional incidence information that enables us to traverse the subdivision. For each halfedge the DCEL stores a pointer to its twin halfedge and a to the next halfedge around its incident face (see Figure  ). In addition, for each halfedge the DCEL stores a pointer to the incident face and the target vertex. For each face the DCEL stores a pointer to a halfedge representing its outer-CCB and an iterator over pointers to halfedges representing its inner-CCBs (traversing over a CCB is thus done with repetitive calls to the next halfedge pointer). For each vertex the DCEL stores a pointer to an incident halfedge. For more information about the DCEL representation see  [dBvKOS97] and Chapter  on Halfedge_data_structure. The DCEL is a low-level container class that stores the objects. The topological map layer adds high-level functions and protection of combinatorial validity. Iterators, handles and circulators are also introduced in this layer (pointers are no longer visible in this layer).

In the following specifications, we implement the subdivision by a DCEL. See Section   for a specification of the requirements for a DCEL in our implementation.

Topological Map

• Class declaration of Topological_map<Dcel>.

• Class declaration of Vertex.

• Class declaration of Halfedge.

• Class declaration of Face.

• Class declaration of Ccb_halfedge_circulator.

• Class declaration of Halfedge_around_vertex_circulator.

Requirements for the Topological Map's DCEL class

In addition to the requirements here, the local types Vertex, Halfedge and Face must fulfill the requirements listed in Sections   through  .

• Class declaration of Dcel.

• Class declaration of Dcel::Vertex.

• Class declaration of Dcel::Halfedge.

• Class declaration of Dcel::Face.

Predefined Interface Class

• Class declaration of Pm_dcel<V,H,F>.

• Class declaration of Tpm_vertex_base.

• Class declaration of Tpm_halfedge_base.

• Class declaration of Pm_face_base.

Example Programs

Simple Topological Map

//example1.C

#include <CGAL/basic.h>
#include <iostream>

#include <CGAL/Topological_map_bases.h>
#include <CGAL/Pm_default_dcel.h>
#include <CGAL/Topological_map.h>


typedef CGAL::Pm_dcel<CGAL::Tpm_vertex_base,
                     CGAL::Tpm_halfedge_base,
                     CGAL::Tpm_face_base> Dcel;  

typedef CGAL::Topological_map<Dcel> Tpm;

typedef  Tpm::Halfedge_handle Halfedge_handle;
typedef  Tpm::Vertex_handle   Vertex_handle;
typedef  Tpm::Face_handle     Face_handle;


int main() {

  Tpm t;

  Face_handle uf=t.unbounded_face();

  std::cout << "inserting edge e1 in face interior ..." ;
  Halfedge_handle e1 = t.insert_in_face_interior(uf);
  CGAL_assertion(t.is_valid());
  std::cout << "map is valid." << endl;

  std::cout << "inserting edge e2 from target vertex of e1 ..." ;
  Halfedge_handle e2=t.insert_from_vertex(e1);
  CGAL_assertion(t.is_valid());
  std::cout <<  "map is valid." << endl;

  std::cout << "inserting edge e3 between target vertices of e2 and e1->twin() ...";
  Halfedge_handle e3=t.insert_at_vertices(e2,e1->twin());
  CGAL_assertion(t.is_valid());
  std::cout << "map is valid." << endl;

  return 0;
}

The results look like this:

inserting edge e1 in face interior ...map is valid.
inserting edge e2 from target vertex of e1 ...map is valid.
inserting edge e3 between target vertices of e2 and e1->twin() ...map is valid.

Topological Map with Additional Information

//example2.C
#include <CGAL/basic.h>
#include <iostream>

#include <CGAL/Topological_map_bases.h>
#include <CGAL/Pm_default_dcel.h>
#include <CGAL/Topological_map.h>


class Face_with_info : public CGAL::Tpm_face_base {
  int inf;
public:
  Face_with_info() : CGAL::Tpm_face_base(), inf(0) {}

  int info() {return inf;}
  void set_info(int i) {inf=i;}
};

typedef Pm_dcel<CGAL::Tpm_vertex_base,
                     CGAL::Tpm_halfedge_base,
                     Face_with_info > Dcel;  

typedef CGAL::Topological_map<Dcel> Tpm;

typedef  Tpm::Halfedge_handle Halfedge_handle;
typedef  Tpm::Vertex_handle   Vertex_handle;
typedef  Tpm::Face_handle     Face_handle;


main() {
  
  Tpm t;

  Face_handle uf=t.unbounded_face();

  std::cout << "inserting e1 in face interior..." << endl;
  Halfedge_handle e1 = t.insert_in_face_interior(uf);
  CGAL_assertion(t.is_valid());

  std::cout << "inserting e2 from vertex..." << endl;
  Halfedge_handle e2=t.insert_from_vertex(e1);
  CGAL_assertion(t.is_valid());

  std::cout << "inserting e3 between vertices of e2 and e1->twin()..." << endl;
  Halfedge_handle e3=t.insert_at_vertices(e2,e1->twin());
  CGAL_assertion(t.is_valid());
  
  std::cout << endl << "setting info of the new face to 10..." << endl;
  Face_handle nf=e3->face() ;
  nf->set_info(10);

  std::cout << endl << "unbounded face info = " << uf->info() << endl;
  std::cout << "new face info = " << nf->info() << endl;

  return 0;
}

The results look like this:

inserting e1 in face interior...
inserting e2 from vertex...
inserting e3 between vertices of e2 and e1->twin()...

setting info of the new face to 10...

unbounded face info = 0
new face info = 10