Class S2Shape

The purpose of S2Shape is to represent polygonal geometry in a flexible way. It is organized as a collection of edges that optionally defines an interior. All geometry represented by an S2Shape must have the same dimension, which means that an S2Shape can represent either a set of points, a set of polylines, or a set of polygons.

class S2Shape ;

S2Shape is defined as an abstract base class in order to give clients control over the underlying data representation. Sometimes an S2Shape does not have any data of its own, but instead "wraps" some other class. There are various useful subtypes defined in *shape.h, and some S2 classes also have a nested "Shape" class (e.g., S2Polygon::Shape). It is easy for clients to implement their own subtypes, since the interface is minimal.

S2Shape operations are typically defined on S2ShapeIndex objects rather than individual shapes. An S2ShapeIndex is simply a collection of S2Shapes, possibly of different dimensions (e.g. 10 points and 3 polygons), organized into a data structure for efficient edge access.

The edges of an S2Shape are identified by a contiguous range of "edge ids" starting at 0. The edges are further subdivided into "chains", where each chain consists of a sequence of edges connected end-to-end (a polyline). For example, an S2Shape representing two polylines AB and CDE would have three edges (AB, CD, DE) grouped into two chains: (AB) and (CD, DE). Similarly, an S2Shape representing 5 points would have 5 chains consisting of one edge each.

S2Shape has methods that allow edges to be accessed either using the global numbering (edge id) or within a particular chain. The global numbering is sufficient for most purposes, but the chain representation is useful for certain algorithms such as intersection (see S2BooleanOperation).

Methods

NameDescription
chain (chain_id) Returns the range of edge ids corresponding to the given edge chain. The edge chains must form contiguous, non-overlapping ranges that cover the entire range of edge ids. This is spelled out more formally below:
chainEdge (chain_id, offset) Returns the edge at offset "offset" within edge chain "chain_id". Equivalent to "shape.edge(shape.chain(chain_id).start + offset)" but may be more efficient.
chainPosition (edge_id) Finds the chain containing the given edge, and returns the position of that edge as a (chain_id, offset) pair.
dimension () Returns the dimension of the geometry represented by this shape.
edge (edge_id) Returns the endpoints of the given edge id.
getReferencePoint () Returns an arbitrary point P along with a boolean indicating whether P is contained by the shape. (The boolean value must be false for shapes that do not have an interior.)
hasInterior () Convenience function that returns true if this shape has an interior.
id () A unique id assigned to this shape by S2ShapeIndex. Shape ids are assigned sequentially starting from 0 in the order shapes are added.
numChains () Returns the number of contiguous edge chains in the shape. For example, a shape whose edges are [AB, BC, CD, AE, EF] would consist of two chains (AB,BC,CD and AE,EF). Every chain is assigned a "chain id" numbered sequentially starting from zero.
numEdges () Returns the number of edges in this shape. Edges have ids ranging from 0 to num_edges() - 1.
userData () Virtual methods that return pointers of your choice.

Inner structs

NameDescription
Chain A range of edge ids corresponding to a chain of zero or more connected edges, specified as a (start, length) pair. The chain is defined to consist of edge ids {start, start + 1, ..., start + length - 1}.
ChainPosition The position of an edge within a given edge chain, specified as a (chain_id, offset) pair. Chains are numbered sequentially starting from zero, and offsets are measured from the start of each chain.
Edge An edge, consisting of two vertices "v0" and "v1". Zero-length edges are allowed, and can be used to represent points.
ReferencePoint A ReferencePoint consists of a point P and a boolean indicating whether P is contained by a particular shape.