Qgis Impl 3d Visualization

qgis-impl-3d-visualization

Quick Reference

Import Pattern

3D classes live in qgis._3d (underscore prefix because Python modules cannot start with a digit). Base classes live in qgis.core.

# 3D-specific classes: ALWAYS import from qgis._3d
from qgis._3d import (
    Qgs3DMapSettings,
    QgsVectorLayer3DRenderer,
    QgsPolygon3DSymbol,
    QgsLine3DSymbol,
    QgsPoint3DSymbol,
    QgsPhongMaterialSettings,
    QgsGoochMaterialSettings,
    QgsMetalRoughMaterialSettings,
    QgsPointLightSettings,
    QgsDirectionalLightSettings,
    QgsCameraPose,
    QgsPointCloudLayer3DRenderer,
    QgsLayoutItem3DMap,
    QgsFlatTerrainSettings,
    QgsDemTerrainSettings,
)

# Base classes: ALWAYS import from qgis.core
from qgis.core import QgsAbstract3DSymbol, QgsAbstract3DRenderer

Symbol Construction Pattern

Material Types

Terrain Providers

---

Critical Warnings

NEVER use setMaterial() on 3D symbols — it is DEPRECATED and removed. ALWAYS use setMaterialSettings() instead. Old code examples referencing setMaterial() will fail.

NEVER import 3D classes from qgis.core — they live in qgis._3d. The ONLY exceptions are QgsAbstract3DSymbol and QgsAbstract3DRenderer, which live in qgis.core.

NEVER construct QgsPolygon3DSymbol or QgsLine3DSymbol with a regular constructor — ALWAYS use the create() factory method. QgsPoint3DSymbol is the exception and uses a regular constructor.

ALWAYS treat all qgis._3d classes as tech preview / unstable API. Method signatures MAY change between QGIS minor versions. ALWAYS verify against the API docs for your specific QGIS version.

ALWAYS use setExtent() on Qgs3DMapSettings before other configuration — it auto-sets the origin to the extent center, which other coordinate-dependent settings rely on.

NEVER call deprecated terrain methods on Qgs3DMapSettings (setTerrainVerticalScale(), setMaxTerrainScreenError(), setMapTileResolution()) — ALWAYS configure these through the terrain settings object instead.

---

Decision Tree

Which symbol class do I need?

Geometry type?
├── Point → QgsPoint3DSymbol()
├── Line → QgsLine3DSymbol.create()
├── Polygon → QgsPolygon3DSymbol.create()
└── Point Cloud → QgsPointCloudLayer3DRenderer + QgsPointCloud3DSymbol subclass

Which material do I need?

Visual effect needed?
├── Standard shading (most cases) → QgsPhongMaterialSettings
├── Non-photorealistic / technical drawing → QgsGoochMaterialSettings (3.16+)
└── Physically-based rendering → QgsMetalRoughMaterialSettings (3.36+)

Which terrain provider do I need?

Terrain data available?
├── No elevation data → QgsFlatTerrainSettings
├── Raster DEM layer → QgsDemTerrainSettings
├── Mesh layer → QgsMeshTerrainSettings
└── Project elevation properties → settings.configureTerrainFromProject()

---

Essential Patterns

Pattern 1: Configure a 3D Scene

from qgis._3d import Qgs3DMapSettings, QgsFlatTerrainSettings
from qgis.core import QgsCoordinateReferenceSystem, QgsRectangle, QgsProject
from qgis.PyQt.QtGui import QColor

settings = Qgs3DMapSettings()
settings.setCrs(QgsCoordinateReferenceSystem("EPSG:3857"))
settings.setExtent(QgsRectangle(1000000, 6000000, 2000000, 7000000))
settings.setBackgroundColor(QColor(135, 206, 235))
settings.setSelectionColor(QColor(255, 255, 0))

# Flat terrain
terrain = QgsFlatTerrainSettings()
terrain.setElevation(0.0)
settings.setTerrainSettings(terrain)

# Add layers
settings.setLayers(QgsProject.instance().mapLayers().values())

Pattern 2: DEM Terrain

from qgis._3d import QgsDemTerrainSettings

terrain = QgsDemTerrainSettings()
terrain.setLayer(dem_raster_layer)
terrain.setResolution(16)
terrain.setSkirtHeight(10.0)
settings.setTerrainSettings(terrain)

# Terrain rendering options
settings.setTerrainRenderingEnabled(True)
settings.setTerrainShadingEnabled(True)

material = QgsPhongMaterialSettings()
material.setDiffuse(QColor(180, 160, 120))
settings.setTerrainShadingMaterial(material)

Pattern 3: Extruded Building Polygons

from qgis._3d import (
    QgsVectorLayer3DRenderer,
    QgsPolygon3DSymbol,
    QgsPhongMaterialSettings,
)
from qgis.PyQt.QtGui import QColor

material = QgsPhongMaterialSettings()
material.setAmbient(QColor(100, 100, 100))
material.setDiffuse(QColor(180, 180, 160))
material.setSpecular(QColor(255, 255, 255))
material.setShininess(50.0)

symbol = QgsPolygon3DSymbol.create()
symbol.setExtrusionHeight(15.0)
symbol.setMaterialSettings(material)
symbol.setEdgesEnabled(True)
symbol.setEdgeColor(QColor(0, 0, 0))
symbol.setEdgeWidth(1.0)

renderer = QgsVectorLayer3DRenderer(symbol)
building_layer.setRenderer3D(renderer)

Pattern 4: 3D Point Symbols

from qgis._3d import QgsVectorLayer3DRenderer, QgsPoint3DSymbol, QgsPhongMaterialSettings
from qgis.PyQt.QtGui import QColor
from qgis.core import Qgis

material = QgsPhongMaterialSettings()
material.setDiffuse(QColor(255, 0, 0))
material.setShininess(100.0)

symbol = QgsPoint3DSymbol()
symbol.setShape(Qgis.Point3DShape.Sphere)
symbol.setShapeProperties({"radius": 5.0})
symbol.setMaterialSettings(material)

renderer = QgsVectorLayer3DRenderer(symbol)
point_layer.setRenderer3D(renderer)

Pattern 5: 3D Line Symbols

from qgis._3d import QgsVectorLayer3DRenderer, QgsLine3DSymbol, QgsPhongMaterialSettings
from qgis.PyQt.QtGui import QColor

material = QgsPhongMaterialSettings()
material.setDiffuse(QColor(0, 100, 200))

symbol = QgsLine3DSymbol.create()
symbol.setWidth(3.0)
symbol.setExtrusionHeight(10.0)
symbol.setMaterialSettings(material)

renderer = QgsVectorLayer3DRenderer(symbol)
line_layer.setRenderer3D(renderer)

Pattern 6: Lighting Configuration

from qgis._3d import QgsPointLightSettings, QgsDirectionalLightSettings
from qgis.core import QgsVector3D
from qgis.PyQt.QtGui import QColor

# Point light: illuminates from a specific position
point_light = QgsPointLightSettings()
point_light.setPosition(QgsVector3D(0, 1000, 0))
point_light.setColor(QColor(255, 255, 255))
point_light.setIntensity(1.0)
point_light.setConstantAttenuation(1.0)
point_light.setLinearAttenuation(0.0)
point_light.setQuadraticAttenuation(0.0)

# Directional light: simulates sunlight
dir_light = QgsDirectionalLightSettings()
dir_light.setDirection(QgsVector3D(0.5, -1.0, 0.5))
dir_light.setColor(QColor(255, 255, 230))
dir_light.setIntensity(0.8)

settings.setLightSources([point_light, dir_light])

Pattern 7: Camera Pose

from qgis._3d import QgsCameraPose
from qgis.core import QgsVector3D

camera = QgsCameraPose()
camera.setCenterPoint(QgsVector3D(1500000, 6500000, 0))
camera.setDistanceFromCenterPoint(500)
camera.setPitchAngle(45.0)   # 0 = top-down, 90 = horizontal
camera.setHeadingAngle(0.0)  # North-facing

Pattern 8: Eye Dome Lighting (Point Clouds)

# Enhances depth perception: especially useful for point clouds
settings.setEyeDomeLightingEnabled(True)
settings.setEyeDomeLightingStrength(1000.0)
settings.setEyeDomeLightingDistance(1)

Pattern 9: 3D Map in Print Layout

from qgis.core import QgsProject, QgsLayout, QgsLayoutSize, QgsLayoutPoint, QgsUnitTypes
from qgis._3d import QgsLayoutItem3DMap, QgsCameraPose
from qgis.core import QgsVector3D

project = QgsProject.instance()
layout = QgsLayout(project)

map_3d = QgsLayoutItem3DMap(layout)

camera = QgsCameraPose()
camera.setCenterPoint(QgsVector3D(0, 0, 0))
camera.setDistanceFromCenterPoint(500)
camera.setPitchAngle(45.0)
camera.setHeadingAngle(0.0)
map_3d.setCameraPose(camera)

# map_3d.setMapSettings(configured_3d_settings)
map_3d.attemptResize(QgsLayoutSize(200, 150, QgsUnitTypes.LayoutMillimeters))
map_3d.attemptMove(QgsLayoutPoint(10, 10, QgsUnitTypes.LayoutMillimeters))
layout.addLayoutItem(map_3d)

---

Common Operations

Altitude Clamping Modes

Control how features relate to terrain elevation:

from qgis.core import Qgis

# Absolute: Z values are absolute heights (ignore terrain)
symbol.setAltitudeClamping(Qgis.AltitudeClamping.Absolute)

# Relative: Z values are added to terrain elevation
symbol.setAltitudeClamping(Qgis.AltitudeClamping.Relative)

# Terrain: features are draped onto terrain (Z values ignored)
symbol.setAltitudeClamping(Qgis.AltitudeClamping.Terrain)

Altitude Binding (Polygons/Lines)

# Vertex: each vertex clamped individually (follows terrain closely)
symbol.setAltitudeBinding(Qgis.AltitudeBinding.Vertex)

# Centroid: entire feature clamped by centroid height (flat placement)
symbol.setAltitudeBinding(Qgis.AltitudeBinding.Centroid)

Coordinate Conversion

from qgis.core import QgsVector3D

# Map CRS coordinates to 3D world coordinates (applies x, -z, y swap)
world = settings.mapToWorldCoordinates(QgsVector3D(x_map, y_map, z_map))

# 3D world coordinates back to map CRS
map_coords = settings.worldToMapCoordinates(QgsVector3D(x_world, y_world, z_world))

Serialize / Restore 3D Settings

from qgis.PyQt.QtXml import QDomDocument
from qgis.core import QgsReadWriteContext, QgsProject

# Save
doc = QDomDocument()
elem = settings.writeXml(doc, QgsReadWriteContext())
doc.appendChild(elem)

# Restore
settings2 = Qgs3DMapSettings()
settings2.readXml(elem, QgsReadWriteContext())
settings2.resolveReferences(QgsProject.instance())

Point Cloud 3D Rendering

from qgis._3d import (
    QgsPointCloudLayer3DRenderer,
    QgsRgbPointCloud3DSymbol,
    QgsSingleColorPointCloud3DSymbol,
    QgsClassificationPointCloud3DSymbol,
    QgsColorRampPointCloud3DSymbol,
)

# RGB point cloud
symbol = QgsRgbPointCloud3DSymbol()
renderer = QgsPointCloudLayer3DRenderer()
renderer.setSymbol(symbol)
point_cloud_layer.setRenderer3D(renderer)

PBR Material (QGIS 3.36+)

from qgis._3d import QgsMetalRoughMaterialSettings
from qgis.PyQt.QtGui import QColor

material = QgsMetalRoughMaterialSettings()
material.setBaseColor(QColor(200, 200, 200))
material.setMetalness(0.8)   # 0.0 = dielectric, 1.0 = metal
material.setRoughness(0.3)   # 0.0 = mirror, 1.0 = matte

Gooch Material (QGIS 3.16+)

from qgis._3d import QgsGoochMaterialSettings
from qgis.PyQt.QtGui import QColor

material = QgsGoochMaterialSettings()
material.setWarm(QColor(255, 200, 100))
material.setCool(QColor(100, 150, 255))
material.setDiffuse(QColor(200, 200, 200))
material.setSpecular(QColor(255, 255, 255))
material.setShininess(50.0)
material.setAlpha(0.25)
material.setBeta(0.5)

---

Version Compatibility

---

Reference Links

• references/methods.md -- Complete API signatures for all 3D classes
• references/examples.md -- Full working code examples
• references/anti-patterns.md -- Common mistakes and how to avoid them

Official Sources

• https://qgis.org/pyqgis/3.40/_3d/index.html
• https://qgis.org/pyqgis/master/_3d/Qgs3DMapSettings.html
• https://qgis.org/pyqgis/master/_3d/QgsPolygon3DSymbol.html
• https://qgis.org/pyqgis/master/_3d/QgsVectorLayer3DRenderer.html

