Surfaces

Surfaces#

Regular-grid terrain and bathymetry models. A configured SurfaceModel is realized against a boundary by Sampler(..., surface=...), and the returned Farm.surface is a queryable Terrain or Bathymetry object. See Terrain and bathymetry for examples.

Surface(x, y, values, *[, metadata])

A regular grid of physical values in meters.

Terrain(x, y, values, *[, metadata])

A surface of elevations relative to a common datum.

Bathymetry(x, y, values, *[, metadata])

A surface of positive water depths, for offshore sites.

SurfaceModel()

Surface generator realized against a farm boundary.

PerlinTerrain([elevation_range, ...])

Perlin-noise terrain model with elevations bounded by elevation_range.

PerlinBathymetry([depth_range, ...])

Perlin-noise bathymetry model with depths bounded by depth_range.

GaussianTerrain([mean, standard_deviation, ...])

Gaussian random-field terrain model around a sloping mean plane.

GaussianBathymetry([mean, ...])

Gaussian random-field bathymetry model around a sloping mean depth.

Lightweight terrain and bathymetry surfaces for generated farms.

class oowl.surfaces.Bathymetry(x, y, values, *, metadata=None)[source]#

A surface of positive water depths, for offshore sites.

Parameters:
class oowl.surfaces.GaussianBathymetry(mean=50.0, standard_deviation=5.0, *, gradient=(0.0, 0.0), correlation_length=1000.0, resolution=100.0, seed=None)[source]#

Gaussian random-field bathymetry model around a sloping mean depth.

Parameters are as for GaussianTerrain, with depth in place of elevation. The field is never clipped, so a nonpositive depth on the canonical grid makes generate raise ValueError.

Parameters:
class oowl.surfaces.GaussianTerrain(mean=0.0, standard_deviation=20.0, *, gradient=(0.0, 0.0), correlation_length=1000.0, resolution=100.0, seed=None)[source]#

Gaussian random-field terrain model around a sloping mean plane.

Elevation is mean plus gradient times the offset from the center of the boundary bounds, plus a zero-mean field with squared-exponential covariance of scale standard_deviation and length correlation_length, output on a grid spaced by resolution. Lengths are in meters and gradient in meters per meter. Negative elevations are permitted.

Parameters:
class oowl.surfaces.PerlinBathymetry(depth_range=(10.0, 50.0), *, correlation_length=1000.0, resolution=100.0, seed=None)[source]#

Perlin-noise bathymetry model with depths bounded by depth_range.

depth_range must be strictly positive, else ValueError. Other parameters are as for PerlinTerrain.

Parameters:
class oowl.surfaces.PerlinTerrain(elevation_range=(0.0, 100.0), *, correlation_length=1000.0, resolution=100.0, seed=None)[source]#

Perlin-noise terrain model with elevations bounded by elevation_range.

Elevations in meters stay within the range without necessarily reaching it. correlation_length is the noise-cell size in meters, not a statistical correlation length, and resolution is the output grid spacing in meters. Nodes shared by grids of different resolution have equal values for the same boundary and seed.

Parameters:
class oowl.surfaces.Surface(x, y, values, *, metadata=None)[source]#

A regular grid of physical values in meters.

x and y are strictly increasing node coordinates and values has shape (len(y), len(x)). Invalid or nonfinite grids raise ValueError.

Parameters:
at(points)[source]#

Bilinearly interpolate values at (N, 2) points, shape (N,).

Raises TypeError for non-numeric points and ValueError for points outside the grid.

Parameters:

points (ArrayLike)

Return type:

np.ndarray

classmethod load(path)[source]#

Read the surface save() wrote to path.

A file holding depth is a Bathymetry and one holding elevation a Terrain, so Terrain.load of a depth grid raises ValueError. A grid saved by another tool loads with the metadata {"kind": ..., "source": "netcdf"}.

Parameters:

path (str | Path)

Return type:

Surface

property maximum: float#

Largest surface value.

property minimum: float#

Smallest surface value.

plot(ax=None, *, cmap=None, title=None, colorbar=True)[source]#

Plot the surface and return its Matplotlib axes.

cmap defaults to the style’s image.cmap.

Parameters:
Return type:

matplotlib.axes.Axes

save(path)[source]#

Write the surface to path, a .nc file, and return the path.

The file is the NetCDF grid oowl.save() writes beside a site with surface_format="netcdf", x, y and depth or elevation in meters, which xarray and windIO read. The metadata is JSON text in the global attribute oowl_metadata, so load() rebuilds an equal surface. Raises ValueError for another suffix or metadata that JSON cannot hold.

Parameters:

path (str | Path)

Return type:

Path

class oowl.surfaces.SurfaceModel[source]#

Surface generator realized against a farm boundary.

A seed given as a numpy.random.Generator is pinned to one integer at construction, so every farm drawn from the model replays alike. Grids above 50,000,000 nodes or an estimated 4 GiB raise ValueError before allocation, naming the length to raise.

abstractmethod generate(boundary, seed=None)[source]#

Generate a surface covering the boundary bounds.

seed overrides the model’s seed.

Parameters:
Return type:

Surface

abstractmethod metadata()[source]#

Return a JSON-compatible model description.

Return type:

dict

class oowl.surfaces.Terrain(x, y, values, *, metadata=None)[source]#

A surface of elevations relative to a common datum.

Parameters: