Class: Qgs3DMapSettings

class qgis.3d.Qgs3DMapSettings

Bases: PyQt5.QtCore.QObject, QgsTemporalRangeObject

Constructor for Qgs3DMapSettings

Qgs3DMapSettings(other: Qgs3DMapSettings) Copy constructor

Definition of the world

Methods

backgroundColor

Returns background color of the 3D map view

childEvent

connectNotify

crs

Returns coordinate reference system used in the 3D scene

customEvent

disconnectNotify

fieldOfView

Returns the camera lens’ field of view

hasSkyboxEnabled

Returns whether skybox is enabled

isSignalConnected

isTerrainShadingEnabled

Returns whether terrain shading is enabled.

layers

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

mapThemeCollection

Returns pointer to the collection of map themes.

mapTileResolution

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

mapToWorldCoordinates

Converts map coordinates to 3D world coordinates (applies offset and turns (x,y,z) into (x,-z,y))

maxTerrainGroundError

Returns maximum ground error of terrain tiles in world units.

maxTerrainScreenError

Returns maximum allowed screen error of terrain tiles in pixels.

origin

Returns coordinates in map CRS at which 3D scene has origin (0,0,0)

outputDpi

Returns DPI used for conversion between real world units (e.g.

pathResolver

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

pointLights

Returns list of point lights defined in the scene

readXml

Reads configuration from a DOM element previously written by writeXml()

receivers

renderers

Returns list of extra 3D renderers

resolveReferences

Resolves references to other objects (map layers) after the call to readXml()

selectionColor

Returns color used for selected features

sender

senderSignalIndex

setBackgroundColor

Sets background color of the 3D map view

setCrs

Sets coordinate reference system used in the 3D scene

setFieldOfView

Sets the camera lens’ field of view

setLayers

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

setMapThemeCollection

Sets pointer to the collection of map themes.

setMapTileResolution

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

setMaxTerrainGroundError

Returns maximum ground error of terrain tiles in world units.

setMaxTerrainScreenError

Sets maximum allowed screen error of terrain tiles in pixels.

setOrigin

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

setOutputDpi

Sets DPI used for conversion between real world units (e.g.

setPathResolver

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

setPointLights

Sets list of point lights defined in the scene

setRenderers

Sets list of extra 3D renderers to use in the scene.

setSelectionColor

Sets color used for selected features

setShowCameraViewCenter

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

setShowLabels

Sets whether to display labels on terrain tiles

setShowTerrainBoundingBoxes

Sets whether to display bounding boxes of terrain tiles (for debugging)

setShowTerrainTilesInfo

Sets whether to display extra tile info on top of terrain tiles (for debugging)

setSkybox

Sets skybox configuration.

setTerrainMapTheme

Sets name of the map theme.

setTerrainShadingEnabled

Sets whether terrain shading is enabled.

setTerrainShadingMaterial

Sets terrain shading material.

setTerrainVerticalScale

Sets vertical scale (exaggeration) of terrain (1 = true scale, > 1 = hills get more pronounced)

setTransformContext

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.

showCameraViewCenter

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

showLabels

Returns whether to display labels on terrain tiles

showTerrainBoundingBoxes

Returns whether to display bounding boxes of terrain tiles (for debugging)

showTerrainTilesInfo

Returns whether to display extra tile info on top of terrain tiles (for debugging)

skyboxFileBase

Returns base part of filenames of skybox (see setSkybox())

skyboxFileExtension

Returns extension part of filenames of skybox (see setSkybox())

terrainMapTheme

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

terrainShadingMaterial

Returns terrain shading material.

terrainVerticalScale

Returns vertical scale (exaggeration) of terrain

timerEvent

transformContext

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.

worldToMapCoordinates

Converts 3D world coordinates to map coordinates (applies offset and turns (x,y,z) into (x,-z,y))

writeXml

Writes configuration to a DOM element, to be used later with readXml()

Signals

backgroundColorChanged

Emitted when the background color has changed [signal]

fieldOfViewChanged

Emitted when the camera lens field of view changes

layersChanged

Emitted when the list of map layers for terrain texture has changed [signal]

mapTileResolutionChanged

Emitted when the map tile resoulution has changed [signal]

maxTerrainGroundErrorChanged

Emitted when the maximum terrain ground error has changed [signal]

maxTerrainScreenErrorChanged

Emitted when the maximum terrain screen error has changed [signal]

pointLightsChanged

Emitted when the list of point lights changes

renderersChanged

Emitted when the list of map’s extra renderers have been modified

selectionColorChanged

Emitted when the selection color has changed [signal]

showCameraViewCenterChanged

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

showLabelsChanged

Emitted when the flag whether labels are displayed on terrain tiles has changed [signal]

showTerrainBoundingBoxesChanged

Emitted when the flag whether terrain’s bounding boxes are shown has changed [signal]

showTerrainTilesInfoChanged

Emitted when the flag whether terrain’s tile info is shown has changed [signal]

terrainGeneratorChanged

Emitted when the terrain generator has changed [signal]

terrainMapThemeChanged

Emitted when terrain’s map theme has changed

terrainShadingChanged

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

terrainVerticalScaleChanged

Emitted when the vertical scale of the terrain has changed [signal]

backgroundColor(self) → QColor

Returns background color of the 3D map view

Return type

QColor

backgroundColorChanged

Emitted when the background color has changed [signal]

childEvent()
connectNotify()
crs(self)QgsCoordinateReferenceSystem

Returns coordinate reference system used in the 3D scene

Return type

QgsCoordinateReferenceSystem

customEvent()
disconnectNotify()
fieldOfView(self) → float

Returns the camera lens’ field of view

New in version 3.8.

Return type

float

fieldOfViewChanged

Emitted when the camera lens field of view changes

New in version 3.8: [signal]

hasSkyboxEnabled(self) → bool

Returns whether skybox is enabled

Return type

bool

isSignalConnected()
isTerrainShadingEnabled(self) → bool

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).

New in version 3.6.

Return type

bool

layers(self) → List[QgsMapLayer]

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

Note

If terrain map theme is set, it has a priority over the list of layers specified here.

Return type

List[QgsMapLayer]

layersChanged

Emitted when the list of map layers for terrain texture has changed [signal]

mapThemeCollection(self)QgsMapThemeCollection

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.

New in version 3.6.

Return type

QgsMapThemeCollection

mapTileResolution(self) → int

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())

Return type

int

mapTileResolutionChanged

Emitted when the map tile resoulution has changed [signal]

mapToWorldCoordinates(self, mapCoords: QgsVector3D)QgsVector3D

Converts map coordinates to 3D world coordinates (applies offset and turns (x,y,z) into (x,-z,y))

Parameters

mapCoords (QgsVector3D) –

Return type

QgsVector3D

maxTerrainGroundError(self) → float

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.

Return type

float

maxTerrainGroundErrorChanged

Emitted when the maximum terrain ground error has changed [signal]

maxTerrainScreenError(self) → float

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.

Return type

float

maxTerrainScreenErrorChanged

Emitted when the maximum terrain screen error has changed [signal]

origin(self)QgsVector3D

Returns coordinates in map CRS at which 3D scene has origin (0,0,0)

Return type

QgsVector3D

outputDpi(self) → float

Returns DPI used for conversion between real world units (e.g. mm) and pixels Default value is 96

New in version 3.10.

Return type

float

pathResolver(self)QgsPathResolver

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

New in version 3.0.

Return type

QgsPathResolver

pointLights(self) → List[QgsPointLightSettings]

Returns list of point lights defined in the scene

New in version 3.6.

Return type

List[QgsPointLightSettings]

pointLightsChanged

Emitted when the list of point lights changes

New in version 3.6: [signal]

readXml(self, elem: QDomElement, context: QgsReadWriteContext)

Reads configuration from a DOM element previously written by writeXml()

Parameters
receivers()
renderers(self) → List[QgsAbstract3DRenderer]

Returns list of extra 3D renderers

Return type

List[QgsAbstract3DRenderer]

renderersChanged

Emitted when the list of map’s extra renderers have been modified

New in version 3.10: [signal]

resolveReferences(self, project: QgsProject)

Resolves references to other objects (map layers) after the call to readXml()

Parameters

project (QgsProject) –

selectionColor(self) → QColor

Returns color used for selected features

Return type

QColor

selectionColorChanged

Emitted when the selection color has changed [signal]

sender()
senderSignalIndex()
setBackgroundColor(self, color: Union[QColor, Qt.GlobalColor])

Sets background color of the 3D map view

Parameters

color (Union[QColor) –

setCrs(self, crs: QgsCoordinateReferenceSystem)

Sets coordinate reference system used in the 3D scene

Parameters

crs (QgsCoordinateReferenceSystem) –

setFieldOfView(self, fieldOfView: float)

Sets the camera lens’ field of view

New in version 3.8.

Parameters

fieldOfView (float) –

setLayers(self, layers: Iterable[QgsMapLayer])

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

Note

If terrain map theme is set, it has a priority over the list of layers specified here.

Parameters

layers (Iterable[QgsMapLayer]) –

setMapThemeCollection(self, mapThemes: QgsMapThemeCollection)

Sets pointer to the collection of map themes.

New in version 3.6.

Parameters

mapThemes (QgsMapThemeCollection) –

setMapTileResolution(self, res: int)

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

Parameters

res (int) –

setMaxTerrainGroundError(self, error: float)

Returns maximum ground error of terrain tiles in world units.

Parameters

error (float) –

setMaxTerrainScreenError(self, error: float)

Sets maximum allowed screen error of terrain tiles in pixels.

Parameters

error (float) –

setOrigin(self, origin: QgsVector3D)

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.

Parameters

origin (QgsVector3D) –

setOutputDpi(self, dpi: float)

Sets DPI used for conversion between real world units (e.g. mm) and pixels

Parameters

dpi (float) – the number of dot per inch

New in version 3.10.

setPathResolver(self, resolver: QgsPathResolver)

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

See also

pathResolver()

New in version 3.0.

Parameters

resolver (QgsPathResolver) –

setPointLights(self, pointLights: Iterable[QgsPointLightSettings])

Sets list of point lights defined in the scene

New in version 3.6.

Parameters

pointLights (Iterable[QgsPointLightSettings]) –

setRenderers(self, renderers: Iterable[QgsAbstract3DRenderer])

Sets list of extra 3D renderers to use in the scene. Takes ownership of the objects.

Parameters

renderers (Iterable[QgsAbstract3DRenderer]) –

setSelectionColor(self, color: Union[QColor, Qt.GlobalColor])

Sets color used for selected features

Parameters

color (Union[QColor) –

setShowCameraViewCenter(self, enabled: bool)

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

New in version 3.4.

Parameters

enabled (bool) –

setShowLabels(self, enabled: bool)

Sets whether to display labels on terrain tiles

Parameters

enabled (bool) –

setShowTerrainBoundingBoxes(self, enabled: bool)

Sets whether to display bounding boxes of terrain tiles (for debugging)

Parameters

enabled (bool) –

setShowTerrainTilesInfo(self, enabled: bool)

Sets whether to display extra tile info on top of terrain tiles (for debugging)

Parameters

enabled (bool) –

setSkybox(self, enabled: bool, fileBase: str = '', fileExtension: str = '')

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.

Parameters
  • enabled (bool) –

  • fileBase (str = '') –

  • fileExtension (str = '') –

setTerrainMapTheme(self, theme: str)

Sets name of the map theme.

New in version 3.6.

Parameters

theme (str) –

setTerrainShadingEnabled(self, enabled: bool)

Sets whether terrain shading is enabled.

New in version 3.6.

Parameters

enabled (bool) –

setTerrainShadingMaterial(self, material: QgsPhongMaterialSettings)

Sets terrain shading material.

New in version 3.6.

Parameters

material (QgsPhongMaterialSettings) –

setTerrainVerticalScale(self, zScale: float)

Sets vertical scale (exaggeration) of terrain (1 = true scale, > 1 = hills get more pronounced)

Parameters

zScale (float) –

setTransformContext(self, context: QgsCoordinateTransformContext)

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.

Parameters

context (QgsCoordinateTransformContext) –

showCameraViewCenter(self) → bool

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

New in version 3.4.

Return type

bool

showCameraViewCenterChanged

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

New in version 3.4: [signal]

showLabels(self) → bool

Returns whether to display labels on terrain tiles

Return type

bool

showLabelsChanged

Emitted when the flag whether labels are displayed on terrain tiles has changed [signal]

showTerrainBoundingBoxes(self) → bool

Returns whether to display bounding boxes of terrain tiles (for debugging)

Return type

bool

showTerrainBoundingBoxesChanged

Emitted when the flag whether terrain’s bounding boxes are shown has changed [signal]

showTerrainTilesInfo(self) → bool

Returns whether to display extra tile info on top of terrain tiles (for debugging)

Return type

bool

showTerrainTilesInfoChanged

Emitted when the flag whether terrain’s tile info is shown has changed [signal]

skyboxFileBase(self) → str

Returns base part of filenames of skybox (see setSkybox())

Return type

str

skyboxFileExtension(self) → str

Returns extension part of filenames of skybox (see setSkybox())

Return type

str

terrainGeneratorChanged

Emitted when the terrain generator has changed [signal]

terrainMapTheme(self) → str

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.

Note

Support for map themes only works if mapThemeCollection() is a valid object (otherwise it is not possible to resolve map themes from names)

New in version 3.6.

Return type

str

terrainMapThemeChanged

Emitted when terrain’s map theme has changed

New in version 3.6: [signal]

terrainShadingChanged

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

New in version 3.6: [signal]

terrainShadingMaterial(self)QgsPhongMaterialSettings

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.

New in version 3.6.

Return type

QgsPhongMaterialSettings

terrainVerticalScale(self) → float

Returns vertical scale (exaggeration) of terrain

Return type

float

terrainVerticalScaleChanged

Emitted when the vertical scale of the terrain has changed [signal]

timerEvent()
transformContext(self)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.

Return type

QgsCoordinateTransformContext

worldToMapCoordinates(self, worldCoords: QgsVector3D)QgsVector3D

Converts 3D world coordinates to map coordinates (applies offset and turns (x,y,z) into (x,-z,y))

Parameters

worldCoords (QgsVector3D) –

Return type

QgsVector3D

writeXml(self, doc: QDomDocument, context: QgsReadWriteContext) → QDomElement

Writes configuration to a DOM element, to be used later with readXml()

Parameters
Return type

QDomElement