qgis-impl-3d-visualization — Anti-Patterns

---

AP-1: Using setMaterial() Instead of setMaterialSettings()

Wrong:

symbol = QgsPolygon3DSymbol.create()
material = QgsPhongMaterialSettings()
material.setDiffuse(QColor(200, 100, 50))
symbol.setMaterial(material)  # DEPRECATED / REMOVED — will raise AttributeError

Right:

symbol = QgsPolygon3DSymbol.create()
material = QgsPhongMaterialSettings()
material.setDiffuse(QColor(200, 100, 50))
symbol.setMaterialSettings(material)  # Correct method name

Why: setMaterial() was replaced by setMaterialSettings() in a breaking API change. Old tutorials and plugins (including some CityJSON examples) still reference the old method. ALWAYS use setMaterialSettings().

---

AP-2: Importing 3D Classes from qgis.core

Wrong:

from qgis.core import QgsPolygon3DSymbol, QgsPhongMaterialSettings  # ImportError

Right:

from qgis._3d import QgsPolygon3DSymbol, QgsPhongMaterialSettings

Why: All 3D-specific classes live in qgis._3d, not qgis.core. The underscore prefix exists because Python modules cannot start with a digit. The ONLY exceptions are the abstract base classes QgsAbstract3DSymbol and QgsAbstract3DRenderer, which live in qgis.core.

---

AP-3: Constructing Polygon/Line Symbols with Regular Constructor

Wrong:

symbol = QgsPolygon3DSymbol()  # May not work — factory pattern required
symbol = QgsLine3DSymbol()     # May not work — factory pattern required

Right:

symbol = QgsPolygon3DSymbol.create()  # Factory method
symbol = QgsLine3DSymbol.create()     # Factory method

Why: QgsPolygon3DSymbol and QgsLine3DSymbol use a factory pattern via create(). QgsPoint3DSymbol is the exception — it uses a regular constructor QgsPoint3DSymbol(). Mixing up the construction patterns leads to errors or unexpected behavior.

---

AP-4: Forgetting setExtent() Before Other Configuration

Wrong:

settings = Qgs3DMapSettings()
settings.setCrs(QgsCoordinateReferenceSystem("EPSG:3857"))
settings.setLayers([layer])
# No setExtent() — origin defaults to (0,0), coordinates will be wrong

Right:

settings = Qgs3DMapSettings()
settings.setCrs(QgsCoordinateReferenceSystem("EPSG:3857"))
settings.setExtent(layer.extent())  # Auto-sets origin to extent center
settings.setLayers([layer])

Why: setExtent() automatically sets the scene origin to the center of the extent. Without it, the origin defaults to (0,0) and all 3D world coordinates will be offset from the data, causing features to render far from the camera or not appear at all.

---

AP-5: Using Deprecated Terrain Methods on Qgs3DMapSettings

Wrong:

settings.setTerrainVerticalScale(2.0)      # Deprecated
settings.setMaxTerrainScreenError(3.0)     # Deprecated
settings.setMapTileResolution(512)         # Deprecated

Right:

terrain = QgsDemTerrainSettings()
terrain.setLayer(dem_layer)
terrain.setResolution(16)
settings.setTerrainSettings(terrain)

Why: Since QGIS 3.42, terrain configuration moved to dedicated terrain settings objects. The old methods on Qgs3DMapSettings are deprecated and may be removed in future versions. ALWAYS use setTerrainSettings() with the appropriate terrain settings class.

---

AP-6: Ignoring the Unstable API Warning

Wrong:

# Assuming 3D API is stable across QGIS versions
# Hardcoding method names without version checks
symbol.setExtrusionFaces(Qgis.ExtrusionFaces.Top)  # Added in a specific version

Right:

# Document minimum version in comments
# Qgis.ExtrusionFaces requires QGIS 3.x+
symbol.setExtrusionFaces(Qgis.ExtrusionFaces.Top)

# For maximum compatibility, check QGIS version
from qgis.core import Qgis
if Qgis.versionInt() >= 34200:
    settings.setTerrainSettings(terrain)

Why: ALL classes in qgis._3d carry a "tech preview / unstable API" warning. Method signatures, class names, and enum values can change between QGIS minor versions. ALWAYS document the minimum QGIS version for each feature used, and add version checks when targeting multiple QGIS releases.

