Class CapDatasetProcessor

Namespace

EncDotNet.S100.Datasets.Pipelines

Assembly

EncDotNet.S100.Datasets.Pipelines.dll

Pipeline processor for CAP 1.2 marine weather warnings (design note docs/design/weather-sources.md §6.1): one CAP alert, an Atom feed of them, or the NWS GeoJSON form from api.weather.gov/alerts, read by CapReader. CAP isn't an S-100 product, and its warnings aren't for navigation.

public sealed class CapDatasetProcessor : IDatasetProcessor, IVectorPortrayalSource, IHeadlessImageRenderer, ITimeAwareDatasetProcessor, ILoadedDatasetProjection

Inheritance

object

CapDatasetProcessor

Implements

IDatasetProcessor

IVectorPortrayalSource

IHeadlessImageRenderer

ITimeAwareDatasetProcessor

ILoadedDatasetProjection

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

What it provides:

• Areas. Each CAP area is one feature (FeatureType): its polygons, its circles as 64-vertex polygons, or, for an area with only zone codes, the NWS marine zones it names, from Default (see CapWarningSet). Codes the layer doesn't have are listed in the pick report and in Warnings, not dropped.
• Time. An area is drawn only while it is in force at the render context's TimeStep, by the rule S-124 navigational warnings use (WarningValidity), and every drawable area is drawn when the context has no time step. As an ITimeAwareDatasetProcessor its steps are the instants the set in force changes (Changes), held until the next one (AtOrBefore), so a host's timeline redraws it exactly when a warning starts or ends.
• Drawing. CapStyle, built with the code-defined portrayal toolkit: outlines and hatching by severity and the event as a label, one sub-layer on the CautionsAndWarnings plane at priority WithinPlanePriority, above S-124 (0).
• Picking. The headline, event, severity, urgency, certainty, times, sender, description and instruction (GetFeatureInfoAt(int)), led by NotForNavigationNotice. A pick only finds areas the last render drew.

CAP alerts aren't listed as navigational warnings (GetNavigationalWarnings() is empty): they don't follow S-124's numbering or cancellation rules.

The file is read whole at construction, which fails with a CapFormatException naming the file when it isn't CAP.

Constructors

CapDatasetProcessor(IAssetSource, string)

Reads the CAP file relativePath from source.

public CapDatasetProcessor(IAssetSource source, string relativePath)

Parameters

source IAssetSource

The asset source holding the file.

relativePath string

The file's source-relative path.

CapDatasetProcessor(Stream, string, MarineZoneLayer?)

Reads CAP from stream, which the processor disposes, resolving zone codes against zones.

public CapDatasetProcessor(Stream stream, string fileName, MarineZoneLayer? zones)

Parameters

stream Stream

The file's bytes; disposed before the constructor returns.

fileName string

The file's name, the dataset's id.

zones MarineZoneLayer

The marine zones; Default when null.

CapDatasetProcessor(string)

Reads the CAP file at path.

public CapDatasetProcessor(string path)

Parameters

path string

The file's path.

Fields

FeatureType

The feature type of every CAP area.

public const string FeatureType = "CapWarningArea"

Field Value

string

LayerKey

The CAP sub-layer's key.

public const string LayerKey = "cap.warnings"

Field Value

string

NotForNavigationNotice

The first line of every pick report on a CAP warning.

public const string NotForNavigationNotice = "Weather warning (CAP), not an S-100 product and not for navigation."

Field Value

string

SpecName

The spec name CAP files are registered under.

public const string SpecName = "CAP"

Field Value

string

WithinPlanePriority

The CAP sub-layer's order within the cautions and warnings plane: after S-124's 0.

public const int WithinPlanePriority = 10

Field Value

int

Properties

AvailableTimes

The ordered, distinct set of time steps available in the dataset. Empty when the dataset carries no temporal dimension.

public IReadOnlyList<DateTime> AvailableTimes { get; }

