Skip to main content

​
Overview

The providers module defines interfaces and implementations for accessing elevation data from various raster sources, including ASCII tile collections and large GeoTIFF files.

​
RasterProvider

Abstract base class for all elevation data providers. 
class RasterProvider(abc.ABC):
    """Interface for providing elevation data from various raster sources."""

​
Abstract Methods

​
get_elevation

Retrieve elevation at projected coordinates. 
@abc.abstractmethod
def get_elevation(self, x: float, y: float) -> Optional[float]
​
x
float
required
X coordinate in the provider’s native CRS (typically UTM meters)
​
y
float
required
Y coordinate in the provider’s native CRS
Returns: Elevation in meters, or None if outside coverage

​
Optional Methods

​
prepare_region

Pre-load or pre-cache data for a region before heavy sampling. 
def prepare_region(
    self,
    cx: float,
    cy: float,
    radius: float,
    progress_callback=None
)
​
cx
float
required
Center X coordinate
​
cy
float
required
Center Y coordinate
​
radius
float
required
Radius in meters to prepare
​
progress_callback
callable
default:"None"
Optional callback function for progress reporting

​
get_native_crs

Return the coordinate reference system of the provider. 
def get_native_crs(self) -> str
Returns: EPSG code or PROJ string (default: "EPSG:25831" for UTM 31N)

​
transform_coordinates

Convert WGS84 lat/lon to provider’s native CRS. 
def transform_coordinates(
    self,
    lat: float,
    lon: float
) -> Tuple[float, float]
​
lat
float
required
Latitude in decimal degrees (WGS84)
​
lon
float
required
Longitude in decimal degrees (WGS84)
Returns: Tuple of (x, y) in native CRS

​
AscRasterProvider

Provider for ESRI ASCII Grid tile collections (e.g., ICGC 5×5km tiles). 
class AscRasterProvider(RasterProvider):
    def __init__(self, tiles_dir: str)

​
Parameters

​
tiles_dir
str
required
Directory containing ASCII Grid (.txt or .asc) files

​
Methods

​
initialize

Scan the tiles directory and build spatial index. 
def initialize(self, progress_callback=None)
​
progress_callback
callable
default:"None"
Optional callback for progress reporting

​
prepare_region

Load tiles within radius of center point into cache. 
def prepare_region(
    self,
    cx: float,
    cy: float,
    radius: float,
    progress_callback=None,
    abort_check=None
)
​
abort_check
callable
default:"None"
Optional callback that returns True to abort loading

​
Caching Behavior

  • First parse: ASCII files are parsed (~500ms per 5×5km tile)
  • Binary cache: Parsed tiles are saved as .npy files (~10ms to load)
  • Memory cache: Tiles are kept in memory for fast repeated access

​
Example

from TerraLab.terrain.providers import AscRasterProvider

provider = AscRasterProvider("/path/to/icgc_tiles/")
provider.initialize()

# Transform lat/lon to UTM
x, y = provider.transform_coordinates(lat=41.3874, lon=2.1686)

# Prepare 50km radius
provider.prepare_region(x, y, radius=50000)

# Get elevation
elev = provider.get_elevation(x, y)
print(f"Elevation: {elev:.1f}m")

​
TiffRasterWindowProvider

Provider for large single GeoTIFF files (e.g., Copernicus 30m DEM). 
class TiffRasterWindowProvider(RasterProvider):
    def __init__(self, tiff_path: str)

​
Parameters

​
tiff_path
str
required
Path to the GeoTIFF file

​
Characteristics

  • Window-based reading: Extracts only needed regions
  • Thread-safe: Uses RASTERIO_LOCK for concurrent access
  • Bilinear interpolation: Sub-pixel elevation sampling
  • Memory efficient: Does not load entire raster

​
Example

from TerraLab.terrain.providers import TiffRasterWindowProvider

provider = TiffRasterWindowProvider("copernicus_dem_30m.tif")

x, y = provider.transform_coordinates(lat=41.3874, lon=2.1686)
elev = provider.get_elevation(x, y)
print(f"Elevation: {elev:.1f}m")

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us