A spatial index for QgsFeature objects. More...

#include <qgsspatialindex.h>

Inheritance diagram for QgsSpatialIndex:

Public Types
enum	Flag { FlagStoreFeatureGeometries = 1 << 0 }
	Flags controlling index behavior. More...

typedef QFlags< Flag >	Flags

Public Types inherited from QgsFeatureSink
enum	Flag { FastInsert = 1 << 1 , RollBackOnErrors = 1 << 2 }
	Flags controlling how features are added to a sink. More...

typedef QFlags< Flag >	Flags

enum	SinkFlag { RegeneratePrimaryKey = 1 << 1 }
	Flags that can be set on a QgsFeatureSink. More...

typedef QFlags< SinkFlag >	SinkFlags

Public Member Functions
	QgsSpatialIndex (const QgsFeatureIterator &fi, const std::function< bool(const QgsFeature &) > &callback, QgsSpatialIndex::Flags flags=QgsSpatialIndex::Flags())
	Constructor - creates R-tree and bulk loads it with features from the iterator.

	QgsSpatialIndex (const QgsFeatureIterator &fi, QgsFeedback *feedback=nullptr, QgsSpatialIndex::Flags flags=QgsSpatialIndex::Flags())
	Constructor - creates R-tree and bulk loads it with features from the iterator.

	QgsSpatialIndex (const QgsFeatureSource &source, QgsFeedback *feedback=nullptr, QgsSpatialIndex::Flags flags=QgsSpatialIndex::Flags())
	Constructor - creates R-tree and bulk loads it with features from the source.

	QgsSpatialIndex (const QgsSpatialIndex &other)

	QgsSpatialIndex (QgsSpatialIndex::Flags flags=QgsSpatialIndex::Flags())
	Constructor for QgsSpatialIndex.

	~QgsSpatialIndex () override
	Destructor finalizes work with spatial index.

bool	addFeature (QgsFeature &feature, QgsFeatureSink::Flags flags=QgsFeatureSink::Flags()) override
	Adds a feature to the index.

bool	addFeature (QgsFeatureId id, const QgsRectangle &bounds)
	Add a feature id to the index with a specified bounding box.

bool	addFeatures (QgsFeatureList &features, QgsFeatureSink::Flags flags=QgsFeatureSink::Flags()) override
	Adds a list of features to the index.

bool	deleteFeature (const QgsFeature &feature)
	Removes a feature from the index.

bool	deleteFeature (QgsFeatureId id, const QgsRectangle &bounds)
	Removes a feature from the index by id and bounds.

QgsGeometry	geometry (QgsFeatureId id) const
	Returns the stored geometry for the indexed feature with matching id.

Q_DECL_DEPRECATED bool	insertFeature (const QgsFeature &feature)
	Adds a feature to the index.

Q_DECL_DEPRECATED bool	insertFeature (QgsFeatureId id, const QgsRectangle &bounds)
	Add a feature id to the index with a specified bounding box.

QList< QgsFeatureId >	intersects (const QgsRectangle &rectangle) const
	Returns a list of features with a bounding box which intersects the specified rectangle.

QList< QgsFeatureId >	nearestNeighbor (const QgsGeometry &geometry, int neighbors=1, double maxDistance=0) const
	Returns nearest neighbors to a geometry.

QList< QgsFeatureId >	nearestNeighbor (const QgsPointXY &point, int neighbors=1, double maxDistance=0) const
	Returns nearest neighbors to a point.

QgsSpatialIndex &	operator= (const QgsSpatialIndex &other)

QAtomicInt	refs () const
	Gets reference count - just for debugging!

Public Member Functions inherited from QgsFeatureSink
virtual	~QgsFeatureSink ()=default

virtual bool	addFeatures (QgsFeatureIterator &iterator, QgsFeatureSink::Flags flags=QgsFeatureSink::Flags())
	Adds all features from the specified iterator to the sink.

virtual void	finalize ()
	Finalizes the sink, flushing any buffered features to the destination.

