Table of Contents

Command-line rendering

s100 is a cross-platform command-line tool for S-100 datasets. It renders one dataset, or a composite of several, to a PNG, JPEG or WebP image, or to a raster tile set for web maps, and serves those tiles to web maps and GIS desktops. It also validates datasets and exchange sets, reports what a dataset contains, picks the features at a point, checks routes, converts S-57 and S-101 cells, predicts tides and tidal currents, serves datasets to AI agents over MCP, and publishes datasets as an S-100 feed.

s100 uses the same portrayal and validation code as the EncDotNet.S100 library and SoundCharts. It renders through headless Skia renderers, so it needs no display and suits batch scripts and CI pipelines.

Install

Download the s100 archive for your platform from the latest GitHub release. Each archive is self-contained: it bundles the .NET runtime and SkiaSharp's native libraries, so you don't need to install .NET.

Platform Asset
Windows x64 s100-<version>-win-x64.zip
Windows arm64 s100-<version>-win-arm64.zip
macOS (Apple silicon) s100-<version>-osx-arm64.tar.gz
Linux x64 s100-<version>-linux-x64.tar.gz
Linux arm64 s100-<version>-linux-arm64.tar.gz

On macOS or Linux, extract the archive and run the tool from the extracted folder:

tar -xzf s100-<version>-<rid>.tar.gz
./s100 list-specs

On Windows, extract the .zip and run s100.exe list-specs.

The macOS binary is code-signed and notarized, and Gatekeeper checks the notarization online the first time it runs. If macOS still quarantines the binary, for example after you copy it from another machine, clear the attribute:

xattr -d com.apple.quarantine ./s100

The Windows s100.exe is Authenticode-signed.

On Linux, every command needs the ICU library for .NET globalization. Minimal and container images often leave it out, and without it s100 stops at startup with a Couldn't find a valid ICU package error. On Ubuntu 24.04 install libicu74; on Debian 12 install libicu72:

sudo apt-get update
sudo apt-get install -y libicu74

render draws labels with a font built into the renderer, so fontconfig is optional. Install fontconfig and a font package such as fonts-dejavu-core if you want labels in a system font, or to silence the Fontconfig error: Cannot load default config file warning.

Nightly builds

Nightly builds of s100 are published from main to the nightly prerelease when main has changed since the last one. Use them to try a fix or feature before it's released. They're unsupported: they pass CI but get no other testing, and they can have bugs or unfinished features.

The release's assets keep the same names, so their links always get the newest nightly:

Platform Asset
Windows x64 s100-nightly-win-x64.zip
Windows arm64 s100-nightly-win-arm64.zip
macOS (Apple silicon) s100-nightly-osx-arm64.tar.gz
Linux x64 s100-nightly-linux-x64.tar.gz
Linux arm64 s100-nightly-linux-arm64.tar.gz

Install and run a nightly the same way as a release. Its version is the next patch release plus the build date, such as 0.25.2-nightly.20261022, and s100 --version marks it as a nightly build. A nightly still shows update notices for newer stable releases. To go back to a stable build, install the archive from the latest release in its place.

Docker

The ghcr.io/philliphoff/s100 container image runs s100 on Linux x64 and arm64, with no other install. See Run s100 in Docker.

The copy inside SoundCharts

SoundCharts ships the same s100 executable in a cli/ folder:

Platform Location
macOS SoundCharts.app/Contents/MacOS/cli/s100
Windows cli/s100.exe next to the app executable
Linux cli/s100 next to the app executable

On macOS this copy is signed with the app, so Gatekeeper doesn't prompt for it.

Run from source

From a clone of the repository, run the tool with the .NET SDK. Arguments after -- go to s100:

dotnet run --project tools/EncDotNet.S100.Cli -- list-specs

Commands

Command What it does
render Renders a dataset, a composite of datasets, or a whole exchange set to an image, or writes a dataset's display list as JSON.
tiles export Renders a dataset, a composite of datasets, or a whole exchange set as XYZ raster tiles: a {z}/{x}/{y} folder, a PMTiles archive, an MBTiles database, a GeoPackage or a GeoTIFF.
tiles serve Serves a built tile set or datasets on XYZ URLs and as WMTS and WMS services, for web maps and GIS desktops on this or another computer.
info Shows the detected product specification, edition, render support, display modes and time steps.
identify Lists the features and coverage values at a latitude and longitude, including weather grids and warnings.
validate Checks a dataset against its specification's rule pack, or checks an exchange set's signatures and checksums.
route check Checks an RTZ or S-421 route against datasets, and its under-keel clearance when it has a draft.
tides stations Lists tide stations near a point, from the offline station catalogue.
tides predict Predicts the tide at a station, as heights, highs and lows, or an S-104 dataset.
tides currents stations Lists tidal current stations near a point, from the offline station catalogue.
tides currents predict Predicts the tidal current at a station, as speeds and directions, slacks and maxima, or an S-111 dataset.
tides update Downloads NOAA's tide and current stations into the offline catalogue, or checks for newer data.
list-specs Lists the supported product specifications.
sources Lists the live data sources --source takes, with their options and what each still needs.
health Checks that a tiles serve, feed serve or mcp serve --transport http on this computer answers, for container health checks.
s57 convert Converts an S-57 cell to an S-101 dataset, or an inland ENC cell to S-401.
s101 convert Converts an S-101 dataset to an S-57 cell or exchange set, for testing and S-57-only tools.
mcp serve Serves the S-100 MCP tools for a set of datasets, over standard input and output or HTTP.
feed serve Serves a folder, exchange set or dataset as an S-100 feed over HTTP.
feed export Writes a folder, exchange set or dataset as a static S-100 feed.

These options work without a command:

Option What it does
--help Prints help. Add it after a command for that command's help, for example s100 render --help.
--version Prints the tool's version. Nightly builds add (nightly build, unsupported).
--skill Prints a single Markdown document that describes every command, option, example, exit code and limitation. It's written for AI agents, has no ANSI styling, and skips the update check.

Update notices

Release and nightly builds check the repository's latest GitHub release at most once every 24 hours. The latest release is always a stable one, never a nightly. When a newer version exists, each run writes one line to standard error:

Update available: s100 0.25.0 (current 0.24.0): https://github.com/philliphoff/EncDotNet.S100/releases/tag/v0.25.0

Standard output and the exit code don't change, so you can still parse JSON output. Network and cache failures are silent. Development builds don't check. To turn the check off, set the S100_NO_UPDATE_CHECK environment variable to 1, true or yes. The container image sets it.

render

s100 render <dataset> <output> [options]
s100 render --layer <dataset> [--layer <dataset> ...] <output> [options]
s100 render <exchange-set> <output> [options]

render detects each input's product specification, runs its portrayal, and writes an image. S-104 defines no portrayal, so S-104 is drawn with SoundCharts' own gauges and isolines; see S-104 portrayal. It has three forms:

  • Single dataset. Pass a dataset file and an output path.
  • Composite. Pass --layer once per dataset. The datasets are drawn into one image in the order the S-98 interoperability rules give them. Give the output path last, or with -o.
  • Exchange set. Pass a folder that holds a CATALOG.XML, a CATALOG.XML file, or a .zip with one at its root. render composites every dataset it can render. s100 recognises an exchange set given as the first argument; you can also name it with --exchange-set or --from.

The output format comes from the output file's extension: .png, .jpg or .jpeg, .webp, or .json for a display list. Any other extension writes PNG, unless you set --format.

Render options

Option Default Description
--layer <path> none Adds a dataset as a composite layer. Repeat it for each dataset.
--exchange-set, --from <path> none Composites an exchange set: a folder with CATALOG.XML, the CATALOG.XML file, or a .zip. Can't be combined with --layer.
--only <specs> all Exchange-set form only. Composites only these product specifications, comma-separated, for example --only S101,S128. Hyphens and case are ignored.
-o, --output <path> positional The output path. Use it instead of the positional output argument.
--source <source> none Composite and exchange-set forms only. Also draws a live data source above the datasets, such as NDBC observations or AIS targets. Repeat it for each source. A source id, optionally followed by : and comma-separated name=value options. Needs --bbox or --center and --scale: the source is started for that area. See Live sources in a render.
--source-timeout <seconds> 30 How long to wait for each --source's first data.
-w, --width <pixels> 1024 Image width.
-h, --height <pixels> 768 Image height.
--format <format> from the extension, else png png, jpeg (or jpg), webp or json. A --format that contradicts a recognised output extension is an error. json works in the single-dataset form only.
--quality <1-100> 90 Encoder quality for jpeg and webp. Ignored for png.
--palette <palette> day day, dusk or night.
--national-language <code> the catalogue's, eng ISO 639-2 language, such as fra, to prefer for chart text where the product's portrayal supports it (S-101, S-131). A feature with no name in that language shows its default name.
--symbol-scale <factor> 1.0 Symbol scale factor.
--text-scale <factor> 1.0 Text scale factor.
--time-step <index> 0 Zero-based time step for time-series datasets (S-104, S-111, GRIB2, NetCDF, CAP). s100 info lists the steps.
--background <hex> opaque white Background colour, #RRGGBB or #AARRGGBB.
--bbox <minLon,minLat,maxLon,maxLat> fit to the data Draws this WGS-84 bounding box. Can't be combined with --center and --scale.
--center <lon,lat> fit to the data Centre of the view. Use with --scale.
--scale <denominator> fit to the data Scale denominator, for example 50000 for 1:50,000. Use with --center.
--no-text off Hides text. Same as --hide text.
--hide <categories> none Hides drawing-instruction categories, comma-separated: text, points, lines, areas. Adds to --no-text.
--basemap <mode> none offline draws the bundled Natural Earth 1:10m land layer under the chart, in a parchment tone (238,232,220). Online tile basemaps aren't available.
--display-mode <mode> ice-concentration S-411 only. ice-concentration, ice-sod (stage of development), or ice-navigational. See Sea-ice display modes.
--show-layer <keys> none Single-dataset form only. Draws sub-layers that are off by default, comma-separated by key, as the SoundCharts Display controls switches do: for example weather.precipitation,weather.cape,weather.cloud. s100 info lists a dataset's layer keys.
--no-updates off Single-dataset form only. Renders an S-101 base cell without its update files. See S-101 updates.
--lua-engine <engine> luacsharp The Lua engine that runs the portrayal rules: luacsharp or moonsharp. See Lua engine.
--debug off Prints full stack traces on error, and portrayal and Lua diagnostics on standard error.

--hide, --no-text and --basemap apply to every layer of a composite.

Live sources in a render

--source draws a live data source over a composite, as SoundCharts draws a live feed over the chart. Each source is started for the --bbox or --center and --scale area and given --source-timeout for its first data. A source with nothing by then, or whose range is narrower than the area, is left out with a warning on standard error, and the image is written without it. An unknown source or option exits with code 2. A source that needs a key reads it from its environment variable, never from --source. sources lists them.

s100 render --layer chart.000 -o buoys.png --bbox -70.9,42.2,-70.5,42.5 --source ndbc.realtime

Render examples

s100 render currents.h5 currents.png --time-step 6 --palette night
s100 render warnings.gml warnings.png --width 2048 --height 1536
s100 render warnings.gml warnings.jpg --quality 85
s100 render warnings.gml preview.webp
s100 render seaice.gml seaice.png --no-text
s100 render seaice.gml seaice.png --basemap offline
s100 render chart.gml chart.png --hide text,points
s100 render enc.000 window.png --bbox -1.5,50.0,-1.0,50.5
s100 render enc.000 window.png --center -1.25,50.25 --scale 50000
s100 render bathy.h5 window.png --bbox -1.5,50.0,-1.0,50.5

Composite several datasets:

s100 render --layer enc.000 --layer bathy.h5 --layer warnings.gml chart.png
s100 render --layer enc.000 --layer bathy.h5 -o chart.png --bbox -1.5,50.0,-1.0,50.5
s100 render --layer enc.000 --layer warnings.gml chart.png --basemap offline

Composite an exchange set:

s100 render exchange-set/ chart.png
s100 render exchange-set/CATALOG.XML chart.png
s100 render --exchange-set exchange-set.zip -o chart.png
s100 render --from exchange-set/ chart.png --only S101,S102

Viewport

Without --bbox or --center and --scale, render fits the image to the dataset's extent, or to the combined extent of every layer. The fit handles the antimeridian: data that crosses ±180°, such as an S-411 product spanning 175°E to 225°E, is framed on its own narrow extent instead of the whole world.

With an explicit viewport:

  • A single vector dataset also applies scale visibility (S-100 Part 9), so features outside their display-scale range are hidden.
  • Gridded S-102, S-104 and S-111 coverages sample only the cells inside the viewport. For a projected grid, the window is transformed into the grid's own CRS, and the sampled cells are reprojected for output.
  • Station and node datasets (S-104, S-111) draw their glyphs in the viewport.
  • Any part of the image outside the data shows the background or basemap.

Compositing multiple datasets

  • Layer order. The S-98 interoperability rules order layers by display plane. The order of your --layer options only breaks ties within a plane, so it usually has no visible effect. For example, an S-102 surface already draws above an S-101 chart.
  • Overlapping cells. Where a finer chart cell's data coverage overlaps a coarser cell, the coarser cell is hidden there, as in SoundCharts. A cell's data coverage is the union of its coverage areas, and a finer cell takes part only where its coverage meets the coarser cell's, not just its bounding box. Cells are ranked by compilation scale, or by minimum display scale when a cell has none. Between cells of the same minimum display scale, the one with the finer maximum display scale ranks finer. Cells of the same rank don't hide each other.
  • No S-101 updates. The composite and exchange-set forms don't apply S-101 update files. To render a cell with its updates, render it on its own.
  • Skipped datasets. In an exchange set, datasets with an unsupported product specification, a missing file, or data protection (encryption) are skipped with a warning on standard error. Update files, and updates whose base cell isn't in the set, are skipped too. If nothing renderable is left, render exits with code 2.
  • ZIP archives. A .zip exchange set is extracted to a temporary folder, which is deleted afterwards, even if rendering fails. You need temporary disk space about the size of the uncompressed set.

