EncDotNet.S100.Datasets.S57 0.25.1

EncDotNet.S100.Datasets.S57

This package reads IHO S-57 (Edition 3.1) Electronic Navigational Chart (ENC) cells and translates them into the S-101 document model, so the S-101 Part 9A Lua portrayal in EncDotNet.S100.Datasets.S101 can draw them. An inland ENC cell is translated into S-401 instead. The package also validates S-57 cells and reads and verifies S-57 exchange sets. Reference it when you need the translation itself, its diagnostics, or the S-57 records. To open and render an S-57 cell like any other dataset, use the EncDotNet.S100 package.

This isn't an S-52 implementation. A translated cell is drawn with whatever the S-101 portrayal catalogue produces for it. The mappings follow the IHO S-57 to S-101 Conversion Guidance (S-101PT6 INF02A, draft 2021) and S-65 Annex B.

The S-57 records are read by the EncDotNet.S57 package, which is built on EncDotNet.Iso8211.

Install

dotnet add package EncDotNet.S100.Datasets.S57

Translate a cell

using EncDotNet.S100.Datasets.S101;
using EncDotNet.S100.Datasets.S57;

S57Dataset s57 = S57Dataset.Open("path/to/cell.000");

// S-401 for an inland ENC, otherwise S-101.
var translator = S57ToS101Translator.ForTarget(s57.TranslationTarget);
S101Document document = translator.Translate(s57);

// From here, use the S-101 pipeline.
S101Dataset cell = S101Dataset.FromDocument(document);
foreach (var feature in new S101VectorSource(cell).GetFeatures().Take(5))
    Console.WriteLine($"{feature.Id} {feature.FeatureType} ({feature.GeometryType})");

new S57ToS101Translator() always targets S-101.

To convert a cell from the command line, use s100 s57 convert. See Bringing S-57 into the pipeline.

Main types

• S57Dataset: opens a .000 cell and exposes the parsed EncDotNet.S57.S57Document, the S-57 product specification it declares (DeclaredProductSpecification) and the TranslationTarget that follows from it. The static TranslationTargetFor(document) does the same for a document you've already parsed. The static IsS57File(path) tells an S-57 .000 file from an S-101 one. ReadMetadata reads a cell's extent and display scale window without translating or portraying it. See Read metadata.
• S57ToS101Translator: translates an S57Document into an S101Document. It maps object and attribute codes, splits multipoint soundings, builds the information complex attribute from textual attributes, and converts nodes, edges and area rings into S-101 spatial records. ForTarget(target) builds a translator for S-101 or S-401 from the bundled mapping and catalogues; ForTarget(target, mapping) takes your own mapping.
• S57TranslationTarget: the S-100 product a translation produces: the bundled feature catalogue the output is checked against, and the product specification and edition the translated document declares. S101 is the default. S401 (edition 1.3.0) is for inland ENCs. Both share the S-101 document model. A target whose catalogue has no RangeSystem class (S-401) skips the C_AGGR → RangeSystem step and reports those aggregations as unmapped.
• S57ProductSpecification: the codes a cell can declare in its DSID/PRSP subfield: 1 (maritime ENC), 2 (Object Catalogue Data Dictionary) and 10 (inland ENC, as declared by IENC producers such as USACE). TryParse parses the raw subfield value.
• S57S101Mapping: the code mapping table, embedded from the IHO S-57 to S-101 conversion guidance. ForSpec(spec) returns the table for a target product: Default for S-101, or for S-401, Default restricted to the feature classes and attributes the bundled S-401 catalogue defines. See Inland ENCs.
• S101AllowedEnumValues: drops enumerated attribute values that the destination feature catalogue doesn't permit. Default reads the S-101 feature catalogue; ForSpec(spec) reads another bundled catalogue, such as S-401, once per product. It loads on first use.
• S101FeatureAttributeBindings: has the same Default and ForSpec shape. It answers DefinesFeatureType(code) and DefinesAttribute(code). Binds and IsSingleValued cover information types too, and BindsInformationType(feature, association, informationType) tells you whether a feature class can reference an information type (for example, S-401 LockBasin → AdditionalInformation → TimeScheduleInGeneral).
• S57TranslationDiagnostics: counts what a translation dropped. See Translation diagnostics.
• S57ExchangeSetVerification and S57ExchangeSetCatalog: S-57 exchange sets. See Exchange-set integrity verification and Exchange-set cell enumeration.

The S57DatasetProcessor that renders, picks and validates an S-57 cell is in EncDotNet.S100.Datasets.Pipelines.

