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/).New in version 2.10:
Methods
- param errorMsg:
buffer(self, distance: float, segments: int, endCapStyle: Qgis.EndCapStyle, joinStyle: Qgis.JoinStyle, miterLimit: float, errorMsg: str = '') -> 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.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 = '') float ¶
- Parameters:
errorMsg (str = '') –
- Return type:
float
- buffer(self, distance: float, segments: int, errorMsg: str = '') QgsAbstractGeometry ¶
buffer(self, distance: float, segments: int, endCapStyle: Qgis.EndCapStyle, joinStyle: Qgis.JoinStyle, miterLimit: float, errorMsg: str = ‘’) -> QgsAbstractGeometry Buffers a geometry.
- Parameters:
distance (float) –
segments (int) –
errorMsg (str = '') –
- Return type:
- centroid(self, errorMsg: str = '') QgsPoint ¶
Calculates the centroid of this. May return a
`None`
.New in version 3.0.
- Parameters:
errorMsg (str = '') –
- Return type:
- combine(self, geom: QgsAbstractGeometry, errorMsg: str = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry ¶
Calculate the combination of this and
geom
.- Parameters:
geom (QgsAbstractGeometry) – geometry to perform the operation
errorMsg (str = '') – Error message returned by GEOS
parameters (
QgsGeometryParameters
= QgsGeometryParameters()) – can be used to specify parameters which control the union results (since QGIS 3.28)
New in version 3.0.
combine(self, geomList: Iterable[QgsAbstractGeometry], errorMsg: str, parameters:
QgsGeometryParameters
= QgsGeometryParameters()) -> 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)
New in version 3.0.
combine(self, geometries: Iterable[QgsGeometry], errorMsg: str = ‘’, parameters:
QgsGeometryParameters
= QgsGeometryParameters()) -> 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)
New in version 3.0.
- Return type:
- contains(self, geom: QgsAbstractGeometry, errorMsg: str = '') bool ¶
Checks if
geom
contains this.New in version 3.0.
- Parameters:
geom (QgsAbstractGeometry) –
errorMsg (str = '') –
- Return type:
bool
- convexHull(self, errorMsg: str = '') QgsAbstractGeometry ¶
Calculate the convex hull of this.
- Parameters:
errorMsg (str = '') –
- Return type:
- crosses(self, geom: QgsAbstractGeometry, errorMsg: str = '') bool ¶
Checks if
geom
crosses this.New in version 3.0.
- Parameters:
geom (QgsAbstractGeometry) –
errorMsg (str = '') –
- Return type:
bool
- difference(self, geom: QgsAbstractGeometry, errorMsg: str = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry ¶
Calculate the difference of this and
geom
.- Parameters:
geom (QgsAbstractGeometry) – geometry to perform the operation
errorMsg (str = '') – Error message returned by GEOS
parameters (
QgsGeometryParameters
= QgsGeometryParameters()) – can be used to specify parameters which control the difference results (since QGIS 3.28)
New in version 3.0.
- Return type:
- disjoint(self, geom: QgsAbstractGeometry, errorMsg: str = '') bool ¶
Checks if
geom
is disjoint from this.New in version 3.0.
- Parameters:
geom (QgsAbstractGeometry) –
errorMsg (str = '') –
- Return type:
bool
- distance(self, geom: QgsAbstractGeometry, errorMsg: str = '') float ¶
Calculates the distance between this and
geom
.New in version 3.0.
- Parameters:
geom (QgsAbstractGeometry) –
errorMsg (str = '') –
- Return type:
float
- distanceWithin(self, geom: QgsAbstractGeometry, maxdistance: float, errorMsg: str = '') bool ¶
Checks if
geom
is withinmaxdistance
distance from this geometryNew in version 3.22.
- Parameters:
geom (QgsAbstractGeometry) –
maxdistance (float) –
errorMsg (str = '') –
- Return type:
bool
- envelope(self, errorMsg: str = '') QgsAbstractGeometry ¶
- Parameters:
errorMsg (str = '') –
- Return type:
- 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 = '') QgsAbstractGeometry ¶
- Parameters:
distance (float) –
errorMsg (str = '') –
- Return type:
- intersection(self, geom: QgsAbstractGeometry, errorMsg: str = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry ¶
Calculate the intersection of this and
geom
.- Parameters:
geom (QgsAbstractGeometry) – geometry to perform the operation
errorMsg (str = '') – Error message returned by GEOS
parameters (
QgsGeometryParameters
= QgsGeometryParameters()) – can be used to specify parameters which control the intersection results (since QGIS 3.28)
New in version 3.0.
- Return type:
- intersects(self, geom: QgsAbstractGeometry, errorMsg: str = '') bool ¶
Checks if
geom
intersects this.New in version 3.0.
- Parameters:
geom (QgsAbstractGeometry) –
errorMsg (str = '') –
- Return type:
bool
- isEmpty(self, errorMsg: str) bool ¶
- Parameters:
errorMsg (str) –
- Return type:
bool
- isEqual(self, geom: QgsAbstractGeometry, errorMsg: str = '') bool ¶
Checks if this is equal to
geom
. If both are Null geometries,`False`
is returned.New in version 3.0.
- Parameters:
geom (QgsAbstractGeometry) –
errorMsg (str = '') –
- Return type:
bool
- isSimple(self, errorMsg: str = '') bool ¶
Determines whether the geometry is simple (according to OGC definition).
New in version 3.0.
- Parameters:
errorMsg (str = '') –
- Return type:
bool
- isValid(self, errorMsg: str = '', allowSelfTouchingHoles: bool = False, errorLoc: QgsGeometry = 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 (str = '') –
allowSelfTouchingHoles (bool = False) –
errorLoc (
QgsGeometry
= None) –
- Return type:
bool
- length(self, errorMsg: str = '') float ¶
- Parameters:
errorMsg (str = '') –
- Return type:
float
- logError(self, engineName: str, message: str)¶
Logs an error
message
encountered during an operation.See also
New in version 3.16.
- Parameters:
engineName (str) –
message (str) –
- offsetCurve(self, distance: float, segments: int, joinStyle: Qgis.JoinStyle, miterLimit: float, errorMsg: str = '') QgsAbstractGeometry ¶
Offsets a curve.
- Parameters:
distance (float) –
segments (int) –
joinStyle (Qgis.JoinStyle) –
miterLimit (float) –
errorMsg (str = '') –
- Return type:
- overlaps(self, geom: QgsAbstractGeometry, errorMsg: str = '') bool ¶
Checks if
geom
overlaps this.New in version 3.0.
- Parameters:
geom (QgsAbstractGeometry) –
errorMsg (str = '') –
- Return type:
bool
- pointOnSurface(self, errorMsg: str = '') QgsPoint ¶
Calculate a point that is guaranteed to be on the surface of this. May return a
`None`
.New in version 3.0.
- Parameters:
errorMsg (str = '') –
- Return type:
- 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, errorMsg: str = '') str ¶
Returns the Dimensional Extended 9 Intersection Model (DE-9IM) representation of the relationship between the geometries.
- Parameters:
geom (QgsAbstractGeometry) – geometry to relate to
errorMsg (str = '') – destination storage for any error message
- Return type:
str
- Returns:
DE-9IM string for relationship, or an empty string if an error occurred
New in version 2.12.
- relatePattern(self, geom: QgsAbstractGeometry, pattern: str, errorMsg: str = '') bool ¶
Tests whether two geometries are related by a specified Dimensional Extended 9 Intersection Model (DE-9IM) pattern.
- Parameters:
geom (QgsAbstractGeometry) – geometry to relate to
pattern (str) – DE-9IM pattern for match
errorMsg (str = '') – destination storage for any error message
- Return type:
bool
- Returns:
True
if geometry relationship matches with pattern
New 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.New in version 3.16.
- Parameters:
enabled (bool) –
- simplify(self, tolerance: float, errorMsg: str = '') QgsAbstractGeometry ¶
- Parameters:
tolerance (float) –
errorMsg (str = '') –
- Return type:
- splitGeometry(self, splitLine: QgsLineString, topological: bool, topologyTestPoints: Iterable[QgsPoint], errorMsg: str = '', skipIntersectionCheck: bool = False) Tuple[QgsGeometryEngine.EngineOperationResult, List[QgsGeometry]] ¶
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 :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!
- Return type:
Tuple[QgsGeometryEngine.EngineOperationResult, List[QgsGeometry]]
- Returns:
0 in case of success, 1 if geometry has not been split, error else
- Parameters:
topologyTestPoints (Iterable[QgsPoint]) –
errorMsg (str = '') –
- symDifference(self, geom: QgsAbstractGeometry, errorMsg: str = '', parameters: QgsGeometryParameters = QgsGeometryParameters()) QgsAbstractGeometry ¶
Calculate the symmetric difference of this and
geom
.- Parameters:
geom (QgsAbstractGeometry) – geometry to perform the operation
errorMsg (str = '') – Error message returned by GEOS
parameters (
QgsGeometryParameters
= QgsGeometryParameters()) – can be used to specify parameters which control the difference results (since QGIS 3.28)
New in version 3.0.
- Return type:
- touches(self, geom: QgsAbstractGeometry, errorMsg: str = '') bool ¶
Checks if
geom
touches this.New in version 3.0.
- Parameters:
geom (QgsAbstractGeometry) –
errorMsg (str = '') –
- Return type:
bool
- within(self, geom: QgsAbstractGeometry, errorMsg: str = '') bool ¶
Checks if
geom
is within this.New in version 3.0.
- Parameters:
geom (QgsAbstractGeometry) –
errorMsg (str = '') –
- Return type:
bool