QgsElevationMap Class Reference

Stores digital elevation model in a raster image which may get updated as a part of map layer rendering process. More...

#include <qgselevationmap.h>

Public Member Functions
	QgsElevationMap ()=default
	QgsElevationMap (const QgsElevationMap &other)
	QgsElevationMap (const QImage &image)
	Constructs an elevation map from an existing raw elevation image.
	QgsElevationMap (const QSize &size, float devicePixelRatio=1.0)
	Constructs an elevation map with the given width and height.
void	applyEyeDomeLighting (QImage &image, int distance, float strength, float rendererScale) const
	Applies eye dome lighting effect to the given image.
void	applyHillshading (QImage &image, bool multiDirectional, double altitude, double azimuth, double zFactor, double cellSizeX, double cellSizeY) const
	Applies hill shading effect to the given image.
void	combine (const QgsElevationMap &otherElevationMap, Qgis::ElevationMapCombineMethod method)
	Combines this elevation map with otherElevationMap.
void	fillWithRasterBlock (QgsRasterBlock *block, int top, int left, double zScale=1.0, double offset=0.0)
	Fills the elevation map with values contains in a raster block starting from position defined by top and left.
bool	isNoData (QRgb colorRaw) const
	Returns whether the encoded value is a no data value.
bool	isValid () const
	Returns whether the elevation map is valid.
float	noDataValue () const
	Returns the no data value for the elevation map.
QgsElevationMap &	operator= (const QgsElevationMap &other)
QPainter *	painter () const
	Returns painter to the underlying QImage with elevations.
QImage	rawElevationImage () const
	Returns raw elevation image with elevations encoded as color values.
QRgb *	rawElevationImageData ()
	Returns pointer to the actual elevation image data.

Static Public Member Functions
static float	decodeElevation (QRgb colorRaw)
	Converts a color back to elevation value.
static QRgb	encodeElevation (float z)
	Converts elevation value to an actual color.
static std::unique_ptr< QgsElevationMap >	fromRasterBlock (QgsRasterBlock *block)
	Creates an elevation map based on data from the given raster block.

Detailed Description

Stores digital elevation model in a raster image which may get updated as a part of map layer rendering process.

Afterwards the elevations can be used for post-processing effects of the rendered color map image.

Elevations are encoded as colors in QImage, thanks to this it is not only possible to set elevation for each pixel, but also to use QPainter for more complex updates of elevations. We encode elevations to 24 bits in range of [-7900, 8877] with precision of three decimal digits, which should give millimiter precision and enough range for elevation values in meters.

Since

QGIS 3.28

Definition at line 44 of file qgselevationmap.h.

Constructor & Destructor Documentation

QgsElevationMap() [1/4]

QgsElevationMap::QgsElevationMap ( )

default

QgsElevationMap() [2/4]

QgsElevationMap::QgsElevationMap ( const QSize &  size, float  devicePixelRatio = 1.0  )

explicit

Constructs an elevation map with the given width and height.

Definition at line 29 of file qgselevationmap.cpp.

QgsElevationMap() [3/4]

QgsElevationMap::QgsElevationMap ( const QImage &  image )

explicit

Constructs an elevation map from an existing raw elevation image.

The image must have ARGB32 format and obtained by the rawElevationImage() method.

See also

rawElevationImage()

Since

QGIS 3.30

Definition at line 36 of file qgselevationmap.cpp.

QgsElevationMap() [4/4]

QgsElevationMap::QgsElevationMap

(

const QgsElevationMap &

other

)

Definition at line 40 of file qgselevationmap.cpp.

Member Function Documentation

applyEyeDomeLighting()

void QgsElevationMap::applyEyeDomeLighting	(	QImage &	image,
		int	distance,
		float	strength,
		float	rendererScale
	)		const

Applies eye dome lighting effect to the given image.

The effect makes angled surfaces darker and adds silhouettes in case of larger differences of elevations between neighboring pixels.

The distance parameter tells how many pixels away from the original pixel to sample neighboring pixels. Normally distance of 2 pixels gives good results.

The strength parameter adjusts how strong the added shading will be. Good default for this value seems to be 1000.

The rendererScale parameter adjusts scale of elevation values. It is recommended to set this to the map's scale denominator to get similarly looking results at different map scales.

Definition at line 84 of file qgselevationmap.cpp.

applyHillshading()

void QgsElevationMap::applyHillshading	(	QImage &	image,
		bool	multiDirectional,
		double	altitude,
		double	azimuth,
		double	zFactor,
		double	cellSizeX,
		double	cellSizeY
	)		const

Applies hill shading effect to the given image.

If the multidirectinal parameter is true, the algorithm will considered a multi horizontal directional light to apply the shading.

The parameter altitude (could also be named zenith) is the vertical direction of the light.

The parameter azimuth is the horizontal direction of the light considered if multidirectional is false.

The parameter zFactor is the vertical exageration of the terrain.

The parameters cellSizeX and cellSizeY are the sizes of the elevation map cells in unit consistent with the unit of the encoded elevation in this elevation map.

Since

QGIS 3.30

Definition at line 173 of file qgselevationmap.cpp.

combine()

void QgsElevationMap::combine	(	const QgsElevationMap &	otherElevationMap,
		Qgis::ElevationMapCombineMethod	method
	)

Combines this elevation map with otherElevationMap.

This elevation map keeps its size and takes elevation values of otherElevationMap that is not null for same row and column following the combine method. The other elevation map can have a different size, only rows and columns contained in this elevation map will be considered.

Since

QGIS 3.30

Definition at line 335 of file qgselevationmap.cpp.

decodeElevation()

float QgsElevationMap::decodeElevation ( QRgb  colorRaw )

static

Converts a color back to elevation value.

Definition at line 53 of file qgselevationmap.cpp.

encodeElevation()

QRgb QgsElevationMap::encodeElevation ( float  z )

static

Converts elevation value to an actual color.

Definition at line 46 of file qgselevationmap.cpp.

fillWithRasterBlock()

void QgsElevationMap::fillWithRasterBlock	(	QgsRasterBlock *	block,
		int	top,
		int	left,
		double	zScale = 1.0,
		double	offset = 0.0
	)

Fills the elevation map with values contains in a raster block starting from position defined by top and left.

The z scale zScale and vertical offset are applied if provided.

Definition at line 381 of file qgselevationmap.cpp.

fromRasterBlock()

std::unique_ptr< QgsElevationMap > QgsElevationMap::fromRasterBlock ( QgsRasterBlock *  block )

static

Creates an elevation map based on data from the given raster block.

Definition at line 59 of file qgselevationmap.cpp.

isNoData()

bool QgsElevationMap::isNoData ( QRgb  colorRaw ) const

inline

Returns whether the encoded value is a no data value.

Definition at line 149 of file qgselevationmap.h.

isValid()

bool QgsElevationMap::isValid

(

)

const

Returns whether the elevation map is valid.

Since

QGIS 3.30

Definition at line 376 of file qgselevationmap.cpp.

noDataValue()

float QgsElevationMap::noDataValue ( ) const

inline

Returns the no data value for the elevation map.

Definition at line 152 of file qgselevationmap.h.

operator=()

QgsElevationMap & QgsElevationMap::operator=

(

const QgsElevationMap &

other

)

Definition at line 77 of file qgselevationmap.cpp.

painter()

QPainter * QgsElevationMap::painter

(

)

const

Returns painter to the underlying QImage with elevations.

Definition at line 324 of file qgselevationmap.cpp.

rawElevationImage()

QImage QgsElevationMap::rawElevationImage ( ) const

inline

Returns raw elevation image with elevations encoded as color values.

Definition at line 102 of file qgselevationmap.h.

rawElevationImageData()

QRgb * QgsElevationMap::rawElevationImageData ( )

inline

Returns pointer to the actual elevation image data.

Since

QGIS 3.36

Definition at line 110 of file qgselevationmap.h.

---

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

• /build/qgis-3.41.0+git20241119+45a0abf3bec+99sid/src/core/qgselevationmap.h
• /build/qgis-3.41.0+git20241119+45a0abf3bec+99sid/src/core/qgselevationmap.cpp