EncDotNet.S100.Datasets.S102 0.25.0

EncDotNet.S100.Datasets.S102

This package reads S-102 Bathymetric Surface datasets from HDF5 files and portrays their depth grids with the S-102 portrayal catalogue. It also validates a dataset against the S-102 Edition 3.0.0 checklist. Reference it when you need the depth and uncertainty grids directly. To open and render a dataset without wiring catalogues yourself, use the EncDotNet.S100 package instead.

Install

dotnet add package EncDotNet.S100.Datasets.S102
dotnet add package EncDotNet.S100.Hdf5.PureHdf

EncDotNet.S100.Hdf5.PureHdf provides the HDF5 reader the example uses.

Read a dataset

using EncDotNet.S100.Datasets.S102;
using EncDotNet.S100.Hdf5.PureHdf;

using var file = PureHdfFile.Open("path/to/dataset.h5");
S102Dataset bathymetry = S102DatasetReader.Read(file);

BathymetryCoverage grid = bathymetry.Coverages[0];
Console.WriteLine($"EPSG:{bathymetry.HorizontalCRS}, " +
                  $"{grid.NumPointsLatitudinal} x {grid.NumPointsLongitudinal} cells");

grid.Values is row-major from the grid origin. Depths are in metres, and cells without data hold the fill value 1,000,000. Origin and spacing are in the dataset's horizontal CRS, which may be projected. For a full walk through the grid, see Reading product data.

Main types

• S102Dataset: the dataset, with its horizontal CRS, vertical datum and bathymetry coverages.
• S102DatasetReader: reads an S102Dataset from an IHdf5File.
  • The horizontal CRS comes from the Edition 3.0.0 horizontalCRS root attribute. If that's missing, the reader uses the Edition 2.1 horizontalDatumValue attribute, so both editions are georeferenced correctly.
  • The verticalDatum root attribute (S-102 Ed 3.0.0 §12.3) becomes S102Dataset.VerticalDatum, an S-100 register code. S102CoverageSource resolves it to a label through EncDotNet.S100.DataModel.VerticalDatums.
  • ReadMetadata(file) returns a DatasetMetadata with the declared product specification, the grid extent and HorizontalCrsEpsg (for UTM reprojection). It reads only the georeferencing attributes, not the depth and uncertainty values.
• BathymetryCoverage and BathymetryValue: a grid and its values. BathymetryCoverage.GroupPath is the HDF5 path of the coverage, such as /BathymetryCoverage/BathymetryCoverage.01. Validation findings use it as RelatedFeatureId.
• S102CoverageSource: the ICoverageSource for the coverage pipeline. See Downsampling.
• S102PortrayalCatalogue: the coverage portrayal catalogue that shades depths. See Portrayal.

The S102DatasetProcessor that renders, samples and validates a dataset is in EncDotNet.S100.Datasets.Pipelines.

Portrayal

S102PortrayalCatalogue runs the bundled BathymetryCoverage.lua rule (S-102 Edition 3.0.0, Annex B) through an ILuaEngine. It resolves the colour tokens the rule emits (DEPDW, DEPMD, DEPMS, DEPVS, DEPIT, NODTA) against the bundled ColorProfiles/colorProfile.xml. The Day, Dusk and Night palettes are all loaded, and SwitchPaletteAsync selects one. Call SwitchPaletteAsync before ResolveColorScheme: it loads the Lua rule, and ResolveColorScheme throws InvalidOperationException until it has.

The four S-102 context parameters come from MarinerSettings:

• FourShades switches between two depth bands (DEPVS and DEPDW, split at SafetyContour) and four (DEPVS, DEPMS, DEPMD and DEPDW, split at ShallowContour, SafetyContour and DeepContour).
• SafetyContour, ShallowContour and DeepContour are depth boundaries in metres.

If the contours are out of order, the catalogue clamps them to ShallowContour ≤ SafetyContour ≤ DeepContour and logs a diagnostic instead of throwing. Settings sliders can pass through out-of-order values while you drag them, and that mustn't stop rendering.

Cells whose depth equals S102CoverageSource.FillValue (1,000,000) are painted with the active palette's NODTA colour through CoverageColorScheme.NoDataColor. Set S102PortrayalCatalogue.RenderNoDataFill = false to leave them transparent. Do this when S-102 is drawn over another layer, such as an S-101 ENC, so the unsurveyed part of the rectangular grid doesn't hide the chart underneath.

Downsampling

When S102CoverageSource draws a grid at a smaller scale, it reduces blocks of cells to one value. Both its overview pyramid and its viewport sampling keep the shallowest depth (minimum) and the largest uncertainty (maximum) in each block. Every source cell belongs to a block, so a narrow shoal can't fall between sample points. The blocks are balanced across the sampled area so the reduced grid's georeferencing stays exact, and the pyramid stops before a level would need a partial 2×2 block at an edge. Coverage read trace spans report s100.coverage.reducer=min.

Validation

The bundled rule pack, EncDotNet.S100.Datasets.S102.Validation.S102DatasetRules.Default, checks an S102Dataset against the S-102 Edition 3.0.0 checklist and returns a ValidationReport. S102DatasetProcessor.Validate() runs it for you. To run it directly:

using EncDotNet.S100.Datasets.S102.Validation;

var report = S102DatasetRules.Default.Run(dataset);
foreach (var finding in report.Findings)
    Console.WriteLine($"{finding.RuleId} {finding.Severity}: {finding.Message}");

For the validation API and your own rules, see Custom catalogues and validation.

See also

• Reading product data: read the depth grid cell by cell.
• Render S-102 to PNG: render a dataset from .NET or the command line.
• Compose S-101 and S-102: draw bathymetry under an ENC.