voxcity.downloader.citygml¶

CityGML Parser Module for PLATEAU Data

This module provides functionality to parse CityGML files from Japan’s PLATEAU dataset, extracting building footprints, terrain information, and vegetation data. The module handles various LOD (Level of Detail) representations and coordinate systems.

Main features: - Download and extract PLATEAU data from URLs - Parse CityGML files for buildings, terrain, and vegetation - Handle coordinate transformations and validations - Support for mesh code decoding

Functions¶

`decode_2nd_level_mesh`(mesh6)	Decode a standard (2nd-level) mesh code to geographic coordinates.
`decode_mesh_code`(mesh_str)	Decode mesh codes into geographic boundary coordinates.
`get_tile_polygon_from_filename`(filename)	Extract and decode mesh code from PLATEAU filename into boundary polygon.
`download_and_extract_zip`(url[, extract_to, ...])	Download and extract a zip file from a URL to specified directory.
`validate_coords`(coords)	Validate that coordinates are finite numbers.
`swap_coordinates`(polygon)	Swap coordinate order in a polygon (lat/lon to lon/lat or vice versa).
`extract_terrain_info`(file_path, namespaces)	Extract terrain elevation data from CityGML file.
`extract_vegetation_info`(file_path, namespaces)	Extract vegetation features from CityGML file.
`extract_building_footprint`(building, namespaces)	Extract building footprint from CityGML building element.
`process_citygml_file`(file_path)	Process a CityGML file to extract all relevant features.
`parse_file`(file_path[, file_type])	Parse a file based on its type (auto-detected or specified).
`swap_coordinates_if_needed`(gdf[, geometry_col])	Ensure correct coordinate order in GeoDataFrame geometries.
`load_buid_dem_veg_from_citygml`([url, base_dir, ...])	Load and process PLATEAU data from URL or local files.

Module Contents¶

voxcity.downloader.citygml.decode_2nd_level_mesh(mesh6)¶

Decode a standard (2nd-level) mesh code to geographic coordinates.

Parameters:

mesh6 (str) – A 6-digit mesh code string.

Returns:

(lat_sw, lon_sw, lat_ne, lon_ne) coordinates in degrees representing: the southwest and northeast corners of the mesh.

Return type:

tuple

Notes

The mesh system divides Japan into a grid of cells
Each 2nd-level mesh is 1/12° latitude × 0.125° longitude

voxcity.downloader.citygml.decode_mesh_code(mesh_str)¶

Decode mesh codes into geographic boundary coordinates.

Parameters:: mesh_str (str) – A mesh code string (6 or 8 digits).
Returns:: List of (lon, lat) tuples forming a closed polygon in WGS84.
Return type:: list
Raises:: ValueError – If mesh code length is invalid or unsupported.

Notes

6-digit codes represent standard 2nd-level mesh
8-digit codes represent 2nd-level mesh subdivided 10×10

voxcity.downloader.citygml.get_tile_polygon_from_filename(filename)¶

Extract and decode mesh code from PLATEAU filename into boundary polygon.

Parameters:: filename (str) – PLATEAU format filename (e.g. ‘51357348_bldg_6697_op.gml’)
Returns:: List of (lon, lat) tuples forming the tile boundary polygon in WGS84.
Return type:: list
Raises:: ValueError – If no mesh code found in filename.

voxcity.downloader.citygml.download_and_extract_zip(url, extract_to='.', ssl_verify=True, ca_bundle=None, timeout=60)¶

Download and extract a zip file from a URL to specified directory.

Parameters:

url (str) – URL of the zip file to download.
extract_to (str) – Directory to extract files to (default: current directory).
ssl_verify (bool) – Whether to verify SSL certificates (default: True).
ca_bundle (str|None) – Path to a CA bundle file. Overrides verify when provided.
timeout (int|float) – Request timeout in seconds (default: 60).

Returns:

(extraction_path, folder_name) where files were extracted.

Return type:

tuple

Notes

Creates a subdirectory named after the zip file (without .zip)
Prints status messages for success/failure

voxcity.downloader.citygml.validate_coords(coords)¶

Validate that coordinates are finite numbers.

Parameters:: coords (list) – List of coordinate tuples.
Returns:: True if all coordinates are valid (not inf/NaN), False otherwise.
Return type:: bool

voxcity.downloader.citygml.swap_coordinates(polygon)¶

Swap coordinate order in a polygon (lat/lon to lon/lat or vice versa).

Parameters:: polygon (Polygon/MultiPolygon) – Input polygon with coordinates to swap.
Returns:: New polygon with swapped coordinates.
Return type:: Polygon/MultiPolygon

Notes

Handles both single Polygon and MultiPolygon geometries
Creates new geometry objects rather than modifying in place

voxcity.downloader.citygml.extract_terrain_info(file_path, namespaces)¶

Extract terrain elevation data from CityGML file.

Parameters:

file_path (str) – Path to CityGML file.
namespaces (dict) – XML namespace mappings.

Returns:

List of dictionaries containing terrain features:

relief_id: Feature identifier
tin_id: TIN surface identifier
triangle_id/breakline_id/mass_point_id: Specific element ID
elevation: Height value
geometry: Shapely geometry object
source_file: Original file name

Return type:

list

Notes

Processes TIN Relief, breaklines, and mass points
Validates all geometries before inclusion
Handles coordinate conversion and validation

voxcity.downloader.citygml.extract_vegetation_info(file_path, namespaces)¶

Extract vegetation features from CityGML file.

Parameters:

file_path (str) – Path to CityGML file.
namespaces (dict) – XML namespace mappings.

Returns:

List of dictionaries containing vegetation features:

object_type: ‘PlantCover’ or ‘SolitaryVegetationObject’
vegetation_id: Feature identifier
height: Vegetation height (if available)
geometry: Shapely geometry object
source_file: Original file name

Return type:

list

Notes

Handles both PlantCover and SolitaryVegetationObject features
Processes multiple LOD representations
Validates geometries before inclusion

voxcity.downloader.citygml.extract_building_footprint(building, namespaces)¶

Extract building footprint from CityGML building element.

Parameters:

building (Element) – XML element representing a building.
namespaces (dict) – XML namespace mappings.

Returns:

(pos_list, ground_elevation) where:

pos_list: XML element containing footprint coordinates
ground_elevation: Ground level elevation if available

Return type:

tuple

Notes

Tries multiple LOD representations (LOD0-LOD2)
For LOD1/LOD2 solids, finds the bottom face
Returns None if no valid footprint found

voxcity.downloader.citygml.process_citygml_file(file_path)¶

Process a CityGML file to extract all relevant features.

Parameters:

file_path (str) – Path to CityGML file.

Returns:

(buildings, terrain_elements, vegetation_elements) where each is a list: of dictionaries containing feature information.

Return type:

tuple

Notes

Processes buildings, terrain, and vegetation features
Validates all geometries
Handles coordinate transformations
Includes error handling and reporting

voxcity.downloader.citygml.parse_file(file_path, file_type=None)¶

Parse a file based on its type (auto-detected or specified).

Parameters:

file_path (str) – Path to file to parse.
file_type (str, optional) – Force specific file type parsing. Valid values: ‘citygml’, ‘geojson’, ‘xml’

Returns:

(buildings, terrain_elements, vegetation_elements) lists.

Return type:

tuple

Notes

Auto-detects file type from extension if not specified
Currently fully implements CityGML parsing only
Returns empty lists for unsupported types

voxcity.downloader.citygml.swap_coordinates_if_needed(gdf, geometry_col='geometry')¶

Ensure correct coordinate order in GeoDataFrame geometries.

Parameters:

gdf (GeoDataFrame) – Input GeoDataFrame.
geometry_col (str) – Name of geometry column.

Returns:

List of geometries with corrected coordinate order.

Return type:

list

Notes

Assumes input is EPSG:6697 but may be in lat-lon order
Handles Polygon, MultiPolygon, and Point geometries
Returns geometries in lon-lat order

voxcity.downloader.citygml.load_buid_dem_veg_from_citygml(url=None, base_dir='.', citygml_path=None, rectangle_vertices=None, ssl_verify=True, ca_bundle=None, timeout=60)¶

Load and process PLATEAU data from URL or local files.

Parameters:

url (str, optional) – URL to download PLATEAU data from.
base_dir (str) – Base directory for file operations.
citygml_path (str, optional) – Path to local CityGML files.
rectangle_vertices (list, optional) – List of (lon, lat) tuples defining a bounding rectangle for filtering tiles.

Returns:

(gdf_buildings, gdf_terrain, gdf_vegetation) GeoDataFrames: containing processed features.

Return type:

tuple

Notes

Can process from URL (download & extract) or local files
Optionally filters tiles by geographic extent
Handles coordinate transformations
Creates GeoDataFrames with proper CRS