Property Value

IReadOnlyList<DateTime>

Cap12Spec

The spec every CAP file reports: CAP/1.2.0.

public static SpecRef Cap12Spec { get; }

Property Value

SpecRef

FileName

The dataset's file name.

public string FileName { get; }

Property Value

string

Metadata

The lightweight, product-agnostic DatasetMetadata for this dataset — its declared specification and, where cheaply derivable, its geographic extent, horizontal CRS, display-scale window, and temporal coverage. Overriding processors derive it once from the already-parsed dataset (never a second parse) and cache it, so hosts can frame a viewport, register a layer, draw an out-of-scale indicator, or gate visibility without re-reading the dataset. The default implementation does not override this and instead returns a fresh, minimal value carrying only Spec on each access; processors that can supply an extent (and other facts) override it with the derive-once-and-cache behaviour above. See issue #467 / #460.

public DatasetMetadata Metadata { get; }

Property Value

DatasetMetadata

Remarks

The areas' WGS-84 extent and the first start to the last end of the drawable warnings.

Spec

The product specification (name + edition) this dataset declares conformance to. Each per-spec processor returns a fixed name (e.g. "S-101"); the edition portion is populated from the dataset itself (HDF5 productSpecification attribute, GML application namespace, S-101 ProductSpecificationEdition, etc.) when known, otherwise defaults to SpecVersion default.

public SpecRef Spec { get; }

Property Value

SpecRef

TimeSemantics

What the time steps are, which one is drawn between steps, and how long a step stays valid. Defaults to Default: forecast steps, nearest within the typical step.

public TimeSemantics TimeSemantics { get; }

Property Value

TimeSemantics

Warnings

Every area of the file, resolved and timed.

public CapWarningSet Warnings { get; }

Property Value

CapWarningSet

Methods

BuildMetadata(CapWarningSet)

Builds the dataset metadata of a set of CAP areas.

public static DatasetMetadata BuildMetadata(CapWarningSet warnings)

Parameters

warnings CapWarningSet

The areas.

Returns

DatasetMetadata

BuildVectorPortrayalAsync(RenderContext?, CancellationToken)

Builds an immutable, Mapsui-free snapshot of this dataset's vector portrayal for the supplied render context. Implementations run under the processor's render gate and snapshot all mutable portrayal state (palette, ECDIS display, asset pre-warm) so the result is safe to convert to Mapsui layers off the gate.

public Task<VectorPortrayalResult> BuildVectorPortrayalAsync(RenderContext? context = null, CancellationToken cancellationToken = default)

Parameters

context RenderContext

Optional render context (palette, scales, ECDIS, mariner).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<VectorPortrayalResult>

The Mapsui-free vector portrayal result.

CreateLoadedData()

Allocates the LoadedDatasetData variant wrapping this processor's already-parsed model. Never re-reads the source bytes.

public LoadedDatasetData CreateLoadedData()

Returns

LoadedDatasetData

The catalog payload wrapping the resident model (e.g. an S125DatasetData or S102CoverageData).

DrawnAt(DateTime?)

The areas drawn at timeStep, or every drawable area when it is null.

public IReadOnlyList<CapWarningArea> DrawnAt(DateTime? timeStep)

Parameters

timeStep DateTime?

The render context's time step (UTC), or null.

Returns

IReadOnlyList<CapWarningArea>

EnumerateFeatures()

Enumerates a lightweight summary of every feature exposed by this processor — used to seed the viewer's feature-search index without forcing a full GetFeatureInfo(string) call per feature.

public IEnumerable<FeatureSummary> EnumerateFeatures()

Returns

IEnumerable<FeatureSummary>

Remarks

Coverage products (S-102, S-104, S-111) and any processor that does not expose discrete features should leave this returning the default empty enumeration.

GetFeatureGeometryAt(int)

