voxcity.utils.lc ================ .. py:module:: voxcity.utils.lc .. autoapi-nested-parse:: Land Cover Classification Utilities for VoxelCity This module provides utilities for handling land cover data from various sources, including color-based classification, data conversion between different land cover classification systems, and spatial analysis of land cover polygons. Supported land cover data sources: - Urbanwatch - OpenEarthMapJapan - ESRI 10m Annual Land Cover - ESA WorldCover - Dynamic World V1 - OpenStreetMap - Standard classification Functions --------- .. autoapisummary:: voxcity.utils.lc.get_land_cover_classes voxcity.utils.lc.get_source_class_descriptions voxcity.utils.lc.convert_land_cover voxcity.utils.lc.get_class_priority voxcity.utils.lc.create_land_cover_polygons voxcity.utils.lc.get_nearest_class voxcity.utils.lc.get_dominant_class voxcity.utils.lc.convert_land_cover_array Module Contents --------------- .. py:function:: get_land_cover_classes(source) Get land cover classification mapping for a specific data source. Each data source has its own color-to-class mapping system. This function returns the appropriate RGB color to land cover class dictionary based on the specified source. :param source: Name of the land cover data source. Supported sources: "Urbanwatch", "OpenEarthMapJapan", "ESRI 10m Annual Land Cover", "ESA WorldCover", "Dynamic World V1", "Standard", "OpenStreetMap" :type source: str :returns: Dictionary mapping RGB tuples to land cover class names :rtype: dict .. rubric:: Example >>> classes = get_land_cover_classes("Urbanwatch") >>> print(classes[(255, 0, 0)]) # Returns 'Building' .. py:function:: get_source_class_descriptions(source) Get a formatted string describing land cover classes for a specific source. :param source: Name of the land cover data source. :type source: str :returns: Formatted string describing the source's land cover classes. :rtype: str .. py:function:: convert_land_cover(input_array, land_cover_source='Urbanwatch') Optimized version using direct numpy array indexing instead of np.vectorize. This is 10-100x faster than the original. Returns 1-based class indices (1-14) for consistency with voxel representations. .. py:function:: get_class_priority(source) Get priority rankings for land cover classes to resolve conflicts during classification. When multiple land cover classes are present in the same area, this priority system determines which class should take precedence. Higher priority values indicate classes that should override lower priority classes. :param source: Name of the land cover data source :type source: str :returns: Dictionary mapping class names to priority values (higher = more priority) :rtype: dict Priority Logic for OpenStreetMap: - Built Environment: Highest priority (most definitive structures) - Water Bodies: High priority (clearly defined features) - Vegetation: Medium priority (managed vs natural) - Natural Non-Vegetation: Lower priority (often default classifications) - Uncertain/No Data: Lowest priority .. py:function:: create_land_cover_polygons(land_cover_geojson) Create polygon geometries and spatial index from land cover GeoJSON data. This function processes GeoJSON land cover data to create Shapely polygon geometries and builds an R-tree spatial index for efficient spatial queries. :param land_cover_geojson: List of GeoJSON feature dictionaries containing land cover polygons with geometry and properties :type land_cover_geojson: list :returns: A tuple containing: - land_cover_polygons (list): List of tuples (polygon, class_name) - idx (rtree.index.Index): Spatial index for efficient polygon lookup :rtype: tuple .. note:: Each GeoJSON feature should have: - geometry.coordinates[0]: List of coordinate pairs defining the polygon - properties.class: String indicating the land cover class .. py:function:: get_nearest_class(pixel, land_cover_classes) Find the nearest land cover class for a given pixel color using RGB distance. This function determines the most appropriate land cover class for a pixel by finding the class with the minimum RGB color distance to the pixel's color. :param pixel: RGB color values as (R, G, B) tuple :type pixel: tuple :param land_cover_classes: Dictionary mapping RGB tuples to class names :type land_cover_classes: dict :returns: Name of the nearest land cover class :rtype: str .. rubric:: Example >>> classes = {(255, 0, 0): 'Building', (0, 255, 0): 'Tree'} >>> nearest = get_nearest_class((250, 5, 5), classes) >>> print(nearest) # Returns 'Building' .. py:function:: get_dominant_class(cell_data, land_cover_classes) Determine the dominant land cover class in a cell based on pixel majority. This function analyzes all pixels within a cell, classifies each pixel to its nearest land cover class, and returns the most frequently occurring class. :param cell_data: 3D array of RGB pixel data for the cell :type cell_data: numpy.ndarray :param land_cover_classes: Dictionary mapping RGB tuples to class names :type land_cover_classes: dict :returns: Name of the dominant land cover class in the cell :rtype: str .. note:: If the cell contains no data, returns 'No Data' .. py:function:: convert_land_cover_array(input_array, land_cover_classes) Convert an array of land cover class names to integer indices. This function maps string-based land cover class names to integer indices for numerical processing and storage efficiency. :param input_array: Array containing land cover class names as strings :type input_array: numpy.ndarray :param land_cover_classes: Dictionary mapping RGB tuples to class names :type land_cover_classes: dict :returns: Array with 0-based integer indices corresponding to land cover classes :rtype: numpy.ndarray .. note:: Classes not found in the mapping are assigned index -1 Indices are 0-based as source-specific indices. Use convert_land_cover() to remap to standard 1-based indices for voxel representation.