Spatial Module

Spatial analysis utilities for environmental data.

The spatial module provides tools for geospatial analysis and processing of topographic and bathymetric data.

Spatial Analysis

Data Selection and Interpolation

`select_data`(data, corners)	Select spatial data within specified rectangular boundaries.
`interp`(base, data[, dist, method, fill_values])	Interpolate spatial data onto a regular grid or specified points.
`fillna`(data[, var_, method])	Fill missing values in spatial data using interpolation from valid data.

Profile Analysis

`normal_profiles`(topobat, info[, n_points])	Extract normal profiles from spatial topography/bathymetry data.
`confidence_interval_2d`(data[, loc0, angle, ...])	Calculate 2D confidence intervals and statistics for profile data.

Coordinate Transformations

`rotate_coords`(x, y, angle)	Rotate coordinates by specified angle around the origin.
`global_to_local_coords`(x_glob, y_glob, ...)	Transform global coordinates to local rotated coordinate system.
`local_to_global_coords`(x_loc, y_loc, alpha, ...)	Transform local rotated coordinates back to global coordinate system.

Geometric Operations

`continuous_line`(data[, limiting_distance])	Create continuous line from scattered points by connecting nearest neighbors.
`create_polygon`(data[, crs, sides])	Create a closed polygon from coordinates and optional additional sides.
`triangulation`(x, y)	Create Delaunay triangulation from coordinate arrays.

Voronoi Diagrams

`generate_CVD`(points, iterations, bounding_box)	Generate Centroidal Voronoi Diagram using Lloyd's algorithm.
`bounded_voronoi`(towers, bounding_box)	Generate bounded Voronoi diagram with finite regions.
`centroid_region`(vertices)	Calculate centroid of a polygon region.
`in_box`(towers, bounding_box)	Check if points are within rectangular bounding box.

Geospatial Tools

`merge_land_sea`(topo, bati, linea0, corners)	Merge topography and bathymetry datasets using coastline as boundary.
`spatial_mask`(data, polygon[, op])	Apply spatial mask to data points based on polygon geometry.

environmentaltools.spatial.remove_lowland(data, reference_value: float = 0, replace_value: float = 2)[source]

Remove low-lying areas on land side of topobathymetry.

Identifies and replaces low-lying land areas (below sea level) with a specified elevation value to prevent unrealistic flooding in models.

Parameters:

data (np.ndarray) – 2D array of elevation values (topobathymetry grid)
reference_value (float, optional) – Elevation threshold for identifying low areas (m). Default: 0 (sea level)
replace_value (float, optional) – Elevation value to assign to low areas (m). Default: 2

Returns:

Modified elevation array with low land areas replaced

Return type:

np.ndarray

Notes

The function: 1. Extracts the coastline (zero-elevation contour) 2. Creates a land polygon from coastline and domain boundary 3. Identifies low-lying areas within the land polygon 4. Replaces elevations below reference_value with replace_value

This prevents unrealistic ponding or flooding in low-lying coastal areas.

environmentaltools.spatial.merge_sea_sea(tb, bd, corners, sea='south')[source]

Merge shallow topobathymetry with deep-water bathymetry.

Combines near-shore topobathymetry data with offshore deep-water bathymetry by defining a transition depth contour and blending the datasets.

Parameters:

tb (pd.DataFrame) – Topobathymetry data (shallow/nearshore) with columns [‘x’, ‘y’, ‘z’]
bd (pd.DataFrame) – Deep-water bathymetry data with columns [‘x’, ‘y’, ‘z’]
corners (pd.DataFrame) – Domain corner coordinates with columns [‘x’, ‘y’]
sea (str, optional) – Sea location: ‘south’, ‘east’, or ‘south-east’. Default: ‘south’

Returns:

Merged topobathymetry with deep-water bathymetry

Return type:

pd.DataFrame

Notes

The function: 1. Extracts -40m depth contour from topobathymetry 2. Creates polygon from contour and domain boundaries 3. Replaces topobathymetry data outside polygon with deep bathymetry 4. Generates HTML map showing the blending boundary

environmentaltools.spatial.transform_coordinates(data, proj_from, proj_to, by_columns=False)[source]

Transform spatial coordinates between different projection systems.

Converts coordinates from one coordinate reference system (CRS) to another using pyproj transformations. Supports common projections used in environmental and geographic applications.

Parameters:

data (pd.DataFrame, np.ndarray, or list) – Coordinate data to transform. Format depends on by_columns parameter: - If by_columns=False: DataFrame with ‘x’ and ‘y’ columns - If by_columns=True: Array/list with shape (n, 2) or (2,)
proj_from (str) – Source projection in EPSG format (e.g., ‘epsg:4326’, ‘epsg:25830’). Common options: - ‘epsg:4326’: WGS84 geographic (latitude/longitude) - ‘epsg:23030’: European Datum 1950 UTM Zone 30N - ‘epsg:25830’: ETRS89 UTM Zone 30N - ‘epsg:25829’: ETRS89 UTM Zone 29N - ‘epsg:3857’: Web Mercator (Pseudo-Mercator)
proj_to (str) – Target projection in EPSG format (same format as proj_from)
by_columns (bool, optional) – If True, data is treated as array with columns [lon/x, lat/y]. If False, data is treated as DataFrame with ‘x’ and ‘y’ attributes. Default: False

Returns:

Transformed coordinates in target projection (same type as input)

Return type:

pd.DataFrame, np.ndarray, or list

Notes

WGS84 (EPSG:4326) uses (longitude, latitude) order, while most projected CRS use (x, y) order. The function handles coordinate order correctly for each projection type.

For UTM zones, consider implementing automatic zone detection based on longitude: zone = int((lon + 180) / 6) + 1

Examples

>>> import pandas as pd
>>> # Transform from WGS84 to UTM 30N
>>> data = pd.DataFrame({'x': [-3.5], 'y': [37.0], 'z': [100]})
>>> transformed = transform_coordinates(data, 'epsg:4326', 'epsg:25830')