Class WeatherCoverageSource

Namespace

EncDotNet.S100.Datasets.Weather

Assembly

EncDotNet.S100.Datasets.Weather.dll

Serves one parameter group of a WeatherGridSet (for example the 10 m wind, or the combined sea state) to the coverage pipeline.

public sealed class WeatherCoverageSource : ICoverageSource

Inheritance

object

WeatherCoverageSource

Implements

ICoverageSource

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Each parameter of the group is a value field named by its id ("wind.u", "wave.hs"). When the group has the wind U and V components but no stored speed or direction, Sample(GridRegion, CancellationToken) adds "wind.speed" and "wind.from_direction" as ComputedFields, derived cell by cell (see WindComponents); the surface current group gets "current.speed" and "current.to_direction" the same way (CurrentComponents). Those aren't in ValueFields, which lists stored fields; FieldNames lists both.

Time steps are decoded only when Sample(GridRegion, CancellationToken) first needs them, through each step's WeatherStepDecoder, and the most recently used steps are kept (CacheCapacity). Missing values are NaN, which is also NoDataValue.

Overview levels 1 and 2 are the base grid decimated 2× and 4× per axis: they keep every second or fourth point, starting at the origin, so they need no extra memory and directions are never averaged. A stride in the sampled region decimates the same way.

Like other sources, this one isn't meant to be shared across threads without serialising select-then-sample; the step cache is safe to use from more than one thread.

Constructors

WeatherCoverageSource(WeatherGridSet, string, IReadOnlyList<WeatherParameter>, SpecRef, int)

Creates a coverage source over some parameters of a grid set.

public WeatherCoverageSource(WeatherGridSet gridSet, string name, IReadOnlyList<WeatherParameter> parameters, SpecRef spec = default, int cacheCapacity = 2)

Parameters

gridSet WeatherGridSet

The grid set.

name string

The group name, for example WindGroup.

parameters IReadOnlyList<WeatherParameter>

The parameters to serve, all from gridSet, with distinct ids. Unknown parameters are allowed; they're served under their reader's id.

spec SpecRef

The product identity reported in Spec and on the portrayal: the file format and its version, for example SpecRef.Parse("NetCDF/4.0.0"), NetCDF/3.0.0 or GRIB2/2.0.0 (SpecName accepts these non-S-100 names). A processor always passes one; default(SpecRef), whose Name is null, is only for a grid built in memory with no file behind it.

cacheCapacity int

How many decoded time steps to keep; at least 1.

Exceptions

ArgumentException

parameters is empty, holds a parameter from another set or a repeated id, or has no time steps at all.

Fields

DefaultCacheCapacity

The default number of decoded time steps kept, 2.

public const int DefaultCacheCapacity = 2

Field Value

int

MaxOverviewLevel

The coarsest overview level: level 2, the grid decimated 4× per axis.

public const int MaxOverviewLevel = 2

Field Value

int

Properties

AvailableOverviewLevels

The overview levels this source can serve, in increasing order. Level 0 is always the native (base) grid; higher levels are downsampled (level N = 2^N × coarser per axis). Sources without an overview pyramid return a single-element list describing the base grid.

public IReadOnlyList<CoverageOverviewLevel> AvailableOverviewLevels { get; }

Property Value

IReadOnlyList<CoverageOverviewLevel>

AvailableTimes

The time steps this coverage can be sampled at, in the order the dataset stores them. Empty for static products (S-102); populated for time-varying products (S-104, S-111).

public IReadOnlyList<DateTime> AvailableTimes { get; }

Property Value

IReadOnlyList<DateTime>

Remarks

The union of the parameters' valid times, in time order.

CacheCapacity

How many decoded time steps are kept.

public int CacheCapacity { get; }

Property Value

int

DerivedFields

The fields derived at sampling time, added to every SampledCoverage as ComputedFields.

public IReadOnlyList<ComputedCoverageField> DerivedFields { get; }

Property Value

IReadOnlyList<ComputedCoverageField>

FieldNames

Every field a sample carries: the stored parameters, then the derived fields.

public IReadOnlyList<string> FieldNames { get; }

Property Value

IReadOnlyList<string>

GridSet

The grid set this source serves.

public WeatherGridSet GridSet { get; }

Property Value

WeatherGridSet

