Class: QgsGeometryEngine

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/).

Class Hierarchy

Inheritance diagram of qgis.core.QgsGeometryEngine

Subclasses

QgsGeos

Does vector analysis using the GEOS library and handles import, export, and exception handling.

Abstract Methods

area

buffer

centroid

Calculates the centroid of this.

combine

Calculate the combination of this and geom.

contains

Checks if geom contains this.

convexHull

Calculate the convex hull of this.

crosses

Checks if geom crosses this.

difference

Calculate the difference of this and geom.

disjoint

Checks if geom is disjoint from this.

distance

Calculates the distance between this and geom.

distanceWithin

Checks if geom is within maxdistance distance from this geometry

envelope

geometryChanged

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

interpolate

intersection

Calculate the intersection of this and geom.

intersects

Checks if geom intersects this.

isEmpty

isEqual

Checks if this is equal to geom.

isSimple

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

isValid

Returns True if the geometry is valid.

length

offsetCurve

Offsets a curve.

overlaps

Checks if geom overlaps this.

pointOnSurface

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

prepareGeometry

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

relate

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

relatePattern

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

simplify

symDifference

Calculate the symmetric difference of this and geom.

touches

Checks if geom touches this.

within

Checks if geom is within this.

Methods

logError

Logs an error message encountered during an operation.

setLogErrors

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

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsGeometryEngine. See the FAQ for more details.

splitGeometry

Splits this geometry according to a given line.

Attributes

EngineError

InvalidBaseGeometry

InvalidInput

MethodNotImplemented

NodedGeometryError

NothingHappened

SplitCannotSplitPoint

Success

class qgis.core.QgsGeometryEngine[source]

Bases: object

EngineError = 1002
class EngineOperationResult

Bases: int

InvalidBaseGeometry = 1004
InvalidInput = 1005
MethodNotImplemented = 1001
NodedGeometryError = 1003
NothingHappened = 1000
SplitCannotSplitPoint = 1006
Success = 0
abstract area(self, errorMsg: str | None | None = '') float[source]
Parameters:

errorMsg (Optional[Optional[str]] = '')

Return type:

float

abstract buffer(self, distance: float, segments: int, errorMsg: str | None | None = '') QgsAbstractGeometry | None[source]
Parameters:
  • distance (float)

  • segments (int)

  • errorMsg (Optional[Optional[str]] = '')

Return type:

Optional[QgsAbstractGeometry]

abstract buffer(self, distance: float, segments: int, endCapStyle: Qgis.EndCapStyle, joinStyle: Qgis.JoinStyle, miterLimit: float, errorMsg: str | None | None = '') QgsAbstractGeometry | None[source]

Buffers a geometry.

Parameters:
  • distance (float)

  • segments (int)

  • endCapStyle (Qgis.EndCapStyle)

  • joinStyle (Qgis.JoinStyle)

  • miterLimit (float)

  • errorMsg (Optional[Optional[str]] = '')

Return type:

Optional[QgsAbstractGeometry]

abstract centroid(self, errorMsg: str | None | None = '') QgsPoint | None[source]

Calculates the centroid of this. May return a `None`.

Parameters:

errorMsg (Optional[Optional[str]] = '')

Return type:

Optional[QgsPoint]

