Enum GraphOptions.SiblingPairs
Controls how sibling edge pairs (i.e., pairs consisting of an edge and its reverse edge) are handled. Layer types that define an interior (e.g., polygons) normally discard such edge pairs since they do not affect the result (i.e., they define a "loop" with no interior). The various options include:
enum SiblingPairs
: int { ... }
Enum members
| Name | Description |
|---|
DISCARD
Discards all sibling edge pairs.
DISCARD EXCESS
Like DISCARD, except that a single sibling pair is kept if the result would otherwise be empty. This is useful for polygons with degeneracies (S2LaxPolygonShape), and for simplifying polylines while ensuring that they are not split into multiple disconnected pieces.
KEEP
Keeps sibling pairs. This can be used to create polylines that double back on themselves, or degenerate loops (with a layer type such as S2LaxPolygonShape).
REQUIRE
Requires that all edges have a sibling (and returns an error otherwise). This is useful with layer types that create a collection of adjacent polygons (a polygon mesh).
CREATE
Ensures that all edges have a sibling edge by creating them if necessary. This is useful with polygon meshes where the input polygons do not cover the entire sphere. Such edges always have an empty set of labels.
If edge_type() is EdgeType::UNDIRECTED, a sibling edge pair is considered to consist of four edges (two duplicate edges and their siblings), since only two of these four edges will be used in the final output.
Furthermore, since the options REQUIRE and CREATE guarantee that all edges will have siblings, S2Builder implements these options for undirected edges by discarding half of the edges in each direction and changing the edge_type() to EdgeType::DIRECTED. For example, two undirected input edges between vertices A and B would first be converted into two directed edges in each direction, and then one edge of each pair would be discarded leaving only one edge in each direction.
Degenerate edges are considered not to have siblings. If such edges are present, they are passed through unchanged by SiblingPairs::DISCARD. For
SiblingPairs
:REQUIRE or SiblingPairs::CREATE with undirected edges, the number of copies of each degenerate edge is reduced by a factor of two.
Any of the options that discard edges (DISCARD, DISCARD_EXCESS, and REQUIRE/CREATE in the case of undirected edges) have the side effect that when duplicate edges are present, all of the corresponding edge labels are merged together and assigned to the remaining edges. (This avoids the problem of having to decide which edges are discarded.) Note that this merging takes place even when all copies of an edge are kept, and that even labels attached to duplicate degenerate edges are merged. For example, consider the graph {AB1, AB2, BA3, CD4, CD5} (where XYn denotes an edge from X to Y with label "n"). With SiblingPairs::DISCARD, we need to discard one of the copies of AB. But which one? Rather than choosing arbitrarily, instead we merge the labels of all duplicate edges (even ones where no sibling pairs were discarded), yielding {AB12, CD45, CD45} (assuming that duplicate edges are being kept).