zero2route3d-sdk 0.2.0__py3-none-any.whl

zero2route3d/api.py

@@ -0,0 +1,244 @@
+"""High-level, single-call functional API for zero2route3d.
+
+Enables fast, one-line spatial mobility calculations directly from coordinates,
+GeoJSON files, or GeoPandas DataFrames without manual engine instantiation.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+from .environmental_raster import EnvironmentalSurfaceSampler, MCDAWeights
+from .isochrone_engine import IsochroneEngine3D, IsochroneResult
+from .map_matching_3d import GPXPoint, HMMMapMatcher3D, MapMatching3DResult
+from .mobility_profiles import MobilityProfile, resolve_profile
+from .network_source import NetworkSourceManager, RoadSegment
+from .pareto_router import ParetoFrontierResult, ParetoMultiObjectiveRouter
+from .routing_engine import RouteResult3D, RoutingEngine3D, Waypoint
+
+#: Anything the helpers below accept as a road network.
+NetworkInput = Union[str, Path, Sequence[RoadSegment], Dict[str, Any], Any]
+#: A registered profile key, or a ready-made (possibly custom) MobilityProfile.
+ProfileInput = Union[str, MobilityProfile]
+
+__all__ = [
+    "NetworkInput",
+    "ProfileInput",
+    "match_gps_track_3d",
+    "solve_3d_isochrones",
+    "solve_3d_route",
+    "solve_4d_pareto_frontier",
+]
+
+
+def _load_network(network_input: NetworkInput) -> List[RoadSegment]:
+    """Parse road segments from a filepath, GeoJSON dict, segment list or GeoDataFrame.
+
+    Raises ValueError / FileNotFoundError for input that cannot be interpreted.
+    Returning an empty network instead would push the failure downstream, where
+    it resurfaces as a misleading "could not snap origin to network graph".
+    """
+    if isinstance(network_input, (list, tuple)) and network_input:
+        if all(isinstance(item, RoadSegment) for item in network_input):
+            return list(network_input)
+        raise ValueError(
+            "A network given as a sequence must contain RoadSegment objects; got "
+            f"{type(network_input[0]).__name__}."
+        )
+
+    mgr = NetworkSourceManager()
+    if isinstance(network_input, (str, Path)):
+        path = Path(network_input)
+        if not path.exists():
+            raise FileNotFoundError(f"Network file not found: {path}")
+        if path.suffix.lower() not in (".json", ".geojson"):
+            raise ValueError(
+                f"Unsupported network file type '{path.suffix}'. Provide a "
+                ".geojson/.json file, a GeoJSON dict, a GeoDataFrame, or a list "
+                "of RoadSegment objects."
+            )
+        with open(path, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+        return mgr.extract_from_geojson(data)
+
+    if isinstance(network_input, dict):
+        return mgr.extract_from_geojson(network_input)
+
+    # geopandas.GeoDataFrame, duck-typed so geopandas stays an optional import.
+    if hasattr(network_input, "geometry") and hasattr(network_input, "iterfeatures"):
+        from .integrations import from_geodataframe
+
+        return from_geodataframe(network_input)
+
+    raise ValueError(
+        f"Unsupported network input of type {type(network_input).__name__}. Provide "
+        "a GeoJSON path or dict, a geopandas.GeoDataFrame, or a list of RoadSegment "
+        "objects."
+    )
+
+
+def _build_engine(
+    network: NetworkInput,
+    dem_sampler: Optional[EnvironmentalSurfaceSampler] = None,
+    mcda_weights: Optional[MCDAWeights] = None,
+    fetch_online_dem: bool = False,
+) -> RoutingEngine3D:
+    """Load a network into a routing engine, optionally warming the elevation cache."""
+    segments = _load_network(network)
+    if not segments:
+        raise ValueError("The supplied network contains no usable road segments.")
+
+    sampler = dem_sampler or EnvironmentalSurfaceSampler()
+    if fetch_online_dem and not sampler.has_elevation_source:
+        coords = sorted(
+            {(round(pt[0], 5), round(pt[1], 5)) for seg in segments for pt in (seg.p1, seg.p2)}
+        )
+        sampler.prefetch_elevations(coords)
+
+    engine = RoutingEngine3D(sampler=sampler, weights=mcda_weights)
+    engine.build_graph(segments)
+    return engine
+
+
+def _to_waypoint(pt: Any, name: str = "") -> Waypoint:
+    """Coerce a (lon, lat[, elev]) tuple or a Waypoint into a Waypoint."""
+    if isinstance(pt, Waypoint):
+        return pt
+    if isinstance(pt, (tuple, list)) and len(pt) >= 2:
+        return Waypoint(
+            lon=float(pt[0]),
+            lat=float(pt[1]),
+            elevation_m=float(pt[2]) if len(pt) > 2 else 0.0,
+            name=name,
+        )
+    raise ValueError(f"Invalid waypoint {pt!r}: expected (lon, lat[, elevation]) or a Waypoint.")
+
+
+def solve_3d_route(
+    origin: Union[Tuple[float, float], Tuple[float, float, float], Waypoint],
+    destination: Union[Tuple[float, float], Tuple[float, float, float], Waypoint],
+    network: NetworkInput,
+    profile: ProfileInput = "adult",
+    dem_sampler: Optional[EnvironmentalSurfaceSampler] = None,
+    mcda_weights: Optional[MCDAWeights] = None,
+    intermediate_stops: Optional[Sequence[Union[Tuple[float, float], Waypoint]]] = None,
+    optimize_stops_order: bool = False,
+    fetch_online_dem: bool = False,
+) -> RouteResult3D:
+    """Solve a multi-criteria 3D least-cost route in a single call.
+
+    Args:
+        origin: Start (lon, lat) or (lon, lat, elev) or Waypoint.
+        destination: End (lon, lat) or (lon, lat, elev) or Waypoint.
+        network: Road network GeoJSON filepath, dictionary, GeoDataFrame, or RoadSegment list.
+        profile: Profile key (e.g. 'adult', 'wheelchair', 'bicycle') or a MobilityProfile
+            instance -- including a custom one, which is now honoured rather than
+            silently replaced by the default profile.
+        dem_sampler: Optional environmental/elevation raster sampler.
+        mcda_weights: Optional AHP multi-criteria weighting configuration.
+        intermediate_stops: Optional intermediate waypoints.
+        optimize_stops_order: Solve TSP tour over intermediate stops if True.
+        fetch_online_dem: Query Open-Elevation once for every network node when no
+            DEM raster is configured. Needs network access; without it (and without
+            a DEM) the route is computed on flat terrain.
+
+    Returns:
+        RouteResult3D containing 3D coordinates, elevation profile, and rich kinematic statistics.
+
+    Raises:
+        ValueError: if the network or the profile cannot be interpreted.
+    """
+    resolved_profile = resolve_profile(profile, strict=True)
+    engine = _build_engine(network, dem_sampler, mcda_weights, fetch_online_dem)
+
+    waypoints = [_to_waypoint(origin, "Origin")]
+    if intermediate_stops:
+        for idx, stop in enumerate(intermediate_stops, start=1):
+            waypoints.append(_to_waypoint(stop, f"Stop {idx}"))
+    waypoints.append(_to_waypoint(destination, "Destination"))
+
+    return engine.calculate_route(
+        waypoints, profile_key=resolved_profile, optimize_tsp=optimize_stops_order
+    )
+
+
+def solve_3d_isochrones(
+    center: Union[Tuple[float, float], Waypoint],
+    network: NetworkInput,
+    profile: ProfileInput = "adult",
+    time_intervals_min: Sequence[float] = (5.0, 10.0, 15.0),
+    dem_sampler: Optional[EnvironmentalSurfaceSampler] = None,
+    fetch_online_dem: bool = False,
+) -> IsochroneResult:
+    """Compute anisotropic 3D isochrone travel-time wavefront bands from a center point."""
+    resolved_profile = resolve_profile(profile, strict=True)
+    engine = _build_engine(network, dem_sampler, None, fetch_online_dem)
+
+    origin_wp = _to_waypoint(center, "Center")
+
+    iso_engine = IsochroneEngine3D(engine)
+    return iso_engine.compute_isochrones(
+        origin_wp, profile_key=resolved_profile, time_intervals_min=time_intervals_min
+    )
+
+
+def solve_4d_pareto_frontier(
+    origin: Union[Tuple[float, float], Waypoint],
+    destination: Union[Tuple[float, float], Waypoint],
+    network: NetworkInput,
+    profile: ProfileInput = "bicycle",
+    dem_sampler: Optional[EnvironmentalSurfaceSampler] = None,
+    fetch_online_dem: bool = False,
+) -> ParetoFrontierResult:
+    """Compute non-dominated 4D Pareto frontier trade-offs across Time, Climb, Heat, and Calories."""
+    resolved_profile = resolve_profile(profile, strict=True)
+    engine = _build_engine(network, dem_sampler, None, fetch_online_dem)
+
+    start_wp = _to_waypoint(origin, "Origin")
+    end_wp = _to_waypoint(destination, "Destination")
+
+    start_node = engine.find_nearest_node((start_wp.lon, start_wp.lat))
+    end_node = engine.find_nearest_node((end_wp.lon, end_wp.lat))
+
+    if start_node is None or end_node is None:
+        raise ValueError("Could not snap origin or destination to network graph.")
+
+    pareto_router = ParetoMultiObjectiveRouter(engine.nodes, engine.adj, engine.sampler)
+    return pareto_router.solve_pareto_frontier(start_node, end_node, profile_key=resolved_profile)
+
+
+def match_gps_track_3d(
+    gpx_points: Sequence[Union[GPXPoint, Tuple[float, float], Tuple[float, float, float]]],
+    network: NetworkInput,
+    sigma_z: float = 4.07,
+    beta: float = 3.0,
+) -> MapMatching3DResult:
+    """Match noisy GPS/GPX track coordinates onto the 3D road network via HMM Viterbi decoding.
+
+    Args:
+        gpx_points: GPXPoint objects or (lon, lat[, elevation]) tuples.
+        network: Road network, in any form accepted by the other helpers.
+        sigma_z: GPS emission standard deviation in metres.
+        beta: Transition-probability scale for route-vs-crow-fly distance.
+    """
+    engine = _build_engine(network)
+
+    pts: List[GPXPoint] = []
+    for p in gpx_points:
+        if isinstance(p, GPXPoint):
+            pts.append(p)
+        elif isinstance(p, (tuple, list)) and len(p) >= 2:
+            pts.append(
+                GPXPoint(
+                    lon=float(p[0]),
+                    lat=float(p[1]),
+                    elevation_raw_m=float(p[2]) if len(p) > 2 else 0.0,
+                )
+            )
+        else:
+            raise ValueError(f"Invalid GPS point {p!r}: expected (lon, lat[, elevation]).")
+
+    matcher = HMMMapMatcher3D(engine.nodes, engine.adj, sigma_z=sigma_z, beta=beta)
+    return matcher.match_gps_track(pts)

zero2route3d/basemap.py

@@ -0,0 +1,44 @@
+"""OpenStreetMap XYZ tile basemap loader for 02Route 3D."""
+
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+OSM_BASEMAP_NAME = "OpenStreetMap Standard"
+OSM_BASEMAP_PROPERTY = "zero2route3d/osm_basemap"
+OSM_BASEMAP_URI = (
+    "type=xyz&url=https://tile.openstreetmap.org/{z}/{x}/{y}.png&zmin=0&zmax=19&crs=EPSG3857"
+)
+OSM_ATTRIBUTION = "© OpenStreetMap contributors"
+
+
+def add_osm_basemap(project: Any = None) -> Tuple[Any, bool]:
+    """Add or reveal the standard OSM XYZ layer.
+
+    Returns the layer and a boolean indicating whether a new layer was created.
+    """
+    from qgis.core import QgsProject, QgsRasterLayer
+
+    target = project or QgsProject.instance()
+    for layer in target.mapLayers().values():
+        if layer.customProperty(OSM_BASEMAP_PROPERTY, False):
+            layer_tree = target.layerTreeRoot().findLayer(layer.id())
+            if layer_tree is not None:
+                layer_tree.setItemVisibilityChecked(True)
+            return layer, False
+
+    layer = QgsRasterLayer(OSM_BASEMAP_URI, OSM_BASEMAP_NAME, "wms")
+    if not layer.isValid():
+        raise ValueError("QGIS could not create the OpenStreetMap basemap.")
+    layer.setCustomProperty(OSM_BASEMAP_PROPERTY, True)
+    layer.setCustomProperty("zero2route3d/attribution", OSM_ATTRIBUTION)
+    if hasattr(layer, "serverProperties") and layer.serverProperties() is not None:
+        layer.serverProperties().setAttribution(OSM_ATTRIBUTION)
+        layer.serverProperties().setAttributionUrl("https://www.openstreetmap.org/copyright")
+    else:
+        layer.setAttribution(OSM_ATTRIBUTION)
+        layer.setAttributionUrl("https://www.openstreetmap.org/copyright")
+    target.addMapLayer(layer, False)
+    # Insert at the bottom of the layer tree
+    target.layerTreeRoot().insertLayer(len(target.layerTreeRoot().children()), layer)
+    return layer, True

zero2route3d/cli.py

@@ -0,0 +1,251 @@
+"""Command Line Interface (CLI) for zero2route3d.
+
+Provides standalone terminal commands for routing, isochrone generation,
+mobility profile inspection, and 3D format export.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from . import __version__
+from .api import solve_3d_isochrones, solve_3d_route
+from .mobility_profiles import PROFILE_CATEGORIES, PROFILES, list_profile_keys
+
+
+def _parse_coords(coord_str: str) -> Tuple[float, float]:
+    """Parse a 'lon,lat' argument, raising an argparse-friendly error on bad input."""
+    parts = [chunk.strip() for chunk in str(coord_str).split(",")]
+    if len(parts) < 2:
+        raise argparse.ArgumentTypeError(f"Expected 'lon,lat', got '{coord_str}'.")
+    try:
+        lon, lat = float(parts[0]), float(parts[1])
+    except ValueError:
+        raise argparse.ArgumentTypeError(
+            f"Expected numeric 'lon,lat', got '{coord_str}'."
+        ) from None
+    if not (-180.0 <= lon <= 180.0 and -90.0 <= lat <= 90.0):
+        raise argparse.ArgumentTypeError(
+            f"Coordinates out of range: lon={lon}, lat={lat} (expected WGS84 lon,lat)."
+        )
+    return (lon, lat)
+
+
+def _parse_intervals(value: str) -> List[float]:
+    """Parse a comma-separated list of positive minute values."""
+    try:
+        intervals = [float(chunk.strip()) for chunk in str(value).split(",") if chunk.strip()]
+    except ValueError:
+        raise argparse.ArgumentTypeError(
+            f"Expected comma-separated minutes, got '{value}'."
+        ) from None
+    if not intervals or any(minutes <= 0 for minutes in intervals):
+        raise argparse.ArgumentTypeError("Isochrone intervals must be positive minute values.")
+    return intervals
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="zero2route3d",
+        description="02Route 3D - Headless 3D Spatial Mobility & Kinematic Routing Engine",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    p_profiles = subparsers.add_parser(
+        "profiles", help=f"List all {len(PROFILES)} calibrated mobility profiles"
+    )
+    p_profiles.add_argument(
+        "--category",
+        choices=["all", *sorted(PROFILE_CATEGORIES)],
+        default="all",
+        help="Restrict the listing to one profile category.",
+    )
+
+    p_route = subparsers.add_parser(
+        "route", help="Compute 3D least-cost kinematic route between two points"
+    )
+    p_route.add_argument(
+        "--origin", required=True, type=_parse_coords, help="Origin coordinates as 'lon,lat'"
+    )
+    p_route.add_argument(
+        "--dest", required=True, type=_parse_coords, help="Destination coordinates as 'lon,lat'"
+    )
+    p_route.add_argument("--network", required=True, help="Path to road network GeoJSON file")
+    p_route.add_argument(
+        "--profile", default="adult", choices=list_profile_keys(), help="Mobility profile key"
+    )
+    p_route.add_argument(
+        "--dem", help="Optional DEM GeoTIFF used to sample real elevations along the route"
+    )
+    p_route.add_argument(
+        "--fetch-dem",
+        action="store_true",
+        help="Query Open-Elevation for network elevations when no --dem is given (needs network).",
+    )
+    p_route.add_argument("--out-geojson", help="Output GeoJSON filepath")
+    p_route.add_argument("--out-gpx", help="Output GPX 1.1 track filepath")
+    p_route.add_argument("--out-dxf", help="Output AutoCAD DXF 3D Polyline filepath")
+    p_route.add_argument("--out-html", help="Output self-contained interactive HTML report")
+
+    p_iso = subparsers.add_parser(
+        "isochrone", help="Compute 3D anisotropic isochrone wavefront bands"
+    )
+    p_iso.add_argument(
+        "--center", required=True, type=_parse_coords, help="Center coordinates as 'lon,lat'"
+    )
+    p_iso.add_argument("--network", required=True, help="Path to road network GeoJSON file")
+    p_iso.add_argument(
+        "--intervals",
+        default="5,10,15",
+        type=_parse_intervals,
+        help="Comma-separated time intervals in minutes",
+    )
+    p_iso.add_argument("--profile", default="adult", choices=list_profile_keys())
+    p_iso.add_argument("--dem", help="Optional DEM GeoTIFF for real elevation sampling")
+    p_iso.add_argument(
+        "--fetch-dem",
+        action="store_true",
+        help="Query Open-Elevation for network elevations when no --dem is given (needs network).",
+    )
+    p_iso.add_argument("--out-geojson", help="Output GeoJSON filepath")
+
+    return parser
+
+
+def _make_sampler(dem_path: Optional[str]) -> Optional[object]:
+    if not dem_path:
+        return None
+    from .environmental_raster import EnvironmentalSurfaceSampler
+
+    return EnvironmentalSurfaceSampler(dem=dem_path)
+
+
+def _cmd_profiles(args: argparse.Namespace) -> int:
+    if args.category == "all":
+        keys = list_profile_keys()
+        heading = "all categories"
+    else:
+        keys = list(PROFILE_CATEGORIES[args.category]["keys"])
+        heading = str(PROFILE_CATEGORIES[args.category]["title"])
+
+    print(f"=== 02Route 3D Mobility Profiles - {heading} (v{__version__}) ===")
+    header = (
+        f"{'Key':<16} {'Name':<24} {'Category':<15} "
+        f"{'Speed':<12} {'Max Slope':<11} {'Stairs Policy'}"
+    )
+    print(header)
+    print("-" * len(header))
+    for key in keys:
+        prof = PROFILES.get(key)
+        if prof is None:
+            continue
+        stairs = "Allowed" if prof.stair_allowed else "Forbidden"
+        print(
+            f"{prof.key:<16} {prof.name:<24} {prof.category:<15} "
+            f"{prof.base_speed_kmh:>5.1f} km/h {prof.max_slope_pct:>8.1f}%   {stairs}"
+        )
+    return 0
+
+
+def _cmd_route(args: argparse.Namespace) -> int:
+    print(f"Calculating 3D route from {args.origin} to {args.dest} [Profile: {args.profile}]...")
+    result = solve_3d_route(
+        args.origin,
+        args.dest,
+        network=args.network,
+        profile=args.profile,
+        dem_sampler=_make_sampler(args.dem),  # type: ignore[arg-type]
+        fetch_online_dem=args.fetch_dem,
+    )
+
+    if not result.is_network_matched:
+        print(f"Error: {result.status_message}", file=sys.stderr)
+        return 1
+
+    stats = result.statistics
+    print("Success!")
+    print(f"  Distance:         {stats.total_distance_km:.2f} km")
+    print(f"  Duration:         {stats.total_duration_min:.1f} min")
+    print(f"  Elevation Gain:   +{stats.elevation_gain_m:.1f} m")
+    print(f"  Elevation Loss:   -{stats.elevation_loss_m:.1f} m")
+    print(f"  Max Slope:        {stats.max_slope_pct:.1f}%")
+    print(f"  Calories:         {stats.total_calories_kcal:.0f} kcal")
+
+    if args.out_geojson:
+        Path(args.out_geojson).write_text(
+            json.dumps(result.to_geojson_feature(), indent=2), encoding="utf-8"
+        )
+        print(f"  Saved GeoJSON:    {args.out_geojson}")
+
+    if args.out_gpx:
+        Path(args.out_gpx).write_text(result.to_gpx(), encoding="utf-8")
+        print(f"  Saved GPX:        {args.out_gpx}")
+
+    if args.out_dxf:
+        result.to_dxf(args.out_dxf)
+        print(f"  Saved DXF 3D:     {args.out_dxf}")
+
+    if args.out_html:
+        result.to_html(args.out_html)
+        print(f"  Saved report:     {args.out_html}")
+
+    return 0
+
+
+def _cmd_isochrone(args: argparse.Namespace) -> int:
+    print(f"Computing 3D isochrones from {args.center} with intervals {args.intervals} min...")
+    iso_res = solve_3d_isochrones(
+        args.center,
+        network=args.network,
+        profile=args.profile,
+        time_intervals_min=args.intervals,
+        dem_sampler=_make_sampler(args.dem),  # type: ignore[arg-type]
+        fetch_online_dem=args.fetch_dem,
+    )
+
+    print(f"Reachable nodes: {iso_res.total_reachable_nodes}")
+    for band in iso_res.bands:
+        print(
+            f"  Band {band.time_cutoff_min:5.1f} min: "
+            f"{band.reachable_node_count:6d} nodes, "
+            f"{len(band.boundary_points):4d} hull vertices, "
+            f"area {band.area_sqkm:.2f} km2"
+        )
+
+    if args.out_geojson:
+        Path(args.out_geojson).write_text(
+            json.dumps(iso_res.to_geojson(), indent=2), encoding="utf-8"
+        )
+        print(f"  Saved GeoJSON:    {args.out_geojson}")
+
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    handlers = {
+        "profiles": _cmd_profiles,
+        "route": _cmd_route,
+        "isochrone": _cmd_isochrone,
+    }
+    handler = handlers.get(args.command or "")
+    if handler is None:
+        parser.print_help()
+        return 2
+
+    try:
+        return handler(args)
+    except (FileNotFoundError, ValueError, KeyError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

zero2route3d/copernicus_dem.py

@@ -0,0 +1,76 @@
+"""Public Copernicus DEM GLO-30 tile URL and extent helpers."""
+
+from __future__ import annotations
+
+import math
+from typing import List, Sequence, Tuple
+
+
+class CopernicusDemError(ValueError):
+    """Raised when a Copernicus DEM request extent is invalid or too large."""
+
+
+class CopernicusDemTileSource:
+    """Build URLs for the public one-degree Copernicus DEM COG tiles."""
+
+    BASE_URL = "https://copernicus-dem-30m.s3.amazonaws.com"
+
+    @classmethod
+    def tile_id(cls, lon: float, lat: float) -> str:
+        try:
+            lon_value = float(lon)
+            lat_value = float(lat)
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise CopernicusDemError("Copernicus tile coordinates must be numeric.") from exc
+        if not (math.isfinite(lon_value) and math.isfinite(lat_value)):
+            raise CopernicusDemError("Copernicus tile coordinates must be finite.")
+        if not (-180.0 <= lon_value <= 180.0 and -90.0 <= lat_value <= 90.0):
+            raise CopernicusDemError("Copernicus tile coordinates are outside WGS84 bounds.")
+
+        lat_index = math.floor(lat_value)
+        lon_index = math.floor(lon_value)
+        north_south = "N" if lat_index >= 0 else "S"
+        east_west = "E" if lon_index >= 0 else "W"
+        return f"{north_south}{abs(lat_index):02d}_00_{east_west}{abs(lon_index):03d}_00"
+
+    @classmethod
+    def tile_url(cls, lon: float, lat: float) -> str:
+        tile = cls.tile_id(lon, lat)
+        prefix = f"Copernicus_DSM_COG_10_{tile}_DEM"
+        return f"{cls.BASE_URL}/{prefix}/{prefix}.tif"
+
+    @classmethod
+    def tiles_for_bbox(
+        cls,
+        bbox: Sequence[float],
+        max_tiles: int = 16,
+    ) -> List[Tuple[int, int, str]]:
+        if not bbox or len(bbox) < 4:
+            raise CopernicusDemError("A four-coordinate extent is required for Copernicus DEM.")
+        min_lon, min_lat, max_lon, max_lat = (float(value) for value in bbox[:4])
+        if not all(math.isfinite(value) for value in (min_lon, min_lat, max_lon, max_lat)):
+            raise CopernicusDemError("The Copernicus DEM extent contains invalid coordinates.")
+        if min_lon > max_lon:
+            min_lon, max_lon = max_lon, min_lon
+        if min_lat > max_lat:
+            min_lat, max_lat = max_lat, min_lat
+        min_lon = max(-180.0, min(180.0, min_lon))
+        max_lon = max(-180.0, min(180.0, max_lon))
+        min_lat = max(-90.0, min(90.0, min_lat))
+        max_lat = max(-90.0, min(90.0, max_lat))
+
+        lon_start = math.floor(min_lon)
+        lon_end = math.floor(max_lon if max_lon < 180.0 else 179.999999)
+        lat_start = math.floor(min_lat)
+        lat_end = math.floor(max_lat if max_lat < 90.0 else 89.999999)
+        tiles = []
+        for lat_index in range(lat_start, lat_end + 1):
+            for lon_index in range(lon_start, lon_end + 1):
+                url = cls.tile_url(lon_index + 0.1, lat_index + 0.1)
+                tiles.append((lon_index, lat_index, url))
+        if len(tiles) > max(1, int(max_tiles)):
+            raise CopernicusDemError(
+                f"The extent spans {len(tiles)} Copernicus DEM tiles; zoom to a smaller area "
+                f"(maximum {max_tiles})."
+            )
+        return tiles