EncDotNet.S100.Datasets.S128 0.24.0

EncDotNet.S100.Datasets.S128

Reader and portrayal-pipeline integration for IHO S-128 (Catalogue of Nautical Products) datasets, encoded as GML per S-100 Part 10b.

Upstream source

The bundled FC and PC live under src/EncDotNet.S100.Specifications/content/S128/{fc,pc}/ and are surfaced through the standard Specification.OpenFeatureCatalogueAsync() / Specification.CreatePortrayalCatalogueSource() factory methods.

What S-128 encodes

An S-128 dataset is a catalogue of the nautical products produced by a single agency. Each "feature" describes one product and its coverage:

Plus metadata records modelled in the FC as information types but encoded as features inside the inline <S128:members> container in the upstream sample (DistributorInformation, ProducerInformation, ContactDetails, CatalogueSectionHeader).

Public surface

Outline-only coverages

The bundled portrayal catalogue is the IHO upstream's, unedited. Its rules fill each product's coverage with CHYLW / CHGRN / CHMGD at transparency 0.30 (70 % opaque) on displayPlane OVERRADAR, and the S-98 layer stack puts S-128 on OtherChartOverlays, above the ENC's line work. Nested products (a harbour cell inside an approach cell) compound to about 91 % opaque and hide the chart, against S-98 Main §9.2.1.

Upstream has since reached the same view: issue #51 recommends outlines only, and the Lua port of the catalogue (#56) comments the fills out. S128PortrayalCatalogue does the same with an adapter, Adapter/outlineOnly.xsl. It xsl:imports the upstream main.xsl and, for ElectronicProduct, PhysicalProduct and S100Service surfaces, keeps everything the upstream rule emits except its areaInstruction. Coverages draw as the upstream dashed outlines.

S128CoverageOverlayTests checks that the adapter output equals the upstream output minus the fills, and that the upstream rule still emits them. When a catalogue refresh drops the fills, that test fails and the adapter can be removed. Moving to the upstream Lua catalogue is tracked in #763.

Producer-bug compensations

The reader inherits the four mitigations applied to other GML-encoded products in this codebase (S-122 in particular). When real-world S-128 samples surface, edge cases here may need expanding.

