Generic WCS Source
WCSSource
WCSSource
Bases: DataSource
Fetch a raster band from any OGC Web Coverage Service.
Builds a GetCoverage HTTP request for the grid bounding box, receives
GeoTIFF bytes, and parses them via rasterio.MemoryFile (same
approach as URLSource).
Parameters
url:
Base URL of the WCS service (no query parameters).
layer:
Coverage identifier (COVERAGEID for 2.0, IDENTIFIER for 1.1).
version:
WCS version string — "2.0.1" (default) or "1.1.1".
format:
Output format MIME type (default "image/tiff").
timeout:
HTTP request timeout in seconds.
cache_dir:
Optional path to a directory for caching fetched rasters on disk.
On a cache hit the HTTP request is skipped entirely. Useful for
static sources (terrain, bathymetry) where the data never changes.
cache_ttl:
Maximum age of a cache entry, as a :class:~datetime.timedelta or a
number of seconds. An older entry is refetched. The default
None never expires, which suits terrain and bathymetry; set it
for coverages that are updated.
extra_subsets:
Additional SUBSET= values appended to the WCS 2.0 request (e.g.
['time("2023-01-01T00:00:00.000Z")'] for time-aware coverages).
Ignored for WCS 1.x requests.
axis_labels:
Names of the longitude and latitude axes used in the WCS 2.0
SUBSET= parameters, as (lon_label, lat_label). The default
("Long", "Lat") matches the EPSG:4326 axis abbreviations; some
servers use e.g. ("lon", "lat") or ("x", "y") instead. The
bounds are always given in EPSG:4326 (SUBSETTINGCRS). Ignored
for WCS 1.x requests.
valid_range:
Optional (lo, hi) tuple. Pixels outside this range are set to
NaN. Use this to mask out nodata sentinels that the server encodes
as extreme numeric values (e.g. (-500, 9000) for Norwegian DTM
data where values below −500 m or above 9000 m are fill values).
Either bound may be None. The cached array is the one the
server sent, so changing the range re-masks it without requesting
the coverage again.
resampling:
How the coverage is resampled onto the reference grid:
"bilinear" (default), "nearest", "mode", "average",
"min" or "max". The coverage is requested at the server's
native resolution, so "max" or "min" keeps small features
of a finer coverage on a coarser grid. See
:class:~geobn.sources.DataSource.
WCSSource is a generic OGC Web Coverage Service
client. It supports WCS 2.0.1, 1.1.1, and 1.0.0.
Request construction
WCS 2.0.1 uses SUBSET parameters:
The bounds are in EPSG:4326 (SUBSETTINGCRS). Lat/Long are the default axis
labels; servers that name the axes differently (e.g. lat/lon or y/x) reject
this request. Pass axis_labels=(lon_label, lat_label) to match the server:
The axis names are listed in the server's DescribeCoverage response.
extra_subsets adds further subsets, e.g. ['time("2023-01-01T00:00:00.000Z")'].
WCS 1.1.1 uses a BBOX parameter.
WCS 1.0.0 uses COVERAGE, BBOX, WIDTH, and HEIGHT parameters
(common for ArcGIS Image Server WCS endpoints).
Nodata masking with valid_range
If the returned GeoTIFF declares a nodata value, those pixels are converted to NaN
automatically. Pass valid_range=(lo, hi) to additionally replace out-of-range
sentinel values with NaN — needed for services that encode nodata as extreme
numbers without declaring it. See
Masking sentinel values for the
full description; it works the same on every source.
Disk caching
Pass cache_dir to cache responses to disk. The cache key is a SHA-256 hash of the
request URL and parameters (bounding box, output size, format, axis labels and extra
subsets), plus an internal cache-format version (bumped when cached content semantics
change, so outdated entries are refetched). Corrupt or missing cache entries trigger a
fresh request. valid_range is not part of the key: the response is cached as it
arrived and the range is applied on the way out, so adjusting it costs no new request.
cache_ttl sets how long an entry stays usable, as a timedelta or a number of seconds.
It is not part of the key either — freshness is a property of the entry, not of what was
requested — so changing it never orphans a cached coverage. Leave it unset for terrain and
bathymetry, which do not change:
source = geobn.WCSSource(
url="https://example.com/wcs",
layer="sea_surface_temperature",
cache_ttl=timedelta(hours=3),
)
If the coverage has expired and the request then fails, the expired entry is returned with
a UserWarning naming its age.
Recipes
Kartverket Norwegian DTM (10 m):
source = geobn.WCSSource(
url="https://hoydedata.no/arcgis/services/las_dtm_somlos/ImageServer/WCSServer",
layer="las_dtm",
version="1.0.0",
format="GeoTIFF",
valid_range=(-500.0, 9000.0), # mask fill values outside elevation range
cache_dir="cache/",
)
bn.set_input("elevation", source)
EMODnet European Bathymetry:
source = geobn.WCSSource(
url="https://ows.emodnet-bathymetry.eu/wcs",
layer="emodnet:mean",
version="1.0.0",
valid_range=(-15000.0, 9000.0), # negative depths are valid; mask extreme sentinels
cache_dir="cache/",
)
bn.set_input("depth", source)
EMODnet Shipping Density: