Terrain

get_cache_root(custom_path=None)

Get the root directory for caching files.

Return type:

str

Parameters:

custom_path (str)

clear_cache()

Clears the entire cache directory after confirming it is safe to do so.

clear_localdem_cache(confirm=True)

Clears the local DEM cache directory.

This removes all files in the ‘localdem’ subdirectory of the cache root, which stores downloaded DEM tiles.

Parameters:

confirm (bool) – If True, prompt the user for confirmation before clearing the cache.

build_tile_index(tile_list_file)

Build an R-tree spatial index for DEM tiles from a tile list file.

Each line in the file is a tile name encoding lat/lon in the filename. Tiles are parsed into 1x1 degree bounding boxes and indexed spatially.

Parameters:

tile_list_file (str) – Path to the text file listing available DEM tiles.

Returns:

A tuple of (rtree_index,

tile_bboxes) where tile_bboxes is a list of (tile_name, bounding_box) pairs.

Return type:

Tuple[index.Index, List[Tuple[str, box]]]

download_dem_files(lon_min, lat_min, lon_max, lat_max, aws_dir)

Download DEM tile files covering a geographic bounding box.

Tiles are downloaded from the specified AWS directory and cached locally. Already-downloaded tiles are reused from the cache.

Parameters:

• lon_min (float) – Western longitude bound (degrees).

• lat_min (float) – Southern latitude bound (degrees).

• lon_max (float) – Eastern longitude bound (degrees).

• lat_max (float) – Northern latitude bound (degrees).

• aws_dir (str) – Base URL of the AWS-hosted DEM tile directory.

Returns:

List of local file paths to the downloaded DEM tiles.

Return type:

List[str]

merge_tiles(output_filename, tile_file_list)

Merge multiple DEM tile files into a single GeoTIFF using GDAL Warp.

Parameters:

• output_filename (str) – Path for the merged output GeoTIFF file.

• tile_file_list (List[str]) – List of file paths to DEM tiles to merge.

Raises:

• ValueError – If tile_file_list is empty or contains invalid paths.

• RuntimeError – If GDAL merge operation fails.

generate_demfile(latitude, longitude, aws_dir='https://copernicus-dem-30m.s3.amazonaws.com/')

Generate a DEM file covering the specified latitude and longitude extents.

Return type:

str

Parameters:

• latitude (ndarray)

• longitude (ndarray)

• aws_dir (str)

get_elevations(lats, lons, dem_file)

Extract elevation values for given latitudes and longitudes from a DEM file.

Reads the entire raster band once and indexes it in bulk, rather than querying pixel-by-pixel, for efficient batch lookups.

Return type:

ndarray

Parameters:

• lats (ndarray)

• lons (ndarray)

• dem_file (str)

get_min_max_elevations(dem_file)

Get the minimum and maximum elevation values from a DEM file.

Parameters:

dem_file (str) – Path to the DEM file.

Returns:

(min_elevation, max_elevation) in the DEM file.

Return type:

Tuple[float, float]

ray_terrain_intersection(lat0, lon0, h0, az, tilt, precision=10.0, dem_file=None)

Batch computation of ray-terrain intersections using a DEM for multiple observer positions. Vectorized to handle multiple observers efficiently.

Parameters:

• lat0 (np.ndarray) – Array of observer latitudes (degrees).

• lon0 (np.ndarray) – Array of observer longitudes (degrees).

• h0 (float) – Altitude of the observer above the ellipsoid (meters).

• az (np.ndarray) – Azimuth angle of the ray (degrees).

• tilt (np.ndarray) – Tilt angle of the ray below horizontal (degrees, 0–90).

• precision (float) – Precision of the slant range sampling (meters).

• dem_file (str) – Path to the DEM file. If None, one will be generated.

Returns:

(intersection_lats, intersection_lons,

intersection_alts). Observers with no terrain intersection have NaN in all three arrays.

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

Raises:

ValueError – If tilt or azimuth values are out of range, or if tilt is too close to horizontal (±90°) where slant-range geometry is undefined.