Custom catalogues and validation
Every dataset is interpreted through two catalogues from its product
specification. The feature catalogue (S-100 Part 5) defines its feature
types and attributes. The portrayal catalogue (S-100 Part 9) defines how
they're drawn. EncDotNet.S100 bundles the official catalogues, but you might
need a newer edition or your own symbology. This guide shows how to:
- use your own catalogues with
S100FeatureCatalogue,S100PortrayalCatalogueandS100Layer - check a dataset against its product's validation rules with
Validate() - add rules of your own with
ValidationRuleBuilderandValidationRuleSet<T>
The examples use files from
tests/datasets.
Use your own feature catalogue
Load a feature catalogue with S100FeatureCatalogue.FromStream. Use it to read
features, or pair it with a dataset in a layer to render:
using EncDotNet.S100;
using var featureCatalogue = S100FeatureCatalogue.FromStream(File.OpenRead("FeatureCatalogue.xml"));
using var dataset = S100Dataset.Open("navwarn_surface.gml");
foreach (var feature in featureCatalogue.EnumerateFeatures(dataset))
Console.WriteLine($"{feature.FeatureRef}: {feature.FeatureTypeName ?? feature.FeatureType}");
FromStream reads the whole stream, so you can dispose the stream as soon as
it returns. Use a catalogue for the dataset's product: feature type and
attribute names are looked up by code, so a catalogue for another product
resolves nothing.
Use your own portrayal catalogue
A portrayal catalogue is a folder: portrayal_catalogue.xml plus the rules,
symbols, line styles, area fills and colour profiles it lists. Point
S100PortrayalCatalogue.FromAssetSource at the folder, or at a ZIP archive of
it, and render through a layer:
using EncDotNet.S100;
using EncDotNet.S100.Core;
using var portrayalFolder = FileSystemAssetSource.Create("my-s124-portrayal");
using var dataset = S100Dataset.Open("navwarn_surface.gml");
using var renderer = new PngS100DatasetRenderer();
var layer = new S100Layer
{
Dataset = dataset,
PortrayalCatalogue = S100PortrayalCatalogue.FromAssetSource(portrayalFolder),
};
byte[] png = await renderer.RenderAsync(layer);
A layer can set FeatureCatalogue, PortrayalCatalogue, both or neither. Any
catalogue you leave null is the bundled one. The composite
RenderAsync(IReadOnlyList<S100Layer>, …) also takes layers, so each dataset
in a composite can have its own catalogues.
Important
Include every file that portrayal_catalogue.xml lists. A missing rule file
fails the render with a FileNotFoundException that names it, but a missing
symbol is skipped and the image renders without it. If the output looks
incomplete, compare your folder with the bundled catalogue's.
Start from a bundled catalogue
To make your own catalogue, start from a copy of the bundled one. In this
repository they're under
src/EncDotNet.S100.Specifications/content/,
one folder per product (for example S124/). In each, fc/ holds the feature
catalogue and pc/ the portrayal catalogue folder.
In an application that uses the package, get the bundled feature catalogue with
Specification.OpenFeatureCatalogueAsync:
using EncDotNet.S100.Specifications;
await using (var bundled = await Specification.OpenFeatureCatalogueAsync("S-124"))
await using (var copy = File.Create("FeatureCatalogue.xml"))
await bundled.CopyToAsync(copy);
Validate a dataset
Validate() runs the product's bundled rule pack against the parsed dataset.
These are the same rules SoundCharts shows.
using EncDotNet.S100;
using var dataset = S100Dataset.Open("navwarn_surface.gml");
var report = dataset.Validate();
if (report is null)
Console.WriteLine("No validation rules for this product.");
else if (report.IsValid)
Console.WriteLine("No findings.");
else
foreach (var finding in report.Findings)
Console.WriteLine($"{finding.Severity} {finding.RuleId}: {finding.Message}");
Every product in the library has a rule pack except S-401 inland ENC, which uses the S-101 reader but not its rules.
Note
Validate() returns null when the product has no rule pack. That isn't a
pass. A report with no findings (IsValid) means the rules ran and found
nothing.
The report has these members (namespace EncDotNet.S100.Validation):
HasErrorsandHasWarningssummarize the report.FindingsOfSeverity(ValidationSeverity.Error)filters it.- Each finding has a
RuleId(for exampleS124-R-1.1), aSeverityand aMessage. Where possible it also has a location (PointorBoundingBox) and theRelatedFeatureIdit concerns.
Datasets with positions also get a {product}-PROJ-AXIS warning, such as
S122-PROJ-AXIS, when their latitude and longitude were swapped or don't fit
their declared extent. See
Check the axis order.
The report is cached with the dataset, so calling Validate() again returns
the same report without running the rules again.
Write your own rules
Rules run against a product's typed model or dataset type. To get one, see
Reading product data. Build rules with
ValidationRuleBuilder:
Checkreports one pass-or-fail condition.Yieldreports any number of findings, such as one per offending feature.
using EncDotNet.S100.Datasets.S124;
using EncDotNet.S100.Datasets.S124.DataModel;
using EncDotNet.S100.Datasets.S124.Validation;
using EncDotNet.S100.Validation;
var titled = ValidationRuleBuilder.RuleFor<S124NavigationalWarning>("MY-1")
.WithDescription("A warning names its general area.")
.WithSeverity(ValidationSeverity.Warning)
.Check(warning => !string.IsNullOrEmpty(warning.Preamble?.GeneralArea))
.Build();
var partsHaveText = ValidationRuleBuilder.RuleFor<S124NavigationalWarning>("MY-2")
.WithDescription("Every part carries warning text.")
.WithSeverity(ValidationSeverity.Info)
.Yield((warning, context) => warning.Parts
.Where(part => string.IsNullOrEmpty(part.WarningInformation))
.Select(part => new ValidationFinding
{
RuleId = "MY-2",
Severity = ValidationSeverity.Info,
Message = $"Part {part.Id} has no warning text.",
RelatedFeatureId = part.Id,
}))
.Build();
var rules = S124NavigationalWarningRules.Default.Add(titled).Add(partsHaveText);
var warning = S124NavigationalWarning.From(S124Dataset.Open("navwarn_surface.gml"), out _);
foreach (var finding in rules.Run(warning).Findings)
Console.WriteLine($"{finding.Severity} {finding.RuleId}: {finding.Message}");
A failed Check reports its description as the message, unless you pass a
failureMessage.
Rule sets are immutable. Add and Remove(ruleId) return a new set and leave
the product's Default pack unchanged. Start from Default to extend the
product's rules, or from ValidationRuleSet<T>.Empty to run only your own. A
rule that throws becomes an Error finding instead of stopping the run.
Each product's rule pack is a static Default property on a class in the
product's Validation namespace, such as S124NavigationalWarningRules or
S102DatasetRules. The per-product READMEs list the rules.
Next steps
- Reading product data: the typed models and dataset types that rules run against.
- Top APIs: the main entry points in each package.