Returns the renderer-neutral geometry of the feature at the given enumeration ordinal — the same index reported by Ordinal and carried by Ordinal, so a pick resolves to its outline the same collision-free way GetFeatureInfoAt(int) resolves its attributes. Lets a host highlight or outline a picked feature without reaching into a product's feature model.

public S100FeatureGeometry? GetFeatureGeometryAt(int ordinal)

Parameters

ordinal int

Returns

S100FeatureGeometry

The feature's geometry, or null when the ordinal is out of range or this processor does not expose discrete vector features (coverage / non-vector products leave the default and pick through GetCoverageInfo(double, double, DateTime?)).

GetFeatureInfo(string)

Returns information about a feature identified by its reference string (as stored in the rendered feature via the renderer's feature-ref key), or null if the feature cannot be found.

public FeatureInfo? GetFeatureInfo(string featureRef)

Parameters

featureRef string

Returns

FeatureInfo

Remarks

Real-world datasets occasionally contain features that share a gml:id (a producer bug), so callers that already know the feature's position within the dataset should prefer GetFeatureInfoAt(int) for a collision-free lookup.

GetFeatureInfoAt(int)

Returns information about the feature at the given enumeration ordinal — the same index reported via Ordinal from EnumerateFeatures(). Used by the search index so duplicate gml:ids (a real producer bug) still route to the correct feature.

public FeatureInfo? GetFeatureInfoAt(int ordinal)

Parameters

ordinal int

Returns

FeatureInfo

Feature info, or null when the ordinal is out of range or this processor does not expose discrete features.

Remarks

The attributes, in order: the notice, headline, event, severity, urgency, certainty, onset (or effective), expires, the hazard's end when the NWS gives one, sent, the sender, the area, its zones and any zone codes not found, the message type and status, a supersession, the description, the instruction and the identifier. Missing values are left out.

HitTestFeatures(double, double, double)

Hit-tests this dataset's vector features against a geographic point, returning every feature whose geometry contains the point (area features) or lies within radiusMeters of it (point / curve features), in feature-enumeration order. The reusable geographic complement to GetCoverageInfo(double, double, DateTime?): a caller resolves each hit to full attributes via GetFeatureInfoAt(int) (or GetFeatureInfo(string)) and ranks the results across datasets itself — for example by a rendering paint stack, which the processor contract deliberately knows nothing about.

public IReadOnlyList<FeatureGeometryHit> HitTestFeatures(double latitude, double longitude, double radiusMeters)

Parameters

latitude double

Pick latitude in WGS-84 degrees.

longitude double

Pick longitude in WGS-84 degrees.

radiusMeters double

Search tolerance for point/curve features in metres; area features use exact containment and ignore it. Negative or non-finite values are treated as 0.

Returns

IReadOnlyList<FeatureGeometryHit>

The matching features in enumeration order — each Ordinal aligns with GetFeatureInfoAt(int) — or an empty list. Vector processors override this; coverage / non-vector processors leave the default empty implementation and expose picks through GetCoverageInfo(double, double, DateTime?) instead.

Remarks

Only the areas the last render drew (every drawable area before the first render).

ReadMetadata(string)

Reads the metadata of the CAP file at path: its spec, extent and time coverage.

public static DatasetMetadata ReadMetadata(string path)

Parameters

path string

The file's path.

Returns

DatasetMetadata

RenderHeadlessAsync(int, int, RenderContext?, RgbaColor?, CancellationToken)

Renders the warnings in force at the context's time step to a bitmap, framed on every area of the file (or on Viewport).

public Task<SKBitmap> RenderHeadlessAsync(int widthPixels, int heightPixels, RenderContext? context = null, RgbaColor? background = null, CancellationToken cancellationToken = default)

Parameters

widthPixels int

Output width in pixels.

heightPixels int

Output height in pixels.

context RenderContext

Palette, time step, scales and viewport.

background RgbaColor?

Background fill; opaque white by default.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<SKBitmap>

A new bitmap owned by the caller.