Class: QgsGeometryEngine¶
- class qgis.core.QgsGeometryEngine¶
Bases:
sip.wrapper
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 callingQgsGeometry.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 callingintersects()
,within()
, etc) then the geometry should first be prepared by callingprepareGeometry()
before performing the tests.Example¶
# polygon_geometry contains a complex polygon, with many vertices polygon_geometry = QgsGeometry.fromWkt('Polygon((...))') # create a :py:class:`.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/).Added in version 2.10:
Methods
- param errorMsg:
buffer(self, distance: float, segments: int, endCapStyle: Qgis.EndCapStyle, joinStyle: Qgis.JoinStyle, miterLimit: float, errorMsg: Optional[Optional[str]] = '') -> Optional[QgsAbstractGeometry] Buffers a geometry.
Calculates the centroid of this.
Calculate the combination of this and
geom
.Checks if
geom
contains this.Calculate the convex hull of this.
Checks if
geom
crosses this.Calculate the difference of this and
geom
.Checks if
geom
is disjoint from this.Calculates the distance between this and
geom
.Checks if
geom
is withinmaxdistance
distance from this geometry- param errorMsg:
Should be called whenever the geometry associated with the engine has been modified and the engine must be updated to suit.
- param distance:
Calculate the intersection of this and
geom
.Checks if
geom
intersects this.- param errorMsg:
Checks if this is equal to
geom
.Determines whether the geometry is simple (according to OGC definition).
Returns
True
if the geometry is valid.- param errorMsg:
Logs an error
message
encountered during an operation.Offsets a curve.
Checks if
geom
overlaps this.Calculate a point that is guaranteed to be on the surface of this.
Prepares the geometry, so that subsequent calls to spatial relation methods are much faster.
Returns the Dimensional Extended 9 Intersection Model (DE-9IM) representation of the relationship between the geometries.
Tests whether two geometries are related by a specified Dimensional Extended 9 Intersection Model (DE-9IM) pattern.
Sets whether warnings and errors encountered during the geometry operations should be logged.
- param tolerance:
Splits this geometry according to a given line.
Calculate the symmetric difference of this and
geom
.Checks if
geom
touches this.Checks if
geom
is within this.Signals
Attributes
- 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 ¶
- Parameters:
errorMsg (Optional[Optional[str]] = '')
- Return type:
float
- buffer(self, distance: float, segments: int, errorMsg: str | None | None = '') QgsAbstractGeometry | None ¶
buffer(self, distance: float, segments: int, endCapStyle: Qgis.EndCapStyle, joinStyle: Qgis.JoinStyle, miterLimit: float, errorMsg: Optional[Optional[str]] = ‘’) -> Optional[QgsAbstractGeometry] Buffers a geometry.
- Parameters:
distance (float)
segments (int)
errorMsg (Optional[Optional[str]] = '')
- Return type:
Optional[QgsAbstractGeometry]
- centroid(self, errorMsg: str | None | None = '') QgsPoint | None ¶
Calculates the centroid of this. May return a
`None`
.Added in version 3.0.
- Parameters:
errorMsg (Optional[Optional[str]] = '')
- Return type:
Optional[QgsPoint]
- combine(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry | None ¶
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)
Added in version 3.0.
combine(self, geomList: Iterable[QgsAbstractGeometry], errorMsg: Optional[Optional[str]], parameters:
QgsGeometryParameters
= QgsGeometryParameters()) -> Optional[QgsAbstractGeometry] Calculate the combination of this andgeometries
.- 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)
Added in version 3.0.
combine(self, geometries: Iterable[QgsGeometry], errorMsg: Optional[Optional[str]] = ‘’, parameters:
QgsGeometryParameters
= QgsGeometryParameters()) -> Optional[QgsAbstractGeometry] Calculate the combination of this andgeometries
.- 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)
Added in version 3.0.
- Return type:
Optional[QgsAbstractGeometry]
- contains(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool ¶
Checks if
geom
contains this.Added in version 3.0.
- Parameters:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool
- convexHull(self, errorMsg: str | None | None = '') QgsAbstractGeometry | None ¶
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 ¶
Checks if
geom
crosses this.Added in version 3.0.
- 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 ¶
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)
Added in version 3.0.
- Return type:
Optional[QgsAbstractGeometry]
- disjoint(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool ¶
Checks if
geom
is disjoint from this.Added in version 3.0.
- Parameters:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool
- distance(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') float ¶
Calculates the distance between this and
geom
.Added in version 3.0.
- Parameters:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
float
- distanceWithin(self, geom: QgsAbstractGeometry | None, maxdistance: float, errorMsg: str | None | None = '') bool ¶
Checks if
geom
is withinmaxdistance
distance from this geometryAdded 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 ¶
- Parameters:
errorMsg (Optional[Optional[str]] = '')
- Return type:
Optional[QgsAbstractGeometry]
- geometryChanged(self)¶
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 ¶
- 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 ¶
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)
Added in version 3.0.
- Return type:
Optional[QgsAbstractGeometry]
- intersects(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool ¶
Checks if
geom
intersects this.Added in version 3.0.
- Parameters:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool
- isEmpty(self, errorMsg: str | None | None) bool ¶
- Parameters:
errorMsg (Optional[Optional[str]])
- Return type:
bool
- isEqual(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool ¶
Checks if this is equal to
geom
. If both are Null geometries,`False`
is returned.Added in version 3.0.
- Parameters:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool
- isSimple(self, errorMsg: str | None | None = '') bool ¶
Determines whether the geometry is simple (according to OGC definition).
Added in version 3.0.
- Parameters:
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool
- isValid(self, errorMsg: str | None | None = '', allowSelfTouchingHoles: bool = False, errorLoc: QgsGeometry | None = None) bool ¶
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 ¶
- Parameters:
errorMsg (Optional[Optional[str]] = '')
- Return type:
float
- logError(self, engineName: str | None, message: str | None)¶
Logs an error
message
encountered during an operation.See also
Added in version 3.16.
- Parameters:
engineName (Optional[str])
message (Optional[str])
- offsetCurve(self, distance: float, segments: int, joinStyle: Qgis.JoinStyle, miterLimit: float, errorMsg: str | None | None = '') QgsAbstractGeometry | None ¶
Offsets a curve.
- Parameters:
distance (float)
segments (int)
joinStyle (Qgis.JoinStyle)
miterLimit (float)
errorMsg (Optional[Optional[str]] = '')
- Return type:
Optional[QgsAbstractGeometry]
- overlaps(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool ¶
Checks if
geom
overlaps this.Added in version 3.0.
- Parameters:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool
- pointOnSurface(self, errorMsg: str | None | None = '') QgsPoint | None ¶
Calculate a point that is guaranteed to be on the surface of this. May return a
`None`
.Added in version 3.0.
- Parameters:
errorMsg (Optional[Optional[str]] = '')
- Return type:
Optional[QgsPoint]
- prepareGeometry(self)¶
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
- relate(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') str ¶
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
Added in version 2.12.
- relatePattern(self, geom: QgsAbstractGeometry | None, pattern: str | None, errorMsg: str | None | None = '') bool ¶
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
Added in version 2.14.
- setLogErrors(self, enabled: bool)¶
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
toFalse
will avoid the automatic error reporting.Added in version 3.16.
- Parameters:
enabled (bool)
- simplify(self, tolerance: float, errorMsg: str | None | None = '') QgsAbstractGeometry | None ¶
- Parameters:
tolerance (float)
errorMsg (Optional[Optional[str]] = '')
- Return type:
Optional[QgsAbstractGeometry]
- splitGeometry(self, splitLine: QgsLineString, topological: bool, topologyTestPoints: Iterable[QgsPoint], errorMsg: str | None | None = '', skipIntersectionCheck: bool = False)¶
Splits this geometry according to a given line.
- Parameters:
splitLine (QgsLineString) – the line that splits the geometry
param[out] newGeometries list of new geometries that have been created with the split :type topological: bool :param topological:
True
if topological editing is enabled param[out] topologyTestPoints points that need to be tested for topological completeness in the dataset param[out] errorMsg error messages emitted, if any :type skipIntersectionCheck: bool = False) -> (QgsGeometryEngine.EngineOperationResult :param skipIntersectionCheck: set toTrue
to skip the potentially expensive initial intersection check. Only set this flag if an intersectiontest has already been performed by the caller!
- Returns:
0 in case of success, 1 if geometry has not been split, error else
- Parameters:
topologyTestPoints (Iterable[QgsPoint])
errorMsg (Optional[Optional[str]] = '')
- symDifference(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry | None ¶
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)
Added in version 3.0.
- Return type:
Optional[QgsAbstractGeometry]
- touches(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool ¶
Checks if
geom
touches this.Added in version 3.0.
- Parameters:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool
- within(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool ¶
Checks if
geom
is within this.Added in version 3.0.
- Parameters:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool