Qgs3DMapSettings class

3 Definition of the world

Reference

Constructors, destructors, conversion operators

Qgs3DMapSettings() defaulted: Constructor for Qgs3DMapSettings.
Qgs3DMapSettings(const Qgs3DMapSettings& other): Copy constructor.

Public functions

auto backgroundColor() const -> QColor: Returns background color of the 3D map view.
auto crs() const -> QgsCoordinateReferenceSystem: Returns coordinate reference system used in the 3D scene.
auto hasSkyboxEnabled() const -> bool: Returns whether skybox is enabled.
auto isTerrainShadingEnabled() const -> bool: Returns whether terrain shading is enabled.
auto layers() const -> QList<QgsMapLayer*>: Returns the list of map layers to be rendered as a texture of the terrain.
auto mapThemeCollection() const -> QgsMapThemeCollection*: Returns pointer to the collection of map themes.
auto mapTileResolution() const -> int: Returns resolution (in pixels) of the texture of a terrain tile.
auto mapToWorldCoordinates(const QgsVector3D& mapCoords) const -> QgsVector3D: Converts map coordinates to 3D world coordinates (applies offset and turns (x,y,z) into (x,-z,y))
auto maxTerrainGroundError() const -> float: Returns maximum ground error of terrain tiles in world units.
auto maxTerrainScreenError() const -> float: Returns maximum allowed screen error of terrain tiles in pixels.
auto origin() const -> QgsVector3D: Returns coordinates in map CRS at which 3D scene has origin (0,0,0)
auto pathResolver() const -> const QgsPathResolver&: Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g.
auto pointLights() const -> QList<QgsPointLightSettings>: Returns list of point lights defined in the scene.
void readXml(const QDomElement& elem, const QgsReadWriteContext& context): Reads configuration from a DOM element previously written by writeXml()
auto renderers() const -> QList<QgsAbstract3DRenderer*>: Returns list of extra 3D renderers.
void resolveReferences(const QgsProject& project): Resolves references to other objects (map layers) after the call to readXml()
auto selectionColor() const -> QColor: Returns color used for selected features.
void setBackgroundColor(const QColor& color): Sets background color of the 3D map view.
void setCrs(const QgsCoordinateReferenceSystem& crs): Sets coordinate reference system used in the 3D scene.
void setLayers(const QList<QgsMapLayer*>& layers): Sets the list of map layers to be rendered as a texture of the terrain.
void setMapThemeCollection(QgsMapThemeCollection* mapThemes): Sets pointer to the collection of map themes.
void setMapTileResolution(int res): Sets resolution (in pixels) of the texture of a terrain tile.
void setMaxTerrainGroundError(float error): Returns maximum ground error of terrain tiles in world units.
void setMaxTerrainScreenError(float error): Sets maximum allowed screen error of terrain tiles in pixels.
void setOrigin(const QgsVector3D& origin): Sets coordinates in map CRS at which our 3D world has origin (0,0,0)
void setPathResolver(const QgsPathResolver& resolver): Sets the path resolver for conversion between relative and absolute paths during rendering operations, e.g.
void setPointLights(const QList<QgsPointLightSettings>& pointLights): Sets list of point lights defined in the scene.
void setRenderers(const QList<QgsAbstract3DRenderer*>& renderers): Sets list of extra 3D renderers to use in the scene. Takes ownership of the objects.
void setSelectionColor(const QColor& color): Sets color used for selected features.
void setShowCameraViewCenter(bool enabled): Sets whether to show camera's view center as a sphere (for debugging)
void setShowLabels(bool enabled): Sets whether to display labels on terrain tiles.
void setShowTerrainBoundingBoxes(bool enabled): Sets whether to display bounding boxes of terrain tiles (for debugging)
void setShowTerrainTilesInfo(bool enabled): Sets whether to display extra tile info on top of terrain tiles (for debugging)
void setSkybox(bool enabled, const QString& fileBase = QString(), const QString& fileExtension = QString()): Sets skybox configuration.
void setTerrainGenerator(QgsTerrainGenerator* gen): Sets terrain generator.
void setTerrainMapTheme(const QString& theme): Sets name of the map theme.
void setTerrainShadingEnabled(bool enabled): Sets whether terrain shading is enabled.
void setTerrainShadingMaterial(const QgsPhongMaterialSettings& material): Sets terrain shading material.
void setTerrainVerticalScale(double zScale): Sets vertical scale (exaggeration) of terrain (1 = true scale, > 1 = hills get more pronounced)
void setTransformContext(const QgsCoordinateTransformContext& context): Sets the coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.
auto showCameraViewCenter() const -> bool: Returns whether to show camera's view center as a sphere (for debugging)
auto showLabels() const -> bool: Returns whether to display labels on terrain tiles.
auto showTerrainBoundingBoxes() const -> bool: Returns whether to display bounding boxes of terrain tiles (for debugging)
auto showTerrainTilesInfo() const -> bool: Returns whether to display extra tile info on top of terrain tiles (for debugging)
auto skyboxFileBase() const -> QString: Returns base part of filenames of skybox (see setSkybox())
auto skyboxFileExtension() const -> QString: Returns extension part of filenames of skybox (see setSkybox())
auto terrainGenerator() const -> QgsTerrainGenerator*: Returns terrain generator. It takes care of producing terrain tiles from the input data.
auto terrainMapTheme() const -> QString: Returns name of the map theme (from the active project) that will be used for terrain's texture.
auto terrainShadingMaterial() const -> QgsPhongMaterialSettings: Returns terrain shading material.
auto terrainVerticalScale() const -> double: Returns vertical scale (exaggeration) of terrain.
auto transformContext() const -> QgsCoordinateTransformContext: Returns the coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.
auto worldToMapCoordinates(const QgsVector3D& worldCoords) const -> QgsVector3D: Converts 3D world coordinates to map coordinates (applies offset and turns (x,y,z) into (x,-z,y))
auto writeXml(QDomDocument& doc, const QgsReadWriteContext& context) const -> QDomElement: Writes configuration to a DOM element, to be used later with readXml()

Signals

void backgroundColorChanged(): Emitted when the background color has changed.
void layersChanged(): Emitted when the list of map layers for terrain texture has changed.
void mapTileResolutionChanged(): Emitted when the map tile resoulution has changed.
void maxTerrainGroundErrorChanged(): Emitted when the maximum terrain ground error has changed.
void maxTerrainScreenErrorChanged(): Emitted when the maximum terrain screen error has changed.
void pointLightsChanged(): Emitted when the list of point lights changes.
void selectionColorChanged(): Emitted when the selection color has changed.
void showCameraViewCenterChanged(): Emitted when the flag whether camera's view center is shown has changed.
void showLabelsChanged(): Emitted when the flag whether labels are displayed on terrain tiles has changed.
void showTerrainBoundingBoxesChanged(): Emitted when the flag whether terrain's bounding boxes are shown has changed.
void showTerrainTilesInfoChanged(): Emitted when the flag whether terrain's tile info is shown has changed.
void terrainGeneratorChanged(): Emitted when the terrain generator has changed.
void terrainMapThemeChanged(): Emitted when terrain's map theme has changed.
void terrainShadingChanged(): Emitted when terrain shading enabled flag or terrain shading material has changed.
void terrainVerticalScaleChanged(): Emitted when the vertical scale of the terrain has changed.

Function documentation

bool Qgs3DMapSettings::isTerrainShadingEnabled() const

Returns whether terrain shading is enabled.

When enabled, in addition to the terrain texture generated from the map, the terrain rendering will take into account position of the lights, terrain normals and terrain shading material (ambient and specular colors, shininess).

QList<QgsMapLayer*> Qgs3DMapSettings::layers() const

Returns the list of map layers to be rendered as a texture of the terrain.

QgsMapThemeCollection* Qgs3DMapSettings::mapThemeCollection() const

Returns pointer to the collection of map themes.

Normally this would be QgsProject::mapThemeCollection() of the currently used project. Without a valid map theme collection object it is not possible to resolve map themes from their names.

int Qgs3DMapSettings::mapTileResolution() const

Returns resolution (in pixels) of the texture of a terrain tile.

This parameter influences how many zoom levels for terrain tiles there will be (together with maxTerrainGroundError())

float Qgs3DMapSettings::maxTerrainGroundError() const

Returns maximum ground error of terrain tiles in world units.

This parameter influences how many zoom levels there will be (together with mapTileResolution()). This value tells that when the given ground error is reached (e.g. 10 meters), it makes no sense to further split terrain tiles into finer ones because they will not add extra details anymore.

float Qgs3DMapSettings::maxTerrainScreenError() const

Returns maximum allowed screen error of terrain tiles in pixels.

