Skip to main content
`Ctrl`+`K`

# networkx.algorithms.planarity.PlanarEmbedding

class PlanarEmbedding(incoming_graph_data=None, **attr)

  Represents a planar graph with its planar embedding.

  The planar embedding is given by a combinatorial embedding.

  Note

  `check_planarity` is the preferred way to check if a graph is planar.

  Neighbor ordering:

  In comparison to a usual graph structure, the embedding also stores the order of all neighbors for every vertex. The order of the neighbors can be given in clockwise (cw) direction or counterclockwise (ccw) direction. This order is stored as edge attributes in the underlying directed graph. For the edge (u, v) the edge attribute ‘cw’ is set to the neighbor of u that follows immediately after v in clockwise direction.

  In order for a PlanarEmbedding to be valid it must fulfill multiple conditions. It is possible to check if these conditions are fulfilled with the method `check_structure()`. The conditions are:

  - Edges must go in both directions (because the edge attributes differ)

  - Every edge must have a ‘cw’ and ‘ccw’ attribute which corresponds to a correct planar embedding.

  As long as a PlanarEmbedding is invalid only the following methods should be called:

  - `add_half_edge()`

  - `connect_components()`

  Even though the graph is a subclass of nx.DiGraph, it can still be used for algorithms that require undirected graphs, because the method `is_directed()` is overridden. This is possible, because a valid PlanarGraph must have edges in both directions.

  Half edges:

  In methods like `add_half_edge` the term “half-edge” is used, which is a term that is used in doubly connected edge lists. It is used to emphasize that the edge is only in one direction and there exists another half-edge in the opposite direction. While conventional edges always have two faces (including outer face) next to them, it is possible to assign each half-edge exactly one face. For a half-edge (u, v) that is oriented such that u is below v then the face that belongs to (u, v) is to the right of this half-edge.

  See also

  `is_planar`

    Preferred way to check if an existing graph is planar.

  `check_planarity`

    A convenient way to create a `PlanarEmbedding`. If not planar, it returns a subgraph that shows this.

  Examples

  Create an embedding of a star graph (compare `nx.star_graph(3)`):

      >>> G = nx.PlanarEmbedding()
      >>> G.add_half_edge(0, 1)
      >>> G.add_half_edge(0, 2, ccw=1)
      >>> G.add_half_edge(0, 3, ccw=2)
      >>> G.add_half_edge(1, 0)
      >>> G.add_half_edge(2, 0)
      >>> G.add_half_edge(3, 0)

  Alternatively the same embedding can also be defined in counterclockwise orientation. The following results in exactly the same PlanarEmbedding:

      >>> G = nx.PlanarEmbedding()
      >>> G.add_half_edge(0, 1)
      >>> G.add_half_edge(0, 3, cw=1)
      >>> G.add_half_edge(0, 2, cw=3)
      >>> G.add_half_edge(1, 0)
      >>> G.add_half_edge(2, 0)
      >>> G.add_half_edge(3, 0)

  After creating a graph, it is possible to validate that the PlanarEmbedding object is correct:

      >>> G.check_structure()

  __init__(incoming_graph_data=None, **attr)

    Initialize a graph with edges, name, or graph attributes.

    Parameters:
      incoming_graph_data input graph (optional, default: None)

        Data to initialize graph. If None (default) an empty graph is created. The data can be an edge list, or any NetworkX graph object. If the corresponding optional Python packages are installed the data can also be a 2D NumPy array, a SciPy sparse array, or a PyGraphviz graph.

      attr keyword arguments, optional (default= no attributes)

        Attributes to add to graph as key=value pairs.

    See also

    `convert`

    Examples

        >>> G = nx.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
        >>> G = nx.Graph(name="my graph")
        >>> e = [(1, 2), (2, 3), (3, 4)]  # list of edges
        >>> G = nx.Graph(e)

    Arbitrary graph attribute pairs (key=value) may be assigned

        >>> G = nx.Graph(e, day="Friday")
        >>> G.graph
        {'day': 'Friday'}

  Methods

  `add_edge`(u_of_edge, v_of_edge, **attr) | Add an edge between u and v.
  `add_edges_from`(ebunch_to_add, **attr) | Add all the edges in ebunch_to_add.
  `add_half_edge`(start_node, end_node, *[, cw, ccw]) | Adds a half-edge from `start_node` to `end_node`.
  `add_half_edge_ccw`(start_node, end_node, ...) | Adds a half-edge from start_node to end_node.
  `add_half_edge_cw`(start_node, end_node, ...) | Adds a half-edge from start_node to end_node.
  `add_half_edge_first`(start_node, end_node) | Add a half-edge and set end_node as start_node's leftmost neighbor.
  `add_node`(node_for_adding, **attr) | Add a single node `node_for_adding` and update node attributes.
  `add_nodes_from`(nodes_for_adding, **attr) | Add multiple nodes.
  `add_weighted_edges_from`(ebunch_to_add[, weight]) | Add weighted edges in `ebunch_to_add` with specified weight attr
  `adjacency`() | Returns an iterator over (node, adjacency dict) tuples for all nodes.
  `check_structure`() | Runs without exceptions if this object is valid.
  `clear`() | Remove all nodes and edges from the graph.
  `clear_edges`() | Remove all edges from the graph without altering nodes.
  `connect_components`(v, w) | Adds half-edges for (v, w) and (w, v) at some position.
  `copy`([as_view]) | Returns a copy of the graph.
  `edge_subgraph`(edges) | Returns the subgraph induced by the specified edges.
  `get_data`() | Converts the adjacency structure into a better readable structure.
  `get_edge_data`(u, v[, default]) | Returns the attribute dictionary associated with edge (u, v).
  `has_edge`(u, v) | Returns True if the edge (u, v) is in the graph.
  `has_node`(n) | Returns True if the graph contains the node n.
  `has_predecessor`(u, v) | Returns True if node u has predecessor v.
  `has_successor`(u, v) | Returns True if node u has successor v.
  `is_directed`() | A valid PlanarEmbedding is undirected.
  `is_multigraph`() | Returns True if graph is a multigraph, False otherwise.
  `nbunch_iter`([nbunch]) | Returns an iterator over nodes contained in nbunch that are also in the graph.
  `neighbors`(n) | Returns an iterator over successor nodes of n.
  `neighbors_cw_order`(v) | Generator for the neighbors of v in clockwise order.
  `next_face_half_edge`(v, w) | Returns the following half-edge left of a face.
  `number_of_edges`([u, v]) | Returns the number of edges between two nodes.
  `number_of_nodes`() | Returns the number of nodes in the graph.
  `order`() | Returns the number of nodes in the graph.
  `predecessors`(n) | Returns an iterator over predecessor nodes of n.
  `remove_edge`(u, v) | Remove the edge between u and v.
  `remove_edges_from`(ebunch) | Remove all edges specified in ebunch.
  `remove_node`(n) | Remove node n.
  `remove_nodes_from`(nodes) | Remove multiple nodes.
  `reverse`([copy]) | Returns the reverse of the graph.
  `set_data`(data) | Inserts edges according to given sorted neighbor list.
  `size`([weight]) | Returns the number of edges or total of all edge weights.
  `subgraph`(nodes) | Returns a SubGraph view of the subgraph induced on `nodes`.
  `successors`(n) | Returns an iterator over successor nodes of n.
  `to_directed`([as_view]) | Returns a directed representation of the graph.
  `to_directed_class`() | Returns the class to use for empty directed copies.
  `to_undirected`([reciprocal, as_view]) | Returns an undirected representation of the digraph.
  `to_undirected_class`() | Returns the class to use for empty undirected copies.
  `traverse_face`(v, w[, mark_half_edges]) | Returns nodes on the face that belong to the half-edge (v, w).
  `update`([edges, nodes]) | Update the graph using nodes/edges/graphs as input.

  Attributes

  `adj` | Graph adjacency object holding the neighbors of each node.
  `degree` | A DegreeView for the Graph as G.degree or G.degree().
  `edges` | An OutEdgeView of the DiGraph as G.edges or G.edges().
  `in_degree` | An InDegreeView for (node, in_degree) or in_degree for single node.
  `in_edges` | A view of the in edges of the graph as G.in_edges or G.in_edges().
  `name` | String identifier of the graph.
  `nodes` | A NodeView of the Graph as G.nodes or G.nodes().
  `out_degree` | An OutDegreeView for (node, out_degree)
  `out_edges` | An OutEdgeView of the DiGraph as G.edges or G.edges().
  `pred` | Graph adjacency object holding the predecessors of each node.
  `succ` | Graph adjacency object holding the successors of each node.