#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

staticconstexpr

Merge strategy that chooses polygon with longest common border

◆ MERGE_MAX_AREA

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

staticconstexpr

Merge strategy that chooses polygon with maximum area

◆ MERGE_MIN_AREA

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

staticconstexpr

Merge strategy that chooses polygon with minimum area

◆ MERGE_MIN_INDEX

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

staticconstexpr

Merge strategy that chooses polygon with smallest input index

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

CoverageCleaner.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CoverageCleaner() [1/2]

◆ CoverageCleaner() [2/2]

Member Function Documentation

◆ clean() [1/3]

◆ clean() [2/3]

◆ clean() [3/3]

◆ cleanGapWidth()

◆ cleanOverlapGap()

◆ getMergedGaps()

◆ getOverlaps()

◆ getResult()

◆ setGapMaximumWidth()

◆ setOverlapMergeStrategy()

◆ setSnappingDistance()

Member Data Documentation

◆ MERGE_LONGEST_BORDER

◆ MERGE_MAX_AREA

◆ MERGE_MIN_AREA

◆ MERGE_MIN_INDEX