Preprocessing Functions
Preprocessing functions derive TAT-C model inputs from external geospatial
datasets. They require the optional preprocess dependencies
(pip install tatc[preprocess]).
Terrain Masks
Terrain masks (tatc.schemas.TerrainMask) for radar stations and
surface platforms are derived by ray-tracing a digital elevation model (DEM),
such as the public Copernicus DEM GLO-30.
Copernicus DEM Tiles
- tatc.preprocess.get_copernicus_dem_tile_urls(longitude: float, latitude: float, radius: float = 0) list[str][source]
Builds the Copernicus DEM GLO-30 tile URL(s) covering a circular region of a specified radius around a longitude/latitude, using the dataset’s 1x1-degree tile grid. The dataset is public and requires no authentication (see https://registry.opendata.aws/copernicus-dem/); each URL is a direct HTTPS link to a Cloud-Optimized GeoTIFF (COG), readable by rasterio (including via /vsicurl/ for partial, range-request reads without downloading the entire file – compute_terrain_mask and sample_dem_elevation do this automatically).
- Parameters:
- Returns:
HTTPS URLs to the covering Copernicus DEM GLO-30 tiles.
- Return type:
Sample DEM Elevation
- tatc.preprocess.sample_dem_elevation(dem_paths: str | list[str], longitude: float, latitude: float) float[source]
Samples terrain elevation at a specified longitude/latitude, from the first of one or more DEM raster sources whose extent contains the point and reports valid (non-nodata) data. Elevation is reported in whatever vertical datum the DEM uses: for most public global DEMs, including Copernicus DEM GLO-30, this is mean sea level (the EGM2008 geoid), which differs from the WGS 84 ellipsoid by the local geoid undulation (up to about 100 m in magnitude).
- Parameters:
- Returns:
The sampled terrain elevation (meters).
- Return type:
- Raises:
ValueError – If none of the provided DEM sources cover the specified point with valid data.
Compute Terrain Mask
- tatc.preprocess.compute_terrain_mask(dem_paths: str | list[str], longitude: float, latitude: float, station_elevation: float, search_radius: float = 100000, min_range: float = 1000, number_azimuths: int = 360, number_range_samples: int = 400, range_spacing: str = 'geometric', effective_earth_radius_factor: float = 1.3333333333333333) TerrainMask[source]
Computes a TerrainMask for a ground-based radar station (or other fixed antenna or instrument) by ray-tracing a digital elevation model (DEM): at each sampled azimuth, terrain elevation is sampled at a series of ranges out to search_radius, converted to a curvature-corrected elevation angle as seen from the station (tatc.utils.compute_terrain_elevation_angle), and the maximum (highest obstruction) angle along that ray is taken as the azimuth’s blocking angle. This is the standard approach used by radio/radar line-of-sight terrain-masking tools, under the simplifying assumption that a single nearest/highest ridge along each azimuth dominates (see tatc.schemas.surface.radar.TerrainMask).
search_radius defaults to a shorter distance than a typical radar’s full hardware range, which keeps the DEM read volume (and, for a remote source, the download size) modest. The curvature-drop correction grows with the square of distance (about 0.3 degrees of angle at 75 km), so distant terrain must be much taller than nearby terrain to block the same angle; in mountainous regions, however, ranges 50 to 100 km away commonly set the blocking angle (validation against NEXRAD radars in Arizona found differences of up to about 1.4 degrees between 50 and 100 km search radii). Choose a radius that reaches the significant relief around the station, and a range sampling (number_range_samples) fine enough not to skip narrow ridge crests close to the station, where small sampling errors produce the largest angle errors.
- Parameters:
dem_paths (str | list[str]) – One or more DEM raster sources, each either a local file path or an HTTP(S) URL to a Cloud- Optimized GeoTIFF (COG); see get_copernicus_dem_tile_urls for a public, global, no-authentication option. Only sources that overlap the search region are read; provide enough sources to fully cover it, or some azimuths/ranges may be skipped for lack of data (see return value notes).
longitude (float) – Longitude (decimal degrees) of the radar station.
latitude (float) – Latitude (decimal degrees) of the radar station.
station_elevation (float) – Elevation (meters) of the radar station’s antenna, above the same vertical datum as the DEM (mean sea level for Copernicus DEM GLO-30 and most public global DEMs, not the WGS 84 ellipsoid; NOAA’s NEXRAD station tables report antenna heights above mean sea level). This should include antenna tower height, not just bare-ground elevation; see sample_dem_elevation to determine the ground elevation at the station’s location.
search_radius (float) – The maximum ground distance (meters) to examine for obstructions.
min_range (float) – The minimum ground distance (meters) to examine, excluding the immediate vicinity of the antenna itself.
number_azimuths (int) – The number of evenly-spaced azimuth samples (one terrain profile per azimuth) spanning a full revolution.
number_range_samples (int) – The number of range samples per azimuthal profile, between min_range and search_radius.
range_spacing (str) – The spacing of range samples: “geometric” (the default) spaces samples in proportion to their range, densely near the station and sparsely far away, so a missed ridge crest causes a similar angle error at every range; “linear” spaces samples evenly.
effective_earth_radius_factor (float) – The ratio of the effective Earth radius to the mean Earth radius, accounting for refraction (see tatc.utils.compute_terrain_elevation_angle): 4/3 for radio waves in a standard atmosphere (the default), or 1 for straight lines of sight (as for the footprints of a SurfacePlatform).
- Returns:
The resulting azimuthal terrain blockage mask. An azimuth with no valid DEM data at any sampled range (e.g. the provided dem_paths do not cover that direction) reports a minimum elevation angle of -90 degrees (no blockage assumed).
- Return type:
- Raises:
ValueError – If range_spacing is not “geometric” or “linear”, if min_range is not positive for geometric spacing, or if none of the provided DEM sources overlap the search region.
Compute Terrain Mask for Station
- tatc.preprocess.compute_terrain_mask_for_station(dem_paths: str | list[str], station: RadarStation, search_radius: float = 100000, min_range: float = 1000, number_azimuths: int = 360, number_range_samples: int = 400, range_spacing: str = 'geometric') TerrainMask[source]
Convenience wrapper around compute_terrain_mask that reads station location and elevation directly from a RadarStation.
- Parameters:
station (RadarStation) – The radar station (its longitude, latitude, and elevation are used).
search_radius (float) – See compute_terrain_mask.
min_range (float) – See compute_terrain_mask.
number_azimuths (int) – See compute_terrain_mask.
number_range_samples (int) – See compute_terrain_mask.
range_spacing (str) – See compute_terrain_mask.
- Returns:
The resulting azimuthal terrain blockage mask.
- Return type:
Compute Terrain Mask for Platform
- tatc.preprocess.compute_terrain_mask_for_platform(dem_paths: str | list[str], platform: SurfacePlatform, search_radius: float = 100000, min_range: float = 1000, number_azimuths: int = 360, number_range_samples: int = 400, range_spacing: str = 'geometric', effective_earth_radius_factor: float = 1) TerrainMask[source]
Convenience wrapper around compute_terrain_mask for the instruments of a SurfacePlatform, a height above the ground at its location. The ground elevation is sampled from the DEM (see sample_dem_elevation), in the DEM’s own vertical datum, rather than taken from the platform’s elevation (above the WGS 84 ellipsoid), so the instruments’ height above the surrounding terrain does not depend on the geoid undulation.
- Parameters:
platform (SurfacePlatform) – The platform (its longitude, latitude, and height are used).
search_radius (float) – See compute_terrain_mask.
min_range (float) – See compute_terrain_mask.
number_azimuths (int) – See compute_terrain_mask.
number_range_samples (int) – See compute_terrain_mask.
range_spacing (str) – See compute_terrain_mask.
effective_earth_radius_factor (float) – See compute_terrain_mask. Defaults to 1 (straight lines of sight, without refraction), as for the platform’s footprints.
- Returns:
The resulting azimuthal terrain blockage mask.
- Return type:
Terrain Slopes and Incidence Angles
The terrain slope and aspect at observed targets, from a DEM, give the local
incidence angle of observations on sloped terrain (see
tatc.utils.compute_local_incidence_angle()), for example, to constrain
side-looking observations of mountainous regions.
Compute Terrain Slope and Aspect
- tatc.preprocess.compute_terrain_slope_aspect(dem_paths: str | list[str], longitudes: float | ndarray, latitudes: float | ndarray, baseline: float = 30) tuple[ndarray, ndarray][source]
Computes the terrain slope and aspect at specified longitudes/latitudes from a digital elevation model (DEM), by central differences of the elevations (interpolated bilinearly) a baseline distance east, west, north, and south of each point. The baseline sets the scale of the terrain the slope represents: the DEM’s cell size (30 meters for Copernicus DEM GLO-30, the default) for the steepest local slopes, or a larger distance, such as an instrument’s ground sample size, for the slope averaged over its samples.
- Parameters:
dem_paths (str | list[str]) – One or more DEM raster sources (see compute_terrain_mask), covering the points and their baselines.
longitudes (float | numpy.ndarray) – Longitudes (decimal degrees) of the points.
latitudes (float | numpy.ndarray) – Latitudes (decimal degrees) of the points, with the same shape as longitudes.
baseline (float) – The distance (meters) from each point at which elevations are differenced.
- Returns:
The slope (degrees from horizontal) and aspect (the azimuth of the downslope direction, in degrees clockwise from north, or 0 on flat terrain) at each point, with the shape of longitudes; numpy.nan where the DEM sources do not cover a point with valid data.
- Return type:
tuple[numpy.ndarray, numpy.ndarray]
- Raises:
ValueError – If baseline is not positive, or if none of the provided DEM sources overlap the points.
Add Local Incidence Angles
- tatc.preprocess.add_local_incidence_angles(observations: GeoDataFrame, dem_paths: str | list[str], baseline: float = 30) GeoDataFrame[source]
Adds the terrain slope and aspect (see compute_terrain_slope_aspect) and the local incidence angle (see tatc.utils.compute_local_incidence_angle) at each target of a data frame of observations with point geometries and satellite angles, such as the ground pixels of tatc.analysis.collect_ground_pixels (with sat_altaz=True) or the observations of tatc.analysis.collect_observations. Observations may then be constrained by their local incidence angle, for example, for side-looking instruments over mountainous terrain (an angle above 90 degrees means the target is hidden behind its own slope).
- Parameters:
observations (geopandas.GeoDataFrame) – The observations, with point geometries (longitude and latitude, in degrees) and the satellite’s elevation angle and azimuth (sat_alt and sat_az columns, in degrees) at each.
dem_paths (str | list[str]) – One or more DEM raster sources (see compute_terrain_mask), covering the points.
baseline (float) – See compute_terrain_slope_aspect.
- Returns:
A copy of the observations, with added columns terrain_slope, terrain_aspect, and local_incidence_angle (degrees; numpy.nan where the DEM sources do not cover a target with valid data).
- Return type:
- Raises:
ValueError – If the observations lack the sat_alt or sat_az columns, or have geometries other than points.
Rasters
Read Raster Weights
- tatc.preprocess.read_raster_weights(path: str, mask: Polygon | MultiPolygon | None = None, aggregate: int = 1, density: bool = False, band: int = 1) tuple[ndarray, tuple[float, float, float, float]][source]
Reads a raster of weights (for example, population counts or densities) from a GeoTIFF in WGS84 (EPSG:4326) geodetic coordinates, for tatc.generation.generate_points_random. Only the part of the raster overlapping the bounds of the mask is read. Missing (nodata or not-a-number) values have zero weight.
Large rasters (for example, a global population count at 30 arc-seconds) can be aggregated to coarser cells of aggregate by aggregate raster cells: summed for totals per cell (counts) or averaged for values per unit area (density).
- Parameters:
path (str) – A local file path or HTTP(S) URL to a raster.
mask (shapely.geometry.Polygon | shapely.geometry.MultiPolygon | None) – An optional mask using WGS84 (EPSG:4326) geodetic coordinates in a Polygon or MultiPolygon.
aggregate (int) – The number of raster cells (in each direction) to combine into each weight.
density (bool) – True, if values are per unit area (averaged when aggregated) rather than totals per cell (summed when aggregated).
band (int) – The raster band to read.
- Returns:
- The weights,
with rows from north to south and columns from west to east, and their bounds (west, south, east, north) in degrees.
- Return type: