.. index:: 3D Tiles, 3d tiles properties
.. _`label_3d_tiles`:

*************************
Working with 3D Tiles
*************************

.. only:: html

   .. contents::
      :local:

What are 3D Tiles?
======================

3D tiles are specification for streaming and rendering large-scale 3D geospatial datasets.
They use a hierarchical structure to efficiently manage and display 3D content,
optimising performance by dynamically loading appropriate levels of detail.
This technology is widely used in urban planning, architecture, simulation, gaming,
and virtual reality, providing a standardised and interoperable solution
for visualising complex geographical data.

.. _figure_3d_tiles_example:

.. figure:: img/3d_tiles.png
   :align: center

   Example of 3D tiles


Currently, QGIS supports two formats of 3D tiles:

* `Cesium 3D tiles <https://cesium.com/why-cesium/3d-tiles/>`_,
  used primarily for complex 3D models of buildings or whole cities.
  Such datasets can be provided by cloud-based platforms such as Cesium Ion
  or Google (*Photorealistic 3D Tiles*).
* `Quantized Mesh tiles <https://github.com/CesiumGS/quantized-mesh>`_,
  used for terrain elevation data.

See :ref:`3d_tiles` for instructions on how to add these data sources to QGIS.

.. _3dtiles_properties:

3D Tiles Properties
===================

The 3D tiles :guilabel:`Layer Properties` dialog provides the following sections:

.. list-table::

   * - |metadata| :ref:`Information <3dtilesinformationmenu>`
     - |system| :ref:`Source <3dtilessourcemenu>`
     - |symbology| :ref:`Symbology <3dtilessymbologymenu>`:sup:`[1]`
   * - |3d| :ref:`3D View <3dtiles3dviewmenu>`:sup:`[1]`
     - |rendering| :ref:`Rendering <3dtilesrenderingmenu>`
     - |elevationscale| :ref:`Elevation <3dtileselevationmenu>`:sup:`[1]`
   * - |editMetadata| :ref:`Metadata <3dtilesmetadatamenu>`
     -
     -


:sup:`[1]` Also available in the :ref:`Layer styling panel <layer_styling_panel>`


.. _3dtilesinformationmenu:

Information Properties
----------------------

The :guilabel:`Information` tab is read-only and represents an interesting
place to quickly grab summarized information and metadata on the current layer.
Provided information are:

* based on the provider of the layer: name, URL, source type and path, number
  of zoom levels
* custom properties, used to store in the active project additional information about the layer.
  More properties can be created and managed using PyQGIS, specifically through
  the :pyqgis:`setCustomProperty() <qgis.core.QgsMapLayer.setCustomProperty>` method.
* the Coordinate Reference System: name, units, method, accuracy, reference
  (i.e. whether it's static or dynamic)
* picked from the :ref:`filled metadata <3dtilesmetadatamenu>`: access,
  extents, links, contacts, history...

.. _3dtilessourcemenu:

Source Properties
-----------------

The |system| :guilabel:`Source` tab displays basic information about
the selected 3D tile, including:

* the :guilabel:`Layer name` to display in the :guilabel:`Layers Panel`;
* the :guilabel:`Coordinate Reference System`:
  Displays the layer's
  :ref:`Coordinate Reference System (CRS) <layer_crs>`.
  You can change the layer's CRS, by selecting a recently used one in
  the drop-down list or clicking on the |setProjection|
  :sup:`Select CRS` button (see :ref:`crs_selector`).
  Use this process only if the layer CRS is wrong or not specified.

.. _3dtilessymbologymenu:

Symbology Properties
--------------------

.. _figure_3d_tiles_symbology:

.. figure:: img/3d_tiles_symbology.png
   :align: center

   3D Tile Layer Symbology

By default, the layer is styled using texture, but you can change it 
to see the wireframe mesh behind the scene by choosing :guilabel:`Wireframe` 
in the drop-down menu. You can also, change the mesh fill and line symbols 
similar to the vector polygons. 
Checking |checkbox| :guilabel:`Use texture colors` will render each mesh element 
with the average value of the full texture. 
This is a good option to try when dealing with a large dataset and
want to get a quick overview of the data.

.. _figure_3d_tiles_textured_and_wireframe:

.. figure:: img/3d_tiles_textured_and_wireframe.png
   :align: center

   3D Tiles - textured and wireframe 

From the :guilabel:`Symbology` tab, you can also set some options that 
invariably act on all features of the layer:

* :guilabel:`Maximum error`: This parameter determines the level of detail 
  displayed in the 3D model. Similar to point clouds, 3D tiles 
  often contain more information than necessary for visual representation.
  By adjusting this setting, you control the balance between display density 
  and rendering speed. A larger value (e.g., 5 mm) may introduce noticeable
  gaps between elements, while a smaller value (e.g., 0.1 mm) could lead to
  the rendering of an excessive number of details, potentially slowing down
  the rendering process. Different units can be selected to tailor the setting
  to your specific needs.
* :guilabel:`Opacity`: Adjusts the visibility of the underlying layer on the 
  map canvas using this tool. Use slider to tailor the visibility 
  of your scene layer according to your preferences. Alternatively, specify the 
  exact percentage of visibility through the menu next to the slider.
* :guilabel:`Blending mode`: You can achieve special rendering effects with these tools
  that you may previously only know from graphics programs.
  The pixels of your overlaying and underlaying layers are mixed through the settings
  described in :ref:`blend-modes`.

.. _3dtiles3dviewmenu:

3D View Properties
------------------

* :guilabel:`Maximum screen space error`: Determines the threshold for swapping
  terrain tiles with more detailed ones (and vice versa) - i.e. how soon the 3D 
  view will use higher quality tiles. Lower numbers mean more details in the 
  scene at the expenses of increased rendering complexity.

* |unchecked| :guilabel:`Show bounding boxes`: Shows 3D bounding boxes of the 
  terrain tiles (useful for troubleshooting terrain issues).

To view the data you can open |new3DMap| :guilabel:`New 3D map view`.

.. _figure_3d_tiles_map_view:

.. figure:: img/3d_tiles_map_view.png
   :align: center

   3D Map View

.. _3dtilesrenderingmenu:

Rendering Properties
--------------------

Under |unchecked| :guilabel:`Scale dependent visibility`,
you can set the :guilabel:`Maximum (inclusive)`
and :guilabel:`Minimum (exclusive)` scales,
defining a range of scales in which features will be visible.
Out of this range, they are hidden.
The |mapIdentification| :sup:`Set to current canvas scale` button helps you
use the current map canvas scale as boundary of the range visibility.
See :ref:`label_scaledepend` for more information.

.. _3dtileselevationmenu:

Elevation Properties
--------------------

The |elevationscale| :guilabel:`Elevation` tab provides options to control
the layer elevation properties within a :ref:`3D map view <label_3dmapview>`.
Specifically, you can set:

* :guilabel:`Elevation Surface`: how the 3D layer vertices Z values
  should be interpreted as terrain elevation.
  You can apply a :guilabel:`Scale` factor and an :guilabel:`Offset`.

.. index:: Metadata, Metadata editor, Keyword
.. _3dtilesmetadatamenu:

Metadata Properties
-------------------

The |editMetadata| :guilabel:`Metadata` tab provides you with options
to create and edit a metadata report on your layer.
See :ref:`metadatamenu` for more information.


.. Substitutions definitions - AVOID EDITING PAST THIS LINE
   This will be automatically updated by the find_set_subst.py script.
   If you need to create a new substitution manually,
   please add it also to the substitutions.txt file in the
   source folder.

.. |3d| image:: /static/common/3d.png
   :width: 1.5em
.. |checkbox| image:: /static/common/checkbox.png
   :width: 1.3em
.. |editMetadata| image:: /static/common/editmetadata.png
   :width: 1.2em
.. |elevationscale| image:: /static/common/elevationscale.png
   :width: 1.5em
.. |mapIdentification| image:: /static/common/mActionMapIdentification.png
   :width: 1.5em
.. |metadata| image:: /static/common/metadata.png
   :width: 1.5em
.. |new3DMap| image:: /static/common/mActionNew3DMap.png
   :width: 1.5em
.. |rendering| image:: /static/common/rendering.png
   :width: 1.5em
.. |setProjection| image:: /static/common/mActionSetProjection.png
   :width: 1.5em
.. |symbology| image:: /static/common/symbology.png
   :width: 2em
.. |system| image:: /static/common/system.png
   :width: 1.5em
.. |unchecked| image:: /static/common/unchecked.png
   :width: 1.3em