virtual bool	flushBuffer ()
	Flushes any internal buffer which may exist in the sink, causing any buffered features to be added to the sink's destination.

virtual QString	lastError () const
	Returns the most recent error encountered by the sink, e.g.

Friends
class	QgsFeatureIteratorDataStream

Detailed Description

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.; QgsMeshSpatialIndex, which is for mesh faces

Definition at line 67 of file qgsspatialindex.h.

Member Typedef Documentation

◆ Flags

typedef QFlags< Flag > QgsSpatialIndex::Flags

Definition at line 79 of file qgsspatialindex.h.

Member Enumeration Documentation

◆ Flag

enum QgsSpatialIndex::Flag

Flags controlling index behavior.

Enumerator
FlagStoreFeatureGeometries	Indicates that the spatial index should also store feature geometries. This requires more memory, but can speed up operations by avoiding additional requests to data providers to fetch matching feature geometries. Additionally, it is required for non-bounding box nearest neighbor searches.

Definition at line 75 of file qgsspatialindex.h.

Constructor & Destructor Documentation

◆ QgsSpatialIndex() [1/5]

QgsSpatialIndex::QgsSpatialIndex ( QgsSpatialIndex::Flags flags = QgsSpatialIndex::Flags() )

Constructor for QgsSpatialIndex.

Creates an empty R-tree index.

Definition at line 341 of file qgsspatialindex.cpp.

◆ QgsSpatialIndex() [2/5]

QgsSpatialIndex::QgsSpatialIndex	(	const QgsFeatureIterator &	fi,
		QgsFeedback *	feedback = `nullptr`,
		QgsSpatialIndex::Flags	flags = `QgsSpatialIndex::Flags()`
	)

explicit

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.

Definition at line 346 of file qgsspatialindex.cpp.

◆ QgsSpatialIndex() [3/5]

QgsSpatialIndex::QgsSpatialIndex	(	const QgsFeatureIterator &	fi,
		const std::function< bool(const QgsFeature &) > &	callback,
		QgsSpatialIndex::Flags	flags = `QgsSpatialIndex::Flags()`
	)

explicit

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.

This construct and bulk load variant allows for a callback function to be specified, which is called for each added feature in turn. It allows for bulk spatial index load along with other feature based operations on a single iteration through a feature source. If callback returns false, the load and iteration is canceled.

Note: Not available in Python bindings

◆ QgsSpatialIndex() [4/5]

QgsSpatialIndex::QgsSpatialIndex	(	const QgsFeatureSource &	source,
		QgsFeedback *	feedback = `nullptr`,
		QgsSpatialIndex::Flags	flags = `QgsSpatialIndex::Flags()`
	)

explicit

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.

Definition at line 358 of file qgsspatialindex.cpp.

◆ QgsSpatialIndex() [5/5]

QgsSpatialIndex::QgsSpatialIndex ( const QgsSpatialIndex & other )

Definition at line 363 of file qgsspatialindex.cpp.

◆ ~QgsSpatialIndex()

QgsSpatialIndex::~QgsSpatialIndex ( )

override

Destructor finalizes work with spatial index.

Definition at line 368 of file qgsspatialindex.cpp.

Member Function Documentation

◆ addFeature() [1/2]

bool QgsSpatialIndex::addFeature	(	QgsFeature &	feature,
		QgsFeatureSink::Flags	flags = `QgsFeatureSink::Flags()`
	)

overridevirtual

Adds a feature to the index.

The flags argument is ignored.

Since: QGIS 3.4

Reimplemented from QgsFeatureSink.

Definition at line 403 of file qgsspatialindex.cpp.

◆ addFeature() [2/2]

bool QgsSpatialIndex::addFeature	(	QgsFeatureId	id,
		const QgsRectangle &	bounds
	)

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

Returns: true if feature was successfully added to index.

Since: QGIS 3.4

Definition at line 444 of file qgsspatialindex.cpp.

◆ addFeatures()

bool QgsSpatialIndex::addFeatures	(	QgsFeatureList &	features,
		QgsFeatureSink::Flags	flags = `QgsFeatureSink::Flags()`
	)

overridevirtual

Adds a list of features to the index.

The flags argument is ignored.

See also: addFeature()

Implements QgsFeatureSink.

Definition at line 422 of file qgsspatialindex.cpp.

◆ deleteFeature() [1/2]

bool QgsSpatialIndex::deleteFeature ( const QgsFeature & feature )

Removes a feature from the index.

Definition at line 474 of file qgsspatialindex.cpp.

◆ deleteFeature() [2/2]

bool QgsSpatialIndex::deleteFeature	(	QgsFeatureId	id,
		const QgsRectangle &	bounds
	)

Removes a feature from the index by id and bounds.

Since: QGIS 3.36

Definition at line 488 of file qgsspatialindex.cpp.

◆ geometry()

QgsGeometry QgsSpatialIndex::geometry ( QgsFeatureId id ) const

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

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

Since: QGIS 3.6

Definition at line 563 of file qgsspatialindex.cpp.

◆ insertFeature() [1/2]

bool QgsSpatialIndex::insertFeature ( const QgsFeature & feature )

Adds a feature to the index.

Deprecated:: QGIS 3.40. Use addFeature() instead.

Definition at line 433 of file qgsspatialindex.cpp.

◆ insertFeature() [2/2]

bool QgsSpatialIndex::insertFeature	(	QgsFeatureId	id,
		const QgsRectangle &	bounds
	)

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

Returns: true if feature was successfully added to index.

Deprecated:: QGIS 3.40. Use addFeature() instead.

Definition at line 439 of file qgsspatialindex.cpp.

◆ intersects()

QList< QgsFeatureId > QgsSpatialIndex::intersects ( const QgsRectangle & rectangle ) const

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.

Definition at line 499 of file qgsspatialindex.cpp.

◆ nearestNeighbor() [1/2]

QList< QgsFeatureId > QgsSpatialIndex::nearestNeighbor	(	const QgsGeometry &	geometry,
		int	neighbors = `1`,
		double	maxDistance = `0`
	)		const

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.

Since: QGIS 3.8

Definition at line 538 of file qgsspatialindex.cpp.

◆ nearestNeighbor() [2/2]

QList< QgsFeatureId > QgsSpatialIndex::nearestNeighbor	(	const QgsPointXY &	point,
		int	neighbors = `1`,
		double	maxDistance = `0`
	)		const

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.

Definition at line 512 of file qgsspatialindex.cpp.

◆ operator=()

QgsSpatialIndex & QgsSpatialIndex::operator= ( const QgsSpatialIndex & other )

Definition at line 372 of file qgsspatialindex.cpp.

◆ refs()

QAtomicInt QgsSpatialIndex::refs ( ) const

Gets reference count - just for debugging!

Definition at line 569 of file qgsspatialindex.cpp.

Friends And Related Symbol Documentation

◆ QgsFeatureIteratorDataStream

friend class QgsFeatureIteratorDataStream

friend

Definition at line 297 of file qgsspatialindex.h.

The documentation for this class was generated from the following files:

/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/qgsspatialindex.h
/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/qgsspatialindex.cpp

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ Flags

Member Enumeration Documentation

◆ Flag

Constructor & Destructor Documentation

◆ QgsSpatialIndex() [1/5]

◆ QgsSpatialIndex() [2/5]

◆ QgsSpatialIndex() [3/5]

◆ QgsSpatialIndex() [4/5]

◆ QgsSpatialIndex() [5/5]

◆ ~QgsSpatialIndex()

Member Function Documentation

◆ addFeature() [1/2]

◆ addFeature() [2/2]

◆ addFeatures()

◆ deleteFeature() [1/2]

◆ deleteFeature() [2/2]

◆ geometry()

◆ insertFeature() [1/2]

◆ insertFeature() [2/2]

◆ intersects()

◆ nearestNeighbor() [1/2]

◆ nearestNeighbor() [2/2]

◆ operator=()

◆ refs()

Friends And Related Symbol Documentation

◆ QgsFeatureIteratorDataStream