Class: QgsSnappingUtils

Contains configuration of snapping and can return answers to snapping queries.

Internally, it keeps a cache of QgsPointLocator instances for multiple layers.

Currently it supports the following queries:

For more complex queries it is possible to use locatorForLayer() method that returns point locator instance with layer’s indexed data.

Indexing strategy determines how fast the queries will be and how much memory will be used.

When working with map canvas, it may be useful to use derived class QgsMapCanvasSnappingUtils which keeps the configuration in sync with map canvas (e.g. current view, active layer).

Class Hierarchy

Inheritance diagram of qgis.core.QgsSnappingUtils

Base classes

QObject

Subclasses

QgsMapCanvasSnappingUtils

Snapping utils instance that is connected to a canvas and updates the configuration (map settings + current layer) whenever that is changed in the canvas.

Methods

addExtraSnapLayer

Supply an extra snapping layer (typically a memory layer).

clearAllLocators

Deletes all existing locators (e.g. when destination CRS has changed and we need to reindex).

config

The snapping configuration controls the behavior of this object

currentLayer

The current layer used if mode is SnapCurrentLayer

dump

Gets extra information about the instance

getExtraSnapLayers

Returns the list of extra snapping layers

indexingStrategy

Find out which strategy is used for indexing - by default hybrid indexing is used

layers

Query layers used for snapping

locatorForLayer

Gets a point locator for the given layer.

mapSettings

removeExtraSnapLayer

Removes an extra snapping layer

setConfig

The snapping configuration controls the behavior of this object

setCurrentLayer

Sets current layer so that if mode is SnapCurrentLayer we know which layer to use

setEnableSnappingForInvisibleFeature

Set if invisible features must be snapped or not.

setIndexingStrategy

Sets a strategy for indexing geometry data - determines how fast and memory consuming the data structures will be

setMapSettings

Assign current map settings to the utils - used for conversion between screen coords to map coords

snapToCurrentLayer

Snap to current layer

snapToMap

Snap to map according to the current configuration.

toggleEnabled

Toggles the state of snapping

Virtual Methods

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

prepareIndexProgress

Called when finished indexing a layer with snapToMap.

prepareIndexStarting

Called when starting to index with snapToMap - can be overridden and e.g. progress dialog can be provided.

Signals

configChanged

Emitted when the snapping settings object changes.

Attributes

IndexAlwaysFull

IndexExtent

IndexHybrid

IndexNeverFull

class qgis.core.QgsSnappingUtils[source]

Bases: QObject

__init__(parent: QObject | None = None, enableSnappingForInvisibleFeature: bool = True)

Constructor for QgsSnappingUtils

Parameters:
  • parent (Optional[QObject] = None) – parent object

  • enableSnappingForInvisibleFeature (bool = True) – True if we want to snap feature even if there are not visible

IndexAlwaysFull = 0
IndexExtent = 3
IndexHybrid = 2
IndexNeverFull = 1
class IndexingStrategy

Bases: int

class LayerConfig

Bases: object

Configures how a certain layer should be handled in a snapping operation

layer: QgsVectorLayer

The layer to configure.

tolerance: float

The range around snapping targets in which snapping should occur.

type: Types

To which geometry properties of this layers a snapping should happen.

unit: MapToolUnit

The units in which the tolerance is specified.

addExtraSnapLayer(self, vl: QgsVectorLayer | None)[source]

Supply an extra snapping layer (typically a memory layer). This can be used by map tools to provide additional snappings points.

Added in version 3.14.

Parameters:

vl (Optional[QgsVectorLayer])

clearAllLocators(self)[source]

Deletes all existing locators (e.g. when destination CRS has changed and we need to reindex)

config(self) QgsSnappingConfig[source]

The snapping configuration controls the behavior of this object

Return type:

QgsSnappingConfig

signal configChanged(snappingConfig: QgsSnappingConfig)[source]

Emitted when the snapping settings object changes.

Parameters:

snappingConfig (QgsSnappingConfig)

currentLayer(self) QgsVectorLayer | None[source]

