Class: QgsMeshLayer

class qgis.core.QgsMeshLayer(path: str = '', baseName: str = '', providerLib: str = '', options: QgsMeshLayer.LayerOptions = QgsMeshLayer.LayerOptions())

Bases: QgsMapLayer

Constructor - creates a mesh layer

The QgsMeshLayer is constructed by instantiating a data provider. The provider interprets the supplied path (url) of the data source to connect to and access the data.

Parameters
  • path (str = '') – The path or url of the parameter. Typically this encodes parameters used by the data provider as url query items.

  • baseName (str = '') – The name used to represent the layer in the legend

  • providerLib (str = '') – The name of the data provider, e.g., “mesh_memory”, “mdal”

  • options (QgsMeshLayer.LayerOptions = QgsMeshLayer.LayerOptions()) – general mesh layer options

Represents a mesh layer supporting display of data on structured or unstructured meshes

The QgsMeshLayer is instantiated by specifying the name of a data provider, such as mdal, and url defining the specific data set to connect to. The vector layer constructor in turn instantiates a QgsMeshDataProvider subclass corresponding to the provider type, and passes it the url. The data provider connects to the data source.

The QgsMeshLayer provides a common interface to the different data types. It does not yet support editing transactions.

The main data providers supported by QGIS are listed below.

section mesh_providers Mesh data providers

subsection mesh_memory Memory data providerType (mesh_memory)

The memory data provider is used to construct in memory data, for example scratch data. There is no inherent persistent storage of the data. The data source uri is constructed. Data can be populated by setMesh(const QString &vertices, const QString &faces), where vertices and faces is comma separated coordinates and connections for mesh. E.g. to create mesh with one quad and one triangle

QString uri(
    "1.0, 2.0 \n" \
    "2.0, 2.0 \n" \
    "3.0, 2.0 \n" \
    "2.0, 3.0 \n" \
    "1.0, 3.0 \n" \
    "---" \
    "0, 1, 3, 4 \n" \
    "1, 2, 3 \n"
  );
  :py:class:`.QgsMeshLayer` *scratchLayer = new QgsMeshLayer(uri, "My Scratch layer", "mesh_memory");

subsection mdal MDAL data provider (mdal)