S-101 updates

When the single-dataset form renders an S-101 base cell (.000), it finds the update files (.001, .002, and so on) in the same folder and applies them in order first (S-100 Part 10a). info and validate do the same. A missing, out-of-order or unreadable update is reported but doesn't stop the command. Pass --no-updates to use the base cell as it is.

Sea-ice display modes

An S-411 dataset carries the full WMO egg code, so the same data can be drawn in any of its display modes:

  • ice-concentration: total concentration. This is the default.
  • ice-sod: stage of development.
  • ice-navigational: a provisional preview derived from total concentration. It isn't a POLARIS or RIO navigational-risk calculation.

In a composite, every S-411 layer uses the mode. Passing --display-mode for a dataset that isn't S-411 is an error. s100 info lists the modes a dataset supports.

Display-list output

With a .json output path or --format json, the single-dataset form writes what the renderer draws as data instead of an image: every line, area, pattern fill, symbol and text label, with its full geometry, resolved colours and sizes, and the anchor it's placed at. A renderer in another process (an ArcGIS Pro or QGIS symbology exporter, a vector PDF or SVG writer) can draw the chart from it the way the viewer does. It's also handy to review, diff or snapshot-test a portrayal change as text.

s100 render 101AA00DS0008.000 chart.json
s100 render warnings.gml out.txt --format json

The entries come from the same scene the image is drawn from, so they already have the portrayal's decisions applied:

  • A line shared by several features (adjoining areas, or a line feature on an area's edge) is given once, by the line drawn last, so a shared dashed edge isn't drawn as overlapping copies that look solid (S-100 Part 9 line suppression).
  • A multi-part curve or surface gives one entry per part.
  • A pattern fill's rings are only the part left visible after higher-priority patterns and opaque fills are cut away.
  • Point symbols and text carry the anchor the viewer uses: the centroid or an interior point of a surface, the position along a curve, and so on.
  • Colours are resolved for the palette, and sizes are in display pixels.

Vector products (S-101, S-57 and the GML products) have display lists. Coverage products (S-102, S-104, S-111) don't, and render exits with code 3. --palette, --national-language, --symbol-scale, --text-scale, --display-mode, --time-step, --hide and --show-layer change the output as they change the image. --width, --height, --quality and --background are ignored. --bbox, --center and --scale are errors, because the output has no viewport. The output has no timings, so two runs over the same dataset and options produce identical files.

The document

{
  "schemaVersion": 2,
  "dataset": "101AA00DS0008.000",
  "product": "S-101",
  "spec": "S-101/0.0.0",
  "palette": "day",
  "symbolScale": 1,
  "textScale": 1,
  "crs": "EPSG:4326",
  "sizeProfile": {
    "svgPixelsPerMillimetre": 3.7795,
    "pointSymbolScale": 0.6,
    "millimetresPerPixel": 0.32,
    "patternPixelsPerMillimetre": 1.5,
    "pixelsPerFontPoint": 1
  },
  "subLayerCount": 2,
  "instructionCount": 517,
  "opCount": 517,
  "categoryCounts": { "areas": 43, "patterns": 17, "lines": 140, "points": 56, "text": 261 },
  "subLayers": [
    { "index": 0, "key": "s101.areas", "name": "S-101 (areas): 101AA00DS0008.000", "plane": "BaseChartUnder", "instructionCount": 60 }
  ],
  "ops": [
    {
      "kind": "line",
      "order": 118,
      "subLayer": 1,
      "feature": "42",
      "plane": "UnderRadar",
      "viewingGroups": [12410],
      "drawingPriority": 15,
      "coordinates": [[62.7584818, -32.4908714], [62.7724818, -32.4828714]],
      "lineStyle": "PILPNT01",
      "stroke": true,
      "widthPx": 1,
      "dashArrayPx": [18.75, 18.75],
      "symbolIntervalPx": 37.5,
      "lineSymbols": [{ "symbol": "PILPNT02", "positionPx": 28.125, "rotation": 0, "scale": 0.8268, "pivot": [0, 0] }],
      "color": "#4C5B63FF",
      "colorToken": "CSTLN"
    },
    {
      "kind": "text",
      "order": 209,
      "subLayer": 1,
      "feature": "25",
      "plane": "UnderRadar",
      "viewingGroups": [33020, 90031],
      "drawingPriority": 15,
      "anchor": [62.7230744, -32.4746663],
      "placement": { "kind": "Line", "part": 0, "linePosition": 0.5, "segment": 1, "segmentPosition": 0.5 },
      "text": "3",
      "fontSizePx": 10,
      "fontWeight": "Medium",
      "fontProportion": "Proportional",
      "fontSlant": "Upright",
      "horizontalAlignment": "Center",
      "verticalAlignment": "Center",
      "color": "#768C97FF",
      "colorToken": "DEPCN"
    }
  ]
}

schemaVersion changes when a field is removed or changes meaning. New fields can appear without a change, so ignore fields you don't know. Fields with no value are left out.

The top level:

Field Meaning
crs Always EPSG:4326: positions are [longitude, latitude] in degrees, as in GeoJSON, to 7 decimal places. Near the antimeridian a line or ring can run past ±180° so it stays continuous.
sizeProfile How S-100 Part 9 sizes were turned into display pixels. millimetresPerPixel converts any …Px value back to millimetres.
instructionCount Drawing instructions in the portrayal's display list.
opCount Entries in ops. An instruction can give several (one per edge or part) or none (no geometry, or every edge drawn by another line).
subLayers The portrayal's sub-layers, drawn in this order.
ops What's drawn, in draw order.

Every entry in ops has:

Field Meaning
kind area, pattern, line, point or text.
order Position in the draw order, from 0. Draw entries in this order.
subLayer Index into subLayers.
feature The dataset feature it portrays.
plane UnderRadar or OverRadar.
viewingGroups The viewing groups it belongs to. It's hidden if any of them is turned off.
drawingPriority Its S-100 Part 9 drawing priority.
scaleMinimum, scaleMaximum The scale denominators it's drawn between (SCAMIN, SCAMAX). Draw it when scaleMaximum ≤ the display's scale denominator ≤ scaleMinimum; a missing one is no limit.

By kind:

Kind Fields
area rings: the outer ring then any holes, each a list of positions. fill (#RRGGBBAA, with transparency applied), fillToken (the palette colour name), transparency, and outline (color, widthPx) when there is one.
pattern rings and areaFill, the catalogue area-fill name. The rings are the part left visible after clipping.
line coordinates; lineStyle, the catalogue line style or _simple_; stroke, false when the style only places symbols; color, colorToken, widthPx; dashArrayPx, alternating on and off lengths, with dashPhasePx where the first dash starts; defaultDash when the line is dashed with no dash lengths given; and lineSymbols repeated every symbolIntervalPx, each with its symbol name, positionPx within the interval, rotation relative to the line's direction, scale and pivot.
point anchor, placement, symbol (the catalogue symbol name), scale (multiply the symbol's SVG size at svgPixelsPerMillimetre by this), pivot (the symbol's pivot as a fraction of its width and height from the centre), rotation in degrees clockwise with rotationCrs (Portrayal keeps the angle on screen, Geographic turns with the chart), and offsetPx. A symbol that couldn't be found has fallbackColor instead, drawn as a dot.
text anchor, placement, text, font (the font reference, when given), fontSizePx, fontWeight, fontProportion, fontSlant, color, colorToken, background, halo (color, widthPx), horizontalAlignment, verticalAlignment, offsetPx and the portrayal's rotation, which the viewer doesn't apply.

offsetPx is [x, y] in display pixels from the anchor, with y as the renderer applies it on screen.

placement says how a point symbol's or text's anchor was chosen:

Field Meaning
kind Point (the feature's point, or the first vertex), Coordinate (a position given by the portrayal, such as each sounding), Line (a fraction along a curve), Surface (inside a surface), CurveMiddleVertex or RingVertexMean.
part The part of a multi-part feature it's on.
linePosition For Line, the fraction along the curve, from 0 to 1.
segment, segmentPosition For Line, the vertex that starts the segment the anchor is on and how far along that segment, in the feature's own latitude and longitude. For CurveMiddleVertex, segment is the vertex.
visibleParts true when the viewer moves the anchor into the part of the surface in view as you pan. anchor is where it goes with the whole surface in view.

tiles export

s100 tiles export <dataset> -o <output> [options]
s100 tiles export --layer <dataset> [--layer <dataset> ...] -o <output> [options]
s100 tiles export <exchange-set> -o <output> [options]
s100 tiles export <folder> -o <output> [options]

tiles export renders datasets as raster tiles on the XYZ Web Mercator grid that MapLibre, Leaflet and OpenLayers use. The tiles carry the S-100 portrayal itself (symbols, scale minimums and palettes), so a web map shows the chart without styling it. It takes the same three input forms as render, and -o is required. It also takes a folder of datasets:

  • Folder. Pass any other folder, and every dataset in it and its subfolders is tiled, as mcp serve finds them. An S-100 exchange set inside it is read through its CATALOG.XML. An S-57 exchange set (an ENC_ROOT folder holding a CATALOG.031) is read as a folder of cells, whether you pass it, its CATALOG.031, or a folder above it, or name it with --from. Loose S-101 cells get their update files, as a single cell does, but cells in an S-100 exchange set don't. A dataset that can't be opened or tiled is skipped with a warning.

The container comes from the output path:

  • Folder. Tiles are written as <output>/{z}/{x}/{y}.png (or .jpg, .webp), with a tiles.json TileJSON file whose tile URL is relative to the folder.
  • PMTiles. An output ending in .pmtiles is written as one PMTiles version 3 archive, which a static web host can serve. Identical tiles are stored once. The archive's metadata holds the same TileJSON fields.
  • MBTiles. An output ending in .mbtiles is written as one MBTiles 1.3 SQLite database, the format many tile servers read. Rows are numbered from the south, as MBTiles requires. The metadata table holds the standard keys plus tileSize and the display settings, prefixed s100:.
  • GeoPackage. An output ending in .gpkg is written as one OGC GeoPackage 1.4 tile pyramid, which QGIS, ArcGIS Pro, GDAL and field apps such as QField open as an offline raster layer. The tiles are in a table named chart, in EPSG:3857 on the Web Mercator grid, so each zoom level is a tile matrix, and rows are numbered from the north as in XYZ. The TileJSON is kept as GeoPackage metadata. WebP tiles register the gpkg_webp extension, which not every reader supports, so use PNG or JPEG for the widest reach.
  • GeoTIFF. An output ending in .tif or .tiff is written as one Cloud-Optimized GeoTIFF in EPSG:3857, for tools that take a single georeferenced image. The maximum zoom is the full-resolution image and each lower zoom is an overview, down to an image a tile or two across, so --min-zoom only limits how far the overviews go. The image is whole tiles of its smallest overview, so it can reach past the data; tiles with nothing on them are left out of the file, and read as transparent. PNG and WebP tiles are stored as RGBA with Deflate compression, and JPEG tiles as they are (no transparency, and empty areas read as black). The file is a BigTIFF when it would pass 4 GB. It can't cross the antimeridian.

Set --container to choose the container whatever the extension. An existing .pmtiles, .mbtiles, .gpkg or .tif file at the output path is replaced only once the new one is finished: the new file is written beside it, with .partial added to its name, and then moved into its place. Until then a tiles serve reading the old file keeps serving it, and if the export fails or is stopped, the old file is left as it was.

Tiles export options

Option Default Description
--layer <path> none Adds a dataset as a composite layer. Repeat it for each dataset.
--exchange-set, --from <path> none Tiles an exchange set: a folder with CATALOG.XML, the CATALOG.XML file, or a .zip. Can't be combined with --layer.
--only <specs> all Exchange-set and folder forms only. Tiles only these product specifications, comma-separated.
-o, --output <path> required A folder, a .pmtiles file, a .mbtiles file, a .gpkg file or a .tif file. Its parent folder must exist.
--container <kind> from the output xyz (a folder), pmtiles, mbtiles, gpkg or geotiff.
--min-zoom <0-24> from the data Lowest zoom level. See Zoom levels.
--max-zoom <0-24> from the data Highest zoom level.
--bbox <minLon,minLat,maxLon,maxLat> the data's extent Writes only the tiles that cover this WGS-84 bounding box. Datasets that can't draw in those tiles aren't portrayed. See Zoom levels.
--tile-size <pixels> 256 256, or 512 for high-DPI tiles of the same grid.
--format <format> png png, jpeg (or jpg) or webp.
--quality <1-100> 90 Encoder quality for jpeg and webp. Ignored for png.
--palette <palette> day day, dusk or night.
--national-language <code> the catalogue's, eng ISO 639-2 language, such as fra, to prefer for chart text where the product's portrayal supports it (S-101, S-131). A feature with no name in that language shows its default name.
--symbol-scale <factor> 1.0 Symbol scale factor.
--text-scale <factor> 1.0 Text scale factor.
--time-step <index> 0 Zero-based time step for time-series datasets (S-104, S-111).
--background <hex> transparent Tile background, #RRGGBB or #AARRGGBB.
--no-text off Hides text. Same as --hide text.
--hide <categories> none Hides drawing-instruction categories, comma-separated: text, points, lines, areas.
--basemap <mode> none offline draws the bundled Natural Earth land layer under the chart.
--display-mode <mode> ice-concentration S-411 only. See Sea-ice display modes.
--display-category <category> all Mariner setting: the ECDIS display category, display-base, standard, other-information or all.
--safety-contour <metres> 30 Mariner setting: the safety contour.
--safety-depth <metres> 30 Mariner setting: the safety depth. Shallower soundings are emphasised.
--shallow-contour <metres> 2 Mariner setting: the shallow contour, used with --four-shades.
--deep-contour <metres> 30 Mariner setting: the deep contour, used with --four-shades.
--four-shades off Mariner setting: shades depth areas in four shades rather than two.
--no-soundings off Mariner setting: doesn't draw soundings.
--no-shallow-water-dangers off Mariner setting: doesn't emphasise isolated dangers in shallow water.
--symbolized-boundaries off Mariner setting: draws symbolized area boundaries rather than plain ones.
--simplified-symbols off Mariner setting: draws simplified point symbols rather than paper-chart ones.
--full-light-lines off Mariner setting: draws light sector legs to their full nominal range.
--ignore-scamin off Mariner setting: draws features at every scale, ignoring their scale minimum (SCAMIN).
--depth-unit <unit> metres Mariner setting: the unit depths are shown in, metres, feet, fathoms-feet or fathoms.
--skip-empty off Doesn't write tiles on which nothing was drawn. A web map shows a missing tile as empty.
--metatile <tiles> 4 Renders blocks of this many tiles square at once, then cuts them apart.
--parallel <workers> processor count Number of blocks rendered at once.
-y, --yes off Writes a tile set of more than 100,000 tiles without asking.
--no-updates off Tiles an S-101 base cell, given on its own, with --layer or loose in a folder, without its update files.
--lua-engine <engine> luacsharp The Lua engine that runs the portrayal rules: luacsharp or moonsharp. See Lua engine.
--debug off Prints full stack traces on error, and portrayal and Lua diagnostics on standard error.

Tiles export examples

s100 tiles export enc.000 -o tiles/
s100 tiles export enc.000 -o chart.pmtiles --min-zoom 10 --max-zoom 15
s100 tiles export --layer enc.000 --layer bathy.h5 -o chart.pmtiles --tile-size 512
s100 tiles export exchange-set/ -o tiles/ --format webp --skip-empty
s100 tiles export enc.000 -o chart.mbtiles --max-zoom 16
s100 tiles export exchange-set/ -o chart.gpkg --format jpeg
s100 tiles export enc.000 -o chart.tif --max-zoom 15 --skip-empty
s100 tiles export --from exchange-set.zip -o night.pmtiles --bbox -1.5,50.0,-1.0,50.5 --palette night

To show a PMTiles archive in MapLibre GL JS, register the pmtiles protocol from the PMTiles JavaScript library and add a raster source over your basemap:

const protocol = new pmtiles.Protocol();
maplibregl.addProtocol("pmtiles", protocol.tile);

map.addSource("chart", {
  type: "raster",
  url: "pmtiles://https://example.com/chart.pmtiles",
  tileSize: 256,
});
map.addLayer({ id: "chart", type: "raster", source: "chart" });

Declare tileSize: 256 for 512-pixel tiles too: they cover the same grid at twice the pixel density. A folder of tiles is added the same way, with tiles: ["https://example.com/tiles/{z}/{x}/{y}.png"] in place of url. The host must answer HTTP range requests for PMTiles; most static hosts do. To try an archive before you publish it, tiles serve it and use its archive.pmtiles URL in place of the host's.

Zoom levels

Each zoom level draws only what's visible at its scale: features outside their scale minimum, and whole cells past their minimum display scale, are left out. A zoom level's scale is measured at the centre latitude of the tiled area, so it's the same in every tile and no feature is cut off at a tile edge. The metadata records that latitude as scaleLatitude.

Where chart cells of different scales overlap, the finer cell hides the coarser one at each zoom level where the finer cell draws. Zoomed out past the finer cell's minimum display scale, the coarser cell shows in full again.

Without --min-zoom, the lowest zoom is the one nearest the coarsest cell's minimum display scale. Without --max-zoom, the highest is one level past the finest cell's compilation scale. Products without these scales, such as GML products and coverages, start at the zoom where their extent fits in about one tile and go six levels deeper, up to zoom 18.

With --bbox, datasets that can't draw in any of its tiles are closed before they're portrayed, and tiles export says how many it left out. A dataset is kept when its extent reaches the tiles that cover the box at the lowest zoom, or the ring of tiles around them, so symbols and text near an edge tile are drawn as they would be without --bbox. This saves time and memory when the box covers a small part of a large folder. The default zoom range then comes from the datasets that are kept. For a box that crosses the antimeridian, every dataset is kept.

tiles export prints the number of tiles before it renders any. Each zoom level has four times the tiles of the one before, so a set grows quickly. Above 100,000 tiles, tiles export asks before writing, or exits with code 2 when it can't ask. Pass --yes to skip the question, or narrow --bbox or the zoom range.

Tile set limits

  • One palette and time step. A tile set holds one --palette and one --time-step. Run tiles export again for each one you need.
  • Coverages. S-102, S-104 and S-111 are portrayed again for each zoom level, so grid sampling and current-arrow spacing suit its resolution.
  • S-101 updates. As with render, the exchange-set form doesn't apply S-101 update files.

tiles serve

s100 tiles serve <tile-set> [options]
s100 tiles serve <dataset> [options]
s100 tiles serve --layer <dataset> [--layer <dataset> ...] [options]
s100 tiles serve <exchange-set> [options]
s100 tiles serve <folder> [options]

tiles serve serves raster tiles over HTTP on the standard XYZ URLs, so a web map running on this computer can use them as a tile source. It serves either:

  • A built tile set: a {z}/{x}/{y} folder, a .pmtiles archive, a .mbtiles database or a .gpkg GeoPackage that tiles export or another tool wrote. A GeoPackage must hold tiles in EPSG:3857 on the Web Mercator grid, as tiles export and GDAL's GoogleMapsCompatible tiling scheme write them. The tile set is read at each request, so if you export it again while it's served, the next request sees the new tiles. A .pmtiles, .mbtiles or .gpkg file keeps serving its old tiles until the new export is finished. Only PNG, JPEG and WebP raster tiles are served, not vector tiles.
  • Datasets, rendered when each tile is first asked for. It takes the same inputs and display options as tiles export: one dataset, repeated --layer, an exchange set, or a folder of datasets. Nothing has to be built in advance, and the tiles are the same as an export of the same datasets would hold.

A folder is served as a built tile set only when it looks like one: it holds a tiles.json, or numbered {z}/{x} subfolders. Any other folder is searched for datasets, as tiles export searches it.

When it renders datasets, tiles serve renders the block of --metatile × --metatile tiles around a requested tile and keeps every tile of the block in memory, up to --cache-mb, so neighbouring tiles come back at once. At most --parallel blocks render at a time. With --verbose, it prints a line for each block it renders: the zoom and tiles, the time spent waiting for a render slot, preparing the zoom level, drawing and encoding, and how many requests waited on it.

While it serves datasets, tiles serve checks their files every --refresh seconds (default 10) and reopens them when they change: when you copy in a new edition, add S-101 update files, or add or remove datasets in a served exchange set or folder. It waits until a change has held for two checks in a row, so a file still being copied isn't read half-written. The new data is opened and portrayed while the old keeps serving, then tiles are rendered from it with an empty cache. If it can't be opened, the old data keeps serving until the files change again. --refresh 0 turns the checks off. A built tile set needs none: it's read at each request.

When rendering datasets, the server publishes the data revision: the fingerprint the --cache-dir tiles are kept under (see below), 32 hexadecimal characters that change whenever a dataset or a setting that changes pixels does, including when --refresh reopens changed datasets. It's in s100.revision in the TileJSON, in the updateSequence attribute of the WMS and WMTS capabilities, and in the S100-Revision header of /healthz. A client that keeps its own tile cache, such as ArcGIS Pro for WMTS, can poll it and put it in its tile URLs (as an extra query parameter, which the server ignores) to fetch fresh tiles after a change. A built tile set has no revision.

With --cache-dir, rendered tiles are also kept in that folder (in its served subfolder), so they come back without rendering after a restart. They're stored under a fingerprint of the data and settings: each input file's path, size and write time (S-101 update files and the whole of an exchange set or folder included), the display and format options, and the s100 version. Change any of them and new tiles are rendered, so a kept tile is never stale. The folder holds up to --cache-dir-mb, least recently used tiles going first, including those of data or settings you no longer serve. --clear-cache empties it before serving. Only the served subfolder is read or deleted, so other files in the folder are left alone, and several servers can share one folder. The zoom levels and the area served are worked out as for tiles export, and --min-zoom, --max-zoom and --bbox narrow them. --palette sets the palette of the plain tile URLs; the other palettes are served too, under their own URLs.

The server has these routes:

  • {z}/{x}/{y}.png (or .jpg, .webp), the tiles. Rows are numbered from the north for every container, MBTiles included. When rendering datasets, {z}/{x}/{y}@2x.png is the same tile at 512 pixels, for high-DPI screens; see High-DPI tiles. Each tile has an ETag so browsers can revalidate it. A tile with nothing on it, or outside the tile set, answers 204 No Content, which web maps show as empty.
  • tiles.json, a TileJSON document with the zoom levels, bounds and display settings, and an absolute tile URL.
  • When rendering datasets, day/, dusk/ and night/ hold the same two routes in that palette, for example night/{z}/{x}/{y}.png and night/tiles.json. Each palette is portrayed the first time it's asked for.
  • When rendering datasets, settings/{hash} registers a set of mariner settings, served as the style {palette}-{hash}, for example day-a1b2/{z}/{x}/{y}.png. See Mariner settings.
  • When rendering time-varying datasets (S-104, S-111), a t query parameter on either route picks the time step, for example {z}/{x}/{y}.png?t=2026-03-21T07:00Z. The time is ISO 8601, UTC unless it says otherwise, and snaps to the nearest step; each dataset then uses its own step nearest to it. The TileJSON lists every step in s100.times, and with t it names the chosen step in s100.time and carries it in its tile URL. Without t, --time-step applies. A t that isn't a time answers 400 Bad Request; datasets that don't vary with time ignore it.
  • With --strict-time, a t (or WMS/WMTS TIME) more than half a step before a time-varying dataset's first step, after its last or inside a gap in its steps draws nothing for that dataset, instead of its nearest step. A step is the median interval between the dataset's steps (an hour for a single step). A tile on which nothing draws answers 204 No Content. The TileJSON then sets s100.strictTime and, with t, lists each time-varying dataset in s100.datasets with its file name, spec and the step it draws in time, null when it has no data at that time. When the datasets draw other than at their steps nearest the nearest listed step, s100.time and the tile URL keep the t asked for.
  • When rendering S-124 navigational warnings, a t (or WMS TIME, or the WMTS Time dimension) draws only the warnings in force at that instant, as the viewer's map does at its view time: a warning that has ended, been cancelled or dropped from the latest in-force bulletin, or isn't in force yet, isn't drawn (S-98 §12.12). Without a time every warning draws, as before. Times at which the same warnings are in force share their tiles, and the TileJSON for such a t keeps it in s100.time and its tile URL. With S-124 alone there are no time steps to list, so the capabilities advertise no Time dimension; a client still sends TIME= (WMS, WMTS KVP) or t.
  • With --overview, tiles below the datasets' minimum zoom show where the datasets are instead of answering 204. See Overview below the minimum zoom.
  • When serving a .pmtiles archive, archive.pmtiles, the archive itself, with HTTP range requests, so a PMTiles client such as MapLibre's pmtiles:// protocol reads it as it would from a static host. Use it to check an archive before you publish it. Its ETag and Last-Modified change when the archive is exported again, so a client notices the new file rather than mixing parts of the two. The TileJSON names it in s100.pmtilesUrl.
  • wmts/1.0.0/WMTSCapabilities.xml, an OGC WMTS 1.0.0 capabilities document, and wmts, the same service in the KVP encoding, so GIS desktops such as QGIS and ArcGIS Pro can add the tiles.
  • wms, an OGC WMS 1.3.0 service: GetCapabilities, GetMap, and, when rendering datasets, GetFeatureInfo and GetLegendGraphic.
  • With --manage-datasets, a POST or DELETE of datasets adds or removes datasets. See Add and remove datasets.
  • With --layers-by product, or datasets added to a named layer, each layer's tiles and TileJSON under layers/{layer}/, as the tiles of every dataset are under the root. See WMTS layers.
  • /, a preview page that shows the tiles over OpenStreetMap, with a palette menu when rendering datasets and a time menu when they vary with time. It loads MapLibre GL JS and the basemap from the internet. Pass --no-viewer to turn it off.
  • /healthz, which answers 200 OK with the text ok while the server runs. It never has a token. When rendering datasets, its S100-Revision header holds the data revision. See health.

Every response allows any origin, so a page served from another port can use the tiles.

By default only this computer can connect. With --host 0.0.0.0, other computers can, and tiles serve adds a random access token to every URL unless you pass --token or --no-token. It prints the tile URL, the TileJSON URL and the preview URL for each network address.

The options below are the server's own. When rendering datasets, the tiles export options for inputs, zoom levels, the area, the tile format and display settings apply too; the output options (-o, --container, --skip-empty, --yes) don't.

Option Default Description
--host <address> 127.0.0.1 The address to listen on. 0.0.0.0 accepts other computers.
--port <port> 8200 The port. 0 picks a free one.
--token <token> generated for a non-loopback host An access token that becomes part of every URL. Letters, digits, - and _.
--no-token off Serves without a token, even on a non-loopback address.
--no-viewer off Doesn't serve the preview page.
--ready-json off When the server is listening, also prints one line of JSON with the bound port and URLs. See Run under a supervising process.
--cache-mb <megabytes> 256 When rendering datasets, the most memory rendered tiles are kept in.
--refresh <seconds> 10 When rendering datasets, how often their files are checked for changes. 0 never checks.
--strict-time off When rendering datasets, a time more than half a step outside a time-varying dataset's steps draws nothing for it, instead of snapping to its nearest step.
--manage-datasets off When rendering datasets, accepts requests to add and remove datasets while serving. See Add and remove datasets.
--overview off When rendering datasets, draws each dataset's coverage outline and name below their minimum zoom instead of nothing, and advertises WMS and WMTS down to zoom 0. See Overview below the minimum zoom.
--layers-by <grouping> none When rendering datasets, also serves them as a WMTS layer per group, each with its own time steps and extent: product, or none. See WMTS layers.
--cache-dir <folder> none When rendering datasets, also keeps rendered tiles in this folder, across runs.
--cache-dir-mb <megabytes> 1024 The most disk space the --cache-dir tiles take.
--clear-cache off Deletes the tiles cached in --cache-dir before serving.
--verbose off When rendering datasets, prints a line for each block rendered, with where its time went.
s100 tiles serve chart.pmtiles
s100 tiles serve chart.mbtiles --port 9000
s100 tiles serve chart.gpkg
s100 tiles serve tiles/ --host 0.0.0.0
s100 tiles serve enc.000
s100 tiles serve --layer enc.000 --layer bathy.h5 --palette night
s100 tiles serve exchange-set/ --only S101 --max-zoom 16
s100 tiles serve exchange-set/ --cache-dir ~/.cache/s100-tiles

To use the tiles in MapLibre GL JS, add a raster source from the TileJSON URL:

map.addSource("chart", {
  type: "raster",
  url: "http://127.0.0.1:8200/tiles.json",
  tileSize: 256,
});
map.addLayer({ id: "chart", type: "raster", source: "chart" });

In Leaflet, use the tile URL: L.tileLayer("http://127.0.0.1:8200/{z}/{x}/{y}.png").addTo(map).

High-DPI tiles

On a high-DPI display, such as one scaled 2x, a map that stretches 256-pixel tiles shows soft text and lines. When it renders datasets, tiles serve also serves 512-pixel tiles of the same 256-pixel grid: each covers the same area at the same zoom as the 256-pixel tile, with symbols, text and line widths drawn at twice the pixel density, as tiles export --tile-size 512 writes them. They aren't 256-pixel tiles enlarged.

Ask for them by adding @2x to the row in any tile URL, for example {z}/{x}/{y}@2x.png, night/{z}/{x}/{y}@2x.png or layers/{layer}/{z}/{x}/{y}@2x.png. So one server answers both 1x and 2x clients:

  • TileJSON: add scale=2 to a TileJSON URL, as in tiles.json?scale=2, for a document whose tile URL has @2x and whose tileSize is 512. The TileJSON lists the pixel ratios served in s100.pixelRatios, [1, 2].

  • MapLibre GL JS: use the scale=2 TileJSON on a high-DPI screen, and declare tileSize: 256 for the source either way, so each tile fills 256 CSS pixels and the screen's extra pixels show the detail:

    const scale = window.devicePixelRatio > 1 ? "?scale=2" : "";
    map.addSource("chart", {
      type: "raster",
      url: "http://127.0.0.1:8200/tiles.json" + scale,
      tileSize: 256,
    });
    

    The preview page does this.

  • Leaflet: put {r} after the row in the tile URL. Leaflet replaces it with @2x on a high-DPI screen and with nothing otherwise: L.tileLayer("http://127.0.0.1:8200/{z}/{x}/{y}{r}.png"). Don't also pass detectRetina, which asks for the next zoom's tiles instead.

--tile-size 512 makes the 512-pixel tiles the plain {z}/{x}/{y} tiles, for a client that can't ask for @2x, such as one that uses WMTS:

s100 tiles serve exchange-set/ --tile-size 512 --cache-dir ~/.cache/s100-tiles
  • WMTS: the WebMercatorQuad matrices have 512-pixel tiles at half the scale denominator of each zoom, for every layer and style. They're no longer the well-known GoogleMapsCompatible scale set, so a client that matches tiles by scale shows each zoom's tiles at their own scale. WMTS has no @2x tiles; its tile size is the --tile-size.
  • XYZ and TileJSON: the TileJSON says tileSize: 512. Declare tileSize: 256 for the source in the web map, as above. @2x serves the same tiles.

WMS GetMap needs neither: it draws at the resolution a client asks for with DPI, MAP_RESOLUTION or FORMAT_OPTIONS=dpi:N.

A 512-pixel tile takes four times the pixels, so it takes more of --cache-mb and --cache-dir-mb, and a --metatile block of them takes four times the memory while it renders. @2x tiles are cached apart from the tiles of the served size, and tiles cached in --cache-dir with one --tile-size aren't reused with the other. A built tile set has the one size it was built at, so tiles serve answers 404 Not Found for its @2x tiles.

Mariner settings

When tiles serve renders datasets, one server can serve the chart with several sets of mariner settings, as the viewer's Mariner settings and display category choose them. The mariner setting options (--display-category, --safety-contour and the rest) set those of the plain tile URLs; without them the tiles look as they always have.

A client registers another set with a PUT of a JSON object to settings/{hash}. It picks the hash, 1 to 64 letters, digits or _, for example a hash of the settings. Every value is optional, and one left out takes the server's own:

curl -X PUT http://127.0.0.1:8200/settings/a1b2 \
  -H "Content-Type: application/json" \
  -d '{ "displayCategory": "Standard", "safetyContour": 10, "fourShades": true }'
Name Value
displayCategory DisplayBase, Standard, OtherInformation or All.
safetyContour, safetyDepth, shallowContour, deepContour Depths in metres, from 0 to 12000.
fourShades, soundings, shallowWaterDangers, plainBoundaries, simplifiedSymbols, fullLightLines, ignoreScaleMinimum true or false.
depthUnit Metres, Feet, FathomsFeet or Fathoms.

The set is then served in each palette as the style {palette}-{hash}, such as day-a1b2 or night-a1b2:

  • on the tile URLs, as day-a1b2/{z}/{x}/{y}.png and day-a1b2/tiles.json,
  • as a WMTS style, and
  • as a WMS STYLES value.

The WMTS and WMS capabilities list the registered styles. Each set is portrayed the first time it's asked for, and its tiles are cached like the others, under its values, so sets with the same values share them.

The PUT answers 201 Created for a new hash and 200 OK when the hash is already registered with the same values, both with the hash, its values and its styles. It answers 409 Conflict when the hash is registered with other values (a hash names one set for the life of the server, so a cached tile is never stale), 400 Bad Request for an unknown name or a value of the wrong type, and 507 Insufficient Storage past 256 sets. A GET of settings/{hash} returns the set, or 404 Not Found. Registered sets last until the server stops, and survive the datasets being reloaded. A style whose hash isn't registered answers 404 Not Found on the tile URLs and an exception on WMTS and WMS. A built tile set has no mariner settings; export one per set with the same options instead.

Dataset metadata

When tiles serve renders datasets, datasets describes each of them, so a client needn't open the datasets itself. tiles.json points to it in s100.datasetsUrl. The document lists the datasets served now, so it follows a reload; a built tile set has none, and datasets answers 404 Not Found.

{
  "notForNavigation": true,
  "datasets": [
    {
      "id": "111US00_DBOFS_20260320T18Z_US4DE1BB",
      "file": "111US00_DBOFS_20260320T18Z_US4DE1BB.h5",
      "product": "S-111",
      "edition": "1.0.0",
      "producer": "US00",
      "bounds": [-75.5999985, 38.7000008, -75.2999649, 39.0000343],
      "coverage": { "type": "MultiPolygon", "coordinates": [ ... ] },
      "coverageSource": "bounds",
      "times": ["2026-03-20T19:00:00Z", "2026-03-20T20:00:00Z", ...],
      "issueTime": "2026-03-20T19:22:48Z",
      "dataDynamicity": { "code": 5, "value": "hydrodynamicForecast", "label": "Forecast" },
      "notForNavigation": true
    }
  ]
}
Member Content
id The file name without its extension, with -2, -3, … when names repeat.
file The file name.
product, edition The product specification, such as S-111, and the edition the dataset declares, or null.
producer The producer code from the file name, by the product's naming convention: US00 from 111US00_…, US from the S-57 cell US5MA1BO.000. null when the name doesn't follow it.
bounds The dataset's own WGS-84 bounds, [west, south, east, north] as in TileJSON, or null when unknown. Use these, not the union in tiles.json, to zoom to a dataset.
coverage A GeoJSON MultiPolygon in WGS-84: the declared data coverage (S-101 DataCoverage, S-57 M_COVR) with its holes, or else the bounds.
coverageSource dataCoverage or bounds, for where coverage came from.
times The dataset's time steps in UTC, ascending; empty when it doesn't vary with time.
issueTime When a time-varying dataset was issued (a forecast's run), or null.
dataDynamicity How S-104 water levels and S-111 currents were produced: the S-104 dataDynamicity code, its name (observation, astronomicalPrediction, analysisOrHybrid, hydrodynamicHindcast or hydrodynamicForecast) and the viewer's label (Observed, Predicted, Analysis, Hindcast or Forecast). null when the dataset doesn't say.
layer The WMTS layer the dataset is in besides s100, or null for none. Present only when the server has such layers.
notForNavigation Always true: nothing tiles serve serves is for navigation.

Overview below the minimum zoom

The chart is drawn from a minimum zoom level that suits the datasets' scale, for a harbour cell about zoom 12. Below it the tiles are empty, the WMS capabilities give the minimum zoom's scale as MaxScaleDenominator, and GIS clients hide the layer, so a user who zooms out loses sight of where the charts are. With --overview, the server draws an overview there instead:

s100 tiles serve ./ENC_ROOT --overview
  • Below the chart's minimum zoom, XYZ and WMTS tiles and WMS GetMap draw each dataset's coverage, outlined and lightly filled in magenta (dimmer at dusk and night), with its name (the id of Dataset metadata). The coverage is the one datasets gives: the declared data coverage, or the dataset's bounds when it declares none. A dataset too small to outline at a zoom is drawn as a small square. Names are left out where they would overlap one already drawn, the first dataset's first.
  • A tile with no coverage on it still answers 204 No Content.
  • tiles.json gives minzoom 0, the chart's minimum zoom in s100.chartMinzoom and the overview's zoom range in s100.overview. The WMS layer's MaxScaleDenominator and the WMTS TileMatrixSetLimits reach zoom 0 to match, so clients keep the layer visible.
  • The overview is the same for every set of mariner settings and at every time, and follows the datasets when --refresh reloads them or --manage-datasets changes them.
  • The legends describe the chart only; they have no row for the overview outline.
  • With --layers-by, each WMTS layer has its own overview below its own minimum zoom, of the datasets in that layer only, on its layers/{layer}/ tiles and its WMTS layer; its TileJSON and TileMatrixSetLimits reach zoom 0 in the same way.

It is off by default, because it changes what existing clients get below the minimum zoom. Without it, a client that wants footprints can draw the coverage polygons from datasets itself, as a separate layer, and show the chart from s100.chartMinzoom (or the minzoom without --overview) up. It applies only when rendering datasets; a built tile set has no coverage to draw.

Run under a supervising process

A program that starts tiles serve itself, such as a GIS add-in, can pass --port 0 to get a free port and --ready-json to learn which one. When the server is listening, tiles serve then prints one line of JSON on standard output, before the usual start-up text:

{"event":"ready","host":"127.0.0.1","port":49731,"token":null,"baseUrl":"http://127.0.0.1:49731/","tiles":"http://127.0.0.1:49731/{z}/{x}/{y}.png","tilesHighDpi":"http://127.0.0.1:49731/{z}/{x}/{y}@2x.png","tileJson":"http://127.0.0.1:49731/tiles.json","wmts":"http://127.0.0.1:49731/wmts/1.0.0/WMTSCapabilities.xml","wms":"http://127.0.0.1:49731/wms","healthz":"http://127.0.0.1:49731/healthz","preview":"http://127.0.0.1:49731/"}

Read standard output until a line starts with { and parse it. Lines printed while datasets are portrayed can come before it. The members are:

Member Content
event Always ready.
host The address to connect to: the --host address, or 127.0.0.1 (::1) when listening on 0.0.0.0 (::).
port The bound port.
token The access token, or null when there's none.
baseUrl The base URL, with the token.
tiles The XYZ tile URL template.
tilesHighDpi The URL template of the 512-pixel @2x tiles, or null when serving a built tile set.
tileJson, wmts, wms The TileJSON, WMTS capabilities and WMS URLs.
pmtiles The URL of the served PMTiles archive's file, or null when not serving a .pmtiles archive.
healthz The health check URL, which has no token.
preview The preview page URL, or null with --no-viewer.
s100 tiles serve exchange-set/ --port 0 --ready-json

Add and remove datasets

With --manage-datasets, a client can change the datasets tiles serve renders without restarting it, with a POST or DELETE of datasets. Like every other route it lives under the token, if there is one. Without the option the datasets can't be changed.

A GET of datasets describes the datasets served, with or without the option; see Dataset metadata.

  • POST datasets with {"paths": ["…"]} (or {"path": "…"}) adds datasets. The paths are files on the server's computer, relative to the folder it was started in unless absolute. Those already served are left as they are. With "layer": "…", every dataset named, added or already served, is put in that WMTS layer, whatever --layers-by says. A layer is named with 1 to 64 letters, digits, _, - and ., starting with a letter or digit, and can't be s100.
  • DELETE datasets with the same body removes datasets. Any served dataset can be removed, including one of those it started with, but at least one must remain.

The body must be sent as application/json. Each request answers with the datasets then served, in drawing order, each with its path, file name and spec, and its layer when there are layers:

curl -X POST http://127.0.0.1:8200/datasets \
  -H "Content-Type: application/json" \
  -d '{ "paths": ["/charts/US5MA1BO.000"] }'
{
  "datasets": [
    { "path": "/charts/US4MA1BO.000", "name": "US4MA1BO.000", "spec": "S-57" },
    { "path": "/charts/US5MA1BO.000", "name": "US5MA1BO.000", "spec": "S-57" }
  ]
}

A change opens and portrays the new set of datasets while the old one keeps serving, and the request returns once the new set serves. The TileJSON, WMTS and WMS documents and the dataset metadata then describe it: its area, zoom levels and time steps. Its data revision (s100.revision in the TileJSON, updateSequence in the capabilities, the S100-Revision header on /healthz) changes too, and is the same again when the set is. Changes are made one at a time. A request answers 400 Bad Request for a malformed body, a path that isn't a file or a file that isn't a dataset, 404 Not Found for removing a dataset that isn't served, 409 Conflict for removing every dataset, 415 Unsupported Media Type for a body that isn't JSON, and 422 Unprocessable Entity when the new set can't be opened; the old set then keeps serving. Each error response has an error member saying why.

Each tile is cached under the datasets that reach it (those whose extent comes within a tile of its block), not under every dataset served, in memory and in --cache-dir. Adding a cell therefore renders only the tiles it reaches, and the others are served from the cache. The latitude the zoom levels' scales are measured at is kept from the datasets the server started with, so adding a dataset elsewhere doesn't change how the others draw; it can differ slightly from a server started with the new set. A dataset whose extent isn't known reaches every tile. --refresh still reopens the datasets when their files change, the added ones included.

Changes last until the server stops. To serve the same set again after a restart, pass it on the command line. A removed dataset leaves its layer; one added again without layer goes back to the layer --layers-by gives it.

WMTS

tiles serve is also an OGC WMTS 1.0.0 service, for GIS desktops and libraries that add tiles from a capabilities document. Its URL is printed at startup:

http://127.0.0.1:8200/wmts/1.0.0/WMTSCapabilities.xml
  • QGIS: choose Layer > Add Layer > Add WMS/WMTS Layer, add a connection with the capabilities URL, connect, and add the s100 layer.
  • ArcGIS Pro: choose Insert > Connections > Server > New WMTS Server and enter the capabilities URL.
  • GDAL: open WMTS:http://127.0.0.1:8200/wmts/1.0.0/WMTSCapabilities.xml.

The service has one layer, s100, on the WebMercatorQuad tile matrix set in EPSG:3857. The tile matrices are numbered by zoom level, from 0 to the maximum zoom, so a WMTS tile is the XYZ tile of the same zoom, column and row. With --tile-size 512, the matrices have 512-pixel tiles (see High-DPI tiles). Below the minimum zoom the tiles are empty, as on the XYZ URLs, so zoom in to see the chart; with --overview they show the datasets' coverage and names (see Overview below the minimum zoom). When rendering datasets, each palette is a WMTS style and the --palette one is the default, and each registered set of mariner settings adds a style per palette; a built tile set has one style, default. For time-varying datasets (S-104, S-111), a Time dimension lists the time steps and defaults to --time-step.

Tiles are served in both WMTS encodings:

  • KVP: wmts?SERVICE=WMTS&REQUEST=GetTile&LAYER=s100&STYLE=night&TILEMATRIXSET=WebMercatorQuad&TILEMATRIX=13&TILEROW=2750&TILECOL=4066, with TIME= for a time step.
  • RESTful: wmts/1.0.0/s100/{Style}/WebMercatorQuad/{TileMatrix}/{TileRow}/{TileCol}.png, with a {Time} segment after the style for time-varying datasets.

When rendering datasets, each style has a LegendURL: the WMS GetLegendGraphic image of its key.

A request the service can't answer gets an OWS exception report that names the parameter at fault. The service has no GetFeatureInfo; use WMS to identify features.

WMTS layers

When it renders datasets, tiles serve can also serve them as several WMTS layers, one per group of datasets, so a GIS client can add, hide and step through each on its own, for example the chart, water levels and currents, from one server. The s100 layer of every dataset stays as it is, so clients that use it see no change.

  • --layers-by product puts each dataset in the layer of its product: chart for S-57, S-101 and S-102, and the product without its hyphen for the rest (S104, S111, S124, …).
  • With --manage-datasets, a client puts datasets in a layer it names by adding them with "layer": "…". That works with or without --layers-by, and wins over it.

Without --layers-by and without layers named by a client, the capabilities have the s100 layer only, as before. The groups aren't the default because each layer is a scene of its own to compose (the vector datasets' portrayals are shared) and because, with one product, its layer would repeat s100.

Each layer draws only its datasets, in the same styles, zoom range and tile matrix set as s100, and its styles link the same legends, of every dataset. In the capabilities it has its own extent, the union of its datasets' bounds, and its own Time dimension, listing only its datasets' time steps, or none when they don't vary with time. Its tiles are at wmts/1.0.0/{layer}/… and LAYER={layer} like s100's. A time snaps to the nearest of the layer's own steps. For XYZ clients, tiles.json lists the layers in s100.layers, each with the URL of its own TileJSON, layers/{layer}/tiles.json (or layers/{layer}/{palette}/tiles.json), whose tiles are layers/{layer}/{z}/{x}/{y}.png; it names the layer in s100.layer. The dataset metadata gives each dataset's layer.

s100 tiles serve --layer enc.000 --layer water-levels.h5 --layer currents.h5 --layers-by product

WMS still has the one layer, s100, of every dataset.

WMS

tiles serve is also an OGC WMS 1.3.0 service, for clients that ask for one image of the area they show, and to identify what's at a point. Its URL is printed at startup:

http://127.0.0.1:8200/wms
  • QGIS: choose Layer > Add Layer > Add WMS/WMTS Layer, add a connection with the URL, connect, and add the s100 layer. With the Identify Features tool, click the chart to see what's there.
  • ArcGIS Pro: choose Insert > Connections > Server > New WMS Server and enter the URL.
  • GDAL: open WMS:http://127.0.0.1:8200/wms?SERVICE=WMS&REQUEST=GetCapabilities.

The service has one layer, s100, in EPSG:3857, EPSG:4326 and CRS:84. As for WMTS, each palette is a style, the --palette one first and the default, each registered set of mariner settings adds a style per palette, and S-104 and S-111 time steps are a time dimension.

GetMap draws its image from the same tiles the XYZ URLs serve, stitched and resampled to the requested area and size, at the zoom level a WMTS client shows at the same scale, so WMS and WMTS show the same features (SCAMIN) at the same scale:

  • WMTS clients read each tile matrix's ScaleDenominator at OGC's 0.28 mm pixel, which gives its resolution in metres per pixel (zoom 14 is 1:34,124, or 9.55 m a pixel; zoom 15 is 1:17,062, or 4.78 m). ArcGIS Pro shows the same levels as 1:36,112 and 1:18,056, at its 96 DPI pixel.
  • A client draws the finest tile matrix whose resolution is no finer than its view's, and enlarges its tiles until it reaches the next one. ArcGIS Pro at 1:23,374 draws zoom 14.
  • GetMap does the same with the request's resolution, the box's width in Web Mercator metres over its width in pixels: the finest zoom level no finer than that, so 1:23,374 draws zoom 14 too. A request less than 1% coarser than a level's resolution, such as one at its rounded scale, draws that level.

Symbols and text are therefore between 1 and 2 times their portrayed size, as in a WMTS client. A request coarser than the minimum zoom draws nothing, and the capabilities give the minimum zoom's scale as MaxScaleDenominator, so clients hide the layer there; with --overview it draws the datasets' coverage and names and the layer has no practical scale limit (see Overview below the minimum zoom). It draws PNG or JPEG images up to 4096 pixels on a side; set TRANSPARENT=TRUE for a PNG to overlay other layers.

Printing. A client exporting a layout at a resolution higher than the screen's, such as ArcGIS Pro or QGIS, asks for more pixels for the same view and says how many dots per inch they're for, with DPI, MAP_RESOLUTION or FORMAT_OPTIONS=dpi:N (the first of these given counts; 24 to 1200, 96 by default). GetMap then draws the 96 DPI map of the same view, sharper: the zoom level, and so which features show at that scale (SCAMIN), comes from the display scale, and symbols and text are scaled by DPI / 96, so they print at the size they have on screen. When the server renders from datasets, it draws the requested area directly at the print resolution rather than from the tiles; a built tile set's tiles are resampled, so they print at the right size but no sharper. Above 96 DPI, images may be up to 4096 × DPI / 96 pixels on a side (at most 16,384) and 67 million pixels in all; ask for a larger print in parts. Without these parameters GetMap is unchanged.

GetFeatureInfo answers from the datasets, as identify does: the vector features at the clicked pixel, with their attributes, and the coverage values there (S-102 depths, S-104 water levels, S-111 currents, weather grids). Point and curve features within 5 pixels of the click (at 96 DPI; scaled with DPI) are matched. FEATURE_COUNT limits the features (1 by default, as WMS defines it), and TIME picks the time step sampled. The answer is in one of these formats (INFO_FORMAT):

Format Content
text/html A table per feature with its attributes, and the coverage values.
application/json, application/geo+json A GeoJSON FeatureCollection: a feature per vector feature and per coverage value, each a point at the clicked position, with what identify --format json --attributes reports as its properties.
text/plain The same as text/html, as text.

A built tile set has no datasets behind it, so its layer isn't queryable.

GetLegendGraphic draws the key of a style; see Legends.

Requests in WMS 1.1.1 are answered too: their SRS, X and Y parameters, and EPSG:4326 boxes in longitude, latitude order. In 1.3.0, EPSG:4326 boxes are latitude first and CRS:84 boxes longitude first. A request the service can't answer gets a WMS service exception report.

Legends

When rendering datasets, tiles serve draws the key of each style as one PNG image, for the legend GIS clients show next to the layer (ArcGIS Pro's Contents pane, QGIS's layer tree). The rows are the ones the viewer's Legend tab shows, from the same portrayal: a section per product (S-102 depth shades and safety contour, S-104 water levels, S-111 speed bands, S-124 warnings, weather fields and so on) with its caption, and its group titles when it has more than one. Each style draws its rows in its palette, on a light sheet by day and a dark one at dusk and night, and with its mariner settings, so four shades or another safety contour change the S-102 rows. A catalogue product with no legend of its own, such as S-101, has no rows: the viewer lists the symbols drawn in its view, and a server has no view.

The WMS capabilities give each style a LegendURL with the image's size, and list the sld:GetLegendGraphic operation; the WMTS capabilities give each style a LegendURL to the same image. The request is:

wms?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetLegendGraphic&LAYER=s100&STYLE=night&FORMAT=image/png
Parameter Meaning
LAYER s100. Required.
STYLE A style of the capabilities: a palette, or {palette}-{hash} of a registered settings set. The default style when left out.
FORMAT image/png, the only format and the default.
WIDTH, HEIGHT The size of each row's glyph in pixels, 1 to 256, as GeoServer reads them. 28 × 14 by default.
DPI, MAP_RESOLUTION, FORMAT_OPTIONS=dpi:N The display resolution, as for GetMap: text and glyphs scale by DPI / 96.

SLD_VERSION is accepted and ignored. The rows are those of the default time step; they don't change with time. The size in the capabilities is the default image's; for a registered set whose legend hasn't been drawn yet, it is the default style's until it has. A built tile set has no legend, and GetLegendGraphic answers a service exception.

The server runs until you press Ctrl+C or it receives SIGTERM.

info

s100 info <dataset> [options]

info prints the detected product specification and edition, and whether the dataset can be rendered headlessly. For a dataset with positions, Axis order says whether they're latitude first, were swapped back from longitude first, or couldn't be checked; a swapped or inconsistent order is also printed on stderr. Check the axis order explains the check. For a time-series dataset it lists the time steps with the indexes render --time-step takes. For a product with display modes, such as S-411, it lists the values render --display-mode takes. For S-104, a Portrayal row says "SoundCharts portrayal: S-104 Ed 2.0.0 defines no symbology", because what render draws for it is SoundCharts' own. For an S-101 base cell, it applies the update files first. For weather data, which isn't S-100, a Notice row says it isn't for navigation. For a weather grid (GRIB2 or NetCDF), Model and Run (UTC) give the model and its run, or say the steps are analyses when the file gives no run; Grid and Extent give the grid's size, spacing and bounds, and Layers the layers it can draw. A Weather parameters table then lists each parameter with its level and step count, whether it's used, and if not, why: for example a second swell partition, a parameter the weather table doesn't have, or a GRIB2 message packed with CCSDS. The time steps are the grid's valid times. For a CAP weather warning file (CAP XML, an Atom feed or NWS GeoJSON), Alerts counts the alerts, their areas and the areas drawn, and a Warnings table lists each alert area with its event, severity, when it's in force (UTC) and how it's drawn (a polygon, a circle, or the NWS marine zones it names), then any zone codes the marine zone layer doesn't have. Its time steps are when warnings start and end, so render --time-step draws what's in force then. For a WPC coded surface bulletin (CODSUS), Bulletin says whether it's an analysis or a forecast, its resolution and its WMO heading, Issued by and Issued (UTC) come from its header, Coverage says it covers WPC's domain only, and a Surface analyses table lists each valid time (one for an analysis, one per forecast time) with its lead time and its counts of cold, warm, occluded and stationary fronts, troughs, highs and lows. Skipped codes lists any feature codes it doesn't know. For a tropical cyclone advisory (an NHC forecast zip, such as al092022_5day_020.zip), Storm, Advisory, Forecast and Intensity give the storm and its basin, the advisory number and issue time (UTC), the forecast's span and the current wind, gusts, pressure and peak forecast wind. Cone, Wind radii and Past track say what the advisory holds; the wind radii and past track come from the _fcst_ and _best_track zips beside the forecast zip. A Forecast points table then lists each point with its time, position, intensity, class and 34, 50 and 64 kt radii by quadrant. Show wind and waves on the chart covers the weather formats.

s100 info currents.h5
s100 info filter_gfswave.pl
s100 info alerts.atom
s100 info al092022_5day_020.zip
Option Default Description
--no-updates off Reads an S-101 base cell without its update files.
--debug off Prints full stack traces on error.

identify

s100 identify <dataset> --lat <latitude> --lon <longitude> [options]
s100 identify --layer <dataset> [--layer <dataset> ...] --lat <latitude> --lon <longitude> [options]
s100 identify <exchange-set> --lat <latitude> --lon <longitude> [options]
s100 identify [<dataset>] --source <source> --lat <latitude> --lon <longitude> [options]

identify reports the vector features at a point and samples the coverage datasets there, as a click on the map does in SoundCharts. It takes the same three input forms as render. Features are ranked as an ECDIS ranks them: points before curves before areas, and nearer before farther. Datasets that can't be read are skipped with a warning on standard error.

Coverage samples come from every dataset that can be sampled: S-102, S-104, S-111 and the GRIB2 and NetCDF weather grids. A weather grid's sample lists each parameter at the nearest grid point and time step with its unit, for example wave.hs 2.52 m, wind.speed.kn 20.2 kn. CAP warning areas are reported as features of type CapWarningArea; --attributes adds their event, severity, times and description. When the result includes weather data, a not-for-navigation notice is printed first.

identify uses the same code as the MCP identify_features and sample tools, so the results match.

--source also picks from a live data source, such as NDBC observations or AIS targets, with or without datasets. Each source is started for the area around the point and given --source-timeout for its first data; one with nothing by then is left out with a warning on standard error rather than failing the command, unless it was the only input. An unknown source or option exits with code 2. A source that needs a key reads it from its environment variable, such as ENCDOTNET_AIS_STREAM_KEY: a key is never accepted as a --source option. sources lists them.

Option Default Description
--lat <latitude> required Latitude in decimal degrees, WGS-84, from -90 to 90.
--lon <longitude> required Longitude in decimal degrees, WGS-84, from -180 to 180.
--layer <path> none Adds a dataset. Repeat it for each dataset. Can't be combined with the exchange-set form.
--from, --exchange-set <path> none Picks across every dataset in an exchange set.
--only <specs> all Exchange-set form only. Loads only these product specifications, comma-separated.
--radius <metres> 50 Search distance for point and curve features, from 0 to 100,000. Area features must contain the point, so they ignore it.
--source <source> none Also picks from a live data source. Repeat it for each source. A source id, optionally followed by : and comma-separated name=value options, such as nmea.weather:Input=udp:10110.
--source-timeout <seconds> 30 How long to wait for each --source's first data.
--spec <spec> all Reports only this product specification or format, for example S-124 or GRIB2.
--time <iso8601> first step A UTC time for S-104, S-111, GRIB2 and NetCDF coverages. The nearest time step is sampled. Ignored for S-102.
--max-results <n> 20 Maximum features to report, from 1 to 200.
--attributes off Includes each feature's attributes.
--format <format> table table or json.
--debug off Prints full stack traces on error.
s100 identify warnings.gml --lat 51.085 --lon 1.30
s100 identify --layer enc.000 --layer bathy.h5 --lat 50.1 --lon -1.4
s100 identify --from exchange-set.zip --lat 50.1 --lon -1.4 --format json
s100 identify chart.000 --lat 50.1 --lon -1.4 --attributes
s100 identify --layer gfswave.grib2 --layer alerts.atom --lat 38.5 --lon -74.5 --time 2026-10-25T03:00Z
s100 identify chart.000 --source ndbc.realtime --lat 42.35 --lon -70.65

The JSON output is an object with point, totalMatched, truncated, features (ranked), samples (one for each specification with a dataset that covers the point), notices when the result includes weather data and, when an input was skipped, warnings. A weather grid's sample value has kind fields: a fields array of name, quantity, unit and value, plus sampleTime and the grid point's cellCentreLatitude and cellCentreLongitude.

validate

s100 validate <dataset-or-exchange-set> [options]

validate does one of two checks, depending on what you pass it.

A dataset file is checked against its product specification's rule pack. Each finding has a rule id that traces to the specification (for example S127-R-2.1), a severity, a message, and, where the rule can locate the problem, a feature id or position. The result depends only on the dataset, not on palette or time step. A specification with no rule pack, such as S-401, reports that no rules are available and exits with code 0. That's different from a dataset that was checked and passed.

An S-57 cell is checked twice: once against S-57 rules for the fields that don't survive translation, and once against the S-101 rule pack after translation. Findings from the second pass have rule ids prefixed with S101-as-S57/. See Bringing S-57 into the pipeline.

An exchange set (a folder with CATALOG.XML, the CATALOG.XML file, or a .zip) has each file's digital signature and checksum verified (S-100 Part 15). An S-57 or S-63 exchange set (CATALOG.031) has its CRCs and signatures verified. The datasets themselves aren't checked against rule packs; validate them one at a time.

Option Default Description
--format <format> text text prints a table. json prints a report for scripts and CI.
--suppress <patterns> none Drops findings whose rule id matches, comma-separated, for example --suppress S101-R-1.2,S101-R-3.2 or --suppress "S101-*".
--strict off Fails on warnings as well as errors. For an exchange set, also fails unsigned files and files without a checksum.
--no-updates off Validates an S-101 base cell without its update files. See S-101 updates.
--debug off Prints full stack traces on error.
s100 validate warnings.gml
s100 validate route.gml --strict
s100 validate currents.h5 --format json
s100 validate chart.000 --suppress S101-R-1.2,S101-R-3.2
s100 validate chart.000 --suppress "S101-*"
s100 validate exchange-set/CATALOG.XML
s100 validate exchange-set.zip --format json
s100 validate s57-set/CATALOG.031

--suppress patterns match rule ids without regard to case. * matches any run of characters and is the only wildcard, so a pattern without * matches one rule id exactly. Use it to mute a known class of finding, such as a feature catalogue version mismatch, so the remaining findings stand out. Suppressed findings are left out of the report and the exit code, and the summary line says how many were suppressed.

validate exits with code 0 when no error-severity findings remain. Warnings and information findings are reported but don't fail unless you pass --strict. Failing findings exit with code 6.

route check

s100 route check <route> <datasets>... [options]

route check checks a route against datasets, as Check route does in SoundCharts. The route is an RTZ file (IEC 61174 Annex S, versions 1.0, 1.1 and 1.2) or an S-421 GML dataset. The datasets are any mix of dataset files, one exchange set (a folder with CATALOG.XML, the CATALOG.XML file, or a .zip) and one folder of datasets. A route file among the datasets is skipped.

It reads the route into a PassagePlan and runs a RouteChecker from EncDotNet.S100.Navigation, with every check:

  • chart: land, drying ground, chart coverage, and, with the safety contour and depth, depth areas, S-102 shoals, soundings and charted dangers.
  • areas: regulated and S-122 protected areas.
  • warnings: S-124 navigational warnings.
  • clearance: the under-keel clearance, when every leg has a draft, from the file or --draft. Charted depth comes from S-102, or S-101 where there's no S-102, and water level from S-104 at each point's ETA.

Route checks and under-keel clearance explains every finding, its thresholds and confidence. The MCP check_route tool and SoundCharts run the same checker, so the verdict, findings, codes and ids match. The results aren't for navigation.

The route's values come from the file: each leg's cross-track limits, draft and static UKC, and the speeds and departure of its planning schedule. RTZ and S-421 have no squat. These options replace the file's value on every leg:

Option Default Description
--draft <metres> the file's Draft for every leg. With a draft on every leg, the UKC check runs; each leg's dangers are also judged against its draft + squat + required UKC.
--squat <metres> 0 Squat allowance.
--speed <knots> the file's Speed over ground. Speeds give the ETAs that warnings, seasonal areas and S-104 water levels are judged at.
--departure <iso8601> the file's, else now Departure time. A time without an offset is UTC.
--required-ukc <metres> the file's Required under-keel clearance.
--corridor <metres> each leg's limits The corridor's half-width: how far it reaches to port, and to starboard, of the track. A side without a limit uses 50 m.

Other options:

Option Default Description
--safety-contour <metres> 30 Safety contour, as the mariner setting.
--safety-depth <metres> 30 Safety depth, for charted dangers and soundings.
--max-wind <knots> the file's Wind limit for the weather check: stretches where a loaded GRIB2 or NetCDF forecast has a higher 10 m wind at the ETA are Check findings. Replaces an RTZ route's vesselMaxWind.
--max-wave <metres> the file's Significant wave height limit for the weather check. Replaces an RTZ route's vesselMaxWave.
--cyclone-radius <knots> 34 Tropical cyclones (loaded NHC advisories): the outermost wind radius tested, 34, 50 or 64 kt. The cone is always tested.
--cyclone-must-review <knots> 50 The weakest radius whose findings are Must review: 64, 50, 34 or never. Weaker radii and the cone are Check.
--no-cyclone-cpa off Doesn't report the route's closest approach to each storm.
--window off Also sweeps departures across the S-104 time range to find the departure window (needs a draft), and across the forecast for the weather check (needs a wind or wave limit).
--tide-predictions <file> off A tide station list (the tide-stations file, .json or .json.gz) to predict water level from where no S-104 covers. A station reaches 10 km through the loaded charts' water. Predictions are the astronomical tide only, not a forecast: the text output names the stations and says so.
--only <specs> all Exchange set or folder only. Loads only these product specifications, comma-separated.
--fail-on <level> must-review When to exit with code 7: must-review, check or never. See Exit codes for CI.
--format <format> text text or json.
--debug off Prints full stack traces on error.

The default safety contour and depth are the S-101 portrayal defaults, which flag most coastal water. Set them to the vessel's values.

s100 route check route.rtz exchange-set/ --safety-contour 10 --safety-depth 10
s100 route check route.gml enc.000 bathy.h5 tides.h5 warnings.gml --draft 7 --required-ukc 1
s100 route check route.rtz exchange-set.zip --corridor 100 --fail-on check
s100 route check route.gml exchange-set/ --departure 2026-03-01T06:00Z --speed 8 --window --format json
s100 route check route.rtz enc.000 gfs.t06z.pgrb2.0p25 gfswave.t06z.grib2 --max-wind 25 --max-wave 3
s100 route check route.rtz enc.000 al142026_5day_017.zip --cyclone-radius 50 --cyclone-must-review 64
s100 route check route.rtz enc/ bathy.h5 --draft 7 --tide-predictions tide-stations.json.gz

The text output gives the verdict, the checks that didn't run in full, the findings by group, then the clearance verdict and its minimum, and the weather verdict with the highest wind and waves and, for each tropical cyclone near the route, the strongest radius it meets and its closest approach. The JSON output is an object with:

  • route: the file, format (rtz or s421), version, routeId (S-421 only), name, number of waypoints and the departure used.
  • settings: the safety contour and depth, and any options that replaced the file's values.
  • check: the report as the MCP check_route tool returns it: the verdict, each check's status (checks), the findings with their details, the summary, each leg's corridor, the clearance (null when the clearance check was skipped; checks says why), the datasets read and the disclaimer. See Check a route.
  • loadWarnings: datasets that couldn't be loaded, when there are any.

Exit codes for CI

route check exits with code 0 when the verdict doesn't reach --fail-on, and with code 7 when it does:

--fail-on Exits with 7 when the verdict is
must-review must_review (a Must review finding, or the clearance is below your UKC setting) or water_level_ends_before_arrival.
check Anything but clear: also Check findings, and a tight or incomplete clearance.
never Never.

A route file that can't be read, or datasets that can't be loaded, exit with code 2.

tides stations

s100 tides stations --near <lat,lon> [options]

tides stations lists the tide stations within a radius of a point, nearest first, from the offline station catalogue. Each station has its id, name and kind: harmonic stations are predicted from their own harmonic constituents, and subordinate stations from a reference station with time and height differences. The table shows a harmonic station's datums as heights above MLLW. A line under the table gives the catalogue's provider and age, and says when it's over 12 months old.

Option Default Description
--near <lat,lon> required The point, latitude first, in decimal degrees: --near 47.6,-122.34.
--radius <distance> 50 (km) How far to look: kilometres, or with a unit (20km, 10nm, 5000m).
--limit <n> 10 The most stations to list, 1 to 500.
--format <format> table table, csv or json. JSON is the list_tide_stations MCP result, with each station's datums, predictable datums and a subordinate station's offsets.
--catalogue <file> the offline cache A tide-stations JSON file (.json, or .json.gz for gzip).
s100 tides stations --near 47.6,-122.34
s100 tides stations --near 47.6,-122.34 --radius 20nm --limit 5 --format json
╭─────────┬───────────────┬─────────────┬───────────┬──────────┬───────────────╮
│ Id      │ Name          │ Kind        │ Reference │ Distance │ Datums (m     │
│         │               │             │           │          │ above MLLW)   │
├─────────┼───────────────┼─────────────┼───────────┼──────────┼───────────────┤
│ 9447130 │ SEATTLE       │ harmonic    │ —         │   0.3 km │ MHHW 3.46 MSL │
│         │ (Madison      │             │           │          │ 2.02 LAT      │
│         │ St.), Elliott │             │           │          │ -1.31         │
│         │ Bay           │             │           │          │               │
│ 9446486 │ Tacoma        │ subordinate │ 9447130   │  39.9 km │ MLLW only     │
│         │ Narrows       │             │           │          │               │
│         │ Bridge        │             │           │          │               │
╰─────────┴───────────────┴─────────────┴───────────┴──────────┴───────────────╯
Stations: NOAA CO-OPS, retrieved 2026-11-11 (0 days ago), 3502 stations.

tides predict

s100 tides predict <station> [options]
s100 tides predict --near <lat,lon> [options]

tides predict predicts the astronomical tide at a station from the offline catalogue. Name the station by id (9447130) or name (Seattle; a unique part of a name will do), or use --near for the nearest station within --radius that can be predicted on the datum. It prints heights in metres above the datum at each step, or with --highs-lows the high and low waters, with a note that the values are predicted.

A prediction is astronomical: it leaves out wind, pressure and river flow, which can move the water 0.5 m or more. It isn't a forecast, isn't S-104, and isn't for navigation. The engine is EncDotNet.S100.Tides and the catalogue is EncDotNet.S100.Tides.Stations.

Option Default Description
--near <lat,lon> none Predict at the nearest station to this point instead of a named one.
--radius <distance> 10 (km) With --near, how far away the station may be: kilometres, or with a unit (20km, 10nm, 5000m).
--from <time> now, rounded down to the step The first time: ISO 8601 (2026-11-18T12:00, 2026-11-18T20:00Z) or a date. Without an offset, it's in this computer's time zone.
--to <time> 24 hours after --from The last time, like --from. At most 366 days after it.
--step <step> 30 (minutes) The time between heights: minutes, or with a unit (10m, 1h, 90s).
--highs-lows off Lists the high and low waters instead of heights at each step.
--datum <datum> MLLW MLLW, MLW, MSL, MHW, MHHW, LAT or HAT. A harmonic station can use any datum NOAA gives it; a subordinate station is MLLW only.
--utc off Reads and prints times in UTC rather than this computer's time zone.
--format <format> table table, csv, json or s104. JSON is the predict_tide MCP result, with times in UTC.
-o, --output <file> 104ZZ01<station>.h5 With --format s104, the file to write.
--catalogue <file> the offline cache A tide-stations JSON file.
s100 tides predict 9447130
s100 tides predict Seattle --from 2026-11-18T12:00 --to 2026-11-18T18:00 --step 10m
s100 tides predict 9447130 --highs-lows --from 2026-11-18 --to 2026-11-25
s100 tides predict --near 47.27,-122.55 --format csv
SEATTLE (Madison St.), Elliott Bay 9447130, harmonic, predicted on MLLW
╭─────────────────────────┬──────────┬──────────────────────────╮
│ Time                    │ High/low │ Predicted (m above MLLW) │
├─────────────────────────┼──────────┼──────────────────────────┤
│ 2026-11-18 04:35 -08:00 │ Low      │                     0.80 │
│ 2026-11-18 11:55 -08:00 │ High     │                     3.42 │
│ 2026-11-18 18:55 -08:00 │ Low      │                     1.41 │
╰─────────────────────────┴──────────┴──────────────────────────╯
Astronomical tide only, not a forecast. Weather and river flow can move the
water 0.5 m or more. Not for navigation.
Stations: NOAA CO-OPS, retrieved 2026-11-11 (7 days ago).

CSV has a header row (time,predicted_m_above_mllw, or time,kind,predicted_m_above_mllw with --highs-lows) and ISO 8601 times with their offset. The station and the note go to standard error.

Write an S-104 dataset

--format s104 writes the series as an S-104 Edition 2.0.0 dataset with one station (data coding format 8), which SoundCharts and the other s100 commands open like any S-104 file:

s100 tides predict 9447130 --from 2026-11-18 --to 2026-11-25 --step 6m --format s104 -o seattle.h5

The dataset says it's a prediction: its producer code is ZZ01, which no real producer has, its data dynamicity is astronomical prediction, and its method text names the station and says it's not an official product. The step must be a whole number of seconds up to 65,535 (18 h 12 min), and the datum must have an S-100 code (all the datums above do). The file is written with PureHDF, whose writer doesn't work in a NativeAOT build; the s100 release builds aren't NativeAOT.

tides currents stations

s100 tides currents stations --near <lat,lon> [options]

tides currents stations lists the tidal current stations within a radius of a point, nearest first, from the offline station catalogue. NOAA lists each depth bin at a station as its own station, such as PUG1701_33, so one place can appear several times. Each station has its id, name, kind (harmonic, or subordinate with a reference station), depth below the surface, and the directions the flood and ebb set toward, in degrees true. A line under the table gives the catalogue's provider and age.

Option Default Description
--near <lat,lon> required The point, latitude first, in decimal degrees: --near 48.406,-122.643.
--radius <distance> 50 (km) How far to look: kilometres, or with a unit (20km, 10nm, 5000m).
--limit <n> 10 The most stations to list, 1 to 500. Each depth bin counts as one.
--format <format> table table, csv or json. JSON is the list_current_stations MCP result, with a subordinate station's time differences and speed ratios.
--catalogue <file> the offline cache A tide-stations JSON file (.json, or .json.gz for gzip).
s100 tides currents stations --near 48.406,-122.643
s100 tides currents stations --near 37.82,-122.46 --radius 5nm --format json

A catalogue downloaded before current stations were added lists none: run tides update again.

tides currents predict

s100 tides currents predict <station> [options]
s100 tides currents predict --near <lat,lon> [options]

tides currents predict predicts the astronomical tidal current at a current station from the offline catalogue. Name the station by id (PUG1701_33), by NOAA's id without its depth bin (PUG1701) or by name (Deception Pass); the last two take the shallowest bin. Or use --near for the nearest station within --radius. It prints the speed in knots, the direction the current sets toward and whether it floods or ebbs at each step, or with --events the slack waters and the maximum and minimum floods and ebbs.

A prediction is astronomical: wind and river flow change real currents, and the strongest stream in a pass can be away from the station. It isn't a forecast, isn't S-111, and isn't for navigation. The engine is EncDotNet.S100.Tides.

Option Default Description
--near <lat,lon> none Predict at the nearest station to this point instead of a named one.
--radius <distance> 10 (km) With --near, how far away the station may be.
--from <time> now, rounded down to the step The first time: ISO 8601 or a date. Without an offset, it's in this computer's time zone.
--to <time> 24 hours after --from The last time, like --from. At most 366 days after it.
--step <step> 30 (minutes) The time between values: minutes, or with a unit (10m, 1h, 90s).
--events off Lists the slacks and maximum and minimum floods and ebbs instead of values at each step.
--utc off Reads and prints times in UTC rather than this computer's time zone.
--format <format> table table, csv, json or s111. JSON is the predict_current MCP result, with times in UTC.
-o, --output <file> 111ZZ01<station>.h5 With --format s111, the file to write.
--catalogue <file> the offline cache A tide-stations JSON file.
s100 tides currents predict PUG1701_33
s100 tides currents predict "Deception Pass" --events --from 2026-11-18 --to 2026-11-19
s100 tides currents predict --near 37.82,-122.46 --step 10m --format csv
Deception Pass (Narrows) PUG1701_33, harmonic, 5.5 m below the surface, flood
108°, ebb 277°
╭─────────────────────────┬─────────────────────┬────────────────┬───────────╮
│ Time                    │ Event               │ Predicted (kn) │ Direction │
├─────────────────────────┼─────────────────────┼────────────────┼───────────┤
│ 2026-11-18 09:44 -08:00 │ Slack, ebb begins   │            0.0 │         — │
│ 2026-11-18 12:42 -08:00 │ Max ebb             │            5.5 │      277° │
│ 2026-11-18 17:00 -08:00 │ Slack, flood begins │            0.0 │         — │
╰─────────────────────────┴─────────────────────┴────────────────┴───────────╯
Astronomical tidal current only, not a forecast. Wind and river flow change real
currents, and the strongest stream in a pass can be away from the station. Not
for navigation.
Stations: NOAA CO-OPS, retrieved 2026-11-11 (7 days ago).

CSV has a header row (time,predicted_speed_kn,direction_deg_true,phase, or time,event,predicted_speed_kn,direction_deg_true with --events) and ISO 8601 times with their offset. At slack the direction is empty. The station and the note go to standard error. A rotary station gives its direction at each maximum and minimum as well.

Write an S-111 dataset

--format s111 writes the series as an S-111 Edition 2.0.0 dataset with one station (data coding format 8), which SoundCharts and the other s100 commands open like any S-111 file:

s100 tides currents predict PUG1701_33 --from 2026-11-18 --to 2026-11-25 --step 10m --format s111 -o deception-pass.h5

The dataset says it's a prediction: its producer code is ZZ01, which no real producer has, its type of current data is astronomical prediction, and its method text names the station and says it's not an official product. The station's depth is written as surfaceCurrentDepth. The step must be a whole number of seconds up to 65,535 (18 h 12 min). As for S-104, the file is written with PureHDF, which doesn't work in a NativeAOT build.

tides update

s100 tides update [--check] [--catalogue <file>]

tides update downloads NOAA CO-OPS's tide and tidal current stations, with their harmonic constituents, datums and subordinate-station offsets, into the offline catalogue. It reads about 2,100 pages from NOAA's metadata API at a pace the API accepts, so it takes about 10 minutes. The other tides commands and s100 mcp serve read the catalogue with no network. SoundCharts reads its own station list; pass its path with --catalogue to fill it.

The catalogue is noaa-tide-stations.json.gz in an EncDotNet.S100/Tides folder in your local application data:

Platform Folder
Windows %LOCALAPPDATA%\EncDotNet.S100\Tides
macOS ~/Library/Application Support/EncDotNet.S100/Tides
Linux ~/.local/share/EncDotNet.S100/Tides

--catalogue keeps it somewhere else. The file format is documented in the station catalogue README, so you can also write your own.

--check asks NOAA whether it has newer data than the catalogue, with a few requests: a new datum epoch, stations added, removed or moved, and datums accepted again. It exits with code 8 when there's newer data. Without a network, a catalogue over 12 months old counts as stale.

Option Default Description
--check off Only checks for newer data. Exits with 0 when the catalogue is current and 8 when it isn't.
--catalogue <file> the offline cache Where to keep the catalogue.
s100 tides update
s100 tides update --check

sources

s100 sources

sources prints a table of the live data sources that identify --source, mcp serve --source and the MCP add_data_source tool take: each source's id, what it shows, the widest view it runs in, its options (* marks a required one, and a key shows its environment variable) and whether it's ready or what it still needs, such as a key's environment variable.

list-specs

s100 list-specs

list-specs prints a table of the product specifications s100 reads, with whether each has a bundled portrayal catalogue and whether it can be rendered headlessly. S-57 is listed with its portrayal shown as "via S-101". The weather formats GRIB2, NetCDF, CAP, CODSUS and TC (tropical cyclone advisories) are listed last, with their portrayal shown as "SoundCharts, in code", and a line under the table says they aren't S-100 products. See Supported specifications.

health

s100 health [--host <address>] [--port <port>] [--timeout <seconds>]

health asks a running tiles serve, feed serve or mcp serve --transport http for its /healthz route and exits with 0 when it answers 200 OK, or 1 when nothing is listening, the server answers with an error, or there's no answer in time. It prints what it asked and what came back. Use it as a container health check: the container image has no shell or curl.

Option Default Description
--host <address> 127.0.0.1 The server's address.
--port <port> 8200 The server's port. tiles serve listens on 8200 by default, feed serve on 8100 and mcp serve --transport http on 8300.
--timeout <seconds> 5 How long to wait for an answer.
s100 health
s100 health --port 8100
Healthy: http://127.0.0.1:8200/healthz

s57 convert

s100 s57 convert -o <output> <source> [options]

s57 convert translates an S-57 base cell (.000) and writes it as an ISO/IEC 8211 encoded S-101 dataset (S-100 Part 10a). An inland ENC cell is written as an S-401 dataset instead. Update files next to the base cell are applied first. The command then prints a summary of what translated and what didn't.

Option Default Description
-o, --output <path> required The S-101 or S-401 file to write.
--target <target> auto auto writes S-401 for an inland ENC and S-101 otherwise. s101 or s401 forces that product.
--report <path> off Also writes the full translation diagnostics as JSON.
--no-updates off Converts the base cell without its update files.
--debug off Prints a full stack trace on error.
s100 s57 convert -o my-s101-dataset.000 my-s57-dataset.000
s100 s57 convert -o my-s401-dataset.000 my-inland-s57-dataset.000
s100 s57 convert --target s101 -o my-s101-dataset.000 my-inland-s57-dataset.000

The output is an ordinary dataset: use info, validate and render on it. Bringing S-57 into the pipeline covers the summary, the report, inland cells and the translation's known gaps.

s101 convert

s100 s101 convert --to s57 -o <output> <source> [options]

s101 convert translates an S-101 base dataset (.000) and writes it as an S-57 Edition 3.1 base cell, following S-65 Annex C. Update datasets next to the base dataset are applied first. The command then prints a summary of what converted, what Annex C dropped or folded into INFORM, and what had no rule. It warns when the dataset isn't S-101 Edition 2.0.0, the edition Annex C converts.

The output is for testing and for tools that read only S-57, such as GDAL/OGR and OpenCPN. It isn't a production ENC: it isn't checked against S-58, and Annex C expects the producer to finish it by hand.

Option Default Description
-o, --output <path> required The S-57 cell to write, or with --exchange-set the directory to write the exchange set into.
--to <format> s57 The format to write. Only s57 is supported.
--exchange-set off Writes ENC_ROOT/CATALOG.031 and ENC_ROOT/<cell>/<cell>.000 under the output directory.
--cell-name <name> source file name With --exchange-set, the cell's name without extension, such as XX5CELL1.
--report <path> off Also writes the full translation diagnostics, with the Annex C clause of each drop, as JSON.
--no-updates off Converts the base dataset without its update datasets.
--no-optional-inform off Skips the conversions to INFORM that Annex C marks optional.
--inform-separator <text> ; The separator between strings folded into one INFORM or NINFOM.
--max-inform-length <n> 300 The recommended maximum length of INFORM and NINFOM.
--inform-length <policy> keep keep keeps a longer text and reports it; truncate cuts it at --max-inform-length.
--national-language <code> first The ISO 639-2 language, such as fra, to prefer for NOBJNM, NINFOM and NTXTDS.
--name-without-usage <policy> by-language A name with no nameUsage: by-language writes an English or unlabelled name to OBJNAM and any other to NOBJNM; drop doesn't convert it.
--debug off Prints a full stack trace on error.
s100 s101 convert --to s57 -o XX5CELL1.000 101XX00CELL1.000
s100 s101 convert --to s57 -o XX5CELL1.000 101XX00CELL1.000 --report report.json
s100 s101 convert --to s57 --exchange-set --cell-name XX5CELL1 -o s57set 101XX00CELL1.000

Read the cell back with info, and check an exchange set's catalogue with validate. Converting S-101 to S-57 covers the summary, what Annex C drops, the options and what a producer still has to do.

mcp serve

s100 mcp serve <dataset-or-exchange-set> [options]
s100 mcp serve --layer <dataset> [--layer <dataset> ...] [options]

mcp serve runs an MCP server over standard input and output, so an AI agent that starts the process can query and render datasets without SoundCharts. With --transport http, it serves the same tools over HTTP instead, so agents on other computers, or in other containers, can connect to it. See MCP over HTTP. It takes the same input forms as render. Datasets that fail to load are skipped with a warning.

To use it, configure your MCP client to run the command s100 with the arguments ["mcp", "serve", "<dataset-or-exchange-set>"].

The server provides the read-only query tools and these session tools: open_dataset, close_dataset, close_all_datasets, set_palette, set_display_category, set_display_mode, set_time_step, set_viewport and render_to_image. The session tools change only the server's in-memory state: they never edit the source datasets or write files. open_dataset adds more datasets while the server runs. Each process is one session, so start another process for a separate session. The tide tools list_tide_stations and predict_tide read the offline station catalogue (see tides update). MCP tools lists them all.

Option Default Description
--layer <path> none Adds a dataset. Repeat it for each dataset. Can't be combined with --from.
--from, --exchange-set <path> none Serves every dataset in an exchange set.
--only <specs> all Exchange-set form only. Loads only these product specifications, comma-separated.
--tide-catalogue <file> the offline cache The tide and current station catalogue list_tide_stations, predict_tide, list_current_stations and predict_current read. See tides update.
--tide-predictions off Fills S-104 and S-111 gaps with predictions from that catalogue: sample and check_route use the nearest tide station within 10 km by water where no S-104 covers a point and time, and sample uses the nearest current station within --current-station-reach where no S-111 does. See Predicted values in sampling.
--current-station-reach <metres> 2000 With --tide-predictions only. How far, by water, a current station's prediction applies. Much shorter than a tide station's 10 km, because tidal currents change over short distances.
--transport <transport> stdio stdio, or http to serve over HTTP.
--host <address> 127.0.0.1 HTTP only. The address to listen on. 0.0.0.0 accepts other computers.
--port <port> 8300 HTTP only. The port. 0 picks a free one.
--token <token> generated for a non-loopback host HTTP only. The bearer token clients must send. Letters, digits, - and _.
--no-token off HTTP only. Serves without a token, even on a non-loopback address.
--source <source> none Adds a live data source at startup, as add_data_source does. Repeat it for each source. A source id, optionally followed by : and comma-separated name=value options, such as nmea.weather:Input=udp:10110; keys come from environment variables. An unknown source or option exits with code 2. It runs once set_viewport narrows the view to its range. See sources.
--live-feeds off With --collections on SoundCharts' collections.json, also adds the live feeds subscribed to in its Library, such as NDBC observations or AIS targets, with their saved settings; keys come from environment variables. They run once set_viewport narrows the view to their range.
--allow-changes off HTTP only. Also serves the tools that open datasets by path and change the Library.
--toolsets <names> all Serves only these toolsets, comma-separated: query, datasets, presentation, routes, tides and library, or a profile such as route-planning. See Choose toolsets. An unknown name exits with code 2.
--lua-engine <engine> luacsharp The Lua engine that runs the portrayal rules: luacsharp or moonsharp. See Lua engine.
--debug off Prints a full stack trace on error.
s100 mcp serve dataset.h5
s100 mcp serve --layer enc.000 --layer bathy.h5
s100 mcp serve --from exchange-set.zip --only S101,S102
s100 mcp serve --layer enc.000 --source ndbc.realtime
s100 mcp serve charts/ --toolsets route-planning

Standard output carries the MCP protocol. Startup messages, load warnings and errors go to standard error. The server runs until the client closes standard input, or until you interrupt it.

MCP over HTTP

s100 mcp serve charts/ --transport http
s100 mcp serve charts/ --transport http --host 0.0.0.0 --token my-token

With --transport http, mcp serve serves the MCP Streamable HTTP transport at http://<host>:<port>/mcp, and prints that URL for each network address. It runs until you interrupt it or it's sent SIGTERM. Several clients can connect at once, and they share one session: one client's set_palette changes what render_to_image draws for the others.

By default only this computer can connect. With --host 0.0.0.0, other computers can, and mcp serve generates a random token unless you pass --token or --no-token. It prints a token it generates at startup, but not one you pass. Clients send the token in a header:

Authorization: Bearer <token>

A request without the token is answered 401 Unauthorized. Pass --token to keep the same token across restarts. A request whose Origin header names another host is answered 403 Forbidden, so a web page open in a browser can't use a server on your computer.

Over HTTP, mcp serve leaves out the tools that reach beyond the datasets you served, because a client could use them to read any file the server can read or make it fetch any URL:

  • open_dataset, close_dataset and close_all_datasets.
  • The Library tools that change it: add_library_source, refresh_library_source, remove_library_source, set_library_source_options, library_action, await_library_idle and set_secom_identity.

The query, session, Library listing and tide tools are served. Pass --allow-changes to serve every tool, as over standard input and output. Sources you add with --collection are in the Library either way.

/healthz answers 200 OK without a token, so s100 health --port 8300 checks the server. See health.

feed serve

s100 feed serve <path> [options]

feed serve publishes a folder, an exchange set (folder, CATALOG.XML, CATALOG.031 or .zip) or a single dataset as an S-100 feed over HTTP, so SoundCharts on another computer can browse and download it. A folder is scanned recursively.

The path is indexed in place; nothing is loaded or copied. feed serve checks it again at most every --refresh seconds, so datasets you add or change while it runs appear in the feed. Files that can't be read are reported at startup and left out.

The server has these routes:

  • feed.json, the feed, with an ETag so readers can revalidate it. It's compressed when the client asks.
  • items/<id>.zip, one for each dataset, holding its updates and exchange-set catalogue.
  • /healthz, which answers 200 OK with the text ok while the server runs. It never has a token. See health.

By default only this computer can connect. With --host 0.0.0.0, other computers can, and feed serve adds a random access token to every URL unless you pass --token or --no-token. It prints one feed URL for each network address.

Option Default Description
--host <address> 127.0.0.1 The address to listen on. 0.0.0.0 accepts other computers.
--port <port> 8100 The port. 0 picks a free one.
--token <token> generated for a non-loopback host An access token that becomes part of every URL. Letters, digits, - and _.
--no-token off Serves without a token, even on a non-loopback address.
--title <title> the folder or file name The feed's title.
--refresh <seconds> 10 The most often the path is checked for changes.
s100 feed serve charts/
s100 feed serve exchange-set.zip --port 9000
s100 feed serve charts/ --host 0.0.0.0

On the other computer, in the SoundCharts Library, choose Add > Connect to a shared feed…, paste the URL into Feed URL, and choose Connect.

The server runs until you press Ctrl+C or it receives SIGTERM.

feed export

s100 feed export <path> --out <directory> [options]

feed export writes the same feed as static files, so any web host can serve it without running s100: a web server, S3, GitHub Pages or a NAS. It takes the same kinds of path as feed serve, and writes:

  • feed.json
  • items/<id>.zip, one for each dataset

Upload the folder's contents, then add the URL of feed.json in SoundCharts.

  • Incremental. Exporting into the same folder again rewrites only the zips whose datasets changed, and removes the zips of datasets that are gone. The stamps it compares are kept in .s100-feed-export.json, which you don't need to upload.
  • Consistent during upload. feed.json is written last, so it never lists a zip that isn't there yet. Other files in the folder are left alone.
  • Outside the published path. --out can't be inside <path>, or the next export would publish the export.
Option Default Description
-o, --out <directory> required The folder to write the feed to. It's created if needed.
--title <title> the folder or file name The feed's title.
s100 feed export charts/ --out site/charts
s100 feed export exchange-set.zip -o export --title "Harbour survey"

When some datasets can't be written, they're left out of the feed and the command exits with code 1.

Lua engine

S-101, S-57, S-401, S-131, S-125 and S-102 are portrayed by the Lua rules in their portrayal catalogues. render, tiles export, tiles serve and mcp serve run those rules on Lua-CSharp unless --lua-engine moonsharp selects MoonSharp, the previous engine:

s100 render chart.000 chart.png --lua-engine moonsharp

The engines produce the same chart, with one known exception: a sectored light whose sectors share a nominal range can list its colours in a different order in its light description. Lua-CSharp lists them as reference Lua does.

Supported specifications

Family Specifications Notes
Vector, ISO 8211 S-101, S-401, S-57 S-57 is translated to S-101, or to S-401 for an inland ENC, and drawn with that product's portrayal, not S-52.
Vector, GML S-122, S-124, S-125, S-127, S-128, S-129, S-131, S-201, S-411, S-412, S-421
Coverage, HDF5 S-102; S-104 data coding formats 1, 2 and 8; S-111 data coding formats 1, 2, 3 and 8 Gridded data is drawn as a coverage; station and node data as glyphs. S-104 has no IHO portrayal, so its stations and grids use SoundCharts' own gauges and isolines; see S-104 portrayal. S-111 draws current arrows over the coverage. Other data coding formats exit with code 4.
Weather, not S-100 GRIB2, NetCDF-3 and NetCDF-4 (CF), CAP 1.2 and NWS alerts GeoJSON, WPC coded surface bulletins (CODSUS), NHC tropical cyclone GIS zips (TC) Wind and wave grids on a regular latitude/longitude grid, and marine weather warnings, drawn with SoundCharts' own styles; and surface analyses drawn as fronts and pressure centres. Tropical cyclone advisories are drawn in storm ink: the cone, wind radii, tracks, forecast points and storm. Not for navigation. See Show wind and waves on the chart.

Exit codes

Code Meaning
0 Success.
1 Unexpected error. Run again with --debug for a stack trace. For feed export, some datasets couldn't be written. For health, the server didn't answer 200 OK.
2 The product specification couldn't be detected, or no datasets could be resolved or loaded from the inputs. An HDF5 file is detected only from its root productSpecification attribute, which S-100 requires; when that's missing, names a product the CLI doesn't read, or the file can't be read as HDF5 (for example an encrypted S-100 dataset outside its exchange set), the message says so. For tiles export, also: the datasets have no geometry, or the tile set is over 100,000 tiles without --yes. For tiles serve: the path isn't a raster tile set it can read, or, as for tiles export, the datasets can't be read or have no geometry. For route check: the route file can't be read. For tides stations and tides predict: there's no station catalogue, no station matches, or the station can't be predicted on the datum.
3 The product specification doesn't support headless rendering or display-list output.
4 The dataset is recognised, but its structure or encoding isn't supported, such as an unsupported data coding format.
5 The dataset is recognised but doesn't conform: a required attribute, dataset or group is missing or malformed.
6 validate only: failing findings, or failed signature or checksum checks.
7 route check only: findings at or above --fail-on.
8 tides update --check only: NOAA has newer data than the catalogue.
other non-zero Invalid arguments, such as a missing file or an unknown palette.

See also