## CGAL::Topological_map<Dcel>

### Definition

An object tpm of the class Topological_map<Dcel> is a graph that 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 circular sequence of halfedges along its boundary. The representation used for the topological map is a DCEL. The available default DCEL class will be described later.

#include <CGAL/Topological_map.h>

### Types

Topological_map<Dcel>::Vertex
| represents a vertex of the topological map.
Topological_map<Dcel>::Halfedge
| represents a halfedge of the topological map.
Topological_map<Dcel>::Face
| represents a face of the topological map.

The following handles, iterators and circulators have appropriate constant1 counterparts. The mutable types are assignable to their constant counterparts. Both circulators are assignable to the Halfedge_iterator. The iterators are assignable to the respective handle types. Wherever the handles appear in function parameter lists, the appropriate iterator can be used as well.

Topological_map<Dcel>::Vertex_handle
| handle to vertex.
Topological_map<Dcel>::Halfedge_handle
| handle to halfedge.
Topological_map<Dcel>::Face_handle
| handle to face.
Topological_map<Dcel>::Vertex_iterator
| a bidirectional iterator over the vertices of the topological map. Its value-type is Topological_map<Dcel>::Vertex.
Topological_map<Dcel>::Halfedge_iterator
| a bidirectional iterator over the halfedges of the topological map. Its value-type is Topological_map<Dcel>::Halfedge.
Topological_map<Dcel>::Edge_iterator
| a bidirectional iterator over the Edges (every other halfedge) of the topological map. Its value-type is Topological_map<Dcel>::Halfedge.
Topological_map<Dcel>::Face_iterator
| a bidirectional iterator over the faces of the topological map. Its value-type is Topological_map<Dcel>::Face.
Topological_map<Dcel>::Ccb_halfedge_circulator
| a forward circulator over the halfedges of a CCB (connected component of the boundary). Its value-type is Topological_map<Dcel>::Halfedge.
Topological_map<Dcel>::Halfedge_around_vertex_circulator
| a forward circulator over the halfedges that have the vertex as their target. Its value-type is Topological_map<Dcel>::Halfedge.
Topological_map<Dcel>::Holes_iterator
| a bidirectional iterator to traverse all the holes ( i.e., inner CCBs) of a face (Holes_iterator++ is the next hole in the face). Its value type is Ccb_halfedge_circulator.

### Creation

Topological_map<Dcel> tpm;
| constructs an empty map - containing one unbounded face.

### Access Functions

Face_handle | tpm.unbounded_face ()
|  | returns the unbounded face of tpm.
Face_iterator | tpm.faces_begin () | returns the begin-iterator of the faces in tpm.
Face_iterator | tpm.faces_end () | returns the past-the-end iterator of the faces in tpm.
Halfedge_iterator | tpm.halfedges_begin ()
|  | returns the begin-iterator of the halfedges in tpm.
Halfedge_iterator | tpm.halfedges_end ()
|  | returns the past-the-end iterator of the halfedges in tpm.
Edge_iterator | tpm.edges_begin () | returns the begin-iterator of the edges in tpm.
Edge_iterator | tpm.edges_end () | returns the past-the-end iterator of the edges in tpm.
Vertex_iterator | tpm.vertices_begin ()
|  | returns the begin-iterator of the vertices in tpm.
Vertex_iterator | tpm.vertices_end ()
|  | returns the past-the-end iterator of the vertices in tpm.

### Predicates

bool | tpm.is_valid () | checks the validity of all the features of tpm. Check for each vertex v whether all incident halfedges (by performing next()->twin()) have v as their target. Check that all the edges on the boundary of each face f point to f as their face.

### Query Functions

The following methods return the number of map components, faces, halfedges or vertives, respectively.

Size | tpm.number_of_faces ()
Size | tpm.number_of_halfedges ()
Size | tpm.number_of_vertices ()

### Modifiers

Halfedge_handle

tpm.insert_at_vertices ( | Halfedge_handle previous1, Halfedge_handle previous2)

inserts a new edge between the vertices v1 and v2 which are the target of previous1 and previous2 respectively. The return value is the new halfedge that has v1 as its source. If a new face is created it will be, by definition, the face incident to the halfedge returned - this means that the order of the vertices on the new face will be v0...,v1,v2,...v0. This sets a requirement on the users (e.g, Planar_map_2) to call the function with the arguments in the right order (i.e., the order that will give the desired face). Insertion at vertices may require updating of the holes (since a new face can be created that contains some of the holes of the old face). To update the holes the function move_hole() should be called by the user.
Precondition: previous1 and previous2 have the same incident face.
Precondition: previous1 and previous2 do not have the same target vertex (i.e., no loop).

Halfedge_handle | tpm.insert_from_vertex ( Halfedge_handle previous)
|  | inserts a new edge for which one endpoint, v1 that is the target of previous, is already in the map. The return value is the new halfedge that has v1 as its source.
Halfedge_handle | tpm.insert_in_face_interior ( Face_handle f)
|  | inserts an edge as a new inner component of f. The return value is the new halfedge.

bool

tpm.move_hole ( | Halfedge_handle e, Face_handle f1, Face_handle f2)

|  | moves the hole represented by the halfedge e from the face f1 to f2. Returns false if e does not represent a hole in f1, and true otherwise.
Halfedge_handle | tpm.split_edge ( Halfedge_handle e)
|  | splits the edge e into e1 and e2 , and adds a new vertex incident both e1 and e2. The return value is the halfedge (e1 or e2) with the same source vertex that e had.

Halfedge_handle

tpm.merge_edge ( | Halfedge_handle e1, Halfedge_handle e2)

merges the two consecutive edges e1 and e2 into one edge. The return value is the halfedge with the same source vertex that e1 had and the same target e2 had. This operation is the inverse of the split_edge operation.
Precondition: e1 and e2 are consecutive halfedges (i.e., e1.target()==e2.source()).
Precondition: There is no other edge attached to the vertex between e1 and e2 (i.e., its degree is exactly 2).

Face_handle | tpm.remove_edge ( Halfedge_handle e)

removes the edge referenced by e from tpm. If the operation causes two faces to merge, the merged face is returned. Otherwise, the face in which the edge was incident is returned. The removal of an edge might create a new hole inside the face (e.g., when removing an edge in the interior of an ``antenna''). In this case by definition e points at the new hole created (i.e., the path from e to its twin goes over the new hole) and its twin points at the outer CCB (i.e., the path from e->twin() to e passes over the outer CCB). This sets a requirement on the users to define which halfedge (e or e->twin()) should be given as the parameter.

### Footnotes

1 | This means that for every iterator or circulator there is a const_iterator and const_circulator counterpart. See [MS96] for a discussion of constant versus mutable iterator types.