QgsTracer class

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

Reference

Derived classes

class QgsMapCanvasTracer: Extension of QgsTracer that provides extra functionality:

Public types

enum PathError { ErrNone, ErrTooManyFeatures, ErrPoint1, ErrPoint2, ErrNoPath }: Possible errors that may happen when calling findShortestPath()

Constructors, destructors, conversion operators

QgsTracer(): Constructor for QgsTracer.

Public functions

auto destinationCrs() const -> QgsCoordinateReferenceSystem: Returns the CRS used for tracing.
auto extent() const -> QgsRectangle: Gets extent to which graph's features will be limited (empty extent means no limit)
auto findShortestPath(const QgsPointXY& p1, const QgsPointXY& p2, PathError* error = nullptr) -> QVector<QgsPointXY>: Given two points, find the shortest path and return points on the way.
auto hasTopologyProblem() const -> bool: Whether there was an error during graph creation due to noding exception, indicating some input data topology problems.
auto init() -> bool: Build the internal data structures.
auto isInitialized() const -> bool: Whether the internal data structures have been initialized.
auto isPointSnapped(const QgsPointXY& pt) -> bool: Find out whether the point is snapped to a vertex or edge (i.e. it can be used for tracing start/stop)
auto layers() const -> QList<QgsVectorLayer*>: Gets layers used for tracing.
auto maxFeatureCount() const -> int: Gets maximum possible number of features in graph. If the number is exceeded, graph is not created.
auto offset() const -> double: Gets offset in map units that should be applied to the traced paths returned from findShortestPath().
void offsetParameters(int& quadSegments, int& joinStyle, double& miterLimit): Gets extra parameters for offset curve algorithm (used when offset is non-zero)
void setDestinationCrs(const QgsCoordinateReferenceSystem& crs, const QgsCoordinateTransformContext& context): Sets the crs and transform context used for tracing.
void setExtent(const QgsRectangle& extent): Sets extent to which graph's features will be limited (empty extent means no limit)
void setLayers(const QList<QgsVectorLayer*>& layers): Sets layers used for tracing.
void setMaxFeatureCount(int count): Gets maximum possible number of features in graph. If the number is exceeded, graph is not created.
void setOffset(double offset): Set offset in map units that should be applied to the traced paths returned from findShortestPath().
void setOffsetParameters(int quadSegments, int joinStyle, double miterLimit): Set extra parameters for offset curve algorithm (used when offset is non-zero)
void setRenderContext(const QgsRenderContext* renderContext): Sets the renderContext used for tracing only on visible features.

Protected functions

void configure() virtual: Allows derived classes to setup the settings just before the tracer is initialized.

Protected slots

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

Enum documentation

enum QgsTracer::PathError

Possible errors that may happen when calling findShortestPath()

Enumerators
ErrNone	No error.
ErrTooManyFeatures	Max feature count threshold was reached while reading features.
ErrPoint1	Start point cannot be joined to the graph.
ErrPoint2	End point cannot be joined to the graph.
ErrNoPath	Points are not connected in the graph.

Function documentation

QgsCoordinateReferenceSystem QgsTracer::destinationCrs() const

Returns the CRS used for tracing.

QVector<QgsPointXY> QgsTracer::findShortestPath(const QgsPointXY& p1, const QgsPointXY& p2, PathError* error = nullptr)

Given two points, find the shortest path and return points on the way.

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

The optional "error" argument may receive error code (PathError enum) if it is not null

bool QgsTracer::hasTopologyProblem() const

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

bool QgsTracer::init()

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.

double QgsTracer::offset() const

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.

void QgsTracer::offsetParameters(int& quadSegments, int& joinStyle, double& miterLimit)

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

void QgsTracer::setDestinationCrs(const QgsCoordinateReferenceSystem& crs, const QgsCoordinateTransformContext& context)

Sets the crs and transform context used for tracing.

void QgsTracer::setOffset(double offset)

Set offset in map units that should be applied to the traced paths returned from findShortestPath().