Class: QgsTracer

Utility class that constructs a planar graph from the input vector layers and provides shortest path search for tracing of existing features.

Class Hierarchy

Base classes

QObject

Subclasses

QgsMapCanvasTracer

Extension of QgsTracer that provides extra functionality.

Methods

addPointsOnIntersectionsEnabled	Returns whether the shortest path's straight segments will include vertices where the input layers intersect, even if no such vertex existed on the input layers
destinationCrs	Returns the CRS used for tracing.
extent	Gets extent to which graph's features will be limited (empty extent means no limit)
findShortestPath	Given two points, find the shortest path and return points on the way.
hasTopologyProblem	Whether there was an error during graph creation due to noding exception, indicating some input data topology problems
init	Build the internal data structures.
invalidateGraph	Destroy the existing graph structure if any (de-initialize)
isInitialized	Whether the internal data structures have been initialized
isPointSnapped	Find out whether the point is snapped to a vertex or edge (i.e. it can be used for tracing start/stop).
layers	Gets layers used for tracing
maxFeatureCount	Gets maximum possible number of features in graph.
offset	Gets offset in map units that should be applied to the traced paths returned from findShortestPath().
offsetParameters	Gets extra parameters for offset curve algorithm (used when offset is non-zero)
setAddPointsOnIntersectionsEnabled	When enable is True, the shortest path's straight segments will include vertices where the input layers intersect, even if no such vertex existed on the input layers
setDestinationCrs	Sets the crs and transform context used for tracing.
setExtent	Sets extent to which graph's features will be limited (empty extent means no limit)
setLayers	Sets layers used for tracing
setMaxFeatureCount	Gets maximum possible number of features in graph.
setOffset	Set offset in map units that should be applied to the traced paths returned from findShortestPath().
setOffsetParameters	Set extra parameters for offset curve algorithm (used when offset is non-zero)
setRenderContext	Sets the renderContext used for tracing only on visible features.

Virtual Methods

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

configure

Allows derived classes to setup the settings just before the tracer is initialized.

Attributes

ErrNoPath
ErrNone
ErrPoint1
ErrPoint2
ErrTooManyFeatures

class qgis.core.QgsTracer

Bases: QObject

__init__()

Constructor for QgsTracer.

ErrNoPath = 4

ErrNone = 0

ErrPoint1 = 2

ErrPoint2 = 3

ErrTooManyFeatures = 1

class PathError

Bases: int

addPointsOnIntersectionsEnabled(self) → bool

Returns whether the shortest path’s straight segments will include vertices where the input layers intersect, even if no such vertex existed on the input layers

Added in version 3.40.

Return type:

bool

virtual configure(self)

Allows derived classes to setup the settings just before the tracer is initialized. This allows the configuration to be set in a lazy way only when it is really necessary. Default implementation does nothing.

destinationCrs(self) → QgsCoordinateReferenceSystem

Returns the CRS used for tracing.

See also

setDestinationCrs()

Return type:

QgsCoordinateReferenceSystem

extent(self) → QgsRectangle

Gets extent to which graph’s features will be limited (empty extent means no limit)

Return type:

QgsRectangle

findShortestPath(self, p1: QgsPointXY, p2: QgsPointXY)

Given two points, find the shortest path and return points on the way. The optional “error” argument may receive error code (PathError enum) if it is not None

Returns:

array of points - trace of linestrings of other features (empty array one error)

Parameters:

• p1 (QgsPointXY)

• p2 (QgsPointXY) -> (List[QgsPointXY])

hasTopologyProblem(self) → bool

Whether there was an error during graph creation due to noding exception, indicating some input data topology problems

Return type:

bool

init(self) → bool

Build the internal data structures. This may take some time depending on how big the input layers are. It is not necessary to call this method explicitly - it will be called by findShortestPath() if necessary.

Return type:

bool

invalidateGraph(self)

Destroy the existing graph structure if any (de-initialize)

isInitialized(self) → bool

Whether the internal data structures have been initialized

Return type:

bool

isPointSnapped(self, pt: QgsPointXY) → bool

Find out whether the point is snapped to a vertex or edge (i.e. it can be used for tracing start/stop)

Parameters:

pt (QgsPointXY)

Return type:

bool

layers(self) → List[QgsVectorLayer]

Gets layers used for tracing

Return type:

List[QgsVectorLayer]

maxFeatureCount(self) → int

Gets maximum possible number of features in graph. If the number is exceeded, graph is not created.

Return type:

int

offset(self) → float

Gets offset in map units that should be applied to the traced paths returned from findShortestPath(). Positive offset for right side, negative offset for left side.

Return type:

float

offsetParameters(self)

Gets extra parameters for offset curve algorithm (used when offset is non-zero)

setAddPointsOnIntersectionsEnabled(self, enable: bool)

When enable is True, the shortest path’s straight segments will include vertices where the input layers intersect, even if no such vertex existed on the input layers

Added in version 3.40.

Parameters:

enable (bool)

setDestinationCrs(self, crs: QgsCoordinateReferenceSystem, context: QgsCoordinateTransformContext)

Sets the crs and transform context used for tracing.

See also

destinationCrs()

Parameters:

• crs (QgsCoordinateReferenceSystem)

• context (QgsCoordinateTransformContext)

setExtent(self, extent: QgsRectangle)

Sets extent to which graph’s features will be limited (empty extent means no limit)

Parameters:

extent (QgsRectangle)

setLayers(self, layers: Iterable[QgsVectorLayer])

Sets layers used for tracing

Parameters:

layers (Iterable[QgsVectorLayer])

setMaxFeatureCount(self, count: int)

Gets maximum possible number of features in graph. If the number is exceeded, graph is not created.

Parameters:

count (int)

setOffset(self, offset: float)

Set offset in map units that should be applied to the traced paths returned from findShortestPath(). Positive offset for right side, negative offset for left side.

Parameters:

offset (float)

setOffsetParameters(self, quadSegments: int, joinStyle: int, miterLimit: float)

Set extra parameters for offset curve algorithm (used when offset is non-zero)

Parameters:

• quadSegments (int)

• joinStyle (int)

• miterLimit (float)

setRenderContext(self, renderContext: QgsRenderContext | None)

Sets the renderContext used for tracing only on visible features.

Added in version 3.4.

Parameters:

renderContext (Optional[QgsRenderContext])