Table of Contents

Bringing S-57 into the pipeline

Most ENC coverage is still encoded as IHO S-57 Edition 3.1 cells. EncDotNet.S100 reads S-57 cells by translating them to S-101, so you can view, validate, render and convert them with the same tools you use for S-101 data.

S-57 has no rendering path of its own. S57ToS101Translator turns each cell into an S101Document, which then goes through S-101 portrayal, validation and rendering. An inland ENC is translated to S-401 instead; see Inland ENCs.

This page covers converting, viewing and validating S-57 cells, how update cells are applied, and the known gaps in the translation. The Datasets.S57 README has the full mapping tables. To work with S-57 records directly, without translating them, see Reading S-57 charts in the EncDotNet documentation. To go the other way, from S-101 to S-57, see Converting S-101 to S-57.

How S-57 cells are detected

S-57 and S-101 datasets both use the .000 extension and the ISO/IEC 8211 encoding. The readers tell them apart by the DSPM (data set parameter) field, which only S-57 has. If a cell is detected as the wrong product, check that it's a genuine S-57 base cell.

Convert a cell to S-101

Convert a base cell with s100 s57 convert:

s100 s57 convert -o US5MA1BO.s101.000 US5MA1BO.000

The output is an ISO/IEC 8211 encoded S-101 dataset (S-100 Part 10a), or an S-401 dataset for an inland ENC. It's an ordinary dataset: inspect it with s100 info, validate it with s100 validate and render it with s100 render. S57ToS101Translator decides the feature, attribute and value mapping, including which values the bundled feature catalogue allows; the command only runs it and writes the result with S101DocumentWriter. For the command's options, see s57 convert.

After converting, the command names the product it wrote (for example as S-101 2.0.0) and prints a translation summary:

  • how many feature records were read and written, and how soundings were accounted for;
  • object classes and attributes that weren't mapped, or that a rule dropped;
  • enumerated values the feature catalogue rejected;
  • features dropped because they had no geometry.

Add --report <path> to also write this information as JSON, broken down by object class, attribute and value, for auditing many cells. The report also records the product written (product, productEdition) and the product the cell itself calls for (detectedProduct).

The counts come from S57TranslationDiagnostics, which you can also use from code; see Translation diagnostics. A high count of feature-catalogue-rejected values usually means a value mapping is wrong, not that the value has no S-101 equivalent.

Apply update cells

S-57 cells are distributed as a base cell (.000) and a series of update cells (.001, .002, and so on), applied in ascending order to bring the base cell up to date (S-57 Part 3, dataset updating). Updates are applied before translation in each case:

  • Exchange sets. S57DatasetProcessor applies each base cell's updates from the same exchange set. SoundCharts warns when an update is refused or cancels the cell.

  • s100 s57 convert. Update files next to the base cell are found by cell name and numeric extension and applied in ascending order. The command prints how many applied and why any weren't. Pass --no-updates to convert the base cell alone.

  • Your own code. S57Dataset.Open(string) and S57Dataset.Open(Stream) read a base cell alone. To apply updates, pass the base cell and the update streams, in ascending order, to S57Dataset.Open(Stream, IReadOnlyList<Stream>):

    using EncDotNet.S100.Datasets.S57;
    
    using var baseCell = File.OpenRead("US5MA1BO.000");
    using var update1 = File.OpenRead("US5MA1BO.001");
    using var update2 = File.OpenRead("US5MA1BO.002");
    
    S57Dataset dataset = S57Dataset.Open(baseCell, [update1, update2]);
    

All three use S57UpdateApplicator, which checks each update before applying it:

  • The update must be for the cell's edition (DSID EDTN). An update for another edition is refused.
  • Its update number (UPDN) must follow the last one applied. Updates the cell already holds, such as those before a re-issue, are skipped; a gap stops the sequence.
  • Each record it changes must follow on. A record it modifies or deletes must be one version (RVER) below the update's, and a record it inserts must be new.
  • An update of edition 0 cancels the cell. Nothing after it applies.

The first update that fails a check stops the sequence, and the updates before it stay applied. The cell always opens; S57Dataset.UpdateReport says what was applied and why the rest wasn't:

if (dataset.UpdateReport is { Success: false } report)
{
    foreach (var message in report.Messages)
        Console.WriteLine($"{message.Severity}: {message.Text}");
}

View a cell in SoundCharts

Drop an S-57 .000 cell, or a folder or exchange set of them, onto SoundCharts. Each cell is translated to S-101 and drawn with the S-101 portrayal catalogue, including the day, dusk and night palettes, display categories and scale-band selection that S-101 cells use.

