QGIS API Documentation  3.7.0-Master (b20e93c)
Public Types | Public Member Functions | Friends | List of all members
QgsSpatialIndex Class Reference

A spatial index for QgsFeature objects. More...

#include <qgsspatialindex.h>

Inheritance diagram for QgsSpatialIndex:
Inheritance graph
[legend]

Public Types

enum  Flag { FlagStoreFeatureGeometries = 1 << 0 }
 Flags controlling index behavior. More...
 
- Public Types inherited from QgsFeatureSink
enum  Flag { FastInsert = 1 << 1 }
 Flags controlling how features are added to a sink. More...
 
enum  SinkFlag { RegeneratePrimaryKey = 1 << 1 }
 Flags that can be set on a QgsFeatureSink. More...
 

Public Member Functions

 QgsSpatialIndex (QgsSpatialIndex::Flags flags=nullptr)
 Constructor for QgsSpatialIndex. More...
 
 QgsSpatialIndex (const QgsFeatureIterator &fi, QgsFeedback *feedback=nullptr, QgsSpatialIndex::Flags flags=nullptr)
 Constructor - creates R-tree and bulk loads it with features from the iterator. More...
 
 QgsSpatialIndex (const QgsFeatureSource &source, QgsFeedback *feedback=nullptr, QgsSpatialIndex::Flags flags=nullptr)
 Constructor - creates R-tree and bulk loads it with features from the source. More...
 
 QgsSpatialIndex (const QgsSpatialIndex &other)
 Copy constructor. More...
 
 ~QgsSpatialIndex () override
 Destructor finalizes work with spatial index. More...
 
bool addFeature (QgsFeature &feature, QgsFeatureSink::Flags flags=nullptr) override
 Adds a feature to the index. More...
 
bool addFeature (QgsFeatureId id, const QgsRectangle &bounds)
 Add a feature id to the index with a specified bounding box. More...
 
bool addFeatures (QgsFeatureList &features, QgsFeatureSink::Flags flags=nullptr) override
 Adds a list of features to the index. More...
 
bool deleteFeature (const QgsFeature &feature)
 Removes a feature from the index. More...
 
QgsGeometry geometry (QgsFeatureId id) const
 Returns the stored geometry for the indexed feature with matching id. More...
 
Q_DECL_DEPRECATED bool insertFeature (const QgsFeature &feature)
 Adds a feature to the index. More...
 
Q_DECL_DEPRECATED bool insertFeature (QgsFeatureId id, const QgsRectangle &bounds)
 Add a feature id to the index with a specified bounding box. More...
 
QList< QgsFeatureIdintersects (const QgsRectangle &rectangle) const
 Returns a list of features with a bounding box which intersects the specified rectangle. More...
 
QList< QgsFeatureIdnearestNeighbor (const QgsPointXY &point, int neighbors=1, double maxDistance=0) const
 Returns nearest neighbors to a point. More...
 
QList< QgsFeatureIdnearestNeighbor (const QgsGeometry &geometry, int neighbors=1, double maxDistance=0) const
 Returns nearest neighbors to a geometry. More...
 
QgsSpatialIndexoperator= (const QgsSpatialIndex &other)
 Implement assignment operator. More...
 
QAtomicInt refs () const
 Gets reference count - just for debugging! More...
 
- Public Member Functions inherited from QgsFeatureSink
virtual ~QgsFeatureSink ()=default
 
virtual bool addFeatures (QgsFeatureIterator &iterator, QgsFeatureSink::Flags flags=nullptr)
 Adds all features from the specified iterator to the sink. More...
 
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. More...
 

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 Enumeration Documentation

◆ 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/4]

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

Constructor for QgsSpatialIndex.

Creates an empty R-tree index.

Definition at line 327 of file qgsspatialindex.cpp.

◆ QgsSpatialIndex() [2/4]

QgsSpatialIndex::QgsSpatialIndex ( const QgsFeatureIterator fi,
QgsFeedback feedback = nullptr,
QgsSpatialIndex::Flags  flags = nullptr 
)
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.

Since
QGIS 2.8

Definition at line 332 of file qgsspatialindex.cpp.

◆ QgsSpatialIndex() [3/4]

QgsSpatialIndex::QgsSpatialIndex ( const QgsFeatureSource source,
QgsFeedback feedback = nullptr,
QgsSpatialIndex::Flags  flags = nullptr 
)
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.

Since
QGIS 3.0

Definition at line 337 of file qgsspatialindex.cpp.

◆ QgsSpatialIndex() [4/4]

QgsSpatialIndex::QgsSpatialIndex ( const QgsSpatialIndex other)

Copy constructor.

Definition at line 342 of file qgsspatialindex.cpp.

◆ ~QgsSpatialIndex()

QgsSpatialIndex::~QgsSpatialIndex ( )
override

Destructor finalizes work with spatial index.

Definition at line 347 of file qgsspatialindex.cpp.

Member Function Documentation

◆ addFeature() [1/2]

bool QgsSpatialIndex::addFeature ( QgsFeature feature,
QgsFeatureSink::Flags  flags = nullptr 
)
overridevirtual

Adds a feature to the index.

The flags argument is ignored.

Since
QGIS 3.4

Reimplemented from QgsFeatureSink.

Definition at line 389 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 430 of file qgsspatialindex.cpp.

◆ addFeatures()

bool QgsSpatialIndex::addFeatures ( QgsFeatureList features,
QgsFeatureSink::Flags  flags = nullptr 
)
overridevirtual

Adds a list of features to the index.

The flags argument is ignored.

See also
addFeature()

Implements QgsFeatureSink.

Definition at line 408 of file qgsspatialindex.cpp.

◆ deleteFeature()

bool QgsSpatialIndex::deleteFeature ( const QgsFeature feature)

Removes a feature from the index.

Definition at line 460 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 538 of file qgsspatialindex.cpp.

◆ insertFeature() [1/2]

bool QgsSpatialIndex::insertFeature ( const QgsFeature feature)

Adds a feature to the index.

Deprecated:
Use addFeature() instead

Definition at line 419 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:
Use addFeature() instead

Definition at line 425 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 474 of file qgsspatialindex.cpp.

◆ nearestNeighbor() [1/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 487 of file qgsspatialindex.cpp.

◆ nearestNeighbor() [2/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 513 of file qgsspatialindex.cpp.

◆ operator=()

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

Implement assignment operator.

Definition at line 351 of file qgsspatialindex.cpp.

◆ refs()

QAtomicInt QgsSpatialIndex::refs ( ) const

Gets reference count - just for debugging!

Definition at line 544 of file qgsspatialindex.cpp.

Friends And Related Function Documentation

◆ QgsFeatureIteratorDataStream

friend class QgsFeatureIteratorDataStream
friend

Definition at line 281 of file qgsspatialindex.h.


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