This parameter decides how aggressively less detailed terrain tiles are swapped to more detailed ones as camera gets closer. Each tile has its error defined in world units - this error gets projected to screen pixels according to camera view and if the tile's error is greater than the allowed error, it will be swapped by more detailed tiles with lower error.

const QgsPathResolver& Qgs3DMapSettings::pathResolver() const

Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g.

for resolving relative symbol paths.

QList<QgsPointLightSettings> Qgs3DMapSettings::pointLights() const

Returns list of point lights defined in the scene.

void Qgs3DMapSettings::setLayers(const QList<QgsMapLayer*>& layers)

Sets the list of map layers to be rendered as a texture of the terrain.

void Qgs3DMapSettings::setMapThemeCollection(QgsMapThemeCollection* mapThemes)

Sets pointer to the collection of map themes.

void Qgs3DMapSettings::setMapTileResolution(int res)

Sets resolution (in pixels) of the texture of a terrain tile.

void Qgs3DMapSettings::setMaxTerrainGroundError(float error)

Returns maximum ground error of terrain tiles in world units.

void Qgs3DMapSettings::setMaxTerrainScreenError(float error)

Sets maximum allowed screen error of terrain tiles in pixels.

void Qgs3DMapSettings::setOrigin(const QgsVector3D& origin)

Sets coordinates in map CRS at which our 3D world has origin (0,0,0)

We move the 3D world origin to the center of the extent of our terrain: this is done to minimize the impact of numerical errors when operating with 32-bit floats. Unfortunately this is not enough when working with a large area (still results in jitter with scenes spanning hundreds of kilometers and zooming in a lot).

Need to look into more advanced techniques like "relative to center" or "relative to eye" to improve the precision.

void Qgs3DMapSettings::setPathResolver(const QgsPathResolver& resolver)

Sets the path resolver for conversion between relative and absolute paths during rendering operations, e.g.

for resolving relative symbol paths.

void Qgs3DMapSettings::setPointLights(const QList<QgsPointLightSettings>& pointLights)

Sets list of point lights defined in the scene.

void Qgs3DMapSettings::setShowCameraViewCenter(bool enabled)

Sets whether to show camera's view center as a sphere (for debugging)

void Qgs3DMapSettings::setSkybox(bool enabled, const QString& fileBase = QString(), const QString& fileExtension = QString())

Sets skybox configuration.

When enabled, map scene will try to load six texture files using the following syntax of filenames: "[base]_[side][extension]" where [side] is one of the following: posx/posy/posz/negx/negy/negz and [base] and [extension] are the arguments passed this method.

void Qgs3DMapSettings::setTerrainGenerator(QgsTerrainGenerator* gen)

Sets terrain generator.

It takes care of producing terrain tiles from the input data. Takes ownership of the generator

void Qgs3DMapSettings::setTerrainMapTheme(const QString& theme)

Sets name of the map theme.

void Qgs3DMapSettings::setTerrainShadingEnabled(bool enabled)

Sets whether terrain shading is enabled.

void Qgs3DMapSettings::setTerrainShadingMaterial(const QgsPhongMaterialSettings& material)

Sets terrain shading material.

void Qgs3DMapSettings::setTransformContext(const QgsCoordinateTransformContext& context)

Sets the coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.

bool Qgs3DMapSettings::showCameraViewCenter() const

Returns whether to show camera's view center as a sphere (for debugging)

QString Qgs3DMapSettings::terrainMapTheme() const

Returns name of the map theme (from the active project) that will be used for terrain's texture.

Empty map theme name means that the map theme is not overridden and the current map theme will be used.

QgsPhongMaterialSettings Qgs3DMapSettings::terrainShadingMaterial() const

Returns terrain shading material.

Diffuse color component is ignored since the diffuse component is provided by 2D rendered map texture. Only used when isTerrainShadingEnabled() is true.

QgsCoordinateTransformContext Qgs3DMapSettings::transformContext() const

Returns the coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.

void Qgs3DMapSettings::pointLightsChanged() signal

Emitted when the list of point lights changes.

void Qgs3DMapSettings::showCameraViewCenterChanged() signal

Emitted when the flag whether camera's view center is shown has changed.

void Qgs3DMapSettings::terrainMapThemeChanged() signal

Emitted when terrain's map theme has changed.

void Qgs3DMapSettings::terrainShadingChanged() signal

Emitted when terrain shading enabled flag or terrain shading material has changed.