Read metadata

S57Dataset.ReadMetadata returns a DatasetMetadata without translating or portraying the cell. It calculates the WGS 84 extent from the raw spatial coordinates, using the DSPM coordinate multiplication factor, and reads the display scale window for the whole cell. A host can use it to frame a view over a folder of S-57 cells before loading each one in full.

The window comes from ResolveCellMinimumDisplayScale(document): the larger of the compilation scale (CSCL) and the largest feature SCAMIN in the cell. CSCL is the largest scale the cell is meant to be viewed at (S-52 §3.1.7; S-65 Annex B §2.1.6 maps it to the S-101 optimum display scale). On its own it would hide content that producers encode to stay visible further out. For example, USACE inland cells are compiled at 1:5,000 with SCAMIN up to 1:300,000. ResolveCompilationScale(document) returns CSCL alone, which ranks the cell against overlapping cells.

Apply update files

S-57 cells come as a base cell (.000) and update files (.001, .002, …).

• S57Dataset.Open(string) reads a base cell only.
• S57Dataset.Open(Stream, IReadOnlyList<Stream>) reads a base cell and applies the update streams in order.
• In an exchange set, S57DatasetProcessor applies each base cell's updates from the same set with S57Document.ApplyChanges before translation.
• s100 s57 convert finds update files next to a loose base cell and applies them. It then writes the product that the updated cell's TranslationTarget names (S-401 for an inland ENC, otherwise S-101), unless --target overrides it.

Translation behaviour

Inland ENCs

An S-57 cell that declares the inland ENC product specification (DSID/PRSP = 10) is translated into S-401. S57S101Mapping.ForSpec builds the S-401 table from the S-101 table:

• Restricted to S-401. RestrictToFeatureTypes limits the table to the feature classes the bundled S-401 catalogue defines. That clears 15 deep-sea and natural-feature targets (for example RAPIDS → Rapids and LITFLT → LightFloat), which S-401 translation reports as rule-dropped. RestrictToAttributes also drops attribute targets that the S-401 catalogue doesn't define, such as CATICE. CATBRG stays, because its bridge category targets exist in both catalogues.
• Inland rules (internal InlandRules). These cover the 53 object classes and 91 attributes of the IEHG Inland ENC Feature Catalogue 2.4 (codes 17000 and up). Rules are resolved by attribute code (ResolveAttribute(ushort, …)), so an inland code and its upper-case twin never hide each other.
• Anchorage rules (internal S401AnchorageRules, applied last). These replace the ACHARE/achare and CATACH/catach rules for S-401 only, so the S-101 table is unchanged.

The inland rules follow the IEHG S-57 ENC to S-401 Conversion Guidance:

• Most inland codes re-register a standard acronym in lower case (bridge = 17011 for BRIDGE = 11) and reuse the standard rule, as the guidance prescribes. The rest map to the S-401 class or attribute whose alias is the IENC acronym (notmrk → NoticeMark, wtwdis → waterwayDistance).
• hunits, the unit of wtwdis, becomes distanceUnitOfMeasurement with the guidance's value changes: hectometres 4 → 7, statute miles 5 → 4, nautical miles 6 → 5. Feet has no S-401 code and is dropped. It's only emitted on the classes that bind it.
• A time schedule (tisdge) becomes an S-401 TimeScheduleInGeneral information record carrying cattab, schref, shptyp, useshp, aptref, dirimp and SORDAT. Every feature linked to it, through a C_ASSO or a feature pointer, references it with AdditionalInformation if its class can. The C_ASSO emits nothing itself. Every link is emitted, even beyond S-401's one AdditionalInformation per feature, because IENC encodes one schedule per ship type or period. A schedule that no emitted feature can carry (for example one on a Bridge, which only takes ServiceHours) is reported as rule-dropped, and the schedule attributes are dropped on features.
• The usable lock and dock dimensions horcll and horclw become horizontalClearanceLength and horizontalClearanceWidth where the class binds them. On LockBasin, which binds no width, horclw fills horizontalClearanceFixed unless HORCLR already does.
• The shore-power attributes of a bunker station (catvol, catfrq, amoamp, catplg, shrnum, allcon) become the sub-attributes of S-401's powerCharacteristics. The translator builds one instance per listed voltage and frequency on BunkerStation, and drops them elsewhere.
• The bridge arch collection c_brga emits no feature. The SpanFixed of its first member bridge links the other members' fixed spans with S-401's BridgeArchAssociation. A c_brga with fewer than two fixed spans is reported as rule-dropped.
• Inland bridges convert the same way as maritime BRIDGE: CATBRG categories on the Bridge, a SpanFixed or SpanOpening carrying the clearances, and point bridges as Landmark. The S-401 catalogue defines all of these. The IENC-only CATBRG value 13 (bridge arch) becomes bridgeConstruction 1 (arch), which keeps the arch a fixed span.
• The ship category, assembly and cargo ranges of a maximum permitted ship dimensions area (lc_csi/lc_cse, lc_asi/lc_ase, lc_cci/lc_cce) all convert. lc_csi is the one whose S-401 target has no alias, so its rule comes from conversion guidance clause 3.82 instead of from the catalogue.
• Four codes have no S-401 equivalent and are reported as rule-dropped: NEWOBJ and its three definition attributes (CLSDEF, CLSNAM, SYMINS).