Metadata

File-level metadata: extent, grid geometry, CRS, no-data sentinel and the value fields the source carries. Available immediately after the source is constructed.

public CoverageMetadata Metadata { get; }

Property Value

CoverageMetadata

Remarks

Implementations may build a new instance on every read. The GridMetadata reflects the currently selected overview level (see SelectOverviewLevel(int)).

Name

The group name, for example "wind".

public string Name { get; }

Property Value

string

Parameters

The parameters served as stored value fields.

public IReadOnlyList<WeatherParameter> Parameters { get; }

Property Value

IReadOnlyList<WeatherParameter>

SelectedOverviewLevel

The level index currently selected by SelectOverviewLevel(int). Defaults to 0 (base grid).

public int SelectedOverviewLevel { get; }

Property Value

int

SelectedTime

The time step currently selected.

public DateTime SelectedTime { get; }

Property Value

DateTime

Spec

The product identity reported in Spec, for example NetCDF/4.0.0; default(SpecRef) for an in-memory grid (see the constructor).

public SpecRef Spec { get; }

Property Value

SpecRef

Methods

CreateForGroups(WeatherGridSet, SpecRef, int)

Creates one source per parameter group of the grid set's known parameters (Group), split by level, in the order the groups first appear. Unknown parameters aren't drawn, so they get no source.

public static IReadOnlyList<WeatherCoverageSource> CreateForGroups(WeatherGridSet gridSet, SpecRef spec = default, int cacheCapacity = 2)

Parameters

gridSet WeatherGridSet

The grid set.

spec SpecRef

The product identity; see the constructor.

cacheCapacity int

How many decoded time steps each source keeps.

Returns

IReadOnlyList<WeatherCoverageSource>

The sources; empty when the set has no known parameters with time steps.

Sample(GridRegion, CancellationToken)

Copies the requested grid region into a SampledCoverage. The underlying grid is already resident in memory (the HDF5 read happens at construction time), so this is a CPU-bound copy rather than an I/O operation; cancellationToken lets a large copy be abandoned cooperatively. The method remains synchronous.

public SampledCoverage Sample(GridRegion region, CancellationToken cancellationToken = default)

Parameters

region GridRegion

The grid subset and stride to sample.

cancellationToken CancellationToken

Signals that the render has been cancelled.

Returns

SampledCoverage

The sampled values for every field in ValueFields, at the currently selected time step and overview level. The result's Metadata describes the geometry of the sampled sub-grid itself (output row/column count, origin and spacing in the native CRS), so GetPosition(int, int) locates each output cell. How cells skipped by a stride greater than one are combined (plain decimation or a reduction such as S-102's shoalest-depth minimum) is source-specific. An empty region yields a zero-cell sample.

Remarks

Decodes the selected time step on first use (synchronous, CPU-bound work for an in-memory grid; I/O-bound for a reader that decodes from the file). cancellationToken is passed to the decoder and checked per row of the copy. Cells skipped by a stride are dropped (plain decimation), as are those skipped by the overview level.

Exceptions

OperationCanceledException

cancellationToken was cancelled during the copy.

SelectOverviewLevel(int)

Selects the overview level to serve on subsequent Metadata reads and Sample(GridRegion, CancellationToken) calls. After the call, Metadata's GridMetadata reflects the level's rows/cols/spacing so viewport-derived GridRegions pick up the correct geometry automatically. Sources without a pyramid must accept level == 0 as a no-op; other values may throw or be silently clamped (see the source's documentation).

public void SelectOverviewLevel(int level)

Parameters

level int

Zero-based level index, expected to be in [0, AvailableOverviewLevels.Count - 1].

Exceptions

ArgumentOutOfRangeException

level isn't in AvailableOverviewLevels (a grid too small to decimate has fewer levels).

SelectTime(DateTime)

Selects the time step served by subsequent Sample(GridRegion, CancellationToken) calls.

public void SelectTime(DateTime time)

Parameters

time DateTime

The requested time. Time-varying sources select the exact match in AvailableTimes when present, otherwise the nearest available time step. Static sources treat the call as a no-op.

Remarks

Selecting a time doesn't decode anything; the step is decoded by the next Sample(GridRegion, CancellationToken). A parameter with no step at the selected time samples as NaN.