QgsRasterDataProvider class

Base class for raster data providers.

Contents

Base classes

class QgsDataProvider
Abstract base class for spatial data provider implementations.
class QgsRasterInterface
Base class for processing filters like renderers, reprojector, resampler etc.

Public types

enum ProviderCapability { NoProviderCapabilities = 0, ReadLayerMetadata = 1 << 1, WriteLayerMetadata = 1 << 2 }
Enumeration with capabilities that raster providers might implement.

Public static functions

static auto create(const QString& providerKey, const QString& uri, const QString& format, int nBands, Qgis::DataType type, int width, int height, double* geoTransform, const QgsCoordinateReferenceSystem& crs, const QStringList& createOptions = QStringList()) -> QgsRasterDataProvider*
Creates a new dataset with mDataSourceURI.
static auto pyramidResamplingMethods(const QString& providerKey) -> QList<QPair<QString, QString>>
Returns a list of pyramid resampling method name and label pairs for given provider.

Constructors, destructors, conversion operators

QgsRasterDataProvider()
Provider capabilities.
QgsRasterDataProvider(const QString& uri, const QgsDataProvider::ProviderOptions& options = QgsDataProvider::ProviderOptions())
Constructor for QgsRasterDataProvider.

Public functions

auto bandOffset(int bandNo) const -> double virtual
Read band offset for raster value.
auto bandScale(int bandNo) const -> double virtual
Read band scale for raster value.
auto block(int bandNo, const QgsRectangle& boundingBox, int width, int height, QgsRasterBlockFeedback* feedback = nullptr) -> QgsRasterBlock* override
Read block of data using given extent and size.
auto buildPyramidList(QList<int> overviewList = QList<int>()) -> QList<QgsRasterPyramid> virtual
Returns the raster layers pyramid list.
auto buildPyramids(const QList<QgsRasterPyramid>& pyramidList, const QString& resamplingMethod = "NEAREST", QgsRaster::RasterPyramidsFormat format = QgsRaster::PyramidsGTiff, const QStringList& configOptions = QStringList(), QgsRasterBlockFeedback* feedback = nullptr) -> QString virtual
Create pyramid overviews.
auto clone() const -> QgsRasterInterface* override
Clone itself, create deep copy.
auto colorInterpretation(int bandNo) const -> int virtual
Returns data type for the band specified by number.
auto dataTimestamp() const -> QDateTime override
Current time stamp of data source.
auto dataType(int bandNo) const -> Qgis::DataType override
Returns data type for the band specified by number.
auto dpi() const -> int
Returns the dpi of the output device.
auto extent() const -> QgsRectangle override
Returns the extent of the layer.
auto getLegendGraphic(double scale = 0, bool forceRefresh = false, const QgsRectangle* visibleExtent = nullptr) -> QImage virtual
Returns the legend rendered as pixmap.
auto getLegendGraphicFetcher(const QgsMapSettings* mapSettings) -> QgsImageFetcher* virtual
Returns a new image downloader for the raster legend.
auto hasPyramids() -> bool
Returns true if raster has at least one populated histogram.
auto htmlMetadata() -> QString pure virtual
Returns metadata in a format suitable for feeding directly into a subset of the GUI raster properties "Metadata" tab.
auto identify(const QgsPointXY& point, QgsRaster::IdentifyFormat format, const QgsRectangle& boundingBox = QgsRectangle(), int width = 0, int height = 0, int dpi = 96) -> QgsRasterIdentifyResult virtual
Identify raster value(s) found on the point position.
auto isEditable() const -> bool virtual
Checks whether the provider is in editing mode, i.e.
auto lastError() -> QString pure virtual
Returns the verbose error text for the last error in this provider.
auto lastErrorFormat() -> QString virtual
Returns the format of the error text for the last error in this provider.
auto lastErrorTitle() -> QString pure virtual
Returns the caption error text for the last error in this provider.
auto providerCapabilities() const -> QgsRasterDataProvider::ProviderCapabilities virtual
Returns flags containing the supported capabilities of the data provider.
auto reload() -> bool virtual
Reload data (data could change)
auto remove() -> bool virtual
Remove dataset.
auto sample(const QgsPointXY& point, int band, bool* ok = nullptr, const QgsRectangle& boundingBox = QgsRectangle(), int width = 0, int height = 0, int dpi = 96) -> double virtual
Samples a raster value from the specified band found at the point position.
void setDpi(int dpi)
Sets the output device resolution.
auto setEditable(bool enabled) -> bool virtual
Turns on/off editing mode of the provider.
auto setInput(QgsRasterInterface* input) -> bool override
Set input.
auto setNoDataValue(int bandNo, double noDataValue) -> bool virtual
Set no data value on created dataset.
void setUseSourceNoDataValue(int bandNo, bool use) virtual
Sets the source nodata value usage.
auto sourceDataType(int bandNo) const -> Qgis::DataType override
Returns source data type for the band specified by number, source data type may be shorter than dataType.
auto sourceHasNoDataValue(int bandNo) const -> bool virtual
Returns true if source band has no data value.
auto sourceNoDataValue(int bandNo) const -> double virtual
Value representing no data value.
auto stepHeight() const -> int virtual
Step height for raster iterations.
auto stepWidth() const -> int virtual
Step width for raster iterations.
auto subLayers() const -> QStringList override
Returns the sublayers of this layer - useful for providers that manage their own layers, such as WMS.
auto supportsLegendGraphic() const -> bool virtual
Returns whether the provider supplies a legend graphic.
auto timestamp() const -> QDateTime override
Time stamp of data source in the moment when data/metadata were loaded by provider.
auto userNoDataValues(int bandNo) const -> QgsRasterRangeList virtual
Returns a list of user no data value ranges.
auto useSourceNoDataValue(int bandNo) const -> bool virtual
Returns the source nodata value usage.
auto validateCreationOptions(const QStringList& createOptions, const QString& format) -> QString virtual
Validates creation options for a specific dataset and destination format.
auto validatePyramidsConfigOptions(QgsRaster::RasterPyramidsFormat pyramidsFormat, const QStringList& configOptions, const QString& fileFormat) -> QString virtual
Validates pyramid creation options for a specific dataset and destination format.
auto write(void* data, int band, int width, int height, int xOffset, int yOffset) -> bool virtual
Writes into the provider datasource.
auto writeBlock(QgsRasterBlock* block, int band, int xOffset = 0, int yOffset = 0) -> bool
Writes pixel data from a raster block into the provider data source.

