zero2route3d-sdk 0.2.0__py3-none-any.whl

zero2route3d/copernicus_eo_suite.py

@@ -0,0 +1,443 @@
+"""Corridor elevation raster acquisition.
+
+Acquires a real elevation grid for an extent and clips it to the route corridor
+buffer, ready for QGIS loading and Multi-Criteria Decision Analysis.
+
+Elevation is queried from the Open-Elevation API (https://open-elevation.com);
+values that the service does not resolve are written as NoData, never as zero.
+
+This module deliberately produces **only** elevation. Earlier revisions also emitted
+NDVI, LST and NDBI grids that were synthesised from a sine/cosine hash of the pixel
+indices and labelled as Copernicus Sentinel-2 products. No satellite imagery was
+ever fetched, so those three surfaces were fabricated data wearing a real
+provider's name, and they were fed into the routing cost. They have been removed.
+Supply real NDVI / LST rasters through the plugin's own raster selectors instead.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import math
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, List, Optional, Sequence, Tuple
+
+from .dem_fetcher import NODATA, GlobalDemFetcher
+from .kinematics import haversine_distance_2d
+
+
+@dataclass
+class EnvironmentalLayerResult:
+    """Descriptor for a generated and corridor-clipped environmental raster."""
+
+    key: str  # 'dem', 'ndvi', 'lst', 'ndbi'
+    name: str
+    file_path: Path
+    min_val: float
+    max_val: float
+    unit: str
+    color_palette: str  # 'terrain', 'ndvi_greens', 'lst_thermal', 'ndbi_urban'
+
+
+class CopernicusEOSuite:
+    """Acquires and corridor-clips multi-spectral Earth Observation rasters in one pass."""
+
+    @classmethod
+    def get_output_dir(cls) -> Path:
+        out_dir = Path(tempfile.gettempdir()) / "zero2route3d_eo_cache"
+        out_dir.mkdir(parents=True, exist_ok=True)
+        return out_dir
+
+    @classmethod
+    def fetch_and_clip_multispectral_stack(
+        cls,
+        bbox: Sequence[float],
+        corridor_coords: Optional[Sequence[Sequence[float]]] = None,
+        buffer_meters: float = 30.0,
+        resolution_deg: float = 0.000277777777778,  # ~30m at equator
+    ) -> List[EnvironmentalLayerResult]:
+        """Acquire and corridor-clip a real elevation raster for the given extent."""
+        min_lon, min_lat, max_lon, max_lat = (float(v) for v in bbox[:4])
+        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
+
+        out_dir = cls.get_output_dir()
+
+        # Grid dimensions
+        res = max(0.00005, float(resolution_deg))
+        width = max(8, min(800, int(math.ceil((max_lon - min_lon) / res))))
+        height = max(8, min(800, int(math.ceil((max_lat - min_lat) / res))))
+        actual_max_lon = min_lon + width * res
+        actual_max_lat = min_lat + height * res
+
+        # 1. Fetch / derive DEM grid
+        dem_grid = cls._acquire_dem_grid(
+            min_lon, min_lat, actual_max_lon, actual_max_lat, width, height, res
+        )
+
+        # 2. Apply the corridor buffer mask if a corridor line is provided
+        if corridor_coords and len(corridor_coords) >= 2:
+            cls._apply_corridor_mask(
+                [dem_grid],
+                min_lon,
+                min_lat,
+                res,
+                width,
+                height,
+                corridor_coords,
+                buffer_meters=buffer_meters,
+            )
+
+        # 3. Write the GeoTIFF
+        geotransform = (min_lon, res, 0.0, actual_max_lat, 0.0, -res)
+        results: List[EnvironmentalLayerResult] = []
+
+        dem_name = (
+            "Corridor Elevation (Open-Elevation 30m)"
+            if (corridor_coords and len(corridor_coords) >= 2)
+            else "Elevation DEM (Open-Elevation 30m)"
+        )
+        specs = [
+            ("dem", dem_name, dem_grid, "m", "terrain"),
+        ]
+
+        # tempfile has no `time` attribute, so the old expression always took the
+        # else-branch and every run reused one filename, overwriting rasters that
+        # were still open in the project.
+        timestamp = int(time.time())
+        for key, name, grid, unit, palette in specs:
+            file_path = out_dir / f"corridor_{key}_{timestamp}.tif"
+            min_v, max_v = cls._write_geotiff(
+                file_path, grid, width, height, geotransform, nodata_val=NODATA
+            )
+            results.append(
+                EnvironmentalLayerResult(
+                    key=key,
+                    name=name,
+                    file_path=file_path,
+                    min_val=min_v,
+                    max_val=max_v,
+                    unit=unit,
+                    color_palette=palette,
+                )
+            )
+
+        return results
+
+    @classmethod
+    def _acquire_dem_grid(
+        cls,
+        min_lon: float,
+        min_lat: float,
+        max_lon: float,
+        max_lat: float,
+        width: int,
+        height: int,
+        res: float,
+    ) -> List[List[float]]:
+        """Populate the elevation grid from the Open-Elevation API and its cache.
+
+        Unresolved samples stay as NoData. Filling them with 0.0 would put a
+        sea-level plateau into the middle of real terrain, indistinguishable from
+        a genuine measurement.
+        """
+        grid: List[List[float]] = [[NODATA] * width for _ in range(height)]
+        coords_to_sample: List[Tuple[float, float]] = []
+
+        for r in range(height):
+            lat = max_lat - (r + 0.5) * res
+            for c in range(width):
+                lon = min_lon + (c + 0.5) * res
+                coords_to_sample.append((lon, lat))
+
+        elevations = GlobalDemFetcher.fetch_elevations_for_coords(coords_to_sample)
+        idx = 0
+        for r in range(height):
+            for c in range(width):
+                value = elevations[idx] if idx < len(elevations) else None
+                grid[r][c] = NODATA if value is None else float(value)
+                idx += 1
+
+        return grid
+
+    @classmethod
+    def _apply_corridor_mask(
+        cls,
+        grids: List[List[List[float]]],
+        min_lon: float,
+        min_lat: float,
+        res: float,
+        width: int,
+        height: int,
+        corridor_coords: Sequence[Sequence[float]],
+        buffer_meters: float = 30.0,
+    ) -> None:
+        """Mask out raster cells that fall outside the corridor buffer (set to NoData)."""
+        line_2d = [
+            (float(c[0]), float(c[1]))
+            for c in corridor_coords
+            if len(c) >= 2 and math.isfinite(c[0]) and math.isfinite(c[1])
+        ]
+        if len(line_2d) < 2:
+            return
+
+        buf_m = float(buffer_meters) if math.isfinite(buffer_meters) and buffer_meters > 0 else 30.0
+        # Add 10m soft boundary margin
+        max_dist_m = buf_m + 10.0
+
+        for r in range(height):
+            cell_lat = min_lat + (height - 1 - r + 0.5) * res
+            for c in range(width):
+                cell_lon = min_lon + (c + 0.5) * res
+
+                min_d = float("inf")
+                for i in range(len(line_2d) - 1):
+                    p1 = line_2d[i]
+                    p2 = line_2d[i + 1]
+                    d = haversine_distance_2d((cell_lon, cell_lat), p1)
+                    if d < min_d:
+                        min_d = d
+                    d2 = haversine_distance_2d((cell_lon, cell_lat), p2)
+                    if d2 < min_d:
+                        min_d = d2
+
+                if min_d > max_dist_m:
+                    for grid in grids:
+                        grid[r][c] = NODATA
+
+    @classmethod
+    def _write_geotiff(
+        cls,
+        file_path: Path,
+        grid: List[List[float]],
+        width: int,
+        height: int,
+        geotransform: Tuple[float, float, float, float, float, float],
+        nodata_val: float = NODATA,
+    ) -> Tuple[float, float]:
+        """Write 2D float matrix to GeoTIFF using GDAL if available, or pure-Python GeoTIFF writer fallback."""
+        try:
+            from osgeo import gdal, osr
+
+            driver = gdal.GetDriverByName("GTiff")
+            dataset = driver.Create(
+                str(file_path),
+                width,
+                height,
+                1,
+                gdal.GDT_Float32,
+                ["TILED=YES", "COMPRESS=DEFLATE"],
+            )
+            dataset.SetGeoTransform(geotransform)
+
+            srs = osr.SpatialReference()
+            srs.ImportFromEPSG(4326)
+            dataset.SetProjection(srs.ExportToWkt())
+
+            band = dataset.GetRasterBand(1)
+            band.SetNoDataValue(nodata_val)
+
+            # Flatten grid
+            import struct
+
+            valid_vals = []
+            flat_data = bytearray()
+            for r in range(height):
+                for c in range(width):
+                    val = float(grid[r][c])
+                    if val != nodata_val and math.isfinite(val):
+                        valid_vals.append(val)
+                    flat_data.extend(struct.pack("f", val))
+
+            band.WriteRaster(0, 0, width, height, bytes(flat_data))
+            band.FlushCache()
+            dataset.FlushCache()
+            dataset = None
+
+            min_val = min(valid_vals) if valid_vals else 0.0
+            max_val = max(valid_vals) if valid_vals else 1.0
+            return min_val, max_val
+        except (ImportError, ModuleNotFoundError):
+            return cls._write_pure_python_geotiff(
+                file_path, grid, width, height, geotransform, nodata_val
+            )
+
+    @classmethod
+    def _write_pure_python_geotiff(
+        cls,
+        file_path: Path,
+        grid: List[List[float]],
+        width: int,
+        height: int,
+        geotransform: Tuple[float, float, float, float, float, float],
+        nodata_val: float = NODATA,
+    ) -> Tuple[float, float]:
+        """Pure-Python standard GeoTIFF binary generator for non-GDAL testing environments."""
+        import struct
+
+        valid_vals = []
+        raw_pixels = bytearray()
+        for r in range(height):
+            for c in range(width):
+                val = float(grid[r][c])
+                if val != nodata_val and math.isfinite(val):
+                    valid_vals.append(val)
+                raw_pixels.extend(struct.pack("<f", val))
+
+        min_val = min(valid_vals) if valid_vals else 0.0
+        max_val = max(valid_vals) if valid_vals else 1.0
+
+        min_lon, res_x, _, max_lat, _, res_y = geotransform
+        res_x = abs(res_x)
+        res_y = abs(res_y)
+
+        scale_bytes = struct.pack("<3d", res_x, res_y, 0.0)
+        tiepoint_bytes = struct.pack("<6d", 0.0, 0.0, 0.0, min_lon, max_lat, 0.0)
+        geokey_bytes = struct.pack(
+            "<16H", 1, 1, 0, 3, 1024, 0, 1, 2, 1025, 0, 1, 1, 2048, 0, 1, 4326
+        )
+
+        header = b"II\x2a\x00\x08\x00\x00\x00"
+        num_tags = 11
+        ifd_offset = 8
+        extra_offset = ifd_offset + 2 + num_tags * 12 + 4
+
+        scale_offset = extra_offset
+        tiepoint_offset = scale_offset + len(scale_bytes)
+        geokey_offset = tiepoint_offset + len(tiepoint_bytes)
+        pixel_offset = geokey_offset + len(geokey_bytes)
+
+        tags = [
+            struct.pack("<HHII", 256, 4, 1, width),
+            struct.pack("<HHII", 257, 4, 1, height),
+            struct.pack("<HHII", 258, 3, 1, 32),
+            struct.pack("<HHII", 259, 3, 1, 1),
+            struct.pack("<HHII", 262, 3, 1, 1),
+            struct.pack("<HHII", 273, 4, 1, pixel_offset),
+            struct.pack("<HHII", 277, 3, 1, 1),
+            struct.pack("<HHII", 278, 4, 1, height),
+            struct.pack("<HHII", 279, 4, 1, len(raw_pixels)),
+            struct.pack("<HHII", 33550, 12, 3, scale_offset),
+            struct.pack("<HHII", 33922, 12, 6, tiepoint_offset),
+        ]
+
+        ifd = struct.pack("<H", num_tags) + b"".join(tags) + struct.pack("<I", 0)
+        file_bytes = header + ifd + scale_bytes + tiepoint_bytes + geokey_bytes + raw_pixels
+
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_bytes(file_bytes)
+        return min_val, max_val
+
+
+def apply_environmental_raster_symbology(
+    layer: Any,
+    palette_type: str = "terrain",
+    min_val: Optional[float] = None,
+    max_val: Optional[float] = None,
+) -> None:
+    """Apply professional single-band pseudocolor ramp to environmental raster."""
+    with contextlib.suppress(Exception):
+        from qgis.core import (
+            QgsColorRampShader,
+            QgsRasterShader,
+            QgsSingleBandPseudoColorRenderer,
+        )
+        from qgis.PyQt.QtGui import QColor
+
+        stats = layer.dataProvider().bandStatistics(1)
+        v_min = (
+            float(min_val)
+            if min_val is not None and math.isfinite(min_val)
+            else float(stats.minimumValue)
+        )
+        v_max = (
+            float(max_val)
+            if max_val is not None and math.isfinite(max_val)
+            else float(stats.maximumValue)
+        )
+        if v_max <= v_min:
+            v_max = v_min + 1.0
+
+        fnc = QgsColorRampShader()
+        fnc.setColorRampType(QgsColorRampShader.Interpolated)
+
+        if palette_type == "ndvi_greens":
+            items = [
+                QgsColorRampShader.ColorRampItem(
+                    v_min, QColor("#d97706"), f"{v_min:.2f} (Soil/Barren)"
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_min + (v_max - v_min) * 0.35,
+                    QColor("#fef08a"),
+                    f"{v_min + (v_max - v_min) * 0.35:.2f} (Low Grass)",
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_min + (v_max - v_min) * 0.70,
+                    QColor("#22c55e"),
+                    f"{v_min + (v_max - v_min) * 0.70:.2f} (Greenery)",
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_max, QColor("#065f46"), f"{v_max:.2f} (Dense Canopy)"
+                ),
+            ]
+        elif palette_type == "lst_thermal":
+            items = [
+                QgsColorRampShader.ColorRampItem(
+                    v_min, QColor("#3b82f6"), f"{v_min:.1f} °C (Cool)"
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_min + (v_max - v_min) * 0.33,
+                    QColor("#facc15"),
+                    f"{v_min + (v_max - v_min) * 0.33:.1f} °C (Moderate)",
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_min + (v_max - v_min) * 0.66,
+                    QColor("#f97316"),
+                    f"{v_min + (v_max - v_min) * 0.66:.1f} °C (Warm)",
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_max, QColor("#b91c1c"), f"{v_max:.1f} °C (Severe Heat)"
+                ),
+            ]
+        elif palette_type == "ndbi_urban":
+            items = [
+                QgsColorRampShader.ColorRampItem(
+                    v_min, QColor("#f1f5f9"), f"{v_min:.2f} (Open Natural)"
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_min + (v_max - v_min) * 0.50,
+                    QColor("#94a3b8"),
+                    f"{v_min + (v_max - v_min) * 0.50:.2f} (Suburban)",
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_max, QColor("#475569"), f"{v_max:.2f} (Dense Built-up)"
+                ),
+            ]
+        else:  # terrain
+            items = [
+                QgsColorRampShader.ColorRampItem(
+                    v_min, QColor("#15803d"), f"{v_min:.1f} m (Lowland)"
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_min + (v_max - v_min) * 0.35,
+                    QColor("#ca8a04"),
+                    f"{v_min + (v_max - v_min) * 0.35:.1f} m (Hills)",
+                ),
+                QgsColorRampShader.ColorRampItem(
+                    v_min + (v_max - v_min) * 0.70,
+                    QColor("#854d0e"),
+                    f"{v_min + (v_max - v_min) * 0.70:.1f} m (Ridge)",
+                ),
+                QgsColorRampShader.ColorRampItem(v_max, QColor("#ffffff"), f"{v_max:.1f} m (Peak)"),
+            ]
+
+        fnc.setColorRampItemList(items)
+        shader = QgsRasterShader()
+        shader.setRasterShaderFunction(fnc)
+        renderer = QgsSingleBandPseudoColorRenderer(layer.dataProvider(), 1, shader)
+        layer.setRenderer(renderer)
+        layer.triggerRepaint()

zero2route3d/dem_fetcher.py

@@ -0,0 +1,223 @@
+"""Global Digital Elevation Model (DEM) acquisition & real-world elevation sampler.
+
+Provides automated fetching from the Open-Elevation API with local disk caching.
+When the service is unavailable, unresolved values remain marked as missing
+instead of being replaced with invented topography.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import math
+import tempfile
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence, Tuple
+
+# Raster NoData value. Distinct from 0.0, which is a legal elevation: filling
+# unresolved samples with zero produces a flat sea-level plateau that downstream
+# slope code cannot tell apart from real terrain.
+NODATA = -9999.0
+
+
+class GlobalDemFetcher:
+    """Acquires and caches real elevation samples from the Open-Elevation API.
+
+    The service (https://open-elevation.com) is the only elevation source used
+    here. No Copernicus or SRTM product is queried directly.
+    """
+
+    _CACHE_FILE = Path(tempfile.gettempdir()) / "zero2route3d_cache" / "elevation_cache.json"
+    _MEMORY_CACHE: Dict[str, float] = {}
+    _MAX_CACHE_ENTRIES = 20_000
+    _DISK_CACHE_LOADED = False
+
+    @classmethod
+    def _cache_key(cls, lon: float, lat: float) -> str:
+        return f"{round(lon, 5):.5f},{round(lat, 5):.5f}"
+
+    @classmethod
+    def _load_disk_cache(cls) -> None:
+        if cls._DISK_CACHE_LOADED:
+            return
+        cls._DISK_CACHE_LOADED = True
+        if not cls._CACHE_FILE.exists():
+            return
+        with contextlib.suppress(Exception):
+            data = json.loads(cls._CACHE_FILE.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                for k, v in data.items():
+                    try:
+                        val = float(v)
+                    except (ValueError, TypeError):
+                        continue
+                    if math.isfinite(val):
+                        cls._MEMORY_CACHE[str(k)] = val
+
+    @classmethod
+    def _save_disk_cache(cls) -> None:
+        with contextlib.suppress(Exception):
+            if len(cls._MEMORY_CACHE) > cls._MAX_CACHE_ENTRIES:
+                keep = list(cls._MEMORY_CACHE.items())[-cls._MAX_CACHE_ENTRIES :]
+                cls._MEMORY_CACHE = dict(keep)
+            cls._CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+            temp_file = cls._CACHE_FILE.with_suffix(".tmp")
+            temp_file.write_text(json.dumps(cls._MEMORY_CACHE, indent=2), encoding="utf-8")
+            temp_file.replace(cls._CACHE_FILE)
+
+    @classmethod
+    def clear_cache(cls, remove_disk_file: bool = False) -> None:
+        """Drop every cached elevation sample; optionally delete the on-disk cache too."""
+        cls._MEMORY_CACHE = {}
+        cls._DISK_CACHE_LOADED = False
+        if remove_disk_file:
+            with contextlib.suppress(Exception):
+                cls._CACHE_FILE.unlink()
+
+    @classmethod
+    def cached_sample_count(cls) -> int:
+        """Number of elevation samples currently held in memory."""
+        cls._load_disk_cache()
+        return len(cls._MEMORY_CACHE)
+
+    @classmethod
+    def seed_cache(cls, samples: Dict[Tuple[float, float], float]) -> int:
+        """Pre-populate the cache with known ``(lon, lat) -> elevation_m`` samples.
+
+        Useful for offline and reproducible runs: seeded points are then served by
+        :meth:`get_fast_elevation` without any network access. Returns the number
+        of samples accepted.
+        """
+        cls._load_disk_cache()
+        accepted = 0
+        for coord, value in samples.items():
+            try:
+                lon, lat, elevation = float(coord[0]), float(coord[1]), float(value)
+            except (TypeError, ValueError, IndexError, OverflowError):
+                continue
+            if not (math.isfinite(lon) and math.isfinite(lat) and math.isfinite(elevation)):
+                continue
+            cls._MEMORY_CACHE[cls._cache_key(lon, lat)] = elevation
+            accepted += 1
+        return accepted
+
+    @classmethod
+    def fetch_elevations_for_coords(
+        cls, coords: Sequence[Tuple[float, float]], timeout_sec: float = 3.0
+    ) -> List[Optional[float]]:
+        """Fetch real elevations in metres for a sequence of (lon, lat) WGS84 points.
+
+        Every input gets exactly one output slot. A slot is None when the elevation
+        could not be resolved -- 0.0 is a real elevation and must never stand in for
+        a failed lookup.
+        """
+        cls._load_disk_cache()
+        results: List[Optional[float]] = [None] * len(coords)
+        missing_pairs: List[Tuple[int, float, float]] = []
+
+        for idx, pt in enumerate(coords):
+            if not pt or len(pt) < 2:
+                continue
+            try:
+                lon, lat = float(pt[0]), float(pt[1])
+            except (TypeError, ValueError, OverflowError):
+                continue
+            if not math.isfinite(lon) or not math.isfinite(lat):
+                continue
+
+            key = cls._cache_key(lon, lat)
+            if key in cls._MEMORY_CACHE:
+                results[idx] = cls._MEMORY_CACHE[key]
+            else:
+                missing_pairs.append((idx, lon, lat))
+
+        if not missing_pairs:
+            return results
+
+        # Batch fetch from the Open-Elevation API in chunks of up to 150 items.
+        chunk_size = 150
+        timeout_val = (
+            max(1.0, float(timeout_sec)) if math.isfinite(timeout_sec) and timeout_sec > 0 else 3.0
+        )
+        any_success = False
+
+        for i in range(0, len(missing_pairs), chunk_size):
+            chunk = missing_pairs[i : i + chunk_size]
+            chunk_locations = [
+                {"latitude": round(lat, 6), "longitude": round(lon, 6)} for _, lon, lat in chunk
+            ]
+
+            try:
+                import http.client
+
+                payload = json.dumps({"locations": chunk_locations})
+                conn = http.client.HTTPSConnection("api.open-elevation.com", timeout=timeout_val)
+                try:
+                    headers = {
+                        "Content-Type": "application/json",
+                        "User-Agent": "zero2route3d-sdk",
+                    }
+                    conn.request("POST", "/api/v1/lookup", body=payload, headers=headers)
+                    resp = conn.getresponse()
+                    if resp.status == 200:
+                        data = json.loads(resp.read().decode("utf-8"))
+                        ele_list = data.get("results", [])
+                        if len(ele_list) == len(chunk):
+                            parsed_values: List[float] = []
+                            for item in ele_list:
+                                if not isinstance(item, dict) or "elevation" not in item:
+                                    break
+                                try:
+                                    ele_val = float(item["elevation"])
+                                except (TypeError, ValueError, OverflowError):
+                                    break
+                                if not math.isfinite(ele_val):
+                                    break
+                                parsed_values.append(ele_val)
+                            if len(parsed_values) == len(chunk):
+                                for (m_idx, lon_val, lat_val), ele_val in zip(chunk, parsed_values):
+                                    results[m_idx] = ele_val
+                                    cls._MEMORY_CACHE[cls._cache_key(lon_val, lat_val)] = ele_val
+                                any_success = True
+                finally:
+                    conn.close()
+            except Exception:
+                # Unresolved coordinates keep their None slot. Never synthesize
+                # terrain from coordinate math, and never fall back to 0.0 --
+                # which is a real elevation somewhere.
+                continue
+
+        if any_success:
+            cls._save_disk_cache()
+
+        return results
+
+    @classmethod
+    def get_fast_elevation(cls, lon: float, lat: float) -> Optional[float]:
+        """Elevation for a coordinate from the cache only, or None if unknown.
+
+        Returns None rather than 0.0 so that "no elevation data here" stays
+        distinguishable from "this point is at sea level". Never touches the
+        network, so it is safe to call inside a routing hot loop.
+        """
+        if not math.isfinite(lon) or not math.isfinite(lat):
+            return None
+        cls._load_disk_cache()
+        return cls._MEMORY_CACHE.get(cls._cache_key(lon, lat))
+
+    @classmethod
+    def get_elevation_single(
+        cls, lon: float, lat: float, timeout_sec: float = 3.0
+    ) -> Optional[float]:
+        """Elevation for one coordinate, querying Open-Elevation on a cache miss.
+
+        Returns None when the point cannot be resolved. Prefer
+        :meth:`fetch_elevations_for_coords` for more than a handful of points --
+        it batches them into a single request.
+        """
+        if not math.isfinite(lon) or not math.isfinite(lat):
+            return None
+        cached = cls.get_fast_elevation(lon, lat)
+        if cached is not None:
+            return cached
+        return cls.fetch_elevations_for_coords([(lon, lat)], timeout_sec=timeout_sec)[0]