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/).
Note
This is an abstract class, with methods which must be implemented by a subclass.
The following methods must be implemented: area()
, buffer()
, centroid()
, combine()
, contains()
, convexHull()
, crosses()
, difference()
, disjoint()
, distance()
, distanceWithin()
, envelope()
, geometryChanged()
, interpolate()
, intersection()
, intersects()
, isEmpty()
, isEqual()
, isSimple()
, isValid()
, length()
, offsetCurve()
, overlaps()
, pointOnSurface()
, prepareGeometry()
, relate()
, relatePattern()
, simplify()
, symDifference()
, touches()
, within()
Class Hierarchy¶
Subclasses¶
Does vector analysis using the GEOS library and handles import, export, and exception handling. |
Abstract Methods
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 within maxdistance distance from this geometry |
|
Should be called whenever the geometry associated with the engine has been modified and the engine must be updated to suit. |
|
Calculate the intersection of this and geom. |
|
Checks if geom intersects this. |
|
Checks if this is equal to geom. |
|
Determines whether the geometry is simple (according to OGC definition). |
|
Returns |
|
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. |
|
Calculate the symmetric difference of this and geom. |
|
Checks if geom touches this. |
|
Checks if geom is within this. |
Methods
Logs an error message encountered during an operation. |
|
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.
Splits this geometry according to a given line. |
Attributes
- 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:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- 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:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- 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:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool
- abstract 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
- abstract distanceWithin(self, geom: QgsAbstractGeometry | None, maxdistance: float, errorMsg: str | None | None = '') bool [source]¶
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
- 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:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- 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:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- 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
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:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- 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.
See also
- 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
toFalse
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 enabledtopologyTestPoints (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:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool
- abstract within(self, geom: QgsAbstractGeometry | None, errorMsg: str | None | None = '') bool [source]¶
Checks if
geom
is within this.- Parameters:
geom (Optional[QgsAbstractGeometry])
errorMsg (Optional[Optional[str]] = '')
- Return type:
bool