Utility functions for use with processing classes. More...

#include <qgsprocessingutils.h>

Public Types
enum class	LayerHint : int { UnknownType , Vector , Raster , Mesh }
	Layer type hints. More...

Static Public Member Functions
static QgsFields	combineFields (const QgsFields &fieldsA, const QgsFields &fieldsB, const QString &fieldsBPrefix=QString())
	Combines two field lists, avoiding duplicate field names (in a case-insensitive manner). More...

static QgsRectangle	combineLayerExtents (const QList< QgsMapLayer * > &layers, const QgsCoordinateReferenceSystem &crs, QgsProcessingContext &context)
	Combines the extent of several map layers. More...

static Q_DECL_DEPRECATED QgsRectangle	combineLayerExtents (const QList< QgsMapLayer * > &layers, const QgsCoordinateReferenceSystem &crs=QgsCoordinateReferenceSystem())
	Combines the extent of several map layers. More...

static QList< QgsMapLayer * >	compatibleLayers (QgsProject *project, bool sort=true)
	Returns a list of map layers from a project which are compatible with the processing framework. More...

static QList< QgsMeshLayer * >	compatibleMeshLayers (QgsProject *project, bool sort=true)
	Returns a list of mesh layers from a project which are compatible with the processing framework. More...

static QList< QgsRasterLayer * >	compatibleRasterLayers (QgsProject *project, bool sort=true)
	Returns a list of raster layers from a project which are compatible with the processing framework. More...

static QList< QgsVectorLayer * >	compatibleVectorLayers (QgsProject *project, const QList< int > &sourceTypes=QList< int >(), bool sort=true)
	Returns a list of vector layers from a project which are compatible with the processing framework. More...

static QString	convertToCompatibleFormat (const QgsVectorLayer layer, bool selectedFeaturesOnly, const QString &baseName, const QStringList &compatibleFormats, const QString &preferredFormat, QgsProcessingContext &context, QgsProcessingFeedback feedback, long long featureLimit=-1)
	Converts a source vector layer to a file path of a vector layer of compatible format. More...

static QString	convertToCompatibleFormatAndLayerName (const QgsVectorLayer layer, bool selectedFeaturesOnly, const QString &baseName, const QStringList &compatibleFormats, const QString &preferredFormat, QgsProcessingContext &context, QgsProcessingFeedback feedback, QString &layerName, long long featureLimit=-1)
	Converts a source vector layer to a file path and layer name of a vector layer of compatible format. More...

static QgsFeatureSink *	createFeatureSink (QString &destination, QgsProcessingContext &context, const QgsFields &fields, QgsWkbTypes::Type geometryType, const QgsCoordinateReferenceSystem &crs, const QVariantMap &createOptions=QVariantMap(), const QStringList &datasourceOptions=QStringList(), const QStringList &layerOptions=QStringList(), QgsFeatureSink::SinkFlags sinkFlags=QgsFeatureSink::SinkFlags(), QgsRemappingSinkDefinition *remappingDefinition=nullptr)
	Creates a feature sink ready for adding features. More...

static void	createFeatureSinkPython (QgsFeatureSink **sink, QString &destination, QgsProcessingContext &context, const QgsFields &fields, QgsWkbTypes::Type geometryType, const QgsCoordinateReferenceSystem &crs, const QVariantMap &createOptions=QVariantMap()) SIP_THROW(QgsProcessingException)
	Creates a feature sink ready for adding features. More...

static bool	decodeProviderKeyAndUri (const QString &string, QString &providerKey, QString &uri)
	Decodes a provider key and layer uri from an encoded string, for use with encodeProviderKeyAndUri() More...