Signals

void statusChanged(const QString&) const
Emit a message to be displayed on status bar, usually used by network providers (WMS,WCS)

Protected functions

void copyBaseSettings(const QgsRasterDataProvider& other)
Copy member variables from other raster data provider. Useful for implementation of clone() method in subclasses.
void readBlock(int bandNo, int xBlock, int yBlock, void* data) virtual
Read block of data.
void readBlock(int bandNo, QgsRectangle const& viewExtent, int width, int height, void* data, QgsRasterBlockFeedback* feedback = nullptr) virtual
Read block of data using give extent and size.
auto userNoDataValuesContains(int bandNo, double value) const -> bool
Returns true if user no data contains value.

Protected variables

int mDpi
Dots per inch.
QList<bool> mSrcHasNoDataValue
Source no data value exists.
QList<double> mSrcNoDataValue
Source no data value is available and is set to be used or internal no data is available.
QList<QgsRasterRangeList> mUserNoDataValue
List of lists of user defined additional no data values for each band, indexed from 0.
QList<bool> mUseSrcNoDataValue
Use source nodata value.

Enum documentation

enum QgsRasterDataProvider::ProviderCapability

Enumeration with capabilities that raster providers might implement.

Enumerators
NoProviderCapabilities

Provider has no capabilities.
ReadLayerMetadata

Provider can read layer metadata from data store. Since QGIS 3.0. See QgsDataProvider::layerMetadata()
WriteLayerMetadata

Provider can write layer metadata to the data store. Since QGIS 3.0. See QgsDataProvider::writeLayerMetadata()

Function documentation

QgsRasterDataProvider::QgsRasterDataProvider(const QString& uri, const QgsDataProvider::ProviderOptions& options = QgsDataProvider::ProviderOptions())

Constructor for QgsRasterDataProvider.

The uri argument gives a provider-specific uri indicating the underlying data source and it's parameters.

The options argument specifies generic provider options.

double QgsRasterDataProvider::bandOffset(int bandNo) const virtual

Read band offset for raster value.

double QgsRasterDataProvider::bandScale(int bandNo) const virtual

Read band scale for raster value.

QList<QgsRasterPyramid> QgsRasterDataProvider::buildPyramidList(QList<int> overviewList = QList<int>()) virtual

Returns the raster layers pyramid list.

Parameters
overviewList used to construct the pyramid list (optional), when empty the list is defined by the provider. A pyramid list defines the POTENTIAL pyramids that can be in a raster. To know which of the pyramid layers ACTUALLY exists you need to look at the existsFlag member in each struct stored in the list.

QgsRectangle QgsRasterDataProvider::extent() const override

Returns the extent of the layer.

Returns QgsRectangle containing the extent of the layer

QImage QgsRasterDataProvider::getLegendGraphic(double scale = 0, bool forceRefresh = false, const QgsRectangle* visibleExtent = nullptr) virtual

Returns the legend rendered as pixmap.

Parameters
scale Optional parameter that is the Scale of the layer
forceRefresh Optional bool parameter to force refresh getLegendGraphic call
visibleExtent Visible extent for providers supporting contextual legends, in layer CRS

This is useful for layers which need to get legend layers remotely as WMS.

QgsImageFetcher* QgsRasterDataProvider::getLegendGraphicFetcher(const QgsMapSettings* mapSettings) virtual

Returns a new image downloader for the raster legend.

Parameters
mapSettings map settings for legend providers supporting contextual legends.
Returns a download handler or null if the provider does not support legend at all. Ownership of the returned object is transferred to caller.

QgsRasterIdentifyResult QgsRasterDataProvider::identify(const QgsPointXY& point, QgsRaster::IdentifyFormat format, const QgsRectangle& boundingBox = QgsRectangle(), int width = 0, int height = 0, int dpi = 96) virtual

Identify raster value(s) found on the point position.

Parameters
point coordinates in data source CRS
format result format
boundingBox context bounding box
width context width
height context height
dpi context dpi
Returns QgsRaster::IdentifyFormatValue: map of values for each band, keys are band numbers (from 1). QgsRaster::IdentifyFormatFeature: map of QgsRasterFeatureList for each sublayer (WMS) - TODO: it is not consistent with QgsRaster::IdentifyFormatValue. QgsRaster::IdentifyFormatHtml: map of HTML strings for each sublayer (WMS). Empty if failed or there are no results (TODO: better error reporting).

The context parameters extent, width and height are important to identify on the same zoom level as a displayed map and to do effective caching (WCS). If context params are not specified the highest resolution is used. capabilities() may be used to test if format is supported by provider. Values are set to 'no data' or empty string if point is outside data source extent.

bool QgsRasterDataProvider::isEditable() const virtual

Checks whether the provider is in editing mode, i.e.

raster write operations will be accepted. By default providers are not editable. Use setEditable() method to enable/disable editing.

QString QgsRasterDataProvider::lastError() pure virtual

Returns the verbose error text for the last error in this provider.

If an operation returns 0 (e.g. draw()), this function returns the text of the error associated with the failure. Interactive users of this provider can then, for example, call a QMessageBox to display the contents.

QString QgsRasterDataProvider::lastErrorTitle() pure virtual

