Namespace NetTopologySuite.Operation.RelateNG

Provides classes to implement the RelateNG algorithm computes topological relationships of Geometrys.
Topology is evaluated based on the Dimensionally-Extended 9-Intersection Model (DE-9IM).
The RelateNG class supports computing the value of boolean topological predicates Standard OGC named predicates are provided by the RelatePredicate functions. Custom relationships can be specified via testing against DE-9IM matrix patterns (see IntersectionMatrixPattern for examples). The full DE-9IM IntersectionMatrix can also be computed.

The algorithm has the following capabilities:

Efficient short-circuited evaluation of topological predicates (including matching custom DE-9IM patterns)
Optimized repeated evaluation of predicates against a single geometry via cached spatial indexes (AKA "prepared mode")
Robust computation (since only point-local topology is required, so that invalid geometry topology cannot cause failures)
Support for mixed-type and overlapping {@link GeometryCollection} inputs (using union semantics)
Support for IBoundaryNodeRule

RelateNG operates in 2D only; it ignores any Z ordinates.

Optimized Short-Circuited Evaluation

The RelateNG algorithm uses strategies to optimize the evaluation of topological predicates, including matching DE-9IM matrix patterns. These include fast tests of dimensions and envelopes, and short-circuited evaluation once the predicate value is known (either satisfied or failed) based on the value of matrix entries. Named predicates used explicit strategy code. DE-9IM matrix pattern matching are short-circuited where possible based on analysis of the pattern matrix entries. Spatial indexes are used to optimize topological computations (such as locating points in geometry elements, and analyzing the topological relationship between geometry edges).

Execution Modes

RelateNG provides two execution modes for evaluating predicates:

Single-shot mode evaluates a predicate for a single case of two geometries. It is provided by the RelateNG static functions which take two input geometries.
Prepared mode optimizes repeated evaluation of predicates against a fixed geometry. It is used by creating an instance of RelateNG on the required geometry with the Prepare functions, and then using the Evaluate methods. It provides much faster performance for repeated operations against a single geometry.

Robustness

RelateNG provides robust evaluation of topological relationships, up to the precision of double-precision computation. It computes topological relationships in the locality of discrete points, without constructing a full topology graph of the inputs. This means that invalid input geometries or numerical round-off do not cause exceptions (although they may return incorrect answers). However, it is necessary to node some inputs together (in particular, linear elements) in order to provide consistent evaluation of the topological structure.

GeometryCollection Handling

GeometryCollections may contain geometries of different dimensions, nested to any level. The element geometries may overlap in any combination. The OGC specification did not provide a definition for the topology of GeometryCollections, or how they behave under the DE-9IM model. RelateNG defines the topology for arbitrary collections of geometries using "union semantics". This is specified as:

GeometryCollections are evaluated as if they were replaced by the topological union of their elements.
The topological location at a point is equal to its location in the geometry of highest dimension which contains it. For example, a point located in the interior of a Polygon and the boundary of a LineString has location Interior.

Zero-length LineString Handling

Zero-length LineStrings are handled as topologically identical to a Point at the same coordinate.

Package Specification

OpenGIS Simple Features Specification for SQL

Classes

IntersectionMatrixPattern

String constants for DE-9IM matrix patterns for topological relationships. These can be used with Evaluate(Geometry, string) and Relate(Geometry, Geometry, string).

DE - 9IM Pattern Matching

Matrix patterns are specified as a 9 - character string containing the pattern symbols for the DE-9IM 3x3 matrix entries, listed row - wise. The pattern symbols are:

Code	Description
0	topological interaction has dimension 0
1	topological interaction has dimension 1
2	topological interaction has dimension 2
F	no topological interaction
T	topological interaction of any dimension
*	any topological interaction is allowed, including none

RelateNG

Computes the value of topological predicates between two geometries based on the Dimensionally - Extended 9-Intersection Model(DE-9IM). Standard and custom topological predicates are provided by RelatePredicate.

The RelateNG algorithm has the following capabilities:

Efficient short-circuited evaluation of topological predicates (including matching custom DE-9IM matrix patterns)
Optimized repeated evaluation of predicates against a single geometry via cached spatial indexes (AKA "prepared mode")
Robust computation (only point-local topology is required, so invalid geometry topology does not cause failures)
GeometryCollection inputs containing mixed types and overlapping polygons are supported, using union semantics.
Zero - length LineStrings are treated as being topologically identical to Points.
Support for IBoundaryNodeRules.

See IntersectionMatrixPattern for a description of DE - 9IM patterns.

If not specified, the standard BoundaryNodeRules.Mod2BoundaryNodeRule is used. RelateNG operates in 2D only; it ignores any Z ordinates.

This implementation replaces RelateOp and IPreparedGeometry.

FUTURE WORK

Support for a distance tolerance to provide "approximate" predicate evaluation