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

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`
`logError`	Logs an error message encountered during an operation.
`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.
`setLogErrors`	Sets whether warnings and errors encountered during the geometry operations should be logged.
`simplify`
`splitGeometry`	Splits this geometry according to a given line.
`symDifference`	Calculate the symmetric difference of this and geom.
`touches`	Checks if geom touches this.
`within`	Checks if geom is within this.

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¶

area(self, errorMsg: str | None | None = '') → float[source]¶

Parameters:: errorMsg (Optional[Optional[str]] = '')
Return type:: float

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]

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]

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]

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]

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]

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]

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

Checks if geom contains this.

Parameters:

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

Return type:

bool

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

Calculate the convex hull of this.

Parameters:: errorMsg (Optional[Optional[str]] = '')
Return type:: Optional[QgsAbstractGeometry]

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

Checks if geom crosses this.

Parameters:

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

Return type:

bool

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]

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

Checks if geom is disjoint from this.

Parameters:

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

Return type:

bool

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

Calculates the distance between this and geom.

Parameters:

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

Return type:

float

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

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

Parameters:: errorMsg (Optional[Optional[str]] = '')
Return type:: Optional[QgsAbstractGeometry]

geometryChanged(self)[source]¶: Should be called whenever the geometry associated with the engine has been modified and the engine must be updated to suit.

interpolate(self, distance: float, errorMsg: str | None | None = '') → QgsAbstractGeometry | None[source]¶

Parameters:

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

Return type:

Optional[QgsAbstractGeometry]

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]

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

Checks if geom intersects this.

Parameters:

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

Return type:

bool

isEmpty(self, errorMsg: str | None | None) → bool[source]¶

Parameters:: errorMsg (Optional[Optional[str]])
Return type:: bool

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:

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

Return type:

bool

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

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

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.