voxcity 0.6.26__py3-none-any.whl → 0.7.0__py3-none-any.whl

voxcity/__init__.py

@@ -1,8 +1,14 @@
-__author__ = """Kunihiko Fujiwara"""
-__email__ = 'kunihiko@nus.edu.sg'
-__version__ = '0.1.0'
-
-# from .generator import *
-# from .download import mbfp
-# # from .utils.draw import rotate_rectangle, draw_rectangle_map
-# from .geo import draw, utils
+__author__ = """Kunihiko Fujiwara"""
+__email__ = 'kunihiko@nus.edu.sg'
+__version__ = '0.1.0'
+
+# Keep package __init__ lightweight to avoid import-time failures.
+# Re-exports of heavy modules/classes are intentionally omitted here.
+# Downstream modules should import directly from their subpackages, e.g.:
+#   from voxcity.geoprocessor.draw import draw_rectangle_map_cityname
+
+__all__ = [
+    "__author__",
+    "__email__",
+    "__version__",
+]

voxcity/downloader/__init__.py

@@ -4,4 +4,5 @@ from .gee import *
 from .osm import *
 from .oemj import *
 from .eubucco import *
-from .overture import *
+from .overture import *
+from .gba import *

voxcity/downloader/gba.py

@@ -0,0 +1,210 @@
+"""
+Downloader for Global Building Atlas (GBA) LOD1 polygons.
+
+This module downloads GeoParquet tiles from the Global Building Atlas (GBA)
+hosted at data.source.coop, selects tiles intersecting a user-specified
+rectangle, loads them into a GeoDataFrame, and filters features to the
+rectangle extent.
+
+Tile scheme:
+- Global 5x5-degree tiles named like: e010_n50_e015_n45.parquet
+  - longitudes: e/w with 3-digit zero padding (e.g., e010, w060)
+  - latitudes: n/s with 2-digit zero padding (e.g., n50, s25)
+  - filename order: west_lon, north_lat, east_lon, south_lat
+
+Usage:
+    gdf = load_gdf_from_gba(rectangle_vertices=[(lon1, lat1), (lon2, lat2), ...])
+
+Notes:
+- Output CRS is EPSG:4326.
+- Requires pyarrow or fastparquet for parquet reading via GeoPandas.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import tempfile
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+import geopandas as gpd
+import pandas as pd
+import requests
+from shapely.geometry import Polygon
+
+
+def _bbox_from_rectangle_vertices(vertices: Sequence[Tuple[float, float]]) -> Tuple[float, float, float, float]:
+    """
+    Convert rectangle vertices in (lon, lat) into bbox as (min_lon, min_lat, max_lon, max_lat).
+    """
+    if not vertices:
+        raise ValueError("rectangle_vertices must be a non-empty sequence of (lon, lat)")
+    lons = [v[0] for v in vertices]
+    lats = [v[1] for v in vertices]
+    return (min(lons), min(lats), max(lons), max(lats))
+
+
+def _pad_lon(deg: int) -> str:
+    return f"{abs(deg):03d}"
+
+
+def _pad_lat(deg: int) -> str:
+    return f"{abs(deg):02d}"
+
+
+def _lon_tag(deg: int) -> str:
+    return ("e" if deg >= 0 else "w") + _pad_lon(deg)
+
+
+def _lat_tag(deg: int) -> str:
+    return ("n" if deg >= 0 else "s") + _pad_lat(deg)
+
+
+def _snap_down(value: float, step: int) -> int:
+    return int(math.floor(value / step) * step)
+
+
+def _snap_up(value: float, step: int) -> int:
+    return int(math.ceil(value / step) * step)
+
+
+def _generate_tile_bounds_for_bbox(
+    min_lon: float, min_lat: float, max_lon: float, max_lat: float, tile_size_deg: int = 5
+) -> Iterable[Tuple[int, int, int, int]]:
+    """
+    Generate 5-degree tile bounds (west, south, east, north) covering bbox.
+    All values are integer degrees aligned to tile_size_deg.
+    """
+    west = _snap_down(min_lon, tile_size_deg)
+    east = _snap_up(max_lon, tile_size_deg)
+    south = _snap_down(min_lat, tile_size_deg)
+    north = _snap_up(max_lat, tile_size_deg)
+
+    for lon in range(west, east, tile_size_deg):
+        for lat in range(south, north, tile_size_deg):
+            yield (lon, lat, lon + tile_size_deg, lat + tile_size_deg)
+
+
+def _tile_filename(west: int, south: int, east: int, north: int) -> str:
+    """
+    Construct GBA tile filename for given integer-degree bounds.
+    Naming convention examples:
+      e010_n50_e015_n45.parquet
+      e140_s25_e145_s30.parquet
+      w060_s30_w055_s35.parquet
+    """
+    return f"{_lon_tag(west)}_{_lat_tag(north)}_{_lon_tag(east)}_{_lat_tag(south)}.parquet"
+
+
+def _tile_url(base_url: str, west: int, south: int, east: int, north: int) -> str:
+    filename = _tile_filename(west, south, east, north)
+    return f"{base_url.rstrip('/')}/{filename}"
+
+
+def _download_parquet(url: str, download_dir: str, timeout: int = 60) -> Optional[str]:
+    """
+    Download a parquet file to download_dir. Returns local filepath or None if not found.
+    """
+    try:
+        with requests.get(url, stream=True, timeout=timeout) as r:
+            if r.status_code != 200:
+                return None
+            filename = os.path.basename(url)
+            local_path = os.path.join(download_dir, filename)
+            with open(local_path, "wb") as f:
+                for chunk in r.iter_content(chunk_size=1024 * 1024):
+                    if chunk:
+                        f.write(chunk)
+        return local_path
+    except requests.RequestException:
+        return None
+
+
+def _filter_to_rectangle(gdf: gpd.GeoDataFrame, rectangle: Polygon, clip: bool) -> gpd.GeoDataFrame:
+    gdf = gdf[gdf.geometry.notnull()].copy()
+    # Ensure CRS is WGS84
+    if gdf.crs is None:
+        gdf.set_crs(epsg=4326, inplace=True)
+    elif gdf.crs.to_epsg() != 4326:
+        gdf = gdf.to_crs(epsg=4326)
+
+    intersects = gdf.intersects(rectangle)
+    gdf = gdf[intersects].copy()
+    if clip and not gdf.empty:
+        # GeoPandas clip performs overlay to trim geometries to rectangle
+        gdf = gpd.clip(gdf, gpd.GeoSeries([rectangle], crs="EPSG:4326").to_frame("geometry"))
+    return gdf
+
+
+def load_gdf_from_gba(
+    rectangle_vertices: Sequence[Tuple[float, float]],
+    base_url: str = "https://data.source.coop/tge-labs/globalbuildingatlas-lod1",
+    download_dir: Optional[str] = None,
+    clip_to_rectangle: bool = False,
+) -> Optional[gpd.GeoDataFrame]:
+    """
+    Download GBA tiles intersecting a rectangle and return combined GeoDataFrame.
+
+    Args:
+        rectangle_vertices: Sequence of (lon, lat) defining the area of interest.
+        base_url: Base URL hosting GBA parquet tiles.
+        download_dir: Optional directory to store downloaded tiles. If None, a
+                      temporary directory is used and cleaned up by the OS later.
+        clip_to_rectangle: If True, geometries are clipped to rectangle extent.
+
+    Returns:
+        GeoDataFrame with EPSG:4326 geometry and an 'id' column, or None if no data.
+    """
+    min_lon, min_lat, max_lon, max_lat = _bbox_from_rectangle_vertices(rectangle_vertices)
+    rectangle = Polygon([
+        (min_lon, min_lat),
+        (max_lon, min_lat),
+        (max_lon, max_lat),
+        (min_lon, max_lat),
+        (min_lon, min_lat),
+    ])
+
+    tmp_dir_created = False
+    if download_dir is None:
+        download_dir = tempfile.mkdtemp(prefix="gba_tiles_")
+        tmp_dir_created = True
+    else:
+        os.makedirs(download_dir, exist_ok=True)
+
+    local_files: List[str] = []
+    for west, south, east, north in _generate_tile_bounds_for_bbox(min_lon, min_lat, max_lon, max_lat):
+        url = _tile_url(base_url, west, south, east, north)
+        local = _download_parquet(url, download_dir)
+        if local is not None:
+            local_files.append(local)
+
+    if not local_files:
+        return None
+
+    gdfs: List[gpd.GeoDataFrame] = []
+    for path in local_files:
+        try:
+            # GeoParquet read
+            gdf = gpd.read_parquet(path)
+            if gdf is not None and not gdf.empty:
+                gdfs.append(gdf)
+        except Exception:
+            # Skip unreadable tiles
+            continue
+
+    if not gdfs:
+        return None
+
+    combined = pd.concat(gdfs, ignore_index=True)
+    combined = gpd.GeoDataFrame(combined, geometry="geometry")
+    combined = _filter_to_rectangle(combined, rectangle, clip=clip_to_rectangle)
+
+    if combined.empty:
+        return None
+
+    # Ensure sequential ids
+    combined["id"] = combined.index.astype(int)
+    combined.set_crs(epsg=4326, inplace=True, allow_override=True)
+    return combined
+
+

voxcity/downloader/gee.py

@@ -217,7 +217,11 @@ def get_dem_image(roi_buffered, source):
     #     dem = collection.mosaic() 
 
     # elif source == 'FABDEM':
-    return dem.clip(roi_buffered)
+    # If we reach here without assigning `dem`, the source is unsupported
+    try:
+        return dem.clip(roi_buffered)
+    except UnboundLocalError:
+        raise ValueError(f"Unsupported or unimplemented DEM source: {source}")
 
 def save_geotiff_esa_land_cover(roi, geotiff_path):
     """Save ESA WorldCover land cover data as a colored GeoTIFF.

voxcity/downloader/mbfp.py

@@ -20,7 +20,7 @@ import pandas as pd
 import os
 from .utils import download_file
 from ..geoprocessor.utils import tile_from_lat_lon, quadkey_to_tile
-from ..geoprocessor.polygon import load_gdf_from_multiple_gz, swap_coordinates
+from ..geoprocessor.io import load_gdf_from_multiple_gz, swap_coordinates
 
 def get_geojson_links(output_dir):
     """Download and load the dataset links CSV file containing building footprint URLs.

voxcity/downloader/oemj.py

@@ -19,6 +19,7 @@ Example Usage:
 """
 
 import requests
+import os
 from PIL import Image, ImageDraw
 from io import BytesIO
 import math
@@ -73,7 +74,7 @@ def num2deg(xtile, ytile, zoom):
     lat_deg = math.degrees(lat_rad)
     return (lon_deg, lat_deg)
 
-def download_tiles(polygon, zoom):
+def download_tiles(polygon, zoom, *, ssl_verify=True, allow_insecure_ssl=False, allow_http_fallback=False, timeout_s=30):
     """Download satellite imagery tiles covering a polygon region.
     
     Downloads all tiles that intersect with the given polygon at the specified zoom level
@@ -112,11 +113,70 @@ def download_tiles(polygon, zoom):
     for x in range(min(min_x, max_x), max(min_x, max_x) + 1):
         for y in range(min(min_y, max_y), max(min_y, max_y) + 1):
             url = f"https://www.open-earth-map.org/demo/Japan/{zoom}/{x}/{y}.png"
-            response = requests.get(url)
-            if response.status_code == 200:
-                tiles[(x, y)] = Image.open(BytesIO(response.content))
-            else:
-                print(f"Failed to download tile: {url}")
+            # Try secure HTTPS first with user-provided verification option
+            content = None
+            try:
+                resp = requests.get(url, timeout=timeout_s, verify=ssl_verify)
+                if resp.status_code == 200:
+                    content = resp.content
+                else:
+                    print(f"Failed to download tile (status {resp.status_code}): {url}")
+            except requests.exceptions.SSLError:
+                # Optionally retry with certificate verification disabled
+                if allow_insecure_ssl:
+                    try:
+                        resp = requests.get(url, timeout=timeout_s, verify=False)
+                        if resp.status_code == 200:
+                            content = resp.content
+                        else:
+                            print(f"Failed to download tile (status {resp.status_code}) with insecure SSL: {url}")
+                    except requests.exceptions.RequestException as e:
+                        # Optionally try HTTP fallback
+                        if allow_http_fallback and url.lower().startswith("https://"):
+                            http_url = "http://" + url.split("://", 1)[1]
+                            try:
+                                resp = requests.get(http_url, timeout=timeout_s)
+                                if resp.status_code == 200:
+                                    content = resp.content
+                                else:
+                                    print(f"Failed to download tile over HTTP (status {resp.status_code}): {http_url}")
+                            except requests.exceptions.RequestException as e2:
+                                print(f"HTTP fallback failed for tile: {http_url} ({e2})")
+                        else:
+                            print(f"SSL error downloading tile: {url} ({e})")
+                else:
+                    if allow_http_fallback and url.lower().startswith("https://"):
+                        http_url = "http://" + url.split("://", 1)[1]
+                        try:
+                            resp = requests.get(http_url, timeout=timeout_s)
+                            if resp.status_code == 200:
+                                content = resp.content
+                            else:
+                                print(f"Failed to download tile over HTTP (status {resp.status_code}): {http_url}")
+                        except requests.exceptions.RequestException as e:
+                            print(f"HTTP fallback failed for tile: {http_url} ({e})")
+                    else:
+                        print(f"SSL error downloading tile: {url}")
+            except requests.exceptions.RequestException as e:
+                # Network error (timeout/connection). Try HTTP if allowed.
+                if allow_http_fallback and url.lower().startswith("https://"):
+                    http_url = "http://" + url.split("://", 1)[1]
+                    try:
+                        resp = requests.get(http_url, timeout=timeout_s)
+                        if resp.status_code == 200:
+                            content = resp.content
+                        else:
+                            print(f"Failed to download tile over HTTP (status {resp.status_code}): {http_url}")
+                    except requests.exceptions.RequestException as e2:
+                        print(f"HTTP fallback failed for tile: {http_url} ({e2})")
+                else:
+                    print(f"Error downloading tile: {url} ({e})")
+
+            if content is not None:
+                try:
+                    tiles[(x, y)] = Image.open(BytesIO(content))
+                except Exception as e:
+                    print(f"Error decoding tile image for {url}: {e}")
     
     return tiles, (min(min_x, max_x), min(min_y, max_y), max(min_x, max_x), max(min_y, max_y))
 
@@ -231,6 +291,11 @@ def save_as_geotiff(image, polygon, zoom, bbox, bounds, output_path):
     pixel_size_x = (lower_right_x - upper_left_x) / image.width
     pixel_size_y = (upper_left_y - lower_right_y) / image.height
     
+    # Ensure output directory exists
+    out_dir = os.path.dirname(output_path)
+    if out_dir:
+        os.makedirs(out_dir, exist_ok=True)
+
     # Create GeoTIFF
     driver = gdal.GetDriverByName('GTiff')
     dataset = driver.Create(output_path, image.width, image.height, 3, gdal.GDT_Byte)
@@ -249,7 +314,7 @@ def save_as_geotiff(image, polygon, zoom, bbox, bounds, output_path):
     
     dataset = None
 
-def save_oemj_as_geotiff(polygon, filepath, zoom=16):
+def save_oemj_as_geotiff(polygon, filepath, zoom=16, *, ssl_verify=True, allow_insecure_ssl=False, allow_http_fallback=False, timeout_s=30):
     """Download and save OpenEarthMap Japan imagery as a georeferenced GeoTIFF file.
     
     This is the main function that orchestrates the entire process of downloading,
@@ -281,7 +346,14 @@ def save_oemj_as_geotiff(polygon, filepath, zoom=16):
         - The output GeoTIFF will be in Web Mercator projection (EPSG:3857)
     """
     try:
-        tiles, bounds = download_tiles(polygon, zoom)
+        tiles, bounds = download_tiles(
+            polygon,
+            zoom,
+            ssl_verify=ssl_verify,
+            allow_insecure_ssl=allow_insecure_ssl,
+            allow_http_fallback=allow_http_fallback,
+            timeout_s=timeout_s,
+        )
         if not tiles:
             raise ValueError("No tiles were downloaded. Please check the polygon coordinates and zoom level.")
 

voxcity/downloader/utils.py

@@ -1,74 +1,74 @@
-# Utility functions for downloading files from various sources
-import requests
-import gdown
-
-def download_file(url, filename):
-    """Download a file from a URL and save it locally.
-    
-    This function uses the requests library to download a file from any publicly 
-    accessible URL and save it to the local filesystem. It handles the download 
-    process and provides feedback on the operation's success or failure.
-    
-    Args:
-        url (str): URL of the file to download. Must be a valid, accessible URL.
-        filename (str): Local path where the downloaded file will be saved.
-                       Include the full path and filename with extension.
-        
-    Returns:
-        None
-        
-    Prints:
-        - Success message with filename if download is successful (status code 200)
-        - Error message with status code if download fails
-        
-    Example:
-        >>> download_file('https://example.com/file.pdf', 'local_file.pdf')
-        File downloaded successfully and saved as local_file.pdf
-    """
-    # Attempt to download the file from the provided URL
-    response = requests.get(url)
-    
-    # Check if the download was successful (HTTP status code 200)
-    if response.status_code == 200:
-        # Open the local file in binary write mode and save the content
-        with open(filename, 'wb') as file:
-            file.write(response.content)
-        print(f"File downloaded successfully and saved as {filename}")
-    else:
-        print(f"Failed to download file. Status code: {response.status_code}")
-
-def download_file_google_drive(file_id, output_path):
-    """Download a file from Google Drive using its file ID.
-    
-    This function specifically handles downloads from Google Drive using the gdown
-    library, which is designed to bypass Google Drive's download restrictions.
-    It's useful for downloading large files or files that require authentication.
-    
-    Args:
-        file_id (str): Google Drive file ID. This is the unique identifier in the 
-                       sharing URL after '/d/' or 'id='.
-        output_path (str): Local path where the downloaded file will be saved.
-                          Include the full path and filename with extension.
-        
-    Returns:
-        bool: True if download was successful, False if any error occurred
-        
-    Prints:
-        Error message with exception details if download fails
-        
-    Example:
-        >>> success = download_file_google_drive('1234abcd...', 'downloaded_file.zip')
-        >>> if success:
-        >>>     print("Download completed successfully")
-    """
-    # Construct the direct download URL using the file ID
-    url = f"https://drive.google.com/uc?id={file_id}"
-    
-    try:
-        # Use gdown to handle the Google Drive download
-        # quiet=False enables download progress display
-        gdown.download(url, output_path, quiet=False)
-        return True
-    except Exception as e:
-        print(f"Error downloading file {file_id}: {str(e)}")
+# Utility functions for downloading files from various sources
+import requests
+import gdown
+
+def download_file(url, filename):
+    """Download a file from a URL and save it locally.
+    
+    This function uses the requests library to download a file from any publicly 
+    accessible URL and save it to the local filesystem. It handles the download 
+    process and provides feedback on the operation's success or failure.
+    
+    Args:
+        url (str): URL of the file to download. Must be a valid, accessible URL.
+        filename (str): Local path where the downloaded file will be saved.
+                       Include the full path and filename with extension.
+        
+    Returns:
+        None
+        
+    Prints:
+        - Success message with filename if download is successful (status code 200)
+        - Error message with status code if download fails
+        
+    Example:
+        >>> download_file('https://example.com/file.pdf', 'local_file.pdf')
+        File downloaded successfully and saved as local_file.pdf
+    """
+    # Attempt to download the file from the provided URL
+    response = requests.get(url)
+    
+    # Check if the download was successful (HTTP status code 200)
+    if response.status_code == 200:
+        # Open the local file in binary write mode and save the content
+        with open(filename, 'wb') as file:
+            file.write(response.content)
+        print(f"File downloaded successfully and saved as {filename}")
+    else:
+        print(f"Failed to download file. Status code: {response.status_code}")
+
+def download_file_google_drive(file_id, output_path):
+    """Download a file from Google Drive using its file ID.
+    
+    This function specifically handles downloads from Google Drive using the gdown
+    library, which is designed to bypass Google Drive's download restrictions.
+    It's useful for downloading large files or files that require authentication.
+    
+    Args:
+        file_id (str): Google Drive file ID. This is the unique identifier in the 
+                       sharing URL after '/d/' or 'id='.
+        output_path (str): Local path where the downloaded file will be saved.
+                          Include the full path and filename with extension.
+        
+    Returns:
+        bool: True if download was successful, False if any error occurred
+        
+    Prints:
+        Error message with exception details if download fails
+        
+    Example:
+        >>> success = download_file_google_drive('1234abcd...', 'downloaded_file.zip')
+        >>> if success:
+        >>>     print("Download completed successfully")
+    """
+    # Construct the direct download URL using the file ID
+    url = f"https://drive.google.com/uc?id={file_id}"
+    
+    try:
+        # Use gdown to handle the Google Drive download
+        # quiet=False enables download progress display
+        gdown.download(url, output_path, quiet=False)
+        return True
+    except Exception as e:
+        print(f"Error downloading file {file_id}: {str(e)}")
         return False

voxcity/errors.py

@@ -0,0 +1,30 @@
+"""
+Package-specific error hierarchy for voxcity.
+
+This enables precise exception handling without leaking low-level
+implementation details across boundaries.
+"""
+
+from __future__ import annotations
+
+
+class VoxCityError(Exception):
+    """Base exception for all voxcity errors."""
+
+
+class ConfigurationError(VoxCityError):
+    """Raised when configuration values are missing or invalid."""
+
+
+class DownloaderError(VoxCityError):
+    """Raised by downloader modules when remote data retrieval fails."""
+
+
+class ProcessingError(VoxCityError):
+    """Raised for failures during grid/voxel processing or geoprocessing."""
+
+
+class VisualizationError(VoxCityError):
+    """Raised for visualization/rendering failures."""
+
+

voxcity/exporter/__init__.py

@@ -1,5 +1,13 @@
-from .envimet import *
-from .magicavoxel import *
-from .obj import *
-from .cityles import *
-from .netcdf import *
+from typing import Protocol, runtime_checkable
+
+from .envimet import *
+from .magicavoxel import *
+from .obj import *
+from .cityles import *
+from .netcdf import *
+
+
+@runtime_checkable
+class Exporter(Protocol):
+    def export(self, obj, output_directory: str, base_filename: str):  # pragma: no cover - protocol
+        ...