The anchorage rules:

• Anchorage and anchor berth CATACH 10 (IENC "anchorage for pushing-navigation vessels") becomes categoryOfAnchorage 16 (conversion guidance clauses 3.3 and 3.4).
• An anchorage area whose CATACH is exactly 8 (small craft mooring area) becomes MooringArea, with categoryOfMooringArea 1 (clause 3.85).
• Clause 3.85's title reads "catach=1, 2, 3". Those are the S-401 categoryOfMooringArea codes, not S-57 values: CATACH 1–3 are unrestricted, deep-water and tanker anchorages. So CATACH 1–3 stay on AnchorageArea.
• A list such as 7,8 also stays on AnchorageArea and keeps every code, because S-401 categoryOfAnchorage binds 8 too.

Limitations

• M_COVR areas with no coverage are dropped. An M_COVR with CATCOV = 2 ("no coverage available") isn't translated. S-101's DataCoverage feature always asserts coverage, so a DataCoverage for a no-data area would claim data over the cell's hole. Overlap suppression between cells of different scales would then blank the coarser cell there. M_COVR with CATCOV = 1, or with no CATCOV, translates to DataCoverage as usual. The RuleDroppedObjectClasses diagnostic counts the dropped ones.
• Feature coverage. Feature class coverage comes from the <S100FC:alias> (S-57 acronym) entries in the bundled S-101 feature catalogue. Across a 3,636-cell NOAA ENC corpus, about 99% of feature instances translate. The classes left unmapped are collections with no S-101 named association (C_ASSO, and any C_AGGR that is neither a range system nor a bridge collection) and meta objects with no S-101 equivalent (M_CSCL). Objects that become S-101 attributes are folded into their host: TOPMAR folds into the master buoy or beacon's topmark complex through the S-57 master/slave relationship. Splits by geometry are handled where S-101 needs them (MORFAC → Dolphin/ShorelineConstruction by primitive, refined by CATMOR; point BRIDGE → Landmark). Bridges are split into a Bridge and its spans, a bridge C_AGGR becomes one Bridge with its span, pylon and pontoon components, and range-system C_AGGR collections become RangeSystem features. See the table above.
• Attributes. Most attribute rules map an S-57 attribute to a simple S-101 attribute bound directly to the feature. A simple attribute passes through only when the resolved class binds it in the target feature catalogue. Otherwise it's counted in RuleDroppedAttributes, which matches the conversion guidance's "not converted" exceptions (for example WATLEV and NATCON on Pile, COLOUR on SeabedArea, and CATTSS on the parts of a traffic separation scheme). The complex attributes in the table above are assembled when the class binds them. Their sub-attributes are checked against the destination attribute's global enumeration, not the narrower permittedValues some complexes declare, in line with the rest of the pipeline. Sub-attributes of the other S-101 complex attributes are left unmapped. SORDAT → reportedDate applies only on the 50 or so classes that bind reportedDate. SORIND has no general S-101 equivalent and isn't mapped.
• Enumerated values. Some S-57 enumerated values have different codes in S-101. Values the destination feature catalogue doesn't permit are dropped and reported in the diagnostics. List values are split into separate S-101 occurrences first, so only the invalid codes are dropped, not the whole attribute.
• Sector lights. Co-located sector arcs of one physical light are several S-57 LIGHTS objects, each with one sector (SECTR1/SECTR2), that resolve to the same S-101 point. They're merged into one LightSectored feature with one sectorCharacteristics instance per arc (the catalogue allows [1..*]). The light that comes first in the document is the primary; the others emit no feature of their own, and SectorLightsMerged counts them. Attributes outside the sector (height, status, name) come from the primary, as they're the same for every arc of a light in the NOAA data.
• Zone of confidence uncertainty. The nested uncertainty complexes of zoneOfConfidence (horizontalPositionUncertainty, verticalUncertainty) are filled in for zones A1–C from the IHO CATZOC accuracy table. Zones D and U have no quantified accuracy and carry only the category.
• Textual information. INFORM, TXTDSC, NINFOM and NTXTDS become a NauticalInformation information type linked to the feature by an AdditionalInformation / theInformation association (the "fuller path" in the conversion guidance), not an inline information complex. A feature with any of the four attributes gets one NauticalInformation record, with an English instance, a national-language instance, or both. NauticalInformationTypesEmitted counts the records. The S-101 portrayal reads the linked record (ProcessNauticalInformation), so text and picture notes render as they did with the inline form.
• Area rings. An S-57 area's boundary edges (FSPT) are chained into rings by shared begin and end nodes, reversing edges where needed, not by their order in FSPT. S-57 lists all interior edges together (USAG = interior) whichever hole they belong to, so grouping by USAG would merge all of an area's holes into one boundary. That ring would jump between holes and draw long spikes. Chaining gives one closed ring per hole, and each becomes its own S-101 interior ring.
• Bridge spans depend on the clearance attributes. S-57 can't say whether a bridge crosses navigable water, so a BRIDGE gets a SpanFixed or SpanOpening only when it carries the clearance attribute that span class makes mandatory (VERCLR or VERCCL). A navigable bridge encoded without it converts to a Bridge alone, and its other clearances are dropped. So does an opening bridge encoded with VERCLR instead of VERCCL. The span type uses the same CATBRG test as the Bridge's openingBridge, so a SpanOpening is only attached to an opening Bridge. Separate BRIDGE spans that no C_AGGR groups each convert to their own Bridge and span.
• Collections. Range-system and bridge C_AGGR collections are converted; other collections aren't. Across the 7,184-cell NOAA base corpus, the translator creates 2,083 RangeSystem features in 931 cells with 6,690 component associations, and no collection is left without components or with dangling references. RangeSystemsEmitted counts them. Other C_AGGR groupings and all C_ASSO associations (mostly LandArea partition groupings) have no S-101 named association and stay unmapped. For S-401, a C_ASSO that links an inland time schedule is used by the time schedule conversion.

Translation diagnostics

S57ToS101Translator.Translate has an overload that takes an S57TranslationDiagnostics. When you pass one, the translator counts what it dropped and why. Use it, for example, to audit a corpus for gaps in S57S101Mapping:

using EncDotNet.S100.Datasets.S57;

var diagnostics = new S57TranslationDiagnostics();
var document = new S57ToS101Translator().Translate(s57, diagnostics);

// Object classes in the data that have no mapping rule.
foreach (var (objl, count) in diagnostics.UnmappedObjectClasses)
    Console.WriteLine($"OBJL {objl}: {count}");

Pass null, or use an overload without the parameter, and nothing is collected. The counters are:

• Gaps, where no rule exists: UnmappedObjectClasses and UnmappedAttributes.
• Drops by design, where a rule exists but produces nothing: RuleDroppedObjectClasses and RuleDroppedAttributes.
• Other losses: DroppedEnumValues (values the feature catalogue rejects) and FeaturesDroppedForNoGeometry.
• Totals: FeatureRecordsRead, FeaturesEmitted, and the sounding counts (SoundingFeaturesRead, SoundingFeaturesEmitted, SoundingPointsEmitted, SoundingFeaturesWithoutPoints).
• Synthesised features and links:
  • SectorLightsMerged: co-located sector arcs merged into one LightSectored.
  • TopmarksAbsorbed: TOPMAR objects folded into a master that binds topmark.
  • NauticalInformationTypesEmitted: NauticalInformation records created for INFORM, TXTDSC, NINFOM and NTXTDS.
  • RangeSystemsEmitted: RangeSystem features created from range-system C_AGGR collections.
  • TimeSchedulesEmitted: S-401 TimeScheduleInGeneral records created for inland tisdge schedules.
  • BridgeSpansEmitted, BridgeAggregationsEmitted, BridgeEquipmentLinked and BridgeCollectionsUnjoined: bridge spans, aggregated bridges, linked lights and signal stations, and bridge collections that couldn't be joined.
  • DerivedFeatureIdentifiersAssigned: derived features, such as bridge spans, given their own FIDS.