abstract combine(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry | None[source]

Calculate the combination of this and geom.

Parameters:
  • geom (Optional[QgsAbstractGeometry]) – geometry to perform the operation

  • errorMsg (Optional[Optional[str]] = '') – Error message returned by GEOS

  • parameters (QgsGeometryParameters = QgsGeometryParameters()) – can be used to specify parameters which control the union results (since QGIS 3.28)

Return type:

Optional[QgsAbstractGeometry]

abstract combine(self, geomList: Iterable[QgsAbstractGeometry], errorMsg: str | None | None, parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry | None[source]

Calculate the combination of this and geometries.

Parameters:
  • geomList (Iterable[QgsAbstractGeometry]) – list of geometries to perform the operation

  • errorMsg (Optional[Optional[str]]) – Error message returned by GEOS

  • parameters (QgsGeometryParameters = QgsGeometryParameters()) – can be used to specify parameters which control the combination results (since QGIS 3.28)

Return type:

Optional[QgsAbstractGeometry]

abstract combine(self, geometries: Iterable[QgsGeometry], errorMsg: str | None | None = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry | None[source]

Calculate the combination of this and geometries.

Parameters:
  • geometries (Iterable[QgsGeometry]) – list of geometries to perform the operation

  • errorMsg (Optional[Optional[str]] = '') – Error message returned by GEOS

  • parameters (QgsGeometryParameters = QgsGeometryParameters()) – can be used to specify parameters which control the combination results (since QGIS 3.28)

Return type:

Optional[QgsAbstractGeometry]

abstract contains(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool[source]

Checks if geom contains this.

Parameters:
Return type:

bool

abstract convexHull(self, errorMsg: str | None | None = '') QgsAbstractGeometry | None[source]

Calculate the convex hull of this.

Parameters:

errorMsg (Optional[Optional[str]] = '')

Return type:

Optional[QgsAbstractGeometry]

abstract crosses(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool[source]

Checks if geom crosses this.

Parameters:
Return type:

bool

abstract difference(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry | None[source]

Calculate the difference of this and geom.

Parameters:
  • geom (Optional[QgsAbstractGeometry]) – geometry to perform the operation

  • errorMsg (Optional[Optional[str]] = '') – Error message returned by GEOS

  • parameters (QgsGeometryParameters = QgsGeometryParameters()) – can be used to specify parameters which control the difference results (since QGIS 3.28)

Return type:

Optional[QgsAbstractGeometry]

abstract disjoint(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool[source]

Checks if geom is disjoint from this.

Parameters:
Return type:

bool

abstract distance(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') float[source]

Calculates the distance between this and geom.

Parameters:
Return type:

float

abstract distanceWithin(self, geom: QgsAbstractGeometry | None, maxdistance: float, errorMsg: str | None | None = '') bool[source]

Checks if geom is within maxdistance distance from this geometry

Added in version 3.22.

Parameters:
  • geom (Optional[QgsAbstractGeometry])

  • maxdistance (float)

  • errorMsg (Optional[Optional[str]] = '')

Return type:

bool

abstract envelope(self, errorMsg: str | None | None = '') QgsAbstractGeometry | None[source]
Parameters:

errorMsg (Optional[Optional[str]] = '')

Return type:

Optional[QgsAbstractGeometry]

abstract geometryChanged(self)[source]

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

abstract interpolate(self, distance: float, errorMsg: str | None | None = '') QgsAbstractGeometry | None[source]
Parameters:
  • distance (float)

  • errorMsg (Optional[Optional[str]] = '')

Return type:

Optional[QgsAbstractGeometry]

abstract intersection(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry | None[source]

Calculate the intersection of this and geom.

Parameters:
  • geom (Optional[QgsAbstractGeometry]) – geometry to perform the operation

  • errorMsg (Optional[Optional[str]] = '') – Error message returned by GEOS

  • parameters (QgsGeometryParameters = QgsGeometryParameters()) – can be used to specify parameters which control the intersection results (since QGIS 3.28)

Return type:

Optional[QgsAbstractGeometry]

abstract intersects(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool[source]

Checks if geom intersects this.

Parameters:
Return type:

bool

abstract isEmpty(self, errorMsg: str | None | None) bool[source]
Parameters:

errorMsg (Optional[Optional[str]])

Return type:

bool

abstract isEqual(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool[source]

Checks if this is equal to geom. If both are Null geometries, `False` is returned.

Parameters:
Return type:

bool

abstract isSimple(self, errorMsg: str | None | None = '') bool[source]

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

Parameters:

errorMsg (Optional[Optional[str]] = '')

Return type:

bool

abstract isValid(self, errorMsg: str | None | None = '', allowSelfTouchingHoles: bool = False, errorLoc: QgsGeometry | None = None) bool[source]

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.

Parameters:
  • errorMsg (Optional[Optional[str]] = '')

  • allowSelfTouchingHoles (bool = False)

  • errorLoc (Optional[QgsGeometry] = None)

Return type:

bool

abstract length(self, errorMsg: str | None | None = '') float[source]
Parameters:

errorMsg (Optional[Optional[str]] = '')

Return type:

float

logError(self, engineName: str | None, message: str | None)[source]

Logs an error message encountered during an operation.

See also

setLogErrors()

Added in version 3.16.

Parameters:
  • engineName (Optional[str])

  • message (Optional[str])

abstract offsetCurve(self, distance: float, segments: int, joinStyle: Qgis.JoinStyle, miterLimit: float, errorMsg: str | None | None = '') QgsAbstractGeometry | None[source]

Offsets a curve.

Parameters:
  • distance (float)

  • segments (int)

  • joinStyle (Qgis.JoinStyle)

  • miterLimit (float)

  • errorMsg (Optional[Optional[str]] = '')

Return type:

Optional[QgsAbstractGeometry]

abstract overlaps(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool[source]

Checks if geom overlaps this.

Parameters:
Return type:

bool

abstract pointOnSurface(self, errorMsg: str | None | None = '') QgsPoint | None[source]

Calculate a point that is guaranteed to be on the surface of this. May return a `None`.

Parameters:

errorMsg (Optional[Optional[str]] = '')

Return type:

Optional[QgsPoint]

abstract prepareGeometry(self)[source]

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.

abstract relate(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') str[source]

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

Parameters:
  • geom (Optional[QgsAbstractGeometry]) – geometry to relate to

  • errorMsg (Optional[Optional[str]] = '') – destination storage for any error message

Return type:

str

Returns:

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

abstract relatePattern(self, geom: QgsAbstractGeometry | None, pattern: str | None, errorMsg: str | None | None = '') bool[source]

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

Parameters:
  • geom (Optional[QgsAbstractGeometry]) – geometry to relate to

  • pattern (Optional[str]) – DE-9IM pattern for match

  • errorMsg (Optional[Optional[str]] = '') – destination storage for any error message

Return type:

bool

Returns:

True if geometry relationship matches with pattern

setLogErrors(self, enabled: bool)[source]

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.

Added in version 3.16.

Parameters:

enabled (bool)

abstract simplify(self, tolerance: float, errorMsg: str | None | None = '') QgsAbstractGeometry | None[source]
Parameters:
  • tolerance (float)

  • errorMsg (Optional[Optional[str]] = '')

Return type:

Optional[QgsAbstractGeometry]

virtual splitGeometry(self, splitLine: QgsLineString, topological: bool, topologyTestPoints: Iterable[QgsPoint], errorMsg: str | None | None = '', skipIntersectionCheck: bool = False)[source]

Splits this geometry according to a given line.

Parameters:
  • splitLine (QgsLineString) – the line that splits the geometry

  • topological (bool) – True if topological editing is enabled

  • topologyTestPoints (Iterable[QgsPoint]) – points that need to be tested for topological completeness in the dataset

  • errorMsg (Optional[Optional[str]] = '') – error messages emitted, if any

  • skipIntersectionCheck (bool = False) -> (QgsGeometryEngine.EngineOperationResult) – 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

  • newGeometries: list of new geometries that have been created with the split

abstract symDifference(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry | None[source]

Calculate the symmetric difference of this and geom.

Parameters:
  • geom (Optional[QgsAbstractGeometry]) – geometry to perform the operation

  • errorMsg (Optional[Optional[str]] = '') – Error message returned by GEOS

  • parameters (QgsGeometryParameters = QgsGeometryParameters()) – can be used to specify parameters which control the difference results (since QGIS 3.28)

Return type:

Optional[QgsAbstractGeometry]

abstract touches(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool[source]

Checks if geom touches this.

Parameters:
Return type:

bool

abstract within(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool[source]

Checks if geom is within this.

Parameters:
Return type:

bool