voxcity.utils.classes
=====================

.. py:module:: voxcity.utils.classes

.. autoapi-nested-parse::

   VoxCity Class Definitions

   This module provides standard class definitions for voxel grid semantics
   and land cover classification used throughout VoxCity.

   Voxel Grid Semantics:
       The 3D voxel grid uses integer codes to represent different urban elements.
       Negative values represent structural elements, while positive values
       represent land cover classes at the ground surface layer.

   Land Cover Classes:
       Land cover is standardized to a 1-based indexing system (1-14) for
       consistency across different data sources. This standard classification
       is used in the voxel representation and exports.



Attributes
----------

.. autoapisummary::

   voxcity.utils.classes.VOXEL_CODES
   voxcity.utils.classes.VOXEL_CODE_DESCRIPTIONS
   voxcity.utils.classes.LAND_COVER_CLASSES
   voxcity.utils.classes.LAND_COVER_DESCRIPTIONS


Functions
---------

.. autoapisummary::

   voxcity.utils.classes.print_voxel_codes
   voxcity.utils.classes.print_land_cover_classes
   voxcity.utils.classes.print_class_definitions
   voxcity.utils.classes.get_land_cover_name
   voxcity.utils.classes.get_voxel_code_name
   voxcity.utils.classes.summarize_voxel_grid
   voxcity.utils.classes.summarize_land_cover_grid


Module Contents
---------------

.. py:data:: VOXEL_CODES

.. py:data:: VOXEL_CODE_DESCRIPTIONS
   :value: Multiline-String

   .. raw:: html

      <details><summary>Show Value</summary>

   .. code-block:: python

      """
      Voxel Grid Semantic Codes:
        -3 : Building volume
        -2 : Tree canopy (vegetation)
        -1 : Ground/Subsurface
        >=1: Land cover class at ground surface (see Land Cover Classes)
      """

   .. raw:: html

      </details>



.. py:data:: LAND_COVER_CLASSES

.. py:data:: LAND_COVER_DESCRIPTIONS
   :value: Multiline-String

   .. raw:: html

      <details><summary>Show Value</summary>

   .. code-block:: python

      """
      VoxCity Standard Land Cover Classes (1-based indices, used in voxel grids):
      --------------------------------------------------
         1: Bareland           - Bare soil, rocks, desert
         2: Rangeland          - Grassland, pasture
         3: Shrub              - Shrubland, bushes
         4: Agriculture land   - Cropland, farmland
         5: Tree               - Forest, tree cover
         6: Moss and lichen    - Moss, lichen cover
         7: Wet land           - Wetland, marsh
         8: Mangrove           - Mangrove forest
         9: Water              - Water bodies
        10: Snow and ice       - Snow, ice, glaciers
        11: Developed space    - Urban areas, parking
        12: Road               - Roads, paved surfaces
        13: Building           - Building footprints
        14: No Data            - Missing or invalid data
      --------------------------------------------------
      Note: Source-specific land cover classes are converted to these
            standard classes during voxelization.
      """

   .. raw:: html

      </details>



.. py:function:: print_voxel_codes() -> None

   Print voxel semantic codes to console.


.. py:function:: print_land_cover_classes() -> None

   Print standard land cover class definitions to console.


.. py:function:: print_class_definitions() -> None

   Print both voxel codes and land cover class definitions.


.. py:function:: get_land_cover_name(index: int) -> str

   Get the land cover class name for a given index.

   :param index: Land cover class index (1-14)

   :returns: Class name string, or "Unknown" if index is invalid


.. py:function:: get_voxel_code_name(code: int) -> str

   Get the semantic name for a voxel code.

   :param code: Voxel code (negative for structures, positive for land cover)

   :returns: Semantic name string


.. py:function:: summarize_voxel_grid(voxel_grid: numpy.ndarray, print_output: bool = True) -> Dict[int, int]

   Summarize the contents of a voxel grid.

   :param voxel_grid: 3D numpy array of voxel codes
   :param print_output: Whether to print the summary

   :returns: Dictionary mapping voxel codes to counts


.. py:function:: summarize_land_cover_grid(land_cover_grid: numpy.ndarray, print_output: bool = True) -> Dict[int, int]

   Summarize the contents of a land cover grid.

   :param land_cover_grid: 2D numpy array of land cover class indices
   :param print_output: Whether to print the summary

   :returns: Dictionary mapping class indices to counts