s100 s57 convert prints these counters as a summary and writes them as JSON with --report. See Bringing S-57 into the pipeline.

Validation

S57DatasetProcessor.Validate() validates in two passes:

1. Before translation, S57PreTranslationRules.Default checks the raw EncDotNet.S57.S57Document for things that don't survive translation.
2. After translation, the translated S-101 document is checked with S101DatasetRules.Default, the same pack that runs on native S-101 cells. Its rule IDs get the prefix S101-as-S57/, so you can tell whether a problem is in the S-57 source or in the translated S-101. This pass only runs for a maritime cell. An inland cell is translated into S-401, which has no rule pack, so its report holds the first pass only.

The translation itself passes the S-101 pack: across the 7,184 cells of the NOAA ENC corpus, the only findings on the translated S-101 are the duplicate feature identifiers in the source data. Findings about a feature or spatial record carry its location (a point, or the envelope of its geometry), so the viewer's validation overlay can mark them.

The rules in S57PreTranslationRules.Default:

The two reports are joined in EncDotNet.S100.Datasets.Pipelines and cached on the processor.

Exchange-set integrity verification

S57ExchangeSetVerification verifies the integrity of an S-57 or S-63 exchange set (a folder with a CATALOG.031). It returns the same ExchangeSetVerificationResult as S-100 exchange-set verification, so s100 validate reports both the same way.

using EncDotNet.S100.Datasets.S57;
using EncDotNet.S100.ExchangeSets;

ExchangeSetVerificationResult result =
    await S57ExchangeSetVerification.VerifyAsync("path/to/exchange-set");

bool intact = result.IntegrityVerified;   // no CRC mismatches or missing files
bool signed = result.AllValid;            // every file signature is valid

The upstream S-57 verifier (EncDotNet.S57 0.5.0 or later) works on a directory (CATALOG.031 and the files it lists), while the S-100 verifier works on an IAssetSource. So this is an adapter that maps the result, not a shared interface.

How the result is mapped:

• Outcomes are mapped by name, from S57VerificationOutcome to VerificationOutcome. The two enums have the same members; mapping by name means a future difference fails with an error instead of mapping to the wrong value.
• The signature outcome (Outcome) and the checksum outcome (ChecksumOutcome) are kept separately.
• S-57 integrity uses a CRC-32 (from CATALOG.031), not the SHA-256 digest of the S-100 model. The CRC values are in FileVerificationResult.Detail, and ComputedSha256 is null.
• The verdict follows S-100. NoChecksum and NotSigned don't fail: an unsigned set that's intact has IntegrityVerified == true and AllValid == false. Only ChecksumMismatch, FileMissing, Error and invalid signatures fail integrity. This matches the upstream S-57 AllValid.
• The upstream S-57 verifier reports every file as NotSigned, because it doesn't verify S-63 signatures yet. CRC checking works.

Exchange-set cell enumeration

S57ExchangeSetCatalog reads a CATALOG.031 (with EncDotNet.S57's S57CatalogReader) and groups the catalogued files into base cells, each with its updates from the same set and, if known, its extent:

using EncDotNet.S100.Datasets.S57;

IReadOnlyList<S57ExchangeSetCell> cells =
    S57ExchangeSetCatalog.ReadBaseCells("path/to/exchange-set");

foreach (S57ExchangeSetCell cell in cells)
{
    Console.WriteLine(cell.RelativePath);          // the .000 base cell
    foreach (string update in cell.UpdateRelativePaths)
        Console.WriteLine($"  {update}");          // .001, .002, … in order
    // cell.BoundingBox is the EPSG:4326 extent, or null.
}

var union = S57ExchangeSetCatalog.UnionBoundingBox(cells);

Files are grouped by their 8-character cell name. The .000 file is the base, and .001, .002, … are its updates in the order they apply. Other entries (.TXT files, certificates, the catalogue itself) are ignored, and update files with no matching base are skipped. Paths use the platform's separators. SelectBaseCells(S57Catalog) does the grouping on a catalogue you've already read, which is useful in tests.

The viewer uses this with a FileSystemAssetSource rooted at the exchange set, so each cell goes through the same S57DatasetProcessor as a single .000 file, with its updates applied before translation. Like the verification adapter, this adapts the directory-based S-57 model rather than sharing an interface.

See also

• Bringing S-57 into the pipeline: convert, view and validate S-57 cells with s100 and SoundCharts.
• S-401 bundled catalogues: the catalogues inland cells are translated for.