static QString	defaultRasterExtension ()
	Returns the default raster extension to use, in the absence of all other constraints (e.g. More...

static QString	defaultVectorExtension ()
	Returns the default vector extension to use, in the absence of all other constraints (e.g. More...

static QString	encodeProviderKeyAndUri (const QString &providerKey, const QString &uri)
	Encodes a provider key and layer uri to a single string, for use with decodeProviderKeyAndUri() More...

static QList< int >	fieldNamesToIndices (const QStringList &fieldNames, const QgsFields &fields)
	Returns a list of field indices parsed from the given list of field names. More...

static QString	formatHelpMapAsHtml (const QVariantMap &map, const QgsProcessingAlgorithm *algorithm)
	Returns a HTML formatted version of the help text encoded in a variant map for a specified algorithm. More...

static QVariant	generateIteratingDestination (const QVariant &input, const QVariant &id, QgsProcessingContext &context)
	Converts an input parameter value for use in source iterating mode, where one individual sink is created per input feature. More...

static QString	generateTempFilename (const QString &basename)
	Returns a temporary filename for a given file, putting it into a temporary folder (creating that folder in the process), but not changing the basename. More...

static QgsFields	indicesToFields (const QList< int > &indices, const QgsFields &fields)
	Returns a subset of fields based on the indices of desired fields. More...

static QgsMapLayer *	mapLayerFromString (const QString &string, QgsProcessingContext &context, bool allowLoadingNewLayers=true, QgsProcessingUtils::LayerHint typeHint=QgsProcessingUtils::LayerHint::UnknownType)
	Interprets a string as a map layer within the supplied context. More...

static QString	normalizeLayerSource (const QString &source)
	Normalizes a layer source string for safe comparison across different operating system environments. More...

static QString	stringToPythonLiteral (const QString &string)
	Converts a string to a Python string literal. More...

static QString	tempFolder ()
	Returns a session specific processing temporary folder for use in processing algorithms. More...

static QgsCoordinateReferenceSystem	variantToCrs (const QVariant &value, QgsProcessingContext &context, const QVariant &fallbackValue=QVariant())
	Converts a variant value to a coordinate reference system. More...

static QString	variantToPythonLiteral (const QVariant &value)
	Converts a variant to a Python literal. More...

static QgsProcessingFeatureSource *	variantToSource (const QVariant &value, QgsProcessingContext &context, const QVariant &fallbackValue=QVariant())
	Converts a variant value to a new feature source. More...

Friends
class	QgsProcessingProvider

class	TestQgsProcessing

Detailed Description

Utility functions for use with processing classes.

Since: QGIS 3.0

Definition at line 50 of file qgsprocessingutils.h.

Member Enumeration Documentation

◆ LayerHint

enum QgsProcessingUtils::LayerHint : int

strong

Layer type hints.

Since: QGIS 3.4

Enumerator
UnknownType	Unknown layer type.
Vector	Vector layer type.
Raster	Raster layer type.
Mesh	Mesh layer type, since QGIS 3.6.

Definition at line 136 of file qgsprocessingutils.h.

Member Function Documentation

◆ combineFields()

QgsFields QgsProcessingUtils::combineFields	(	const QgsFields &	fieldsA,
		const QgsFields &	fieldsB,
		const QString &	fieldsBPrefix = `QString()`
	)

static

Combines two field lists, avoiding duplicate field names (in a case-insensitive manner).

Duplicate field names will be altered to "name_2", "name_3", etc, finding the first non-duplicate name.

Note: Some output file formats (e.g. shapefiles) have restrictions on the maximum length of field names, so be aware that the results of calling this method may be truncated when saving to these formats.

Definition at line 1145 of file qgsprocessingutils.cpp.

◆ combineLayerExtents() [1/2]

QgsRectangle QgsProcessingUtils::combineLayerExtents	(	const QList< QgsMapLayer * > &	layers,
		const QgsCoordinateReferenceSystem &	crs,
		QgsProcessingContext &	context
	)

static

Combines the extent of several map layers.

If specified, the target crs will be used to transform the layer's extent to the desired output reference system using the specified context.

Since: QGIS 3.8

Definition at line 869 of file qgsprocessingutils.cpp.

◆ combineLayerExtents() [2/2]

QgsRectangle QgsProcessingUtils::combineLayerExtents	(	const QList< QgsMapLayer * > &	layers,
		const QgsCoordinateReferenceSystem &	crs = `QgsCoordinateReferenceSystem()`
	)

static

Combines the extent of several map layers.

If specified, the target crs will be used to transform the layer's extent to the desired output reference system.

Deprecated:: Use version with QgsProcessingContext argument instead

Definition at line 902 of file qgsprocessingutils.cpp.

◆ compatibleLayers()

QList< QgsMapLayer * > QgsProcessingUtils::compatibleLayers	(	QgsProject *	project,
		bool	sort = `true`
	)

static

Returns a list of map layers from a project which are compatible with the processing framework.

If the sort argument is true then the layers will be sorted by their QgsMapLayer::name() value.

See also: compatibleRasterLayers(); compatibleVectorLayers()

Definition at line 110 of file qgsprocessingutils.cpp.

◆ compatibleMeshLayers()

QList< QgsMeshLayer * > QgsProcessingUtils::compatibleMeshLayers	(	QgsProject *	project,
		bool	sort = `true`
	)

static

Returns a list of mesh layers from a project which are compatible with the processing framework.

If the sort argument is true then the layers will be sorted by their QgsMapLayer::name() value.

See also: compatibleRasterLayers(); compatibleVectorLayers(); compatibleLayers()

Since: QGIS 3.6

Definition at line 87 of file qgsprocessingutils.cpp.

◆ compatibleRasterLayers()

QList< QgsRasterLayer * > QgsProcessingUtils::compatibleRasterLayers	(	QgsProject *	project,
		bool	sort = `true`
	)

static

Returns a list of raster layers from a project which are compatible with the processing framework.

If the sort argument is true then the layers will be sorted by their QgsMapLayer::name() value.

See also: compatibleVectorLayers(); compatibleMeshLayers(); compatibleLayers()

Definition at line 40 of file qgsprocessingutils.cpp.

◆ compatibleVectorLayers()

QList< QgsVectorLayer * > QgsProcessingUtils::compatibleVectorLayers	(	QgsProject *	project,
		const QList< int > &	sourceTypes = `QList< int >()`,
		bool	sort = `true`
	)

static

Returns a list of vector layers from a project which are compatible with the processing framework.

The sourceTypes list should be filled with a list of QgsProcessing::SourceType values. If the sourceTypes list is non-empty then the layers will be sorted so that only layers with the specified source type included in the list will be returned. Leaving the sourceTypes list empty will cause all vector layers, regardless of their geometry type, to be returned.

If the sort argument is true then the layers will be sorted by their QgsMapLayer::name() value.

See also: compatibleRasterLayers(); compatibleMeshLayers(); compatibleLayers()

Definition at line 64 of file qgsprocessingutils.cpp.

◆ convertToCompatibleFormat()

QString QgsProcessingUtils::convertToCompatibleFormat	(	const QgsVectorLayer *	layer,
		bool	selectedFeaturesOnly,
		const QString &	baseName,
		const QStringList &	compatibleFormats,
		const QString &	preferredFormat,
		QgsProcessingContext &	context,
		QgsProcessingFeedback *	feedback,
		long long	featureLimit = `-1`
	)

static

Converts a source vector layer to a file path of a vector layer of compatible format.

If the specified layer is not of the format listed in the compatibleFormats argument, then the layer will first be exported to a compatible format in a temporary location using baseName. The function will then return the path to that temporary file.

compatibleFormats should consist entirely of lowercase file extensions, e.g. 'shp'.

The preferredFormat argument is used to specify to desired file extension to use when a temporary layer export is required. This defaults to shapefiles.

The featureLimit argument can be used to specify a limit on the number of features read from the layer.

When an algorithm is capable of handling multi-layer input files (such as Geopackage), it is preferable to use convertToCompatibleFormatAndLayerName() which may avoid conversion in more situations.

See also: convertToCompatibleFormatAndLayerName()

Definition at line 1134 of file qgsprocessingutils.cpp.

◆ convertToCompatibleFormatAndLayerName()

QString QgsProcessingUtils::convertToCompatibleFormatAndLayerName	(	const QgsVectorLayer *	layer,
		bool	selectedFeaturesOnly,
		const QString &	baseName,
		const QStringList &	compatibleFormats,
		const QString &	preferredFormat,
		QgsProcessingContext &	context,
		QgsProcessingFeedback *	feedback,
		QString &	layerName,
		long long	featureLimit = `-1`
	)

static

Converts a source vector layer to a file path and layer name of a vector layer of compatible format.

If the specified layer is not of the format listed in the compatibleFormats argument, then the layer will first be exported to a compatible format in a temporary location using baseName. The function will then return the path to that temporary file.

compatibleFormats should consist entirely of lowercase file extensions, e.g. 'shp'.

The featureLimit argument can be used to specify a limit on the number of features read from the layer.

The preferredFormat argument is used to specify to desired file extension to use when a temporary layer export is required. This defaults to shapefiles.

This method should be preferred over convertToCompatibleFormat() when an algorithm is able to correctly handle files with multiple layers. Unlike convertToCompatibleFormat(), it will not force a conversion in this case and will return the target layer name in the layerName argument.

Parameters

layer	source layer to convert (if required)
selectedFeaturesOnly	`true` if only selected features from the layer should be used
baseName	base file name for converted layer, if required
compatibleFormats	a list of lowercase file extensions compatible with the algorithm
preferredFormat	preferred format extension to use if conversion if required
context	processing context
feedback	feedback object
layerName	will be set to the target layer name for multi-layer sources (e.g. Geopackage)
featureLimit	can be used to place a limit on the maximum number of features read from the layer

Returns: path to source layer, or nearly converted compatible layer

See also: convertToCompatibleFormat()

Since: QGIS 3.10

Definition at line 1139 of file qgsprocessingutils.cpp.

◆ createFeatureSink()

QgsFeatureSink * QgsProcessingUtils::createFeatureSink	(	QString &	destination,
		QgsProcessingContext &	context,
		const QgsFields &	fields,
		QgsWkbTypes::Type	geometryType,
		const QgsCoordinateReferenceSystem &	crs,
		const QVariantMap &	createOptions = `QVariantMap()`,
		const QStringList &	datasourceOptions = `QStringList()`,
		const QStringList &	layerOptions = `QStringList()`,
		QgsFeatureSink::SinkFlags	sinkFlags = `QgsFeatureSink::SinkFlags()`,
		QgsRemappingSinkDefinition *	remappingDefinition = `nullptr`
	)

static

Creates a feature sink ready for adding features.

The destination specifies a destination URI for the resultant layer. It may be updated in place to reflect the actual destination for the layer.

Sink parameters such as desired encoding, fields, geometryType and crs must be specified.

The createOptions map can be used to specify additional sink creation options, which are passed to the underlying provider when creating new layers. Known options also include 'fileEncoding', which is used to specify a file encoding to use for created files. If 'fileEncoding' is not specified, the default encoding from the context will be used.

If a layer is created for the feature sink, the layer will automatically be added to the context's temporary layer store.

The caller takes responsibility for deleting the returned sink.

Definition at line 711 of file qgsprocessingutils.cpp.

◆ createFeatureSinkPython()

void QgsProcessingUtils::createFeatureSinkPython	(	QgsFeatureSink **	sink,
		QString &	destination,
		QgsProcessingContext &	context,
		const QgsFields &	fields,
		QgsWkbTypes::Type	geometryType,
		const QgsCoordinateReferenceSystem &	crs,
		const QVariantMap &	createOptions = `QVariantMap()`
	)

static

Creates a feature sink ready for adding features.

The destination specifies a destination URI for the resultant layer. It may be updated in place to reflect the actual destination for the layer.

Sink parameters such as desired fields, geometryType and crs must be specified.

The createOptions map can be used to specify additional sink creation options, which are passed to the underlying provider when creating new layers. Known options also include 'fileEncoding', which is used to specify a file encoding to use for created files. If 'fileEncoding' is not specified, the default encoding from the context will be used.

If a layer is created for the feature sink, the layer will automatically be added to the context's temporary layer store.

Note: this version of the createFeatureSink() function has an API designed around use from the SIP bindings. c++ code should call the other createFeatureSink() version.; available in Python bindings as createFeatureSink()

Definition at line 863 of file qgsprocessingutils.cpp.

◆ decodeProviderKeyAndUri()

bool QgsProcessingUtils::decodeProviderKeyAndUri	(	const QString &	string,
		QString &	providerKey,
		QString &	uri
	)

static

Decodes a provider key and layer uri from an encoded string, for use with encodeProviderKeyAndUri()

Parameters

string	encoded string, as returned by encodeProviderKeyAndUri()
providerKey	ID key for corresponding data provider
uri	decoded layer uri

Returns: true if string was successfully decoded

Since: QGIS 3.14

Definition at line 144 of file qgsprocessingutils.cpp.

◆ defaultRasterExtension()

QString QgsProcessingUtils::defaultRasterExtension ( )

static

Returns the default raster extension to use, in the absence of all other constraints (e.g.

provider based support for extensions).

This method returns the user-set default extension from the processing settings, or a fallback value of "tif".

See also: defaultVectorExtension()

Since: QGIS 3.10

Definition at line 1220 of file qgsprocessingutils.cpp.

◆ defaultVectorExtension()

QString QgsProcessingUtils::defaultVectorExtension ( )

static

Returns the default vector extension to use, in the absence of all other constraints (e.g.

provider based support for extensions).

This method returns the user-set default extension from the processing settings, or a fallback value of "gpkg".

See also: defaultRasterExtension()

Since: QGIS 3.10

Definition at line 1212 of file qgsprocessingutils.cpp.

◆ encodeProviderKeyAndUri()

QString QgsProcessingUtils::encodeProviderKeyAndUri	(	const QString &	providerKey,
		const QString &	uri
	)

static

Encodes a provider key and layer uri to a single string, for use with decodeProviderKeyAndUri()

Since: QGIS 3.14

Definition at line 139 of file qgsprocessingutils.cpp.

◆ fieldNamesToIndices()

QList< int > QgsProcessingUtils::fieldNamesToIndices	(	const QStringList &	fieldNames,
		const QgsFields &	fields
	)

static

Returns a list of field indices parsed from the given list of field names.

Unknown field names are ignored. If the list of field names is empty, it is assumed that all fields are required.

Since: QGIS 3.2

Definition at line 1181 of file qgsprocessingutils.cpp.

◆ formatHelpMapAsHtml()

QString QgsProcessingUtils::formatHelpMapAsHtml	(	const QVariantMap &	map,
		const QgsProcessingAlgorithm *	algorithm
	)

static

Returns a HTML formatted version of the help text encoded in a variant map for a specified algorithm.

Definition at line 994 of file qgsprocessingutils.cpp.

◆ generateIteratingDestination()

QVariant QgsProcessingUtils::generateIteratingDestination	(	const QVariant &	input,
		const QVariant &	id,
		QgsProcessingContext &	context
	)

static

Converts an input parameter value for use in source iterating mode, where one individual sink is created per input feature.

The id parameter represents the unique ID for this output, which is embedded into the resulting parameter value.

Definition at line 908 of file qgsprocessingutils.cpp.

◆ generateTempFilename()

QString QgsProcessingUtils::generateTempFilename ( const QString & basename )

static

Returns a temporary filename for a given file, putting it into a temporary folder (creating that folder in the process), but not changing the basename.

See also: tempFolder()

Definition at line 982 of file qgsprocessingutils.cpp.

◆ indicesToFields()

QgsFields QgsProcessingUtils::indicesToFields	(	const QList< int > &	indices,
		const QgsFields &	fields
	)

static

Returns a subset of fields based on the indices of desired fields.

Since: QGIS 3.2

Definition at line 1204 of file qgsprocessingutils.cpp.

◆ mapLayerFromString()

QgsMapLayer * QgsProcessingUtils::mapLayerFromString	(	const QString &	string,
		QgsProcessingContext &	context,
		bool	allowLoadingNewLayers = `true`,
		QgsProcessingUtils::LayerHint	typeHint = `QgsProcessingUtils::LayerHint::UnknownType`
	)

static

Interprets a string as a map layer within the supplied context.

The method will attempt to load a layer matching the passed string. E.g. if the string matches a layer ID or name within the context's project or temporary layer store then this layer will be returned. If the string is a file path and allowLoadingNewLayers is true, then the layer at this file path will be loaded and added to the context's temporary layer store. Ownership of the layer remains with the context or the context's current project.

The typeHint can be used to dictate the type of map layer expected.

Definition at line 320 of file qgsprocessingutils.cpp.

◆ normalizeLayerSource()

QString QgsProcessingUtils::normalizeLayerSource ( const QString & source )

static

Normalizes a layer source string for safe comparison across different operating system environments.

Definition at line 518 of file qgsprocessingutils.cpp.

◆ stringToPythonLiteral()

QString QgsProcessingUtils::stringToPythonLiteral ( const QString & string )

static

Converts a string to a Python string literal.

E.g. by replacing ' with \'.

See also: variantToPythonLiteral()

Definition at line 627 of file qgsprocessingutils.cpp.

◆ tempFolder()

QString QgsProcessingUtils::tempFolder ( )

static

Returns a session specific processing temporary folder for use in processing algorithms.

See also: generateTempFilename()

Definition at line 947 of file qgsprocessingutils.cpp.

◆ variantToCrs()

QgsCoordinateReferenceSystem QgsProcessingUtils::variantToCrs	(	const QVariant &	value,
		QgsProcessingContext &	context,
		const QVariant &	fallbackValue = `QVariant()`
	)

static

Converts a variant value to a coordinate reference system.

The optional fallbackValue can be used to specify a "default" value which is used if value cannot be successfully converted to a CRS.

Since: QGIS 3.12

Definition at line 430 of file qgsprocessingutils.cpp.

◆ variantToPythonLiteral()

QString QgsProcessingUtils::variantToPythonLiteral ( const QVariant & value )

static

Converts a variant to a Python literal.

See also: stringToPythonLiteral()

Since: QGSIS 3.6

Definition at line 525 of file qgsprocessingutils.cpp.

◆ variantToSource()

QgsProcessingFeatureSource * QgsProcessingUtils::variantToSource	(	const QVariant &	value,
		QgsProcessingContext &	context,
		const QVariant &	fallbackValue = `QVariant()`
	)

static

Converts a variant value to a new feature source.

Sources will either be taken from context's active project, or loaded from external sources and stored temporarily in the context.

The optional fallbackValue can be used to specify a "default" value which is used if value cannot be successfully converted to a source.

This function creates a new object and the caller takes responsibility for deleting the returned object.

Definition at line 353 of file qgsprocessingutils.cpp.

Friends And Related Function Documentation

◆ QgsProcessingProvider

friend class QgsProcessingProvider

friend

Definition at line 459 of file qgsprocessingutils.h.

◆ TestQgsProcessing

friend class TestQgsProcessing

friend

Definition at line 458 of file qgsprocessingutils.h.

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

/build/qgis-3.20.0+99unstable/src/core/processing/qgsprocessingutils.h
/build/qgis-3.20.0+99unstable/src/core/processing/qgsprocessingutils.cpp

Public Types

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ LayerHint

Member Function Documentation

◆ combineFields()

◆ combineLayerExtents() [1/2]

◆ combineLayerExtents() [2/2]

◆ compatibleLayers()

◆ compatibleMeshLayers()

◆ compatibleRasterLayers()

◆ compatibleVectorLayers()

◆ convertToCompatibleFormat()

◆ convertToCompatibleFormatAndLayerName()

◆ createFeatureSink()

◆ createFeatureSinkPython()

◆ decodeProviderKeyAndUri()

◆ defaultRasterExtension()

◆ defaultVectorExtension()

◆ encodeProviderKeyAndUri()

◆ fieldNamesToIndices()

◆ formatHelpMapAsHtml()

◆ generateIteratingDestination()

◆ generateTempFilename()

◆ indicesToFields()

◆ mapLayerFromString()

◆ normalizeLayerSource()

◆ stringToPythonLiteral()

◆ tempFolder()

◆ variantToCrs()

◆ variantToPythonLiteral()

◆ variantToSource()

Friends And Related Function Documentation

◆ QgsProcessingProvider

◆ TestQgsProcessing