A geometry engine is a low-level representation of a QgsAbstractGeometry object, optimised for use with external geometry libraries such as GEOS. More...

#include <qgsgeometryengine.h>

Inheritance diagram for QgsGeometryEngine:

[legend]

Public Types
enum	EngineOperationResult { Success = 0 , NothingHappened = 1000 , MethodNotImplemented , EngineError , NodedGeometryError , InvalidBaseGeometry , InvalidInput , SplitCannotSplitPoint }
	Success or failure of a geometry operation. More...

Public Member Functions
virtual	~QgsGeometryEngine ()=default

virtual double	area (QString *errorMsg=nullptr) const =0

virtual QgsAbstractGeometry *	buffer (double distance, int segments, Qgis::EndCapStyle endCapStyle, Qgis::JoinStyle joinStyle, double miterLimit, QString *errorMsg=nullptr) const =0
	Buffers a geometry.

virtual QgsAbstractGeometry *	buffer (double distance, int segments, QString *errorMsg=nullptr) const =0

virtual QgsPoint *	centroid (QString *errorMsg=nullptr) const =0
	Calculates the centroid of this.

virtual QgsAbstractGeometry *	combine (const QgsAbstractGeometry geom, QString errorMsg=nullptr, const QgsGeometryParameters &parameters=QgsGeometryParameters()) const =0
	Calculate the combination of this and geom.

virtual QgsAbstractGeometry *	combine (const QVector< QgsAbstractGeometry * > &geomList, QString *errorMsg, const QgsGeometryParameters &parameters=QgsGeometryParameters()) const =0
	Calculate the combination of this and geometries.

virtual QgsAbstractGeometry *	combine (const QVector< QgsGeometry > &geometries, QString *errorMsg=nullptr, const QgsGeometryParameters &parameters=QgsGeometryParameters()) const =0
	Calculate the combination of this and geometries.

virtual bool	contains (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Checks if geom contains this.

virtual QgsAbstractGeometry *	convexHull (QString *errorMsg=nullptr) const =0
	Calculate the convex hull of this.

virtual bool	crosses (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Checks if geom crosses this.

virtual QgsAbstractGeometry *	difference (const QgsAbstractGeometry geom, QString errorMsg=nullptr, const QgsGeometryParameters &parameters=QgsGeometryParameters()) const =0
	Calculate the difference of this and geom.

virtual bool	disjoint (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Checks if geom is disjoint from this.

virtual double	distance (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Calculates the distance between this and geom.

virtual bool	distanceWithin (const QgsAbstractGeometry geom, double maxdistance, QString errorMsg=nullptr) const =0
	Checks if geom is within maxdistance distance from this geometry.

virtual QgsAbstractGeometry *	envelope (QString *errorMsg=nullptr) const =0

virtual void	geometryChanged ()=0
	Should be called whenever the geometry associated with the engine has been modified and the engine must be updated to suit.

virtual QgsAbstractGeometry *	interpolate (double distance, QString *errorMsg=nullptr) const =0

virtual QgsAbstractGeometry *	intersection (const QgsAbstractGeometry geom, QString errorMsg=nullptr, const QgsGeometryParameters &parameters=QgsGeometryParameters()) const =0
	Calculate the intersection of this and geom.

virtual bool	intersects (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Checks if geom intersects this.

virtual bool	isEmpty (QString *errorMsg) const =0

virtual bool	isEqual (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Checks if this is equal to geom.

virtual bool	isSimple (QString *errorMsg=nullptr) const =0
	Determines whether the geometry is simple (according to OGC definition).

virtual bool	isValid (QString errorMsg=nullptr, bool allowSelfTouchingHoles=false, QgsGeometry errorLoc=nullptr) const =0
	Returns `true` if the geometry is valid.

virtual double	length (QString *errorMsg=nullptr) const =0

virtual QgsAbstractGeometry *	offsetCurve (double distance, int segments, Qgis::JoinStyle joinStyle, double miterLimit, QString *errorMsg=nullptr) const =0
	Offsets a curve.

virtual bool	overlaps (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Checks if geom overlaps this.

virtual QgsPoint *	pointOnSurface (QString *errorMsg=nullptr) const =0
	Calculate a point that is guaranteed to be on the surface of this.

virtual void	prepareGeometry ()=0
	Prepares the geometry, so that subsequent calls to spatial relation methods are much faster.

virtual QString	relate (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Returns the Dimensional Extended 9 Intersection Model (DE-9IM) representation of the relationship between the geometries.

virtual bool	relatePattern (const QgsAbstractGeometry geom, const QString &pattern, QString errorMsg=nullptr) const =0
	Tests whether two geometries are related by a specified Dimensional Extended 9 Intersection Model (DE-9IM) pattern.

void	setLogErrors (bool enabled)
	Sets whether warnings and errors encountered during the geometry operations should be logged.

virtual QgsAbstractGeometry *	simplify (double tolerance, QString *errorMsg=nullptr) const =0

virtual QgsGeometryEngine::EngineOperationResult	splitGeometry (const QgsLineString &splitLine, QVector< QgsGeometry > &newGeometries, bool topological, QgsPointSequence &topologyTestPoints, QString *errorMsg=nullptr, bool skipIntersectionCheck=false) const
	Splits this geometry according to a given line.

virtual QgsAbstractGeometry *	symDifference (const QgsAbstractGeometry geom, QString errorMsg=nullptr, const QgsGeometryParameters &parameters=QgsGeometryParameters()) const =0
	Calculate the symmetric difference of this and geom.

virtual bool	touches (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Checks if geom touches this.

virtual bool	within (const QgsAbstractGeometry geom, QString errorMsg=nullptr) const =0
	Checks if geom is within this.

Protected Member Functions
	QgsGeometryEngine (const QgsAbstractGeometry *geometry)

void	logError (const QString &engineName, const QString &message) const
	Logs an error message encountered during an operation.

Protected Attributes
const QgsAbstractGeometry *	mGeometry = nullptr

bool	mLogErrors = true

Detailed Description

A geometry engine is a low-level representation of a QgsAbstractGeometry object, optimised for use with external geometry libraries such as GEOS.

QgsGeometryEngine objects provide a mechanism for optimized evaluation of geometric algorithms, including spatial relationships between geometries and operations such as buffers or clipping.

QgsGeometryEngine objects are not created directly, but are instead created by calling QgsGeometry::createGeometryEngine().

Many methods available in the QgsGeometryEngine class can benefit from pre-preparing geometries. For instance, whenever a large number of spatial relationships will be tested (such as calling intersects(), within(), etc) then the geometry should first be prepared by calling prepareGeometry() before performing the tests.

Example

# polygon_geometry contains a complex polygon, with many vertices
polygon_geometry = QgsGeometry.fromWkt('Polygon((...))')
 
# create a QgsGeometryEngine representation of the polygon
polygon_geometry_engine = QgsGeometry.createGeometryEngine(polygon_geometry.constGet())
 
# since we'll be performing many intersects tests, we can speed up these tests considerably
# by first "preparing" the geometry engine
polygon_geometry_engine.prepareGeometry()
 
# now we are ready to quickly test intersection against many other objects
for feature in my_layer.getFeatures():
    feature_geometry = feature.geometry()
    # test whether the feature's geometry intersects our original complex polygon
    if polygon_geometry_engine.intersects(feature_geometry.constGet()):
        print('feature intersects the polygon!')

QgsGeometryEngine operations are backed by the GEOS library (https://trac.osgeo.org/geos/).

Definition at line 67 of file qgsgeometryengine.h.

Member Enumeration Documentation

◆ EngineOperationResult

enum QgsGeometryEngine::EngineOperationResult

Success or failure of a geometry operation.

This gives details about cause of failure.

Enumerator
Success	Operation succeeded.
NothingHappened	Nothing happened, without any error.
MethodNotImplemented	Method not implemented in geometry engine.
EngineError	Error occurred in the geometry engine.
NodedGeometryError	Error occurred while creating a noded geometry.
InvalidBaseGeometry	The geometry on which the operation occurs is not valid.
InvalidInput	The input is not valid.
SplitCannotSplitPoint	Points cannot be split.

Definition at line 75 of file qgsgeometryengine.h.

Constructor & Destructor Documentation

◆ ~QgsGeometryEngine()

virtual QgsGeometryEngine::~QgsGeometryEngine ( )

virtualdefault

◆ QgsGeometryEngine()

QgsGeometryEngine::QgsGeometryEngine ( const QgsAbstractGeometry * geometry )

inlineprotected

Definition at line 361 of file qgsgeometryengine.h.

Member Function Documentation

◆ area()

virtual double QgsGeometryEngine::area ( QString * errorMsg = nullptr ) const

pure virtual

Implemented in QgsGeos.

◆ buffer() [1/2]

virtual QgsAbstractGeometry * QgsGeometryEngine::buffer	(	double	distance,
		int	segments,
		Qgis::EndCapStyle	endCapStyle,
		Qgis::JoinStyle	joinStyle,
		double	miterLimit,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Buffers a geometry.

Implemented in QgsGeos.

◆ buffer() [2/2]

virtual QgsAbstractGeometry * QgsGeometryEngine::buffer	(	double	distance,
		int	segments,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Implemented in QgsGeos.

◆ centroid()

virtual QgsPoint * QgsGeometryEngine::centroid ( QString * errorMsg = nullptr ) const

pure virtual

Calculates the centroid of this.

May return a \c nullptr.

Implemented in QgsGeos.

◆ combine() [1/3]

virtual QgsAbstractGeometry * QgsGeometryEngine::combine	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`,
		const QgsGeometryParameters &	parameters = `QgsGeometryParameters()`
	)		const

pure virtual

Calculate the combination of this and geom.

Parameters

geom	geometry to perform the operation
errorMsg	Error message returned by GEOS
parameters	can be used to specify parameters which control the union results (since QGIS 3.28)

Implemented in QgsGeos.

◆ combine() [2/3]

virtual QgsAbstractGeometry * QgsGeometryEngine::combine	(	const QVector< QgsAbstractGeometry * > &	geomList,
		QString *	errorMsg,
		const QgsGeometryParameters &	parameters = `QgsGeometryParameters()`
	)		const

pure virtual

Calculate the combination of this and geometries.

Parameters

geomList	list of geometries to perform the operation
errorMsg	Error message returned by GEOS
parameters	can be used to specify parameters which control the combination results (since QGIS 3.28)

Implemented in QgsGeos.

◆ combine() [3/3]

virtual QgsAbstractGeometry * QgsGeometryEngine::combine	(	const QVector< QgsGeometry > &	geometries,
		QString *	errorMsg = `nullptr`,
		const QgsGeometryParameters &	parameters = `QgsGeometryParameters()`
	)		const

pure virtual

Calculate the combination of this and geometries.

Parameters

geometries	list of geometries to perform the operation
errorMsg	Error message returned by GEOS
parameters	can be used to specify parameters which control the combination results (since QGIS 3.28)

Implemented in QgsGeos.

◆ contains()

virtual bool QgsGeometryEngine::contains	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Checks if geom contains this.

Implemented in QgsGeos.

◆ convexHull()

virtual QgsAbstractGeometry * QgsGeometryEngine::convexHull ( QString * errorMsg = nullptr ) const

pure virtual

Calculate the convex hull of this.

Implemented in QgsGeos.

◆ crosses()

virtual bool QgsGeometryEngine::crosses	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Checks if geom crosses this.

Implemented in QgsGeos.

◆ difference()

virtual QgsAbstractGeometry * QgsGeometryEngine::difference	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`,
		const QgsGeometryParameters &	parameters = `QgsGeometryParameters()`
	)		const

pure virtual

Calculate the difference of this and geom.

Parameters

geom	geometry to perform the operation
errorMsg	Error message returned by GEOS
parameters	can be used to specify parameters which control the difference results (since QGIS 3.28)

Implemented in QgsGeos.

◆ disjoint()

virtual bool QgsGeometryEngine::disjoint	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Checks if geom is disjoint from this.

Implemented in QgsGeos.

◆ distance()

virtual double QgsGeometryEngine::distance	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Calculates the distance between this and geom.

Implemented in QgsGeos.

◆ distanceWithin()

virtual bool QgsGeometryEngine::distanceWithin	(	const QgsAbstractGeometry *	geom,
		double	maxdistance,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Checks if geom is within maxdistance distance from this geometry.

Since: QGIS 3.22

Implemented in QgsGeos.

◆ envelope()

virtual QgsAbstractGeometry * QgsGeometryEngine::envelope ( QString * errorMsg = nullptr ) const

pure virtual

Implemented in QgsGeos.

◆ geometryChanged()

virtual void QgsGeometryEngine::geometryChanged ( )

pure virtual

Should be called whenever the geometry associated with the engine has been modified and the engine must be updated to suit.

Implemented in QgsGeos.

◆ interpolate()

virtual QgsAbstractGeometry * QgsGeometryEngine::interpolate	(	double	distance,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Implemented in QgsGeos.

◆ intersection()

virtual QgsAbstractGeometry * QgsGeometryEngine::intersection	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`,
		const QgsGeometryParameters &	parameters = `QgsGeometryParameters()`
	)		const

pure virtual

Calculate the intersection of this and geom.

Parameters

geom	geometry to perform the operation
errorMsg	Error message returned by GEOS
parameters	can be used to specify parameters which control the intersection results (since QGIS 3.28)

Implemented in QgsGeos.

◆ intersects()

virtual bool QgsGeometryEngine::intersects	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Checks if geom intersects this.

Implemented in QgsGeos.

◆ isEmpty()

virtual bool QgsGeometryEngine::isEmpty ( QString * errorMsg ) const

pure virtual

Implemented in QgsGeos.

◆ isEqual()

virtual bool QgsGeometryEngine::isEqual	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Checks if this is equal to geom.

If both are Null geometries, \c false is returned.

Implemented in QgsGeos.

◆ isSimple()

virtual bool QgsGeometryEngine::isSimple ( QString * errorMsg = nullptr ) const

pure virtual

Determines whether the geometry is simple (according to OGC definition).

Implemented in QgsGeos.

◆ isValid()

virtual bool QgsGeometryEngine::isValid	(	QString *	errorMsg = `nullptr`,
		bool	allowSelfTouchingHoles = `false`,
		QgsGeometry *	errorLoc = `nullptr`
	)		const

pure virtual

Returns true if the geometry is valid.

If the geometry is invalid, errorMsg will be filled with the reported geometry error.

The allowSelfTouchingHoles argument specifies whether self-touching holes are permitted. OGC validity states that self-touching holes are NOT permitted, whilst other vendor validity checks (e.g. ESRI) permit self-touching holes.

If errorLoc is specified, it will be set to the geometry of the error location.

Implemented in QgsGeos.

◆ length()

virtual double QgsGeometryEngine::length ( QString * errorMsg = nullptr ) const

pure virtual

Implemented in QgsGeos.

◆ logError()

void QgsGeometryEngine::logError	(	const QString &	engineName,
		const QString &	message
	)		const

inlineprotected

Logs an error message encountered during an operation.

See also: setLogErrors()

Since: QGIS 3.16

Definition at line 352 of file qgsgeometryengine.h.

◆ offsetCurve()

virtual QgsAbstractGeometry * QgsGeometryEngine::offsetCurve	(	double	distance,
		int	segments,
		Qgis::JoinStyle	joinStyle,
		double	miterLimit,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Offsets a curve.

Implemented in QgsGeos.

◆ overlaps()

virtual bool QgsGeometryEngine::overlaps	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Checks if geom overlaps this.

Implemented in QgsGeos.

◆ pointOnSurface()

virtual QgsPoint * QgsGeometryEngine::pointOnSurface ( QString * errorMsg = nullptr ) const

pure virtual

Calculate a point that is guaranteed to be on the surface of this.

May return a \c nullptr.

Implemented in QgsGeos.

◆ prepareGeometry()

virtual void QgsGeometryEngine::prepareGeometry ( )

pure virtual

Prepares the geometry, so that subsequent calls to spatial relation methods are much faster.

This should be called for any geometry which is used for multiple relation tests against other geometries.

See also: geometryChanged()

Implemented in QgsGeos.

◆ relate()

virtual QString QgsGeometryEngine::relate	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Returns the Dimensional Extended 9 Intersection Model (DE-9IM) representation of the relationship between the geometries.

Parameters

geom	geometry to relate to
errorMsg	destination storage for any error message

Returns: DE-9IM string for relationship, or an empty string if an error occurred

Implemented in QgsGeos.

◆ relatePattern()

virtual bool QgsGeometryEngine::relatePattern	(	const QgsAbstractGeometry *	geom,
		const QString &	pattern,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Tests whether two geometries are related by a specified Dimensional Extended 9 Intersection Model (DE-9IM) pattern.

Parameters

geom	geometry to relate to
pattern	DE-9IM pattern for match
errorMsg	destination storage for any error message

Returns: true if geometry relationship matches with pattern

Implemented in QgsGeos.

◆ setLogErrors()

void QgsGeometryEngine::setLogErrors ( bool enabled )

inline

Sets whether warnings and errors encountered during the geometry operations should be logged.

By default these errors are logged to the console and in the QGIS UI. But for some operations errors are expected and logging these just results in noise. In this case setting enabled to false will avoid the automatic error reporting.

Since: QGIS 3.16

Definition at line 339 of file qgsgeometryengine.h.

◆ simplify()

virtual QgsAbstractGeometry * QgsGeometryEngine::simplify	(	double	tolerance,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Implemented in QgsGeos.

◆ splitGeometry()

virtual QgsGeometryEngine::EngineOperationResult QgsGeometryEngine::splitGeometry	(	const QgsLineString &	splitLine,
		QVector< QgsGeometry > &	newGeometries,
		bool	topological,
		QgsPointSequence &	topologyTestPoints,
		QString *	errorMsg = `nullptr`,
		bool	skipIntersectionCheck = `false`
	)		const

inlinevirtual

Splits this geometry according to a given line.

Parameters

	splitLine	the line that splits the geometry
[out]	newGeometries	list of new geometries that have been created with the split
	topological	`true` if topological editing is enabled
[out]	topologyTestPoints	points that need to be tested for topological completeness in the dataset
[out]	errorMsg	error messages emitted, if any
	skipIntersectionCheck	set to `true` to skip the potentially expensive initial intersection check. Only set this flag if an intersection test has already been performed by the caller!

Returns: 0 in case of success, 1 if geometry has not been split, error else

Reimplemented in QgsGeos.

Definition at line 312 of file qgsgeometryengine.h.

◆ symDifference()

virtual QgsAbstractGeometry * QgsGeometryEngine::symDifference	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`,
		const QgsGeometryParameters &	parameters = `QgsGeometryParameters()`
	)		const

pure virtual

Calculate the symmetric difference of this and geom.

Parameters

geom	geometry to perform the operation
errorMsg	Error message returned by GEOS
parameters	can be used to specify parameters which control the difference results (since QGIS 3.28)

Implemented in QgsGeos.

◆ touches()

virtual bool QgsGeometryEngine::touches	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Checks if geom touches this.

Implemented in QgsGeos.

◆ within()

virtual bool QgsGeometryEngine::within	(	const QgsAbstractGeometry *	geom,
		QString *	errorMsg = `nullptr`
	)		const

pure virtual

Checks if geom is within this.

Implemented in QgsGeos.

Member Data Documentation

◆ mGeometry

const QgsAbstractGeometry* QgsGeometryEngine::mGeometry = nullptr

protected

Definition at line 342 of file qgsgeometryengine.h.

◆ mLogErrors

bool QgsGeometryEngine::mLogErrors = true

protected

Definition at line 343 of file qgsgeometryengine.h.

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

/build/qgis-3.41.0+git20241116+25ec5511245+99sid/src/core/geometry/qgsgeometryengine.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Example

Member Enumeration Documentation

◆ EngineOperationResult

Constructor & Destructor Documentation

◆ ~QgsGeometryEngine()

◆ QgsGeometryEngine()

Member Function Documentation

◆ area()

◆ buffer() [1/2]

◆ buffer() [2/2]

◆ centroid()

◆ combine() [1/3]

◆ combine() [2/3]

◆ combine() [3/3]

◆ contains()

◆ convexHull()

◆ crosses()

◆ difference()

◆ disjoint()

◆ distance()

◆ distanceWithin()

◆ envelope()

◆ geometryChanged()

◆ interpolate()

◆ intersection()

◆ intersects()

◆ isEmpty()

◆ isEqual()

◆ isSimple()

◆ isValid()

◆ length()

◆ logError()

◆ offsetCurve()

◆ overlaps()

◆ pointOnSurface()

◆ prepareGeometry()

◆ relate()

◆ relatePattern()

◆ setLogErrors()

◆ simplify()

◆ splitGeometry()

◆ symDifference()

◆ touches()

◆ within()

Member Data Documentation

◆ mGeometry

◆ mLogErrors