geos::coverage::CoverageCleaner Class Reference

`#include <CoverageCleaner.h>`

## Public Member Functions

| CoverageCleaner (std::vector< const Geometry * > &coverage)
void | setSnappingDistance (double snapDistance)
void | setOverlapMergeStrategy (int mergeStrategy)
void | setGapMaximumWidth (double maxWidth)
void | clean ()
std::vector< std::unique_ptr< Geometry > > | getResult ()
std::vector< const Polygon * > | getOverlaps ()
std::vector< const Polygon * > | getMergedGaps ()
std::unique_ptr< Geometry > | toGeometry (std::vector< SegmentString * > &segStrings, const GeometryFactory *geomFact)
std::unique_ptr< Geometry > | node (std::vector< const Geometry * > &coverage, double snapDistance)
| CoverageCleaner (const CoverageCleaner &)=delete
CoverageCleaner & | operator= (const CoverageCleaner &)=delete

## Static Public Member Functions

static std::vector< std::unique_ptr< Geometry > > | clean (std::vector< const Geometry * > &coverage, double snapDistance, int mergeStrategy, double maxWidth)
static std::vector< std::unique_ptr< Geometry > > | clean (std::vector< const Geometry * > &coverage, double snapDistance, double maxWidth)
static std::vector< std::unique_ptr< Geometry > > | cleanOverlapGap (std::vector< const Geometry * > &coverage, int mergeStrategy, double maxWidth)
static std::vector< std::unique_ptr< Geometry > > | cleanGapWidth (std::vector< const Geometry * > &coverage, double maxWidth)

## Static Public Attributes

static constexpr int | MERGE_LONGEST_BORDER = 0
static constexpr int | MERGE_MAX_AREA = 1
static constexpr int | MERGE_MIN_AREA = 2
static constexpr int | MERGE_MIN_INDEX = 3

## Detailed Description

Cleans the linework of a set of polygonal geometries to form a valid polygonal coverage. The input is an array of valid Polygon or MultiPolygon geometries which may contain topological errors such as overlaps and gaps. Empty or non-polygonal inputs are removed. Linework is snapped together to eliminate small discrepancies. Overlaps are merged with an adjacent polygon, according to a given merge strategy. Gaps narrower than a given width are filled and merged with an adjacent polygon. The output is an array of polygonal geometries forming a valid polygonal coverage.

** Snapping **

Snapping to nearby vertices and line segment snapping is used to improve noding robustness and eliminate small errors in an efficient way, By default this uses a very small snapping distance based on the extent of the input data. The snapping distance may be specified explicitly. This can reduce the number of overlaps and gaps that need to be merged, and reduce the risk of spikes formed by merging gaps. However, a large snapping distance may introduce undesirable data alteration.

** Overlap Merging **

Overlaps are merged with an adjacent polygon chosen according to a specified merge strategy. The supported strategies are:

- Longest Border: (default) merge with the polygon with longest shared border (MERGE_LONGEST_BORDER.)
- Maximum/Minimum Area: merge with the polygon with largest or smallest area (MERGE_MAX_AREA, MERGE_MIN_AREA.)
- Minimum Index: merge with the polygon with the lowest index in the input array (MERGE_MIN_INDEX.)

This allows sorting the input according to some criteria to provide a priority for merging gaps.

** Gap Merging **

Gaps which are wider than a given distance are merged with an adjacent polygon. Polygon width is determined as twice the radius of the MaximumInscribedCircle of the gap polygon. Gaps are merged with the adjacent polygon with longest shared border. Empty holes in input polygons are treated as gaps, and may be filled in. Gaps which are not fully enclosed ("inlets") are not removed.

Cleaning can be run on a valid coverage to remove gaps.

The clean result is an array of polygonal geometries which match one-to-one with the input array. A result item may be null if:

- the input item is non-polygonal or empty
- the input item is so small it is snapped to collapse
- the input item is covered by another input item (which may be a larger or a duplicate (nearly or exactly) geometry)

The result is a valid coverage according to CoverageValidator::isValid();

** Known Issues **

- Long narrow gaps adjacent to multiple polygons may form spikes when merged with a single polygon.

** Future Enhancements **

- Provide an area-based tolerance for gap merging
- Prevent long narrow gaps from forming spikes by partitioning them before merging.
- Allow merging narrow parts of a gap while leaving wider portions.
- Support a priority value for each input polygon to control overlap and gap merging (this could also allow blocking polygons from being merge targets)

See also
  CoverageValidator

Author
  Martin Davis

## Constructor & Destructor Documentation

## CoverageCleaner() [1/2]

geos::coverage::CoverageCleaner::CoverageCleaner | ( | std::vector< const Geometry * > & | coverage | ) |

Create a new cleaner instance for a set of polygonal geometries.

Parameters

  coverage | an array of polygonal geometries to clean

Referenced by CoverageCleaner().

## CoverageCleaner() [2/2]

geos::coverage::CoverageCleaner::CoverageCleaner | ( | const CoverageCleaner & |  | ) |

delete

Disable copy construction and assignment. Apparently needed to make this class compile under MSVC. (See https://stackoverflow.com/q/29565299)

References CoverageCleaner().

## Member Function Documentation

## clean() [1/3]

void geos::coverage::CoverageCleaner::clean | ( |  | ) |

Cleans the coverage.

## clean() [2/3]

std::vector< std::unique_ptr< Geometry > > geos::coverage::CoverageCleaner::clean | ( | std::vector< const Geometry * > & | coverage,
|  | double | snapDistance,
|  | double | maxWidth )

static

Cleans a set of polygonal geometries to form a valid coverage, using the default overlap merge strategy `MERGE_LONGEST_BORDER`.

Parameters

  coverage | an array of polygonal geometries to clean
  snapDistance | the distance tolerance for snapping
  maxWidth | the maximum width of gaps to merge

Returns
  the clean coverage

## clean() [3/3]

std::vector< std::unique_ptr< Geometry > > geos::coverage::CoverageCleaner::clean | ( | std::vector< const Geometry * > & | coverage,
|  | double | snapDistance,
|  | int | mergeStrategy,
|  | double | maxWidth )

static

Cleans a set of polygonal geometries to form a valid coverage, allowing all cleaning parameters to be specified.

Parameters

  coverage | an array of polygonal geometries to clean
  snapDistance | the distance tolerance for snapping
  mergeStrategy | the strategy to use for merging overlaps
  maxWidth | the maximum width of gaps to merge

Returns
  the clean coverage

## cleanGapWidth()

std::vector< std::unique_ptr< Geometry > > geos::coverage::CoverageCleaner::cleanGapWidth | ( | std::vector< const Geometry * > & | coverage,
|  | double | maxWidth )

static

Cleans a set of polygonal geometries to form a valid coverage, with default snapping tolerance and overlap merging, and merging gaps which are narrower than a specified width.

Parameters

  coverage | an array of polygonal geometries to clean
  maxWidth | the maximum width of gaps to merge

Returns
  the clean coverage

## cleanOverlapGap()

std::vector< std::unique_ptr< Geometry > > geos::coverage::CoverageCleaner::cleanOverlapGap | ( | std::vector< const Geometry * > & | coverage,
|  | int | mergeStrategy,
|  | double | maxWidth )

static

Cleans a set of polygonal geometries to form a valid coverage, using the default snapping distance tolerance.

Parameters

  coverage | an array of polygonal geometries to clean
  mergeStrategy | the strategy to use for merging overlaps
  maxWidth | the maximum width of gaps to merge

Returns
  the clean coverage

## getMergedGaps()

std::vector< const Polygon * > geos::coverage::CoverageCleaner::getMergedGaps | ( |  | ) |

Gets polygons representing the gaps in the input which have been merged.

Returns
  a list of gap polygons

## getOverlaps()

std::vector< const Polygon * > geos::coverage::CoverageCleaner::getOverlaps | ( |  | ) |

Gets polygons representing the overlaps in the input, which have been merged.

Returns
  a list of overlap polygons

## getResult()

std::vector< std::unique_ptr< Geometry > > geos::coverage::CoverageCleaner::getResult | ( |  | ) |

Gets the cleaned coverage.

Returns
  the clean coverage

## setGapMaximumWidth()

void geos::coverage::CoverageCleaner::setGapMaximumWidth | ( | double | maxWidth | ) |

Sets the maximum width of the gaps that will be filled and merged. The width of a gap is twice the radius of the Maximum Inscribed Circle in the gap polygon, A width of zero prevents gaps from being merged.

Parameters

  maxWidth | the maximum gap width to merge

## setOverlapMergeStrategy()

void geos::coverage::CoverageCleaner::setOverlapMergeStrategy | ( | int | mergeStrategy | ) |

Sets the overlap merge strategy to use. The default is `MERGE_LONGEST_BORDER`.

Parameters

  mergeStrategy | the merge strategy code

## setSnappingDistance()

void geos::coverage::CoverageCleaner::setSnappingDistance | ( | double | snapDistance | ) |

Sets the snapping distance tolerance. The default is to use a small fraction of the input extent diameter. A distance of zero prevents snapping from being used.

Parameters

  snapDistance | the snapping distance tolerance

## Member Data Documentation

## MERGE_LONGEST_BORDER

int geos::coverage::CoverageCleaner::MERGE_LONGEST_BORDER = 0

static constexpr

Merge strategy that chooses polygon with longest common border

## MERGE_MAX_AREA

int geos::coverage::CoverageCleaner::MERGE_MAX_AREA = 1

static constexpr

Merge strategy that chooses polygon with maximum area

## MERGE_MIN_AREA

int geos::coverage::CoverageCleaner::MERGE_MIN_AREA = 2

static constexpr

Merge strategy that chooses polygon with minimum area

## MERGE_MIN_INDEX

int geos::coverage::CoverageCleaner::MERGE_MIN_INDEX = 3

static constexpr

Merge strategy that chooses polygon with smallest input index

The documentation for this class was generated from the following file:

- CoverageCleaner.h