Class: QgsSnappingUtils

class qgis.core.QgsSnappingUtils(parent: QObject = None, enableSnappingForInvisibleFeature: bool = True)

Bases: PyQt5.QtCore.QObject

Constructor for QgsSnappingUtils

Parameters
  • parent (QObject = None) – parent object

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

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: - snapToMap() - has multiple modes of operation - snapToCurrentLayer() 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).

Methods

childEvent

clearAllLocators

Deletes all existing locators (e.g.

config

The snapping configuration controls the behavior of this object

connectNotify

currentLayer

The current layer used if mode is SnapCurrentLayer

customEvent

disconnectNotify

dump

Gets extra information about the instance

indexingStrategy

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

isSignalConnected

layers

Query layers used for snapping

locatorForLayer

Gets a point locator for the given layer.

mapSettings

rtype

QgsMapSettings

prepareIndexProgress

Called when finished indexing a layer with snapToMap.

prepareIndexStarting

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

receivers

sender

senderSignalIndex

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.

timerEvent

toggleEnabled

Toggles the state of snapping

Signals

configChanged

Emitted when the snapping settings object changes.

Attributes

IndexAlwaysFull

IndexExtent

IndexHybrid

IndexNeverFull

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

Bases: int

class LayerConfig(l: QgsVectorLayer, t: Union[QgsPointLocator.Types, QgsPointLocator.Type], tol: float, u: QgsTolerance.UnitType)

Bases: sip.wrapper

Create a new configuration for a snapping layer.

```py snapper = QgsMapCanvasSnappingUtils(mapCanvas)

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

snapper.setLayers([snapping_layer1, snapping_layer2]) ```

Parameters
  • l (QgsVectorLayer) – The vector layer for which this configuration is

  • t (Union[QgsPointLocator.Types) – Which parts of the geometry should be snappable

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

  • u (QgsTolerance.UnitType) – The unit in which the tolerance is specified

QgsSnappingUtils.LayerConfig(QgsSnappingUtils.LayerConfig)

layer
tolerance
type
unit
childEvent()
clearAllLocators(self)

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

QgsSnappingConfig

configChanged

Emitted when the snapping settings object changes. [signal]

Parameters

snappingConfig (QgsSnappingConfig) –

connectNotify()
currentLayer(self) → QgsVectorLayer

The current layer used if mode is SnapCurrentLayer

Return type

QgsVectorLayer

customEvent()
disconnectNotify()
dump(self) → str

Gets extra information about the instance

New in version 2.14.

Return type

str

indexingStrategy(self) → QgsSnappingUtils.IndexingStrategy

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

Return type

QgsSnappingUtils.IndexingStrategy

isSignalConnected()
layers(self) → List[QgsSnappingUtils.LayerConfig]

Query layers used for snapping

Return type

List[QgsSnappingUtils.LayerConfig]

locatorForLayer(self, vl: QgsVectorLayer) → QgsPointLocator

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

Parameters

vl (QgsVectorLayer) – the vector layer

Return type

QgsPointLocator

mapSettings(self) → QgsMapSettings
Return type

QgsMapSettings

prepareIndexProgress(self, index: int)

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

Parameters

index (int) –

prepareIndexStarting(self, count: int)

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

Parameters

count (int) –

receivers()
sender()
senderSignalIndex()
setConfig(self, snappingConfig: QgsSnappingConfig)

The snapping configuration controls the behavior of this object

Parameters

snappingConfig (QgsSnappingConfig) –

setCurrentLayer(self, layer: QgsVectorLayer)

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

Parameters

layer (QgsVectorLayer) –

setEnableSnappingForInvisibleFeature(self, enable: bool)

Set if invisible features must be snapped or not.

Parameters

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

Parameters

strategy (QgsSnappingUtils.IndexingStrategy) –

setMapSettings(self, settings: QgsMapSettings)

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

Parameters

settings (QgsMapSettings) –

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

Snap to current layer

Parameters
  • point (QPoint) –

  • type (Union[QgsPointLocator.Types) –

  • filter (QgsPointLocator.MatchFilter = None) –

Return type

QgsPointLocator.Match

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

Snap to map according to the current configuration.

Parameters
  • 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.

Parameters
  • 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

QgsPointLocator.Match

timerEvent()
toggleEnabled(self)

Toggles the state of snapping

New in version 3.0.