Namespace NetTopologySuite.Coverage

Contains classes that operate on polygonal coverages.

A polygonal coverage is a set of polygonal geometries which is non-overlapping and edge-matched (Polygon or MultiPolygon) A set of polygonal geometries is a valid coverage if:

  1. Each geometry is valid.
  2. The interiors of all polygons are disjoint (they are not overlapping). This is the case if no polygon has a boundary which intersects the interior of another polygon.
  3. Where polygons are adjacent (i.e. their boundaries intersect), they are edge matched: the vertices (and thus line segments) of the common boundary match exactly.

A coverage may contain holes and disjoint regions.

Coverage algorithms (such as CoverageUnion) generally require the input coverage to be valid to produce correct results. Coverages can be validated using {@link CoverageValidator}.

Classes

CoverageGapFinder

Finds gaps in a polygonal coverage. Gaps are holes in the coverage which are narrower than a given width.

The coverage should be valid according to {@link CoverageValidator}. If this is not the case, some gaps may not be reported, or the invocation may fail.

This is a more accurate way of identifying gaps than using {@link CoverageValidator#setGapWidth(double)}. Gaps which separate the coverage into two disjoint regions are not detected. Gores are not identified as gaps.>

CoveragePolygonValidator

Validates that a polygon forms a valid polygonal coverage with the set of polygons adjacent to it. If the polygon is coverage-valid an empty { @link LineString} is returned. Otherwise, the result is a linear geometry containing the polygon boundary linework causing the invalidity.

A polygon is coverage-valid if:
  1. The polygon interior does not intersect the interior of other polygons.
  2. If the polygon boundary intersects another polygon boundary, the vertices and line segments of the intersection match exactly.

The algorithm detects the following coverage errors:
  1. the polygon is a duplicate of another one
  2. a polygon boundary segment equals an adjacent segment (with same orientation). This determines that the polygons overlap
  3. a polygon boundary segment is collinear and overlaps an adjacent segment but is not equal to it
  4. a polygon boundary segment touches an adjacent segment at a non-vertex point
  5. a polygon boundary segment crosses into an adjacent polygon
  6. a polygon boundary segment is in the interior of an adjacent polygon

If any of these errors is present, the target polygon does not form a valid coverage with the adjacent polygons.

The validity rules do not preclude properly noded gaps between coverage polygons. However, this class can detect narrow gaps, by specifying a maximum gap width using {@link #setGapWidth(double)}. Note that this will also identify narrow gaps separating disjoint coverage regions, and narrow gores. In some situations it may also produce false positives (i.e.linework identified as part of a gap which is wider than the given width). To fully identify gaps it maybe necessary to use CoverageUnion and analyze the holes in the result to see if they are acceptable.

A polygon may be coverage-valid with respect to a set of surrounding polygons, but the collection as a whole may not form a clean coverage.For example, the target polygon boundary may be fully matched by adjacent boundary segments, but the adjacent set contains polygons which are not coverage - valid relative to other ones in the set. A coverage is valid only if every polygon in the coverage is coverage - valid. Use CoverageValidator to validate an entire set of polygons.

The adjacent set may contain polygons which do not intersect the target polygon. These are effectively ignored during validation (but may decrease performance).

CoverageSimplifier

Simplifies the boundaries of the polygons in a polygonal coverage while preserving the original coverage topology. An area-based simplification algorithm (similar to Visvalingam-Whyatt simplification) is used to provide high-quality results. Also supports simplifying just the inner edges in a coverage, which allows simplifying "patches" without affecting their boundary.

The amount of simplification is determined by a tolerance value, which is a non-negative quantity. It equates roughly to the maximum distance by which a simplified line can change from the original. (In fact, it is the square root of the area tolerance used in the Visvalingam-Whyatt algorithm.)

The simplified result coverage has the following characteristics:
  • It has the same number of polygonal geometries as the input
  • If the input is a valid coverage, then so is the result
  • Node points (inner vertices shared by three or more polygons, or boundary vertices shared by two or more) are not changed
  • Polygons maintain their line-adjacency (edges are never removed)
  • Rings are simplified to a minimum of 4 vertices, to better preserve their shape
  • Rings smaller than the area tolerance are removed where possible. This applies to both holes and "islands" (multipolygon elements which are disjoint or touch another polygon at a single vertex). At least one polygon is retained for each input geometry (the one with largest area).

This class supports simplification using different distance tolerances for inner and outer edges of the coverage(including no simplfication using a tolerance of 0.0). This allows, for example, inner simplification, which simplifies only edges of the coverage which are adjacent to two polygons. This allows partial simplification of a coverage, since a simplified subset of a coverage still matches the remainder of the coverage.

The class allows specifying a separate tolerance for each element of the input coverage.

The input coverage should be valid according to CoverageValidator. Invalid coverages may still be simplified, but the result will likely still be invalid.

NOTE:
Due to different implementations of the PriorityQueue classes used in JTS and NTS the results of the CoverageSimplifier's simplification methods are not guaranteed to be the same. Nonetheless both results are valid.

CoverageUnion

Unions a polygonal coverage in an efficient way.

Valid polygonal coverage topology allows merging polygons in a very efficient way.

CoverageValidator

Validates a polygonal coverage, and returns the locations of invalid polygon boundary segments if found.

A polygonal coverage is a set of polygons which may be edge-adjacent but do not overlap. Coverage algorithms(such as { @link CoverageUnion} or simplification) generally require the input coverage to be valid to produce correct results. A polygonal coverage is valid if:
  1. The interiors of all polygons do not intersect(are disjoint). This is the case if no polygon has a boundary which intersects the interior of another polygon, and no two polygons are identical.
  2. If the boundaries of polygons intersect, the vertices and line segments of the intersection match exactly.

A valid coverage may contain holes(regions of no coverage). Sometimes it is desired to detect whether coverages contain narrow gaps between polygons (which can be a result of digitizing error or misaligned data). This class can detect narrow gaps, by specifying a maximum gap width using {@link #setGapWidth(double)}. Note that this also identifies narrow gaps separating disjoint coverage regions, and narrow gores. In some situations it may also produce false positives (linework identified as part of a gap which is actually wider). See CoverageGapFinder for an alternate way to detect gaps which may be more accurate.