Accesses data using the MDAL drivers (https://github.com/lutraconsulting/MDAL). The url is the MDAL connection string. QGIS must be built with MDAL support to allow this provider.

QString uri = "test/land.2dm";
:py:class:`.QgsMeshLayer` *scratchLayer = new QgsMeshLayer(uri, "My Scratch Layer",  "mdal");

Note

The API is considered EXPERIMENTAL and can be changed without a notice

Methods

activeScalarDatasetAtTime

Returns dataset index from active scalar group depending on the time range.

activeVectorDatasetAtTime

Returns dataset index from active vector group depending on the time range If the temporal properties is not active, return the static dataset

addDatasets

Add datasets to the mesh from file with path.

appendError

Add error message

childEvent

clone

rtype

QgsMeshLayer

connectNotify

createMapRenderer

param rendererContext

customEvent

dataProvider

QgsMeshLayer cannot be copied.

dataset1dValue

Returns the value of 1D mesh dataset defined on edge that are in the search area defined by point ans searchRadius

dataset3dValue

Returns the 3d values of stacked 3d mesh defined by the given point

datasetGroupTreeRootItem

Returns the root items of the dataset group tree item

datasetIndexAtTime

Returns dataset index from datasets group depending on the time range.

datasetValue

Interpolates the value on the given point from given dataset.

decodedSource

param source

disconnectNotify

encodedSource

param source

extent

rtype

QgsRectangle

firstValidTimeStep

Returns the first valid time step of the dataset groups, invalid QgInterval if no time step is present

formatTime

Returns (date) time in hours formatted to human readable form

hasDependencyCycle

Checks whether a new set of dependencies will introduce a cycle this method is now deprecated and always return false, because circular dependencies are now correctly managed.

isSignalConnected

providerType

Returns the provider type for this layer

readCommonStyle

Read style data common to all layer types

readCustomProperties

Read custom properties from project file.

readStyle

param node

readStyleManager

Read style manager’s configuration (if any).

readSymbology

param node

readXml

param layer_node

receivers

reload

rendererSettings

Returns renderer settings

resetDatasetGroupTreeItem

Reset the dataset group tree item to default from provider

sender

senderSignalIndex

setDatasetGroupTreeRootItem

Sets the root items of the dataset group tree item.

setError

Sets error message

setExtent

Sets the extent

setProviderType

Sets the providerType (provider key)

setReferenceTime

Sets the reference time of the layer

setRendererSettings

Sets new renderer settings

setTemporalMatchingMethod

Sets the method used to match the temporal dataset from a requested time, see activeVectorDatasetAtTime()

setTimeSettings

Sets time format settings

setTransformContext

Sets the coordinate transform context to transformContext.

setValid

Sets whether layer is valid or not - should be used in constructor.

snapOnElement

Returns the position of the snapped point on the mesh element closest to point intersecting with the searching area defined by point and searchRadius

staticScalarDatasetIndex

Returns the static scalar dataset index that is rendered if the temporal properties is not active

staticVectorDatasetIndex

Returns the static vector dataset index that is rendered if the temporal properties is not active

subLayers

rtype

List[str]

temporalProperties

rtype

QgsMapLayerTemporalProperties

timeSettings

Returns time format settings

timerEvent

updateTriangularMesh

Gets native mesh and updates (creates if it doesn’t exist) the base triangular mesh

writeCommonStyle

Write style data common to all layer types

writeCustomProperties

Write custom properties to project file.

writeStyle

param node

writeStyleManager

Write style manager’s configuration (if exists).

writeSymbology

param node

writeXml

param layer_node

Signals

activeScalarDatasetGroupChanged

Emitted when active scalar group dataset is changed

activeVectorDatasetGroupChanged

Emitted when active vector group dataset is changed

timeSettingsChanged

Emitted when time format is changed

class LayerOptions(transformContext: QgsCoordinateTransformContext = QgsCoordinateTransformContext())

Bases: sip.wrapper

Constructor for LayerOptions with optional transformContext.

Note

transformContext argument was added in QGIS 3.8

QgsMeshLayer.LayerOptions(QgsMeshLayer.LayerOptions)

Parameters

transformContext (QgsCoordinateTransformContext = QgsCoordinateTransformContext()) –

skipCrsValidation
transformContext
activeScalarDatasetAtTime(self, timeRange: QgsDateTimeRange)QgsMeshDatasetIndex

Returns dataset index from active scalar group depending on the time range. If the temporal properties is not active, return the static dataset

Parameters

timeRange (QgsDateTimeRange) – the time range

Return type

QgsMeshDatasetIndex

Returns

dataset index

Note

the returned dataset index depends on the matching method, see setTemporalMatchingMethod()

New in version 3.14.

activeScalarDatasetGroupChanged

Emitted when active scalar group dataset is changed

New in version 3.14: [signal]

Parameters

index (int) –

activeVectorDatasetAtTime(self, timeRange: QgsDateTimeRange)QgsMeshDatasetIndex

Returns dataset index from active vector group depending on the time range If the temporal properties is not active, return the static dataset

Parameters

timeRange (QgsDateTimeRange) – the time range

Return type

QgsMeshDatasetIndex

Returns

dataset index

Note

the returned dataset index depends on the matching method, see setTemporalMatchingMethod()

New in version 3.14.

activeVectorDatasetGroupChanged

Emitted when active vector group dataset is changed

New in version 3.14: [signal]

Parameters

index (int) –

addDatasets(self, path: str, defaultReferenceTime: Union[QDateTime, datetime.datetime] = QDateTime()) → bool

Add datasets to the mesh from file with path. Use the the time defaultReferenceTime as reference time is not provided in the file

Parameters
  • path (str) – the path to the atasets file

  • defaultReferenceTime (Union[QDateTime) – reference time used if not provided in the file

Return type

bool

Returns

whether the dataset is added

New in version 3.14.

appendError(self, error: QgsErrorMessage)

Add error message

childEvent(self, QChildEvent)
clone(self)QgsMeshLayer
Return type

QgsMeshLayer

connectNotify(self, QMetaMethod)
createMapRenderer(self, rendererContext: QgsRenderContext)QgsMapLayerRenderer
Parameters

rendererContext (QgsRenderContext) –

Return type

QgsMapLayerRenderer

customEvent(self, QEvent)
dataProvider(self)QgsMeshDataProvider

QgsMeshLayer cannot be copied.

Return type

QgsMeshDataProvider

dataset1dValue(self, index: QgsMeshDatasetIndex, point: QgsPointXY, searchRadius: float)QgsMeshDatasetValue

Returns the value of 1D mesh dataset defined on edge that are in the search area defined by point ans searchRadius

Note

It uses previously cached and indexed triangular mesh and so if the layer has not been rendered previously (e.g. when used in a script) it returns NaN value

Parameters
  • index (QgsMeshDatasetIndex) – dataset index specifying group and dataset to extract value from

  • point (QgsPointXY) – the center point of the search area

  • searchRadius (float) – the radius of the searc area in map unit

Return type

QgsMeshDatasetValue

Returns

interpolated value at the projected point. Returns NaN values for values outside the mesh layer and in case triangular mesh was not previously used for rendering

New in version 3.14.

dataset3dValue(self, index: QgsMeshDatasetIndex, point: QgsPointXY)QgsMesh3dDataBlock

Returns the 3d values of stacked 3d mesh defined by the given point

Note

It uses previously cached and indexed triangular mesh and so if the layer has not been rendered previously (e.g. when used in a script) it returns NaN value

Parameters
  • index (QgsMeshDatasetIndex) – dataset index specifying group and dataset to extract value from

  • point (QgsPointXY) – point to query in map coordinates

Return type

QgsMesh3dDataBlock

Returns

all 3d stacked values that belong to face defined by given point. Returns invalid block for point outside the mesh layer or in case triangular mesh was not previously used for rendering or for datasets that do not have type DataOnVolumes

New in version 3.12.

datasetGroupTreeRootItem(self)QgsMeshDatasetGroupTreeItem

Returns the root items of the dataset group tree item

Return type

QgsMeshDatasetGroupTreeItem

Returns

the root item

New in version 3.14.

datasetIndexAtTime(self, timeRange: QgsDateTimeRange, datasetGroupIndex: int)QgsMeshDatasetIndex

Returns dataset index from datasets group depending on the time range. If the temporal properties is not active, returns invalid dataset index

Parameters

timeRange (QgsDateTimeRange) – the time range

Return type

QgsMeshDatasetIndex

Returns

dataset index

Note

the returned dataset index depends on the matching method, see setTemporalMatchingMethod()

New in version 3.14.

Parameters

datasetGroupIndex (int) –

datasetValue(self, index: QgsMeshDatasetIndex, point: QgsPointXY, searchRadius: float = 0)QgsMeshDatasetValue

Interpolates the value on the given point from given dataset. For 3D datasets, it uses dataset3dValue(), n For 1D datasets, it uses dataset1dValue() with searchRadius

Note

It uses previously cached and indexed triangular mesh and so if the layer has not been rendered previously (e.g. when used in a script) it returns NaN value

Parameters
  • index (QgsMeshDatasetIndex) – dataset index specifying group and dataset to extract value from

  • point (QgsPointXY) – point to query in map coordinates

  • searchRadius (float = 0) – the radius of the search area in map unit

Return type

QgsMeshDatasetValue

Returns

interpolated value at the point. Returns NaN values for values outside the mesh layer, nodata values and in case triangular mesh was not previously used for rendering

New in version 3.4.

decodedSource(self, source: str, provider: str, context: QgsReadWriteContext) → str
Parameters
Return type

str

disconnectNotify(self, QMetaMethod)
encodedSource(self, source: str, context: QgsReadWriteContext) → str
Parameters
Return type

str

extent(self)QgsRectangle
Return type

QgsRectangle

firstValidTimeStep(self)QgsInterval

Returns the first valid time step of the dataset groups, invalid QgInterval if no time step is present

New in version 3.14.

Return type

QgsInterval

formatTime(self, hours: float) → str

Returns (date) time in hours formatted to human readable form

Parameters

hours (float) – time in double in hours

Return type

str

Returns

formatted time string

New in version 3.8.

hasDependencyCycle(self, Iterable[QgsMapLayerDependency]) → bool

Checks whether a new set of dependencies will introduce a cycle this method is now deprecated and always return false, because circular dependencies are now correctly managed.

Deprecated since version QGIS: 3.10

isSignalConnected(self, QMetaMethod) → bool
providerType(self) → str

Returns the provider type for this layer

Return type

str

readCommonStyle(self, layerElement: QDomElement, context: QgsReadWriteContext, categories: Union[QgsMapLayer.StyleCategories, QgsMapLayer.StyleCategory] = QgsMapLayer.AllStyleCategories)

Read style data common to all layer types

New in version 3.0.

readCustomProperties(self, layerNode: QDomNode, keyStartsWith: str = '')

Read custom properties from project file.

Parameters
  • layerNode – note to read from

  • keyStartsWith – reads only properties starting with the specified string (or all if the string is empty)*

readStyle(self, node: QDomNode, errorMessage: str, context: QgsReadWriteContext, categories: Union[QgsMapLayer.StyleCategories, QgsMapLayer.StyleCategory] = QgsMapLayer.AllStyleCategories) → bool
Parameters
Return type

bool

readStyleManager(self, layerNode: QDomNode)

Read style manager’s configuration (if any). To be called by subclasses.

readSymbology(self, node: QDomNode, errorMessage: str, context: QgsReadWriteContext, categories: Union[QgsMapLayer.StyleCategories, QgsMapLayer.StyleCategory] = QgsMapLayer.AllStyleCategories) → bool
Parameters
Return type

bool

readXml(self, layer_node: QDomNode, context: QgsReadWriteContext) → bool
Parameters
Return type

bool

receivers(self, PYQT_SIGNAL) → int
reload(self)
rendererSettings(self)QgsMeshRendererSettings

Returns renderer settings

Return type

QgsMeshRendererSettings

resetDatasetGroupTreeItem(self)

Reset the dataset group tree item to default from provider

New in version 3.14.

sender(self) → QObject
senderSignalIndex(self) → int
setDatasetGroupTreeRootItem(self, rootItem: QgsMeshDatasetGroupTreeItem)

Sets the root items of the dataset group tree item. Changes active dataset groups if those one are not enabled anymore :

  • new active scalar dataset group is the first root item enabled child

  • new active vector dataset group is none

Doesn’t take ownership of the pointed item, the root item is cloned.

Parameters

rootItem (QgsMeshDatasetGroupTreeItem) – the new root item

New in version 3.14.

setError(self, error: QgsError)

Sets error message

setExtent(self, rect: QgsRectangle)

Sets the extent

setProviderType(self, providerType: str)

Sets the providerType (provider key)

setReferenceTime(self, referenceTime: Union[QDateTime, datetime.datetime])

Sets the reference time of the layer

Parameters

referenceTime (Union[QDateTime) – the reference time

New in version 3.14.

setRendererSettings(self, settings: QgsMeshRendererSettings)

Sets new renderer settings

Parameters

settings (QgsMeshRendererSettings) –

setTemporalMatchingMethod(self, matchingMethod: QgsMeshDataProviderTemporalCapabilities.MatchingTemporalDatasetMethod)

Sets the method used to match the temporal dataset from a requested time, see activeVectorDatasetAtTime()

Parameters

matchingMethod (QgsMeshDataProviderTemporalCapabilities.MatchingTemporalDatasetMethod) – the matching method

New in version 3.14.

setTimeSettings(self, settings: QgsMeshTimeSettings)

Sets time format settings

New in version 3.8.

Parameters

settings (QgsMeshTimeSettings) –

setTransformContext(self, transformContext: QgsCoordinateTransformContext)

Sets the coordinate transform context to transformContext.

New in version 3.8.

Parameters

transformContext (QgsCoordinateTransformContext) –

setValid(self, valid: bool)

Sets whether layer is valid or not - should be used in constructor.

snapOnElement(self, elementType: QgsMesh.ElementType, point: QgsPointXY, searchRadius: float)QgsPointXY

Returns the position of the snapped point on the mesh element closest to point intersecting with the searching area defined by point and searchRadius

For vertex, the snapped position is the vertex position For edge, the snapped position is the projected point on the edge, extremity of edge if outside the edge For face, the snapped position is the centroid of the face The returned position is in map coordinates.

Note

It uses previously cached and indexed triangular mesh and so if the layer has not been rendered previously (e.g. when used in a script) it returns empty QgsPointXY

Parameters
  • elementType (QgsMesh.ElementType) – the type of element to snap

  • point (QgsPointXY) – the center of the search area in map coordinates

  • searchRadius (float) – the radius of the search area in map units

Return type

QgsPointXY

Returns

the position of the snapped point on the closest element, empty QgsPointXY if no element of type elementType

New in version 3.14.

staticScalarDatasetIndex(self)QgsMeshDatasetIndex

Returns the static scalar dataset index that is rendered if the temporal properties is not active

New in version 3.14.

Return type

QgsMeshDatasetIndex

staticVectorDatasetIndex(self)QgsMeshDatasetIndex

Returns the static vector dataset index that is rendered if the temporal properties is not active

New in version 3.14.

Return type

QgsMeshDatasetIndex

subLayers(self) → List[str]
Return type

List[str]

temporalProperties(self)QgsMapLayerTemporalProperties
Return type

QgsMapLayerTemporalProperties

timeSettings(self)QgsMeshTimeSettings

Returns time format settings

New in version 3.8.

Return type

QgsMeshTimeSettings

timeSettingsChanged

Emitted when time format is changed

New in version 3.8: [signal]

timerEvent(self, QTimerEvent)
updateTriangularMesh(self, transform: QgsCoordinateTransform = QgsCoordinateTransform())

Gets native mesh and updates (creates if it doesn’t exist) the base triangular mesh

Parameters

transform (QgsCoordinateTransform = QgsCoordinateTransform()) – Transformation from layer CRS to destination (e.g. map) CRS. With invalid transform, it keeps the native mesh CRS

New in version 3.14.

writeCommonStyle(self, layerElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext, categories: Union[QgsMapLayer.StyleCategories, QgsMapLayer.StyleCategory] = QgsMapLayer.AllStyleCategories)

Write style data common to all layer types

New in version 3.0.

writeCustomProperties(self, layerNode: QDomNode, doc: QDomDocument)

Write custom properties to project file.

writeStyle(self, node: QDomNode, doc: QDomDocument, errorMessage: str, context: QgsReadWriteContext, categories: Union[QgsMapLayer.StyleCategories, QgsMapLayer.StyleCategory] = QgsMapLayer.AllStyleCategories) → bool
Parameters
Return type

bool

writeStyleManager(self, layerNode: QDomNode, doc: QDomDocument)

Write style manager’s configuration (if exists). To be called by subclasses.

writeSymbology(self, node: QDomNode, doc: QDomDocument, errorMessage: str, context: QgsReadWriteContext, categories: Union[QgsMapLayer.StyleCategories, QgsMapLayer.StyleCategory] = QgsMapLayer.AllStyleCategories) → bool
Parameters
Return type

bool

writeXml(self, layer_node: QDomNode, doc: QDomDocument, context: QgsReadWriteContext) → bool
Parameters
Return type

bool