EncDotNet.Iso8211 0.7.0

EncDotNet.Iso8211

A .NET 10 parser for the ISO/IEC 8211 binary container format — the underlying encoding used by IHO S-57 electronic navigational charts, as well as other geospatial and data exchange standards.

Features

• Parse any ISO 8211 file (not limited to S-57 charts)
• Read the Data Descriptive Record (DDR) to discover field tags, subfield names, and data types
• Decode data records and iterate their fields and subfield values
• Write ISO 8211 files — serialize an Iso8211Document back to bytes (round-trippable, byte-identical for canonical sources)
• Build records from scratch with fluent builders and a DDR encoder
• Low-allocation ref struct reader for streaming large files
• Recovers records larger than the leader's five-digit length field can express
• Immutable record types for parsed data (thread-safe, LINQ-friendly)

Installation

dotnet add package EncDotNet.Iso8211

Quick Start

using EncDotNet.Iso8211;

// Parse a file into an in-memory document
var document = Iso8211DocumentReader.ReadFromFile("chart.000");

// Read the DDR (schema) — defines field tags, subfield names, and data types
var ddr = Iso8211DataDescriptiveRecordReader.Read(document.DataDescriptiveRecord!);

// Iterate data records
foreach (var record in document.DataRecords)
{
    foreach (var field in record.Fields)
    {
        Console.WriteLine($"Field tag: {field.Tag}  ({field.Data.Length} bytes)");

        // Use the DDR field definition to decode subfields
        var fieldDef = ddr.GetFieldDefinition(field.Tag);
        if (fieldDef is not null)
        {
            var reader = new Iso8211FieldReader(fieldDef, field.Data);

            foreach (var subfieldDef in fieldDef.SubfieldDefinitions)
            {
                if (reader.TryGetSubfield<string>(subfieldDef.Name, out var value))
                {
                    Console.WriteLine($"  {subfieldDef.Name} = {value}");
                }
            }
        }
    }
}

Writing ISO 8211

Serialize an existing Iso8211Document back to bytes (the symmetric inverse of the reader — round-trippable, and byte-identical for canonically-encoded sources):

using EncDotNet.Iso8211;

var document = Iso8211DocumentReader.ReadFromFile("chart.000");

// Round-trip: write the document back out.
byte[] bytes = Iso8211DocumentWriter.Write(document);
Iso8211DocumentWriter.WriteToFile("chart-copy.000", document);

To construct records from scratch, use the fluent builders and the DDR encoder:

using System.Collections.Immutable;
using EncDotNet.Iso8211;

// Describe the field's subfields: a 2-char code and a variable-length name.
var formats = ImmutableArray.Create(
    new Iso8211SubfieldFormat { FormatType = Iso8211SubfieldFormatType.CharacterData, Width = 2 },
    new Iso8211SubfieldFormat { FormatType = Iso8211SubfieldFormatType.CharacterData, Width = 0 });

var field = new Iso8211FieldBuilder("EXMP", formats)
    .AddSubfield("US")
    .AddSubfield("EXAMPLE")
    .Build();

var record = new Iso8211RecordBuilder()
    .AddField(field)
    .Build();

var document = new Iso8211DocumentBuilder()
    .AddRecord(record)
    .Build();

byte[] bytes = Iso8211DocumentWriter.Write(document);

Key Types

Background

ISO/IEC 8211 is a general-purpose binary format for encoding structured data into self-describing files. Each file begins with a Data Descriptive Record (DDR) that defines the schema, followed by one or more data records conforming to that schema.

The format is used by IHO S-57 for encoding electronic navigational charts, but it is not specific to maritime data — any domain that needs a compact, self-describing binary container can use ISO 8211.

Records longer than 99 999 bytes

A record leader carries its record's length in five numeric characters, so it cannot express a record of 100 000 bytes or more. Producers that emit one — a dense inland ENC cell whose SG2D coordinate field runs to six figures, for example — write 00000 there instead. The reader recognises that and re-derives the length from the record's own directory (the field area base address plus the sum of the directory's field lengths), so such records are read normally and Iso8211Leader.RecordLength reports the real length.

Iso8211DocumentWriter does the same in reverse: a record longer than 99 999 bytes is written with 00000 as its length, so such files round-trip byte for byte. The field area base address has the same five-digit limit but cannot be left unspecified, because the reader needs it to find the directory. Building or writing a record whose directory pushes the base address past 99 999 therefore throws InvalidOperationException.

Related Packages

• EncDotNet.S57 — S-57 domain model built on top of this parser

License

MIT — see LICENSE for details.