---

AP-7: Not Resolving References After readXml()

Wrong:

settings2 = Qgs3DMapSettings()
settings2.readXml(elem, QgsReadWriteContext())
# Immediately using settings2 — layer references are unresolved

Right:

settings2 = Qgs3DMapSettings()
settings2.readXml(elem, QgsReadWriteContext())
settings2.resolveReferences(QgsProject.instance())  # Resolve layer references

Why: After readXml(), layer references stored in the XML are just IDs. Without calling resolveReferences(), the settings object will have null layer references and terrain layers will not render.

---

AP-8: Point Light with Zero Attenuation

Wrong:

light = QgsPointLightSettings()
light.setPosition(QgsVector3D(0, 1000, 0))
light.setIntensity(1.0)
# Default attenuation may be 0,0,0 — light has infinite range, washes out scene

Right:

light = QgsPointLightSettings()
light.setPosition(QgsVector3D(0, 1000, 0))
light.setIntensity(1.0)
light.setConstantAttenuation(1.0)
light.setLinearAttenuation(0.0)
light.setQuadraticAttenuation(0.0)

Why: ALWAYS explicitly set attenuation values for point lights. The attenuation formula is Total = A0 + A1*D + A2*D^2. With all values at zero, light intensity is undefined. Setting constantAttenuation to 1.0 with zero linear and quadratic values gives uniform light with no distance falloff.

---

AP-9: Missing Terrain Settings When Using DEM

Wrong:

terrain = QgsDemTerrainSettings()
terrain.setLayer(dem_layer)
settings.setTerrainSettings(terrain)
# Terrain renders with gaps between tiles

Right:

terrain = QgsDemTerrainSettings()
terrain.setLayer(dem_layer)
terrain.setResolution(16)
terrain.setSkirtHeight(10.0)  # Prevents gaps between terrain tiles
settings.setTerrainSettings(terrain)

Why: Without setSkirtHeight(), terrain tiles can have visible gaps at their edges due to level-of-detail transitions. ALWAYS set a skirt height for DEM terrain to prevent visual artifacts.

---

AP-10: Using Absolute Altitude Clamping Without Z Values

Wrong:

# Layer has no Z coordinates
symbol.setAltitudeClamping(Qgis.AltitudeClamping.Absolute)
# Features render at Z=0, flat on ground — no visible 3D effect

Right:

# For 2D data, use Terrain clamping to drape on terrain
symbol.setAltitudeClamping(Qgis.AltitudeClamping.Terrain)

# Or use Relative with an offset
symbol.setAltitudeClamping(Qgis.AltitudeClamping.Relative)
symbol.setOffset(5.0)  # 5 meters above terrain

Why: Absolute clamping uses the feature's Z values directly. If the data has no Z coordinates, all features render at Z=0 (ground level), making them invisible if terrain is also at ground level. For 2D data, ALWAYS use Terrain clamping (drape on surface) or Relative with an offset.

---

AP-11: Forgetting to Add Layer to 3D Scene

Wrong:

renderer = QgsVectorLayer3DRenderer(symbol)
layer.setRenderer3D(renderer)
# Layer has a 3D renderer but is not in settings.setLayers() — nothing renders

Right:

renderer = QgsVectorLayer3DRenderer(symbol)
layer.setRenderer3D(renderer)
settings.setLayers([layer])  # ALWAYS include the layer in the scene

Why: Setting a 3D renderer on a layer configures HOW it renders in 3D, but Qgs3DMapSettings.setLayers() controls WHICH layers are included in the 3D scene. Both are required for a layer to appear in the 3D view.

qgis-impl-3d-visualization — Examples

All examples use [CONFIRMED] API methods from PyQGIS 3.40+. No official 3D cookbook exists,

so these are reconstructed from verified API signatures.

---

Example 1: Complete 3D Scene with Extruded Buildings

from qgis.core import (
    QgsProject,
    QgsCoordinateReferenceSystem,
    QgsRectangle,
    QgsVector3D,
)
from qgis._3d import (
    Qgs3DMapSettings,
    QgsFlatTerrainSettings,
    QgsVectorLayer3DRenderer,
    QgsPolygon3DSymbol,
    QgsPhongMaterialSettings,
    QgsPointLightSettings,
    QgsDirectionalLightSettings,
)
from qgis.PyQt.QtGui import QColor

project = QgsProject.instance()
buildings = project.mapLayersByName("buildings")[0]

# --- Scene setup ---
settings = Qgs3DMapSettings()
settings.setCrs(QgsCoordinateReferenceSystem("EPSG:28992"))
settings.setExtent(buildings.extent())
settings.setBackgroundColor(QColor(200, 220, 240))

# Flat terrain
terrain = QgsFlatTerrainSettings()
terrain.setElevation(0.0)
settings.setTerrainSettings(terrain)

# --- Building material ---
material = QgsPhongMaterialSettings()
material.setAmbient(QColor(80, 80, 80))
material.setDiffuse(QColor(200, 190, 170))
material.setSpecular(QColor(255, 255, 255))
material.setShininess(80.0)

# --- 3D building symbol ---
symbol = QgsPolygon3DSymbol.create()
symbol.setExtrusionHeight(12.0)
symbol.setMaterialSettings(material)
symbol.setEdgesEnabled(True)
symbol.setEdgeColor(QColor(60, 60, 60))
symbol.setEdgeWidth(1.0)

# --- Assign renderer ---
renderer = QgsVectorLayer3DRenderer(symbol)
buildings.setRenderer3D(renderer)

# --- Lighting ---
sun = QgsDirectionalLightSettings()
sun.setDirection(QgsVector3D(0.5, -1.0, 0.5))
sun.setColor(QColor(255, 255, 230))
sun.setIntensity(0.8)

fill = QgsPointLightSettings()
fill.setPosition(QgsVector3D(0, 500, 0))
fill.setColor(QColor(200, 200, 255))
fill.setIntensity(0.3)
fill.setConstantAttenuation(1.0)
fill.setLinearAttenuation(0.0)
fill.setQuadraticAttenuation(0.0)

settings.setLightSources([sun, fill])
settings.setLayers([buildings])

---

Example 2: DEM Terrain with Draped Roads

from qgis.core import QgsProject, QgsCoordinateReferenceSystem
from qgis._3d import (
    Qgs3DMapSettings,
    QgsDemTerrainSettings,
    QgsVectorLayer3DRenderer,
    QgsLine3DSymbol,
    QgsPhongMaterialSettings,
)
from qgis.PyQt.QtGui import QColor
from qgis.core import Qgis

project = QgsProject.instance()
dem = project.mapLayersByName("elevation")[0]
roads = project.mapLayersByName("roads")[0]

# --- Scene ---
settings = Qgs3DMapSettings()
settings.setCrs(dem.crs())
settings.setExtent(dem.extent())

# --- DEM terrain ---
terrain = QgsDemTerrainSettings()
terrain.setLayer(dem)
terrain.setResolution(16)
terrain.setSkirtHeight(10.0)
settings.setTerrainSettings(terrain)
settings.setTerrainRenderingEnabled(True)
settings.setTerrainShadingEnabled(True)

terrain_material = QgsPhongMaterialSettings()
terrain_material.setDiffuse(QColor(160, 140, 100))
settings.setTerrainShadingMaterial(terrain_material)

# --- Roads draped on terrain ---
road_material = QgsPhongMaterialSettings()
road_material.setDiffuse(QColor(80, 80, 80))

road_symbol = QgsLine3DSymbol.create()
road_symbol.setWidth(5.0)
road_symbol.setAltitudeClamping(Qgis.AltitudeClamping.Terrain)
road_symbol.setMaterialSettings(road_material)

road_renderer = QgsVectorLayer3DRenderer(road_symbol)
roads.setRenderer3D(road_renderer)

settings.setLayers([dem, roads])

---

Example 3: Point Cloud with Eye Dome Lighting

from qgis.core import QgsProject
from qgis._3d import (
    Qgs3DMapSettings,
    QgsFlatTerrainSettings,
    QgsPointCloudLayer3DRenderer,
    QgsRgbPointCloud3DSymbol,
)
from qgis.PyQt.QtGui import QColor

project = QgsProject.instance()
pc_layer = project.mapLayersByName("point_cloud")[0]

# --- Scene ---
settings = Qgs3DMapSettings()
settings.setCrs(pc_layer.crs())
settings.setExtent(pc_layer.extent())
settings.setBackgroundColor(QColor(30, 30, 30))

terrain = QgsFlatTerrainSettings()
settings.setTerrainSettings(terrain)

# --- Point cloud renderer ---
symbol = QgsRgbPointCloud3DSymbol()
renderer = QgsPointCloudLayer3DRenderer()
renderer.setSymbol(symbol)
pc_layer.setRenderer3D(renderer)

# --- Eye Dome Lighting for depth perception ---
settings.setEyeDomeLightingEnabled(True)
settings.setEyeDomeLightingStrength(1000.0)
settings.setEyeDomeLightingDistance(1)

settings.setLayers([pc_layer])

---

Example 4: 3D Points as Colored Spheres

from qgis.core import QgsProject, Qgis
from qgis._3d import (
    QgsVectorLayer3DRenderer,
    QgsPoint3DSymbol,
    QgsPhongMaterialSettings,
)
from qgis.PyQt.QtGui import QColor

layer = QgsProject.instance().mapLayersByName("sensors")[0]

material = QgsPhongMaterialSettings()
material.setDiffuse(QColor(255, 50, 50))
material.setSpecular(QColor(255, 255, 255))
material.setShininess(120.0)

symbol = QgsPoint3DSymbol()
symbol.setShape(Qgis.Point3DShape.Sphere)
symbol.setShapeProperties({"radius": 3.0})
symbol.setMaterialSettings(material)
symbol.setAltitudeClamping(Qgis.AltitudeClamping.Relative)

renderer = QgsVectorLayer3DRenderer(symbol)
layer.setRenderer3D(renderer)

---

Example 5: 3D Map in Print Layout

from qgis.core import (
    QgsProject,
    QgsLayout,
    QgsLayoutSize,
    QgsLayoutPoint,
    QgsUnitTypes,
    QgsVector3D,
    QgsCoordinateReferenceSystem,
    QgsRectangle,
)
from qgis._3d import (
    Qgs3DMapSettings,
    QgsFlatTerrainSettings,
    QgsLayoutItem3DMap,
    QgsCameraPose,
)
from qgis.PyQt.QtGui import QColor

project = QgsProject.instance()

# --- Configure 3D settings ---
settings = Qgs3DMapSettings()
settings.setCrs(QgsCoordinateReferenceSystem("EPSG:28992"))
settings.setExtent(QgsRectangle(100000, 400000, 200000, 500000))
settings.setBackgroundColor(QColor(200, 220, 240))

terrain = QgsFlatTerrainSettings()
settings.setTerrainSettings(terrain)
settings.setLayers(list(project.mapLayers().values()))

# --- Create layout ---
layout = QgsLayout(project)

# --- Add 3D map item ---
map_3d = QgsLayoutItem3DMap(layout)

camera = QgsCameraPose()
camera.setCenterPoint(QgsVector3D(150000, 450000, 0))
camera.setDistanceFromCenterPoint(20000)
camera.setPitchAngle(45.0)
camera.setHeadingAngle(315.0)
map_3d.setCameraPose(camera)

map_3d.setMapSettings(settings)
map_3d.attemptResize(QgsLayoutSize(200, 150, QgsUnitTypes.LayoutMillimeters))
map_3d.attemptMove(QgsLayoutPoint(10, 10, QgsUnitTypes.LayoutMillimeters))
layout.addLayoutItem(map_3d)

---

Example 6: PBR Material (QGIS 3.36+)

from qgis._3d import (
    QgsVectorLayer3DRenderer,
    QgsPolygon3DSymbol,
    QgsMetalRoughMaterialSettings,
)
from qgis.PyQt.QtGui import QColor

# Metallic building facade
material = QgsMetalRoughMaterialSettings()
material.setBaseColor(QColor(180, 180, 190))
material.setMetalness(0.9)
material.setRoughness(0.2)

symbol = QgsPolygon3DSymbol.create()
symbol.setExtrusionHeight(30.0)
symbol.setMaterialSettings(material)

renderer = QgsVectorLayer3DRenderer(symbol)
building_layer.setRenderer3D(renderer)

---

Example 7: Serialize and Restore 3D Settings

from qgis.PyQt.QtXml import QDomDocument
from qgis.core import QgsReadWriteContext, QgsProject
from qgis._3d import Qgs3DMapSettings

# --- Save settings to XML ---
doc = QDomDocument()
elem = settings.writeXml(doc, QgsReadWriteContext())
doc.appendChild(elem)
xml_string = doc.toString()

