Class: QgsSpatialIndex

A spatial index for QgsFeature objects.

QgsSpatialIndex objects are implicitly shared and can be inexpensively copied.

Note

While the underlying libspatialindex is not thread safe on some platforms, the QgsSpatialIndex class implements its own locks and accordingly, a single QgsSpatialIndex object can safely be used across multiple threads.

See also

QgsSpatialIndexKDBush which is an optimised non-mutable index for point geometries only.

See also

QgsMeshSpatialIndex which is for mesh faces

Class Hierarchy

Inheritance diagram of qgis.core.QgsSpatialIndex

Base classes

QgsFeatureSink

An interface for objects which accept features via addFeature(s) methods.

Abstract Methods

addFeatures

Adds a list of features to the index.

Methods

deleteFeature

Removes a feature from the index.

geometry

Returns the stored geometry for the indexed feature with matching id.

insertFeature

Adds a feature to the index.

intersects

Returns a list of features with a bounding box which intersects the specified rectangle.

nearestNeighbor

Returns nearest neighbors to a point.

refs

Gets reference count - just for debugging!

Virtual Methods

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

addFeature

Adds a feature to the index.

Attributes

FlagStoreFeatureGeometries

class qgis.core.QgsSpatialIndex[source]

Bases: QgsFeatureSink

__init__(flags: QgsSpatialIndex.Flags | QgsSpatialIndex.Flag = QgsSpatialIndex.Flags())

Constructor for QgsSpatialIndex. Creates an empty R-tree index.

Parameters:

flags (Union[QgsSpatialIndex.Flags, QgsSpatialIndex.Flag] = QgsSpatialIndex.Flags())

__init__(fi: QgsFeatureIterator, feedback: QgsFeedback | None = None, flags: QgsSpatialIndex.Flags | QgsSpatialIndex.Flag = QgsSpatialIndex.Flags())

Constructor - creates R-tree and bulk loads it with features from the iterator. This is much faster approach than creating an empty index and then inserting features one by one.

The optional feedback object can be used to allow cancellation of bulk feature loading. Ownership of feedback is not transferred, and callers must take care that the lifetime of feedback exceeds that of the spatial index construction.

Parameters:

  • fi (QgsFeatureIterator)

  • feedback (Optional[QgsFeedback] = None)

  • flags (Union[QgsSpatialIndex.Flags, QgsSpatialIndex.Flag] = QgsSpatialIndex.Flags())

__init__(source: QgsFeatureSource, feedback: QgsFeedback | None = None, flags: QgsSpatialIndex.Flags | QgsSpatialIndex.Flag = QgsSpatialIndex.Flags())

Constructor - creates R-tree and bulk loads it with features from the source. This is much faster approach than creating an empty index and then inserting features one by one.

The optional feedback object can be used to allow cancellation of bulk feature loading. Ownership of feedback is not transferred, and callers must take care that the lifetime of feedback exceeds that of the spatial index construction.

Parameters:

  • source (QgsFeatureSource)

  • feedback (Optional[QgsFeedback] = None)

  • flags (Union[QgsSpatialIndex.Flags, QgsSpatialIndex.Flag] = QgsSpatialIndex.Flags())

__init__(other: QgsSpatialIndex)
Parameters:

other (QgsSpatialIndex)

FlagStoreFeatureGeometries = 1
virtual addFeature(self, feature: QgsFeature, flags: QgsFeatureSink.Flags | QgsFeatureSink.Flag = QgsFeatureSink.Flags()) → bool[source]

Adds a feature to the index.

The flags argument is ignored.

Added in version 3.4.

Parameters:
Return type:

bool

virtual addFeature(self, id: int, bounds: QgsRectangle) → bool[source]

Add a feature id to the index with a specified bounding box.

Return type:

bool

Returns:

True if feature was successfully added to index.

Added in version 3.4.

Parameters:
abstract addFeatures(self, features: Iterable[QgsFeature], flags: QgsFeatureSink.Flags | QgsFeatureSink.Flag = QgsFeatureSink.Flags()) → bool[source]

Adds a list of features to the index.

The flags argument is ignored.

See also

addFeature()

Parameters:
Return type:

bool

deleteFeature(self, feature: QgsFeature) → bool[source]

Removes a feature from the index.

Parameters:

feature (QgsFeature)

Return type:

bool

deleteFeature(self, id: int, bounds: QgsRectangle) → bool[source]

Removes a feature from the index by id and bounds.

Added in version 3.36.

Parameters:
Return type:

bool

geometry(self, id: int) → QgsGeometry[source]

Returns the stored geometry for the indexed feature with matching id.

Geometry is only stored if the QgsSpatialIndex was created with the FlagStoreFeatureGeometries flag.

Raises:

KeyError – if no geometry with the specified feature id exists in the index.

Added in version 3.6.

Parameters:

id (int)

Return type:

QgsGeometry

insertFeature(self, feature: QgsFeature) → bool[source]

Adds a feature to the index.

Deprecated since version 3.40: Use addFeature() instead.

Parameters:

feature (QgsFeature)

Return type:

bool

insertFeature(self, id: int, bounds: QgsRectangle) → bool[source]

Add a feature id to the index with a specified bounding box.

Return type:

bool

Returns:

True if feature was successfully added to index.

Deprecated since version 3.40: Use addFeature() instead.

Parameters:
intersects(self, rectangle: QgsRectangle) → List[int]

Returns a list of features with a bounding box which intersects the specified rectangle.

Note

The intersection test is performed based on the feature bounding boxes only, so for non-point geometry features it is necessary to manually test the returned features for exact geometry intersection when required.

Parameters:

rectangle (QgsRectangle)

Return type:

List[int]

nearestNeighbor(self, point: QgsPointXY, neighbors: int = 1, maxDistance: float = 0) → List[int]

Returns nearest neighbors to a point. The number of neighbors returned is specified by the neighbors argument.

If the maxDistance argument is greater than 0, then only features within the specified distance of point will be considered.

Note that in some cases the number of returned features may differ from the requested number of neighbors. E.g. if not enough features exist within the maxDistance of the search point. If multiple features are equidistant from the search point then the number of returned feature IDs may exceed neighbors.

Warning

If this QgsSpatialIndex object was not constructed with the FlagStoreFeatureGeometries flag, then the nearest neighbor test is performed based on the feature bounding boxes ONLY, so for non-point geometry features this method is not guaranteed to return the actual closest neighbors.

Parameters:

  • point (QgsPointXY)

  • neighbors (int = 1)

  • maxDistance (float = 0)

Return type:

List[int]

nearestNeighbor(self, geometry: QgsGeometry, neighbors: int = 1, maxDistance: float = 0) → List[int]

Returns nearest neighbors to a geometry. The number of neighbors returned is specified by the neighbors argument.

If the maxDistance argument is greater than 0, then only features within the specified distance of point will be considered.

Note that in some cases the number of returned features may differ from the requested number of neighbors. E.g. if not enough features exist within the maxDistance of the search point. If multiple features are equidistant from the search point then the number of returned feature IDs may exceed neighbors.

Warning

If this QgsSpatialIndex object was not constructed with the FlagStoreFeatureGeometries flag, then the nearest neighbor test is performed based on the feature bounding boxes ONLY, so for non-point geometry features this method is not guaranteed to return the actual closest neighbors.

Added in version 3.8.

Parameters:

  • geometry (QgsGeometry)

  • neighbors (int = 1)

  • maxDistance (float = 0)

Return type:

List[int]

refs(self) → int[source]

Gets reference count - just for debugging!

Return type:

int