Class: QgsSnappingUtils

class qgis.core.QgsSnappingUtils

Bases: PyQt5.QtCore.QObject

This class has all the 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).

New in version 2.8.

QgsSnappingUtils(parent: QObject = None, enableSnappingForInvisibleFeature: bool = True) Constructor for QgsSnappingUtils

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

Bases: int

class LayerConfig(l: QgsVectorLayer, t: QgsPointLocator.Types | QgsPointLocator.Type, tol: float, u: Qgis.MapToolUnit)

Bases: sip.wrapper

Create a new configuration for a snapping layer.

snapper = QgsMapCanvasSnappingUtils(mapCanvas)

snapping_layer1 = QgsSnappingUtils.LayerConfig(layer1, QgsPointLocator.Vertex, 10, Qgis::MapToolUnit::Pixels)
snapping_layer2 = QgsSnappingUtils.LayerConfig(layer2, QgsPointLocator.Vertex and QgsPointLocator.Edge, 10, Qgis::MapToolUnit::Pixels)

snapper.setLayers([snapping_layer1, snapping_layer2])
  • l – The vector layer for which this configuration is

  • t – Which parts of the geometry should be snappable

  • tol – The tolerance radius in which the snapping will trigger

  • u – The unit in which the tolerance is specified


addExtraSnapLayer(self, vl: QgsVectorLayer)

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

New in version 3.14.


vl (QgsVectorLayer) –

childEvent(self, QChildEvent)

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

config(self) QgsSnappingConfig

The snapping configuration controls the behavior of this object

Return type:



pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:


connectNotify(self, QMetaMethod)
currentLayer(self) QgsVectorLayer

The current layer used if mode is SnapCurrentLayer

Return type:


customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
dump(self) str

Gets extra information about the instance

New in version 2.14.

Return type:


getExtraSnapLayers(self) Set[QgsVectorLayer]

Returns the list of extra snapping layers

New in version 3.14.

Return type:


indexingStrategy(self) QgsSnappingUtils.IndexingStrategy

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

Return type:


isSignalConnected(self, QMetaMethod) bool
layers(self) List[QgsSnappingUtils.LayerConfig]

Query layers used for snapping

Return type:


locatorForLayer(self, vl: QgsVectorLayer) QgsPointLocator

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


vl (QgsVectorLayer) – the vector layer

Return type:


mapSettings(self) QgsMapSettings
Return type:


prepareIndexProgress(self, index: int)

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


index (int) –

prepareIndexStarting(self, count: int)

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


count (int) –

receivers(self, PYQT_SIGNAL) int
removeExtraSnapLayer(self, vl: QgsVectorLayer)

Removes an extra snapping layer

New in version 3.14.


vl (QgsVectorLayer) –

sender(self) QObject
senderSignalIndex(self) int
setConfig(self, snappingConfig: QgsSnappingConfig)

The snapping configuration controls the behavior of this object


snappingConfig (QgsSnappingConfig) –

setCurrentLayer(self, layer: QgsVectorLayer)

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


layer (QgsVectorLayer) –

setEnableSnappingForInvisibleFeature(self, enable: bool)

Set if invisible features must be snapped or not.


enable (bool) – Enable or not this feature

New in version 3.2.

setIndexingStrategy(self, strategy: QgsSnappingUtils.IndexingStrategy)

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


strategy (QgsSnappingUtils.IndexingStrategy) –

setMapSettings(self, settings: QgsMapSettings)

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


settings (QgsMapSettings) –

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

Snap to current layer

  • point (QPoint) –

  • type (Union[QgsPointLocator.Types) –

  • filter (QgsPointLocator.MatchFilter = None) –

Return type:


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

Snap to map according to the current configuration.

  • point (QPoint) – point in canvas coordinates

  • filter (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

snapToMap(self, pointMap: QgsPointXY, filter: QgsPointLocator.MatchFilter = None, relaxed: bool = False) -> QgsPointLocator.Match Snap to map according to the current configuration.

  • pointMap – point in map coordinates

  • filter – allows discarding unwanted matches.

  • relaxedTrue if this method is non blocking and the matching result can be invalid while indexing

Return type:


timerEvent(self, QTimerEvent)

Toggles the state of snapping

New in version 3.0.