Returns the caption error text for the last error in this provider.

If an operation returns 0 (e.g. draw()), this function returns the text of the error associated with the failure. Interactive users of this provider can then, for example, call a QMessageBox to display the contents.

QgsRasterDataProvider::ProviderCapabilities QgsRasterDataProvider::providerCapabilities() const virtual

Returns flags containing the supported capabilities of the data provider.

double QgsRasterDataProvider::sample(const QgsPointXY& point, int band, bool* ok = nullptr, const QgsRectangle& boundingBox = QgsRectangle(), int width = 0, int height = 0, int dpi = 96) virtual

Samples a raster value from the specified band found at the point position.

The context parameters boundingBox, width and height are important to identify on the same zoom level as a displayed map and to do effective caching (WCS). If context params are not specified the highest resolution is used.

If ok is specified and the point is outside data source extent, or an invalid band number was specified, then ok will be set to false. In this case the function will return a NaN value.

bool QgsRasterDataProvider::setEditable(bool enabled) virtual

Turns on/off editing mode of the provider.

Returns true if the switch to/from editing mode was successful

When in editing mode, it is possible to overwrite data of the provider using writeBlock() calls.

bool QgsRasterDataProvider::setInput(QgsRasterInterface* input) override

Set input.

Returns true if set correctly, false if cannot use that input

bool QgsRasterDataProvider::setNoDataValue(int bandNo, double noDataValue) virtual

Set no data value on created dataset.

Parameters
bandNo band number
noDataValue no data value

int QgsRasterDataProvider::stepHeight() const virtual

Step height for raster iterations.

int QgsRasterDataProvider::stepWidth() const virtual

Step width for raster iterations.

QString QgsRasterDataProvider::validateCreationOptions(const QStringList& createOptions, const QString& format) virtual

Validates creation options for a specific dataset and destination format.

QString QgsRasterDataProvider::validatePyramidsConfigOptions(QgsRaster::RasterPyramidsFormat pyramidsFormat, const QStringList& configOptions, const QString& fileFormat) virtual

Validates pyramid creation options for a specific dataset and destination format.

bool QgsRasterDataProvider::writeBlock(QgsRasterBlock* block, int band, int xOffset = 0, int yOffset = 0)

Writes pixel data from a raster block into the provider data source.

Returns true on success

This will override previously stored pixel values. It is assumed that cells in the passed raster block are aligned with the cells of the data source. If raster block does not cover the whole area of the data source, only a subset of pixels covered by the raster block will be overwritten. By default, writing of raster data starts from the first cell of the raster - it is possible to set offset in pixels by specifying non-zero xOffset and yOffset values.

Writing is supported only by some data providers. Provider has to be in editing mode in order to allow write operations.

void QgsRasterDataProvider::statusChanged(const QString&) const signal

Emit a message to be displayed on status bar, usually used by network providers (WMS,WCS)

void QgsRasterDataProvider::readBlock(int bandNo, int xBlock, int yBlock, void* data) virtual protected

Read block of data.

void QgsRasterDataProvider::readBlock(int bandNo, QgsRectangle const& viewExtent, int width, int height, void* data, QgsRasterBlockFeedback* feedback = nullptr) virtual protected

Read block of data using give extent and size.

Variable documentation

int QgsRasterDataProvider::mDpi protected

Dots per inch.

Extended WMS (e.g. QGIS mapserver) support DPI dependent output and therefore are suited for printing. A value of -1 means it has not been set

QList<double> QgsRasterDataProvider::mSrcNoDataValue protected

Source no data value is available and is set to be used or internal no data is available.

Used internally only Cell value representing original source no data. e.g. -9999, indexed from 0

QList<bool> QgsRasterDataProvider::mUseSrcNoDataValue protected

Use source nodata value.

User can disable usage of source nodata value as nodata. It may happen that a value is wrongly given by GDAL as nodata (e.g. 0) and it has to be treated as regular value.