QgsPointLocator class

The class defines interface for querying point location:

Reference

query nearest vertices / edges to a point
query vertices / edges in rectangle
query areas covering a point

Works with one layer.

Public types

struct MatchFilter: Interface that allows rejection of some matches in intersection queries (e.g.
enum Type { Invalid = 0, Vertex = 1, Edge = 2, Area = 4, All = Vertex | Edge | Area }: The type of a snap result or the filter type for a snap request.

Constructors, destructors, conversion operators

QgsPointLocator(QgsVectorLayer* layer, const QgsCoordinateReferenceSystem& destinationCrs = QgsCoordinateReferenceSystem(), const QgsCoordinateTransformContext& transformContext = QgsCoordinateTransformContext(), const QgsRectangle* extent = nullptr) explicit: Construct point locator for a layer.

Public functions

auto cachedGeometryCount() const -> int: Returns how many geometries are cached in the index.
auto destinationCrs() const -> QgsCoordinateReferenceSystem: Gets destination CRS - may be an invalid QgsCoordinateReferenceSystem if not doing OTF reprojection.
auto edgesInRect(const QgsRectangle& rect, QgsPointLocator::MatchFilter* filter = nullptr) -> MatchList: Find edges within a specified recangle Optional filter may discard unwanted matches.
auto edgesInRect(const QgsPointXY& point, double tolerance, QgsPointLocator::MatchFilter* filter = nullptr) -> MatchList: Override of edgesInRect that construct rectangle from a center point and tolerance.
auto extent() const -> const QgsRectangle*: Gets extent of the area point locator covers - if null then it caches the whole layer.
auto hasIndex() const -> bool: Indicate whether the data have been already indexed.
auto init(int maxFeaturesToIndex = -1) -> bool: Prepare the index for queries.
auto layer() const -> QgsVectorLayer*: Gets associated layer.
auto nearestArea(const QgsPointXY& point, double tolerance, QgsPointLocator::MatchFilter* filter = nullptr) -> Match: Find nearest area to the specified point - up to distance specified by tolerance Optional filter may discard unwanted matches.
auto nearestEdge(const QgsPointXY& point, double tolerance, QgsPointLocator::MatchFilter* filter = nullptr) -> Match: Find nearest edge to the specified point - up to distance specified by tolerance Optional filter may discard unwanted matches.
auto nearestVertex(const QgsPointXY& point, double tolerance, QgsPointLocator::MatchFilter* filter = nullptr) -> Match: Find nearest vertex to the specified point - up to distance specified by tolerance Optional filter may discard unwanted matches.
auto pointInPolygon(const QgsPointXY& point) -> MatchList: find out if the point is in any polygons
void setExtent(const QgsRectangle* extent): Configure extent - if not null, it will index only that area.
void setRenderContext(const QgsRenderContext* context): Configure render context - if not null, it will use to index only visible feature.

Enum documentation

enum QgsPointLocator::Type

The type of a snap result or the filter type for a snap request.

Enumerators
Invalid	Invalid.
Vertex	Snapped to a vertex. Can be a vertex of the geometry or an intersection.
Edge	Snapped to an edge.
Area	Snapped to an area.
All	Combination of vertex, edge and area.

Function documentation

QgsPointLocator::QgsPointLocator(QgsVectorLayer* layer, const QgsCoordinateReferenceSystem& destinationCrs = QgsCoordinateReferenceSystem(), const QgsCoordinateTransformContext& transformContext = QgsCoordinateTransformContext(), const QgsRectangle* extent = nullptr) explicit

Construct point locator for a layer.

If a valid QgsCoordinateReferenceSystem is passed for destinationCrs then the locator will do the searches on data reprojected to the given CRS. For accurate reprojection it is important to set the correct transformContext if a destinationCrs is specified. This is usually taken from the current QgsProject::transformContext().

If extent is not null, the locator will index only a subset of the layer which falls within that extent.

int QgsPointLocator::cachedGeometryCount() const

Returns how many geometries are cached in the index.

QgsCoordinateReferenceSystem QgsPointLocator::destinationCrs() const

Gets destination CRS - may be an invalid QgsCoordinateReferenceSystem if not doing OTF reprojection.

const QgsRectangle* QgsPointLocator::extent() const

Gets extent of the area point locator covers - if null then it caches the whole layer.

bool QgsPointLocator::init(int maxFeaturesToIndex = -1)

Prepare the index for queries.

Does nothing if the index already exists. If the number of features is greater than the value of maxFeaturesToIndex, creation of index is stopped to make sure we do not run out of memory. If maxFeaturesToIndex is -1, no limits are used. Returns false if the creation of index has been prematurely stopped due to the limit of features, otherwise true

QgsVectorLayer* QgsPointLocator::layer() const

Gets associated layer.

Match QgsPointLocator::nearestArea(const QgsPointXY& point, double tolerance, QgsPointLocator::MatchFilter* filter = nullptr)

Find nearest area to the specified point - up to distance specified by tolerance Optional filter may discard unwanted matches.

This will first perform a pointInPolygon and return first result. If no match is found and tolerance is not 0, it will return nearestEdge.

void QgsPointLocator::setExtent(const QgsRectangle* extent)

Configure extent - if not null, it will index only that area.

void QgsPointLocator::setRenderContext(const QgsRenderContext* context)

Configure render context - if not null, it will use to index only visible feature.