voxcity.utils.lc¶

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¶

`get_land_cover_classes`(source)	Get land cover classification mapping for a specific data source.
`get_source_class_descriptions`(source)	Get a formatted string describing land cover classes for a specific source.
`convert_land_cover`(input_array[, land_cover_source])	Optimized version using direct numpy array indexing instead of np.vectorize.
`get_class_priority`(source)	Get priority rankings for land cover classes to resolve conflicts during classification.
`create_land_cover_polygons`(land_cover_geojson)	Create polygon geometries and spatial index from land cover GeoJSON data.
`get_nearest_class`(pixel, land_cover_classes)	Find the nearest land cover class for a given pixel color using RGB distance.
`get_dominant_class`(cell_data, land_cover_classes)	Determine the dominant land cover class in a cell based on pixel majority.
`convert_land_cover_array`(input_array, land_cover_classes)	Convert an array of land cover class names to integer indices.

Module Contents¶

voxcity.utils.lc.get_land_cover_classes(source)[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.

Parameters:: source (str) – Name of the land cover data source. Supported sources: “Urbanwatch”, “OpenEarthMapJapan”, “ESRI 10m Annual Land Cover”, “ESA WorldCover”, “Dynamic World V1”, “Standard”, “OpenStreetMap”
Returns:: Dictionary mapping RGB tuples to land cover class names
Return type:: dict

Example

>>> classes = get_land_cover_classes("Urbanwatch")
>>> print(classes[(255, 0, 0)])  # Returns 'Building'

voxcity.utils.lc.get_source_class_descriptions(source)[source]¶

Get a formatted string describing land cover classes for a specific source.

Parameters:: source (str) – Name of the land cover data source.
Returns:: Formatted string describing the source’s land cover classes.
Return type:: str

voxcity.utils.lc.convert_land_cover(input_array, land_cover_source='Urbanwatch')[source]¶

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.

voxcity.utils.lc.get_class_priority(source)[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.

Parameters:: source (str) – Name of the land cover data source
Returns:: Dictionary mapping class names to priority values (higher = more priority)
Return type:: 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

voxcity.utils.lc.create_land_cover_polygons(land_cover_geojson)[source]¶

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.

Parameters:

land_cover_geojson (list) – List of GeoJSON feature dictionaries containing land cover polygons with geometry and properties

Returns:

A tuple containing:

land_cover_polygons (list): List of tuples (polygon, class_name)
idx (rtree.index.Index): Spatial index for efficient polygon lookup

Return type:

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

voxcity.utils.lc.get_nearest_class(pixel, land_cover_classes)[source]¶

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.

Parameters:

pixel (tuple) – RGB color values as (R, G, B) tuple
land_cover_classes (dict) – Dictionary mapping RGB tuples to class names

Returns:

Name of the nearest land cover class

Return type:

str

Example

>>> classes = {(255, 0, 0): 'Building', (0, 255, 0): 'Tree'}
>>> nearest = get_nearest_class((250, 5, 5), classes)
>>> print(nearest)  # Returns 'Building'

voxcity.utils.lc.get_dominant_class(cell_data, land_cover_classes)[source]¶

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.

Parameters:

cell_data (numpy.ndarray) – 3D array of RGB pixel data for the cell
land_cover_classes (dict) – Dictionary mapping RGB tuples to class names

Returns:

Name of the dominant land cover class in the cell

Return type:

str

Note

If the cell contains no data, returns ‘No Data’

voxcity.utils.lc.convert_land_cover_array(input_array, land_cover_classes)[source]¶

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.

Parameters:

input_array (numpy.ndarray) – Array containing land cover class names as strings
land_cover_classes (dict) – Dictionary mapping RGB tuples to class names

Returns:

Array with 0-based integer indices corresponding to land cover classes

Return type:

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.