1. s100gml namespace tolerance. Accepts http://www.iho.int/s100gml/5.0 (canonical for 2.0.0), http://www.iho.int/s100gml/1.0, and the legacy profile namespace http://www.iho.int/S100/profile/s100gml/1.0.
2. <member> and <members> containers. Both the wrapper and inline variants are accepted; the upstream 2.0.0 sample uses inline <S128:members>.
3. Comma-and-whitespace tokenisation in gml:posList/gml:pos. Handles lon,lat lon,lat tokens smuggled in via the gml:coordinates convention.
4. lon-lat axis-order swap heuristic. When a <gml:Envelope> is present and parsed coords clearly fall outside as-is but inside when swapped, the reader globally flips axes. Skipped silently when no envelope is declared (the upstream 2.0.0 sample omits it).
5. gml:gmlId identifier fallback. Some S-128 GML 1.0 IC-ENC/DK catalogue datasets key features with the non-standard gml:gmlId attribute instead of gml:id. The reader accepts either; without this the feature identifier is empty and the geometry provider drops the feature (rendering blank — see issue #243).
6. Exterior-less polygons. Some GML 1.0 datasets emit <gml:Polygon><gml:posList>… directly, omitting the <gml:exterior>/<gml:LinearRing> wrapper. The shared GmlCoordinateParser falls back to a direct posList/pos sequence under the surface as the exterior ring.
7. Single-ordinate <gml:pos> rings. Some GML 1.0 datasets split each coordinate's ordinates across consecutive single-value <gml:pos> elements (<gml:pos>41.68</gml:pos><gml:pos>21.61</gml:pos>…). The shared GmlCoordinateParser detects this and flattens the ordinates into (lat, lon) pairs.

Note on GML 1.0 datasets. Compensations 5–7 recover geometry from the older S-128 GML 1.0 encoding so those catalogues are no longer blank. Full portrayal of GML 1.0 feature classes (ElectronicChart, PaperChart, …) and a reliable axis order for lon-lat datasets that ship no <gml:Envelope> are tracked separately in issue #247.

Status heuristic

S-128 2.0.0 does not surface a single status enum on product entries. S128ProductEntry.Status is derived as follows:

1. If serviceStatus is present → Planned (1), InForce (2), Withdrawn (3).
2. Else if distributionStatus is present → InForce (1) / Withdrawn (2).
3. Otherwise defaults to InForce.

Resolution of theReference xlink references with ProductMapping/categoryOfProductMapping=1 (supersedes) is handled by the typed-model projection — see Strongly-typed data model.

Strongly-typed data model

EncDotNet.S100.Datasets.S128.DataModel.S128ProductCatalogue projects the feature-bag S128Dataset into a strongly-typed catalogue with:

• Polymorphic Products collection over the common S128CatalogueEntry base; instances are sealed S128ElectronicProduct, S128PhysicalProduct, or S128Service.
• Dedicated typed records for Producers, Distributors, Contacts, and SectionHeaders metadata.
• Resolved supersedes navigation. Every theReference xlink with ProductMapping/categoryOfProductMapping=1 ("Higher Priority Alternative", S-128 § 12) is resolved at projection time. Each entry exposes Supersedes (forward traversal) and SupersededBy (reverse traversal, populated by inverting the forward map). Cycles and chains tolerated.
• Other categoryOfProductMapping values surface in RelatedProducts with their raw category text preserved for future-edition compatibility.
• Permissive projection: unresolved xlinks and parse failures emit ProjectionDiagnostic entries rather than throwing. The projection only throws when both Features and InformationTypes are empty.

Quick start (typed model)

using EncDotNet.S100.Datasets.S128;
using EncDotNet.S100.Datasets.S128.DataModel;

var dataset = S128Dataset.Open("catalogue.gml");
var catalogue = S128ProductCatalogue.From(dataset, out var diagnostics);

foreach (var product in catalogue.Products)
{
    Console.WriteLine($"{product.FeatureType} {product.Id} " +
        $"(ed. {product.EditionNumber}, spec {product.ProductSpecificationName})");

    foreach (var superseded in product.Supersedes)
        Console.WriteLine($"  supersedes → {superseded.Id}");

    foreach (var successor in product.SupersededBy)
        Console.WriteLine($"  superseded by → {successor.Id}");
}

foreach (var d in diagnostics)
    Console.WriteLine(d);

Coordinate ordering

Per S-100 Part 10b §6.2, all coordinates inside <gml:pos> / <gml:posList> for EPSG:4326 are lat lon.

Validation

Validation/S128CatalogueRules.cs ships a pilot pack of seven Tier-1 / Tier-2 rules over S128ProductCatalogue. Rule identifiers follow the convention S128-R-{clause} and trace to clauses of S-128 Edition 2.0.0 (§ 12 Feature Catalogue, plus S-100 Part 10b §6 for geometry).

Run the default pack:

using EncDotNet.S100.Datasets.S128;
using EncDotNet.S100.Datasets.S128.DataModel;
using EncDotNet.S100.Datasets.S128.Validation;

await using var stream = File.OpenRead("catalogue.gml");
var dataset = S128Dataset.Open(stream);
var catalogue = S128ProductCatalogue.From(dataset, out _);

var report = S128CatalogueRules.Validate(catalogue);
foreach (var f in report.Findings)
    Console.WriteLine($"[{f.Severity}] {f.RuleId}: {f.Message}");

Tier-3 cross-dataset rules (e.g. cross-referencing catalogue entries against actually loaded S-1xx datasets) are deferred until the MCP validate_all surface lands.

Portrayal

The bundled main.xsl includes per-feature templates (ElectronicProduct.xsl, PhysicalProduct.xsl, S100Service.xsl, DistributorInformation.xsl) plus simpleLineStyle.xsl / textStyle.xsl and a Default.xsl fallback. No locally-authored XSLT ships in this PR — status-driven (in-force / superseded / withdrawn / planned) styling is not in the upstream PC and is left as a TODO.

Out of scope (this release)

• Status-driven local XSLT styling (in-force / superseded / withdrawn / planned). The data-model side of supersedes is now resolved via S128ProductCatalogue; the corresponding XSLT portrayal hook is still deferred.
• Auto-downloading datasets pointed at by onlineResource.linkage URLs.
• Dataset authoring / serialisation.
• Multi-language label resolution.
• A dedicated catalogue browser side panel in the viewer (datasets load through the existing pipeline and render as coverage polygons).