# --- Restore settings from XML ---
doc2 = QDomDocument()
doc2.setContent(xml_string)
root = doc2.documentElement()

restored = Qgs3DMapSettings()
restored.readXml(root, QgsReadWriteContext())
restored.resolveReferences(QgsProject.instance())

---

Example 8: Gooch Non-Photorealistic Material (QGIS 3.16+)

from qgis._3d import (
    QgsVectorLayer3DRenderer,
    QgsPolygon3DSymbol,
    QgsGoochMaterialSettings,
)
from qgis.PyQt.QtGui import QColor

material = QgsGoochMaterialSettings()
material.setWarm(QColor(255, 200, 100))
material.setCool(QColor(100, 150, 255))
material.setDiffuse(QColor(200, 200, 200))
material.setSpecular(QColor(255, 255, 255))
material.setShininess(50.0)
material.setAlpha(0.25)
material.setBeta(0.5)

symbol = QgsPolygon3DSymbol.create()
symbol.setExtrusionHeight(20.0)
symbol.setMaterialSettings(material)

renderer = QgsVectorLayer3DRenderer(symbol)
layer.setRenderer3D(renderer)

---

Example 9: Multiple Light Sources

from qgis._3d import QgsPointLightSettings, QgsDirectionalLightSettings
from qgis.core import QgsVector3D
from qgis.PyQt.QtGui import QColor

# Key light (directional — simulates sun)
key = QgsDirectionalLightSettings()
key.setDirection(QgsVector3D(0.3, -1.0, 0.4))
key.setColor(QColor(255, 250, 230))
key.setIntensity(1.0)

# Fill light (point — softens shadows)
fill = QgsPointLightSettings()
fill.setPosition(QgsVector3D(-500, 300, 200))
fill.setColor(QColor(180, 200, 255))
fill.setIntensity(0.4)
fill.setConstantAttenuation(1.0)
fill.setLinearAttenuation(0.001)
fill.setQuadraticAttenuation(0.0)

# Rim light (point — adds depth)
rim = QgsPointLightSettings()
rim.setPosition(QgsVector3D(0, 200, -500))
rim.setColor(QColor(255, 255, 255))
rim.setIntensity(0.3)
rim.setConstantAttenuation(1.0)
rim.setLinearAttenuation(0.001)
rim.setQuadraticAttenuation(0.0)

settings.setLightSources([key, fill, rim])

qgis-impl-3d-visualization — Methods Reference

Qgs3DMapSettings

Central configuration class for 3D scenes. Import from qgis._3d.

Coordinate System and Extent

Coordinate Conversion

Layers

Terrain

Light Sources (3.26+)

Camera

Visual Settings

Eye Dome Lighting (3.18+)

Serialization

---

QgsPolygon3DSymbol

Factory: QgsPolygon3DSymbol.create() -> QgsAbstract3DSymbol. Import from qgis._3d.

---

QgsLine3DSymbol

Factory: QgsLine3DSymbol.create() -> QgsAbstract3DSymbol. Import from qgis._3d.

---

QgsPoint3DSymbol

Constructor: QgsPoint3DSymbol(). Import from qgis._3d.

Static helpers:

• shapeFromString(str) -> Qgis.Point3DShape
• shapeToString(Qgis.Point3DShape) -> str

---

QgsVectorLayer3DRenderer

Constructor: QgsVectorLayer3DRenderer(symbol: QgsAbstract3DSymbol | None = None). Import from qgis._3d.

Apply to a layer: layer.setRenderer3D(renderer)

---

QgsPointCloudLayer3DRenderer

Import from qgis._3d.

---

QgsPhongMaterialSettings

Import from qgis._3d.

---

QgsGoochMaterialSettings (3.16+)

Import from qgis._3d.

---

QgsMetalRoughMaterialSettings (3.36+)

Import from qgis._3d.

---

QgsPointLightSettings

Constructor: QgsPointLightSettings(). Import from qgis._3d.

Attenuation formula: Total = A0 + A1*D + A2*D^2

---

QgsDirectionalLightSettings (3.16+)

Constructor: QgsDirectionalLightSettings(). Import from qgis._3d.

---

QgsCameraPose

Constructor: QgsCameraPose(). Import from qgis._3d.

---

Terrain Settings Classes

QgsFlatTerrainSettings

QgsDemTerrainSettings

---

QgsLayoutItem3DMap (3.4+)

Import from qgis._3d.