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

#include <qgstracer.h>

Inheritance diagram for QgsTracer:

[legend]

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

Public Member Functions
	QgsTracer ()
	Constructor for QgsTracer.
	~QgsTracer () override
bool	addPointsOnIntersectionsEnabled () const
	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.
QgsCoordinateReferenceSystem	destinationCrs () const
	Returns the CRS used for tracing.
QgsRectangle	extent () const
	Gets extent to which graph's features will be limited (empty extent means no limit).
QVector< QgsPointXY >	findShortestPath (const QgsPointXY &p1, const QgsPointXY &p2, PathError *error=nullptr)
	Given two points, find the shortest path and return points on the way.
bool	hasTopologyProblem () const
	Whether there was an error during graph creation due to noding exception, indicating some input data topology problems.
bool	init ()
	Build the internal data structures.
bool	isInitialized () const
	Whether the internal data structures have been initialized.
bool	isPointSnapped (const QgsPointXY &pt)
	Find out whether the point is snapped to a vertex or edge (i.e. it can be used for tracing start/stop).
QList< QgsVectorLayer * >	layers () const
	Gets layers used for tracing.
int	maxFeatureCount () const
	Gets maximum possible number of features in graph. If the number is exceeded, graph is not created.
double	offset () const
	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	setAddPointsOnIntersectionsEnabled (bool enable)
	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.
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 Slots
void	invalidateGraph ()
	Destroy the existing graph structure if any (de-initialize).

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

Detailed Description

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

Definition at line 44 of file qgstracer.h.

Member Enumeration Documentation

◆ PathError

enum QgsTracer::PathError

Possible errors that may happen when calling findShortestPath().

Enumerator
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.

Definition at line 132 of file qgstracer.h.

Constructor & Destructor Documentation

◆ QgsTracer()

QgsTracer::QgsTracer ( )

default

Constructor for QgsTracer.

◆ ~QgsTracer()

QgsTracer::~QgsTracer ( )

override

Definition at line 613 of file qgstracer.cpp.

Member Function Documentation

◆ addPointsOnIntersectionsEnabled()

bool QgsTracer::addPointsOnIntersectionsEnabled ( ) const

inline

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.

Since: QGIS 3.40

Definition at line 163 of file qgstracer.h.

◆ configure()

virtual void QgsTracer::configure ( )

inlineprotectedvirtual

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.

Reimplemented in QgsMapCanvasTracer.

Definition at line 171 of file qgstracer.h.

◆ destinationCrs()

QgsCoordinateReferenceSystem QgsTracer::destinationCrs ( ) const

inline

Returns the CRS used for tracing.

See also: setDestinationCrs()

Definition at line 64 of file qgstracer.h.

◆ extent()

QgsRectangle QgsTracer::extent ( ) const

inline

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

Definition at line 79 of file qgstracer.h.

◆ findShortestPath()

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.

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

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

Definition at line 752 of file qgstracer.cpp.

◆ hasTopologyProblem()

bool QgsTracer::hasTopologyProblem ( ) const

inline

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

Definition at line 129 of file qgstracer.h.

◆ init()

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.

Definition at line 691 of file qgstracer.cpp.

◆ invalidateGraph

void QgsTracer::invalidateGraph ( )

protectedslot

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

Definition at line 703 of file qgstracer.cpp.

◆ isInitialized()

bool QgsTracer::isInitialized ( ) const

inline

Whether the internal data structures have been initialized.

Definition at line 123 of file qgstracer.h.

◆ isPointSnapped()

bool QgsTracer::isPointSnapped ( const QgsPointXY & pt )

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

Definition at line 846 of file qgstracer.cpp.

◆ layers()

QList< QgsVectorLayer * > QgsTracer::layers ( ) const

inline

Gets layers used for tracing.

Definition at line 56 of file qgstracer.h.

◆ maxFeatureCount()

int QgsTracer::maxFeatureCount ( ) const

inline

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

Definition at line 110 of file qgstracer.h.

◆ offset()

double QgsTracer::offset ( ) const

inline

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.

Definition at line 87 of file qgstracer.h.

◆ offsetParameters()

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

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

Definition at line 677 of file qgstracer.cpp.

◆ setAddPointsOnIntersectionsEnabled()

void QgsTracer::setAddPointsOnIntersectionsEnabled ( bool enable )

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.

Since: QGIS 3.40

Definition at line 860 of file qgstracer.cpp.

◆ setDestinationCrs()

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

Sets the crs and transform context used for tracing.

See also: destinationCrs()

Definition at line 650 of file qgstracer.cpp.

◆ setExtent()

void QgsTracer::setExtent ( const QgsRectangle & extent )

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

Definition at line 663 of file qgstracer.cpp.

◆ setLayers()

void QgsTracer::setLayers ( const QList< QgsVectorLayer * > & layers )

Sets layers used for tracing.

Definition at line 618 of file qgstracer.cpp.

◆ setMaxFeatureCount()

void QgsTracer::setMaxFeatureCount ( int count )

inline

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

Definition at line 112 of file qgstracer.h.

◆ setOffset()

void QgsTracer::setOffset ( double offset )

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.

Definition at line 672 of file qgstracer.cpp.

◆ setOffsetParameters()

void QgsTracer::setOffsetParameters	(	int	quadSegments,
		int	joinStyle,
		double	miterLimit )

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

Definition at line 684 of file qgstracer.cpp.

◆ setRenderContext()

void QgsTracer::setRenderContext ( const QgsRenderContext * renderContext )

Sets the renderContext used for tracing only on visible features.

Since: QGIS 3.4

Definition at line 657 of file qgstracer.cpp.

The documentation for this class was generated from the following files:

/build/qgis-3.99.0+git20251205+26c88405ac0+99sid/src/core/qgstracer.h
/build/qgis-3.99.0+git20251205+26c88405ac0+99sid/src/core/qgstracer.cpp

Public Types

Public Member Functions

Protected Slots

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ PathError

Constructor & Destructor Documentation

◆ QgsTracer()

◆ ~QgsTracer()

Member Function Documentation

◆ addPointsOnIntersectionsEnabled()

◆ configure()

◆ destinationCrs()

◆ extent()

◆ findShortestPath()

◆ hasTopologyProblem()

◆ init()

◆ invalidateGraph

◆ isInitialized()

◆ isPointSnapped()

◆ layers()

◆ maxFeatureCount()

◆ offset()

◆ offsetParameters()

◆ setAddPointsOnIntersectionsEnabled()

◆ setDestinationCrs()

◆ setExtent()

◆ setLayers()

◆ setMaxFeatureCount()

◆ setOffset()

◆ setOffsetParameters()

◆ setRenderContext()