The current layer used if mode is SnapCurrentLayer

Return type:

Optional[QgsVectorLayer]

dump(self) str[source]

Gets extra information about the instance

Return type:

str

getExtraSnapLayers(self) Set[QgsVectorLayer]

Returns the list of extra snapping layers

Added in version 3.14.

Return type:

Set[QgsVectorLayer]

indexingStrategy(self) QgsSnappingUtils.IndexingStrategy[source]

Find out which strategy is used for indexing - by default hybrid indexing is used

Return type:

QgsSnappingUtils.IndexingStrategy

layers(self) List[QgsSnappingUtils.LayerConfig]

Query layers used for snapping

Return type:

List[QgsSnappingUtils.LayerConfig]

locatorForLayer(self, vl: QgsVectorLayer | None) QgsPointLocator | None[source]

Gets a point locator for the given layer. If such locator does not exist, it will be created

Parameters:

vl (Optional[QgsVectorLayer]) – the vector layer

Return type:

Optional[QgsPointLocator]

mapSettings(self) QgsMapSettings[source]
Return type:

QgsMapSettings

virtual prepareIndexProgress(self, index: int)[source]

Called when finished indexing a layer with snapToMap. When index == count the indexing is complete

Parameters:

index (int)

virtual prepareIndexStarting(self, count: int)[source]

Called when starting to index with snapToMap - can be overridden and e.g. progress dialog can be provided

Parameters:

count (int)

removeExtraSnapLayer(self, vl: QgsVectorLayer | None)[source]

Removes an extra snapping layer

Added in version 3.14.

Parameters:

vl (Optional[QgsVectorLayer])

setConfig(self, snappingConfig: QgsSnappingConfig)[source]

The snapping configuration controls the behavior of this object

Parameters:

snappingConfig (QgsSnappingConfig)

setCurrentLayer(self, layer: QgsVectorLayer | None)[source]

Sets current layer so that if mode is SnapCurrentLayer we know which layer to use

Parameters:

layer (Optional[QgsVectorLayer])

setEnableSnappingForInvisibleFeature(self, enable: bool)[source]

Set if invisible features must be snapped or not.

Parameters:

enable (bool) – Enable or not this feature

Added in version 3.2.

setIndexingStrategy(self, strategy: QgsSnappingUtils.IndexingStrategy)[source]

Sets a strategy for indexing geometry data - determines how fast and memory consuming the data structures will be

Parameters:

strategy (QgsSnappingUtils.IndexingStrategy)

setMapSettings(self, settings: QgsMapSettings)[source]

Assign current map settings to the utils - used for conversion between screen coords to map coords

Parameters:

settings (QgsMapSettings)

snapToCurrentLayer(self, point: QPoint, type: QgsPointLocator.Types | QgsPointLocator.Type, filter: QgsPointLocator.MatchFilter | None = None) QgsPointLocator.Match[source]

Snap to current layer

Parameters:
Return type:

QgsPointLocator.Match

snapToMap(self, point: QPoint, filter: QgsPointLocator.MatchFilter | None = None, relaxed: bool = False) QgsPointLocator.Match[source]

Snap to map according to the current configuration.

Parameters:
  • point (QPoint) – point in canvas coordinates

  • filter (Optional[QgsPointLocator.MatchFilter] = None) – allows discarding unwanted matches.

  • relaxed (bool = False) – True if this method is non blocking and the matching result can be invalid while indexing

Return type:

QgsPointLocator.Match

snapToMap(self, pointMap: QgsPointXY, filter: QgsPointLocator.MatchFilter | None = None, relaxed: bool = False) QgsPointLocator.Match[source]

Snap to map according to the current configuration.

Parameters:
  • pointMap (QgsPointXY) – point in map coordinates

  • filter (Optional[QgsPointLocator.MatchFilter] = None) – allows discarding unwanted matches.

  • relaxed (bool = False) – True if this method is non blocking and the matching result can be invalid while indexing

Return type:

QgsPointLocator.Match

toggleEnabled(self)[source]

Toggles the state of snapping