S-57 has no minimum display scale. Instead, SoundCharts stops drawing a cell once you zoom out past the larger of its compilation scale (DSPM CSCL) and the largest SCAMIN on any of its features. Past that point, only the cell's extent border is drawn. Up to that point, SCAMIN hides individual features as usual.

The compilation scale alone isn't the cut-off because it's the largest scale the cell is meant to be viewed at (S-52 §3.1.7). Using it would hide cells such as USACE inland charts, which are compiled at 1:5,000 but carry SCAMIN values up to 1:300,000. Where cells overlap, the compilation scale still decides which is more detailed: that cell draws on top and hides the coarser one beneath it.

Validate a cell

s100 validate runs two rule packs on an S-57 cell:

  • S57PreTranslationRules, against the S-57 cell, for dataset fields that don't survive translation.
  • The S-101 rule pack, against the translated dataset. These findings' rule ids start with S101-as-S57/, so you can tell them from findings on native S-101 data.

Together they catch problems in the source encoding and in the translated result. Across the 7,184-cell NOAA ENC corpus, the translation passes the S-101 rule pack except for duplicate feature identifiers that are present in NOAA's source cells. Findings that refer to a feature or geometry carry its location, so the SoundCharts validation overlay marks them on the map.

For an inland cell only the S-57 pack runs, because there is no S-401 rule pack.

Inland ENCs

An S-57 inland ENC (IENC), such as a USACE river chart, declares the inland ENC product specification in its DSID record (PRSP = 10; a maritime ENC declares 1). It's still listed as an S-57 dataset, but it's translated to S-401 (the IEHG inland ENC specification) instead of S-101 and drawn with the bundled S-401 catalogues. Once the cell loads, the SoundCharts ECDIS display controls switch to the S-401 viewing groups. A host that has no S-401 portrayal catalogue registered translates inland cells to S-101.

Convert an inland cell

s100 s57 convert writes an inland cell as an S-401 dataset, so its inland features survive. Across 21 USACE cells with 72,726 feature records, the S-401 output has 72,479 features and the S-101 output has 64,394. The product is chosen after update cells are applied. Pass --target to override it:

s100 s57 convert -o U37IL005.s401.000 U37IL005.000
s100 s57 convert --target s101 -o U37IL005.s101.000 U37IL005.000

--target s101 writes S-101 and drops the inland features that have no S-101 equivalent. --target s401 also works on a maritime cell, but prints a warning because the cell doesn't declare the inland specification.

How inland features translate

The inland object classes and attributes (codes 17000 and up, from the IEHG Inland ENC Feature Catalogue 2.4) are mapped to their S-401 counterparts, following the IEHG S-57 ENC to S-401 Conversion Guidance. They include distance marks, notice marks, waterway gauges, inland bridges and shoreline constructions. Across 21 USACE cells, every inland feature translates.

Some features follow specific clauses of the guidance:

  • Anchorage areas (clauses 3.3, 3.4 and 3.85), for both achare/catach and ACHARE/CATACH:
    • An anchorage area whose category is exactly 8 (small craft mooring area) becomes an S-401 MooringArea with categoryOfMooringArea 1.
    • Category 10 (anchorage for pushing-navigation vessels) becomes categoryOfAnchorage 16, on anchorage areas and anchor berths.
    • Clause 3.85's title lists "catach=1, 2, 3" for mooring areas. Those are S-401 mooring-area codes; in S-57, categories 1 to 3 are unrestricted, deep-water and tanker anchorages. So they stay anchorage areas, as does a mixed list such as 7,8.
  • Waterway distances. The unit (hunits) becomes distanceUnitOfMeasurement. Feet, which S-401 lacks, is dropped.
  • Time schedules. A tisdge object becomes an S-401 TimeScheduleInGeneral information record. The lock, berth, gate or other feature it's linked to (through a C_ASSO or a feature pointer) references it. A feature with several schedules references all of them, even though S-401 allows one such reference per feature. The summary's TimeScheduleInGeneral records row (and the report's timeSchedulesEmitted) counts them. S-401 bridges can't carry a time schedule, so a schedule linked only to a bridge is dropped.
  • Locks. The usable length and width (horcll, horclw) become the horizontal clearance length and width. A lock basin carries its width as its horizontal clearance.
  • Gates. VERCLR becomes verticalClearanceOpen (clause 3.55). S-101 has no such rule, so in S-101 output a gate's VERCLR is dropped.
  • Bunker stations. Shore-power details (voltage, frequency, amperage, plug, connectors, allowed consumption) become S-401 power characteristics.
  • Bridge arches. The fixed spans of an inland bridge arch, which IENC groups in a c_brga collection, are linked with S-401's bridge arch association. CATBRG 13 (bridge arch), an IENC extension of the maritime attribute, becomes bridgeConstruction 1 (arch) on the bridge (clauses 3.7 and 3.144).
  • Maximum permitted ship dimensions. An lg_sdm area carries its ship, assembly and cargo ranges in six paired attributes (lc_csi/lc_cse, lc_asi/lc_ase, lc_cci/lc_cce), and all six convert (clause 3.82). lc_csi is the only one whose S-401 attribute declares no IENC alias, so its target comes from the clause.

The only inland codes that don't convert are NEWOBJ and the three attributes that define it (CLSDEF, CLSNAM, SYMINS). NEWOBJ has no fixed meaning, so S-401 has no equivalent. They're reported as rule-dropped.

Known fidelity gaps

The translation covers about 99% of feature instances across a 3,636-cell NOAA ENC corpus. These are the remaining differences you're most likely to see in a translation summary:

  • Feature classes that become attributes or associations. TOPMAR (topmark) becomes an attribute of its parent structure, not a separate feature. C_ASSO associations and C_AGGR aggregations that are neither range systems nor bridge collections have no S-101 named association. MORFAC is split by primitive and CATMOR. An M_NSYS with an ORIENT value becomes a LocalDirectionOfBuoyage (S-65 Annex B §12.2). Range-system C_AGGR collections become RangeSystem features.
  • Bridges are split into spans (S-65 Annex B §4.8.10).
    • A BRIDGE with the clearance its span type needs (VERCLR for a fixed span; VERCCL for an opening span, that is CATBRG 2, 3, 4, 5 or 7) becomes a Bridge and a SpanFixed or SpanOpening. A BridgeAggregation links them, and the span carries the clearances, their accuracies and VERDAT.
    • S-57 can't say whether a bridge crosses navigable water, so a bridge without that clearance becomes a Bridge alone. An opening span with no VERCOP gets an unlimited open clearance.
    • A point BRIDGE becomes a Landmark with categoryOfLandmark bridge.
    • A C_AGGR of BRIDGE objects becomes one Bridge, with its spans and any PYLONS or PONTON as components. The collection's lights and signal stations are linked to that Bridge as theEquipment of a StructureEquipment association. IENC places bridge lights on the navigable span and the piers either side, with no master object, and groups a bridge's vertical clearance indicators (sistaw, catsiw 16) and bridge-passage traffic signal stations (sistat, catsit 8) with it, so collection membership is the only link (IENC Encoding Guide 2.4.1, clauses N.1.1, I.3.3 and R.2.1). Other members, such as fenders and notice marks, convert on their own. A collection that also holds a navigation line or track is a track grouping, not a bridge collection.
    • The Bridge carries the collection's name. Members' own, different names are kept as extra featureNames that aren't drawn (nameUsage 3 in S-401; none in S-101, which has no such value), because spans can't carry a name.
    • Members that don't join, such as twin bridges or parts separated by gaps, make a multi-part Bridge: one curve or one surface per part, drawn and queried part by part. Only members that mix curves and surfaces convert one by one, as a Bridge each, with each light linked to the nearest of them.
    • The summary's Bridge spans, Aggregated bridges, Bridge equipment linked and Bridge collections not joined rows (and the report's bridgeSpansEmitted, bridgeAggregationsEmitted, bridgeEquipmentLinked and bridgeCollectionsUnjoined) count them.
  • Bridge categories. CATBRG is split into bridgeConstruction, bridgeFunction, categoryOfOpeningBridge and openingBridge on the Bridge (S-65 Annex B §4.8.10). The span type uses the same opening test. The IENC-only value 13 (bridge arch) becomes bridgeConstruction 1 (arch), following the IEHG conversion guidance; an arch is a fixed span.
  • Vertical clearances are complex attributes. VERCLR, VERCCL, VERCOP and VERCSA become the verticalClearanceValue of verticalClearanceFixed, Closed, Open and Safe, with VERACC nested as their uncertainty (S-65 Annex B §2.2.4.3). This applies only to feature classes that bind the complex attribute, such as CableOverhead, PipelineOverhead, Conveyor, Crane or Tunnel. Elsewhere the clearance is dropped and counted as rule-dropped.
  • Orientation. On NavigationLine, CurrentNonGravitational, TidalStreamFloodEbb and Crane, ORIENT becomes the orientation complex attribute. Classes that bind orientationValue directly keep it as a simple attribute.
  • Directional lights. A LIGHTS object with CATLIT 1 (directional function) or 16 (moiré effect) becomes LightSectored, and its ORIENT goes into lightSector > directionalCharacter (S-65 Annex B §12.8.6.1). CATLIT 16 also sets moireEffect. Without SECTR1 and SECTR2 there's no sectorLimit, so the portrayal draws the direction line. In the NOAA base corpus this moves 34 lights from LightAllAround to LightSectored and carries ORIENT on 32 lights.
  • Sector lights. Co-located S-57 LIGHTS sector objects are merged into one LightSectored feature with one sectorCharacteristics per arc. Other attributes come from the primary member.
  • Attributes the target class doesn't bind are dropped. An S-57 attribute is kept only when the S-101 (or S-401) class it maps to binds the target attribute. The rest are counted as rule-dropped. This matches the conversion guidance's "will not be converted" exceptions, such as WATLEV on a dolphin or COLOUR on a seabed area. In the NOAA base corpus the largest group is WATLEV: 14,591 instances, nearly all on dolphins.
  • Zone of confidence. Quantified zones (CATZOC A1 to C) fill the nested horizontalPositionUncertainty and verticalUncertainty complex attributes from the IHO CATZOC accuracy table. ZOC D and U keep only the category.
  • Textual information. For S-101, INFORM, TXTDSC, NINFOM and NTXTDS become a NauticalInformation information type bound by an AdditionalInformation association, the conversion guidance's fuller option, not an inline information complex attribute. For S-401, each becomes its own information instance on the feature, as the IEHG conversion guidance specifies by default.
  • Source indication (S-401). SORIND goes verbatim into the sourceIndication complex attribute's source. S-101 has no equivalent, so there it stays unmapped.
  • Primitives S-101 doesn't permit. A point DAMCON becomes a Landmark (category 27, dam), a point RUNWAY that's a helicopter landing pad becomes a Helipad and any other point RUNWAY isn't converted, and an area RECTRC isn't converted, as S-65 Annex B specifies. The NOAA base corpus has 96 area recommended tracks. A point PIPSOL becomes an Obstruction when a depth or dredged area covers it and a Landmark when none does (S-65 Annex B §11.6.1). Annex B names no category for either, so the Landmark's mandatory categoryOfLandmark is left empty (null) for the producer to review.
  • Tidal streams and currents without a speed. S-101 makes speed mandatory on TidalStreamFloodEbb and CurrentNonGravitational, but S-57 lets CURVEL be empty. Without one, the speed complex is still written, with speedMaximum empty (null), the S-65 Annex B convention for a mandatory attribute with no S-57 value. The S-101 rules then draw the stream arrow without a speed, as S-52 does, instead of "?".
  • Underwater hazard depths. Obstructions, rocks and wrecks get surroundingDepth, the least depth of the depth areas under them, and, when they have no VALSOU, defaultClearanceDepth, from the tables in S-101 DCEG clause 30.1, as S-65 Annex B asks. Without them the S-101 rules draw a hazard of unknown depth as "?".
  • Derived features get their own identifier. A bridge span keeps the agency and FIDN of its BRIDGE but takes the next free FIDS, so feature object identifiers stay unique. The Bridge keeps the S-57 identifier. The summary's Derived feature identifiers row (derivedFeatureIdentifiersAssigned) counts them.
  • Meta objects with no S-101 equivalent (M_CSCL, M_HDAT, M_HOPA, M_PROD, M_UNIT) aren't converted, as S-65 Annex B specifies. M_CSCL's scale should go onto DataCoverage, which isn't done yet.
  • Objects of classes with no rule draw as "?". An object whose class the mapping doesn't cover isn't dropped. It keeps its geometry as an S57UnknownObject feature, which the S-101 portrayal draws with the "?" symbol (QUESMRK1) at a point, along a line or inside an area, as S-52 draws an object of unknown class. Pick it to see its object class, its S-57 attributes and, for a point, its position. This is always on: the "?" marks are where the translation has gaps, such as the tidal stream panels (TS_PAD) and incineration areas (ICNARE) it doesn't convert yet, and objects of classes S-57 doesn't define. A class a rule drops on purpose stays dropped. The summary still counts these classes as unmapped.

The Datasets.S57 README has the complete list of limitations.

See also