QGIS API Documentation  3.21.0-Master (56b4176581)
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
QgsGeometryEngine Class Referenceabstract

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:
Inheritance graph
[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 QgsAbstractGeometrybuffer (double distance, int segments, Qgis::EndCapStyle endCapStyle, Qgis::JoinStyle joinStyle, double miterLimit, QString *errorMsg=nullptr) const =0
 Buffers a geometry. More...
 
virtual QgsAbstractGeometrybuffer (double distance, int segments, QString *errorMsg=nullptr) const =0
 
virtual QgsPointcentroid (QString *errorMsg=nullptr) const =0
 Calculates the centroid of this. More...
 
virtual QgsAbstractGeometrycombine (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Calculate the combination of this and geom. More...
 
virtual QgsAbstractGeometrycombine (const QVector< QgsAbstractGeometry * > &geomList, QString *errorMsg) const =0
 Calculate the combination of this and geometries. More...
 
virtual QgsAbstractGeometrycombine (const QVector< QgsGeometry > &geometries, QString *errorMsg=nullptr) const =0
 Calculate the combination of this and geometries. More...
 
virtual bool contains (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Checks if geom contains this. More...
 
virtual QgsAbstractGeometryconvexHull (QString *errorMsg=nullptr) const =0
 Calculate the convex hull of this. More...
 
virtual bool crosses (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Checks if geom crosses this. More...
 
virtual QgsAbstractGeometrydifference (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Calculate the difference of this and geom. More...
 
virtual bool disjoint (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Checks if geom is disjoint from this. More...
 
virtual double distance (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Calculates the distance between this and geom. More...
 
virtual bool distanceWithin (const QgsAbstractGeometry *geom, double maxdistance, QString *errorMsg=nullptr) const =0
 Checks if geom is within maxdistance distance from this geometry. More...
 
virtual QgsAbstractGeometryenvelope (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. More...
 
virtual QgsAbstractGeometryinterpolate (double distance, QString *errorMsg=nullptr) const =0
 
virtual QgsAbstractGeometryintersection (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Calculate the intersection of this and geom. More...
 
virtual bool intersects (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Checks if geom intersects this. More...
 
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. More...
 
virtual bool isSimple (QString *errorMsg=nullptr) const =0
 Determines whether the geometry is simple (according to OGC definition). More...
 
virtual bool isValid (QString *errorMsg=nullptr, bool allowSelfTouchingHoles=false, QgsGeometry *errorLoc=nullptr) const =0
 Returns true if the geometry is valid. More...
 
virtual double length (QString *errorMsg=nullptr) const =0
 
virtual QgsAbstractGeometryoffsetCurve (double distance, int segments, Qgis::JoinStyle joinStyle, double miterLimit, QString *errorMsg=nullptr) const =0
 Offsets a curve. More...
 
virtual bool overlaps (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Checks if geom overlaps this. More...
 
virtual QgsPointpointOnSurface (QString *errorMsg=nullptr) const =0
 Calculate a point that is guaranteed to be on the surface of this. More...
 
virtual void prepareGeometry ()=0
 Prepares the geometry, so that subsequent calls to spatial relation methods are much faster. More...
 
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. More...
 
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. More...
 
void setLogErrors (bool enabled)
 Sets whether warnings and errors encountered during the geometry operations should be logged. More...
 
virtual QgsAbstractGeometrysimplify (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. More...
 
virtual QgsAbstractGeometrysymDifference (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Calculate the symmetric difference of this and geom. More...
 
virtual bool touches (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Checks if geom touches this. More...
 
virtual bool within (const QgsAbstractGeometry *geom, QString *errorMsg=nullptr) const =0
 Checks if geom is within this. More...
 

Protected Member Functions

 QgsGeometryEngine (const QgsAbstractGeometry *geometry)
 
void logError (const QString &engineName, const QString &message) const
 Logs an error message encountered during an operation. More...
 

Protected Attributes

const QgsAbstractGeometrymGeometry = 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!')
static QgsGeometry fromWkt(const QString &wkt)
Creates a new geometry from a WKT string.
static QgsGeometryEngine * createGeometryEngine(const QgsAbstractGeometry *geometry)
Creates and returns a new geometry engine representing the specified geometry.

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

Since
QGIS 2.10

Definition at line 68 of file qgsgeometryengine.h.

Member Enumeration Documentation

◆ 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 76 of file qgsgeometryengine.h.

Constructor & Destructor Documentation

◆ ~QgsGeometryEngine()

virtual QgsGeometryEngine::~QgsGeometryEngine ( )
virtualdefault

◆ QgsGeometryEngine()

QgsGeometryEngine::QgsGeometryEngine ( const QgsAbstractGeometry geometry)
inlineprotected

Definition at line 355 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.

Since
QGIS 3.0 the centroid is returned

Implemented in QgsGeos.

◆ combine() [1/3]

virtual QgsAbstractGeometry* QgsGeometryEngine::combine ( const QgsAbstractGeometry geom,
QString *  errorMsg = nullptr 
) const
pure virtual

Calculate the combination of this and geom.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ combine() [2/3]

virtual QgsAbstractGeometry* QgsGeometryEngine::combine ( const QVector< QgsAbstractGeometry * > &  geomList,
QString *  errorMsg 
) const
pure virtual

Calculate the combination of this and geometries.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ combine() [3/3]

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

Calculate the combination of this and geometries.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ contains()

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

Checks if geom contains this.

Since
QGIS 3.0 geom is a pointer

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.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ difference()

virtual QgsAbstractGeometry* QgsGeometryEngine::difference ( const QgsAbstractGeometry geom,
QString *  errorMsg = nullptr 
) const
pure virtual

Calculate the difference of this and geom.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ disjoint()

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

Checks if geom is disjoint from this.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ distance()

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

Calculates the distance between this and geom.

Since
QGIS 3.0 geom is a pointer

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
pure virtual

Calculate the intersection of this and geom.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ intersects()

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

Checks if geom intersects this.

Since
QGIS 3.0 geom is a pointer

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.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ isSimple()

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

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

Since
QGIS 3.0

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 346 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.

Since
QGIS 3.0 geom is a pointer

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.

Since
QGIS 3.0 the centroid is returned

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
geomgeometry to relate to
errorMsgdestination storage for any error message
Returns
DE-9IM string for relationship, or an empty string if an error occurred
Since
QGIS 2.12

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
geomgeometry to relate to
patternDE-9IM pattern for match
errorMsgdestination storage for any error message
Returns
true if geometry relationship matches with pattern
Since
QGIS 2.14

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 333 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
splitLinethe line that splits the geometry
[out]newGeometrieslist of new geometries that have been created with the split
topologicaltrue if topological editing is enabled
[out]topologyTestPointspoints that need to be tested for topological completeness in the dataset
[out]errorMsgerror messages emitted, if any
skipIntersectionCheckset 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 306 of file qgsgeometryengine.h.

◆ symDifference()

virtual QgsAbstractGeometry* QgsGeometryEngine::symDifference ( const QgsAbstractGeometry geom,
QString *  errorMsg = nullptr 
) const
pure virtual

Calculate the symmetric difference of this and geom.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ touches()

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

Checks if geom touches this.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

◆ within()

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

Checks if geom is within this.

Since
QGIS 3.0 geom is a pointer

Implemented in QgsGeos.

Member Data Documentation

◆ mGeometry

const QgsAbstractGeometry* QgsGeometryEngine::mGeometry = nullptr
protected

Definition at line 336 of file qgsgeometryengine.h.

◆ mLogErrors

bool QgsGeometryEngine::mLogErrors = true
protected

Definition at line 337 of file qgsgeometryengine.h.


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