@metsa/isom-maplibre 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Malthe Poulsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# isom-maplibre
+
+A [MapLibre GL](https://maplibre.org) style that renders orienteering maps per
+[ISOM 2017-2](https://orienteering.sport/iof/mapping/), the IOF International
+Specification for Orienteering Maps, at 1:10,000.
+
+Every line width, dash, pattern and symbol is computed from the ISOM dimensions
+(mm at 1:15,000, enlarged ×1.5 and converted at 96 dpi), uses the ISOM colours,
+and is stacked in the ISOM colour order. The dimensions are cross-checked against
+the [OpenOrienteering Mapper](https://www.openorienteering.org/apps/mapper/)
+ISOM 2017-2 symbol set.
+
+## Install
+
+```sh
+npm install @metsa/isom-maplibre maplibre-gl
+```
+
+Releases are published to npm with provenance.
+
+## Usage
+
+### In-memory GeoJSON
+
+`isomGeojsonStyle()` returns the GeoJSON style (one GeoJSON source per table,
+no sprite) with your data attached, and `registerIsomIcons()` supplies the
+pattern and symbol images at runtime:
+
+```ts
+import maplibregl from "maplibre-gl";
+import { isomGeojsonStyle, registerIsomIcons } from "@metsa/isom-maplibre";
+
+const map = new maplibregl.Map({
+  container: "map",
+  style: isomGeojsonStyle({ contours, water, paths }), // FeatureCollections, lng/lat
+});
+registerIsomIcons(map);
+```
+
+Tables you leave out start empty; fill them later with
+`map.getSource(table).setData(featureCollection)`. `DETAIL_TABLES` lists them.
+The style without data is also exported as
+`@metsa/isom-maplibre/style.geojson.json`.
+
+### Vector tiles
+
+```ts
+import style from "@metsa/isom-maplibre/style.json";
+```
+
+The style reads one vector source per table from `/tiles/<table>` (TileJSON)
+and its images from the sprite `/sprite/isom`. Point those URLs at your server
+and build the sprite from `ICONS` (SVGs keyed by image id), or pass `-sprites`
+to the generator (see [Development](#development)). Two optional sources serve
+large tile sets:
+
+- `overview`: one source whose layers carry `vegetation_areas`, `water`,
+  `paths` and `manmade`, drawn below zoom 13 in place of the per-table sources.
+- `coverage`: polygons outlining where data exists. From zoom 10 they are white
+  paper under the map, so a basemap merged underneath never shows through; below
+  zoom 10 they are a translucent brown patch marking where maps are.
+
+Every layer except the background carries `metadata` for selecting layers
+without parsing ids: `isom:pass` (`detail`, `overview` or `coverage`), and on
+symbol layers `isom:code` and `isom:group` (the ISOM colour group). The style's
+own `metadata["isom:tables"]` lists the tables in definition order.
+
+## Data
+
+Each feature carries a string `isom_code` property. Codes without a symbol stay
+invisible.
+
+| Table              | Geometry        | `isom_code`                                                          |
+|--------------------|-----------------|----------------------------------------------------------------------|
+| `contours`         | lines           | 101.000, 101.001 (slope line), 102.000, 103.000, 104.000, 105.000    |
+| `cliffs`           | lines, polygons | 201.000, 202.000, 206.000                                            |
+| `knolls_points`    | points          | 109.000, 111.000                                                     |
+| `vegetation_areas` | polygons, lines | 401.000 to 410.000, 412.000, 413.000, 415.000                        |
+| `water`            | lines, polygons | 301.000, 302.000, 304.000, 305.000, 306.000, 308.000                 |
+| `paths`            | lines           | 502.000 to 507.000                                                   |
+| `manmade`          | lines, polygons | 501.000, 509.000, 510.000, 511.000, 515.000, 516.000, 520.000, 521.000, 521.001 (large building: outline and 65% infill), 529.000 |
+
+A 101.001 slope line is a two-point line from the contour downhill; the symbol
+takes its bearing from it. Coordinates are lng/lat, as for any MapLibre source.
+
+## Scale
+
+Up to zoom 15 every dimension is constant; above it the whole map magnifies ×2
+per zoom level, which keeps ISOM proportions intact. Zoom 15 is true 1:10,000
+at about 56° latitude. At latitude φ the true-scale zoom is
+`log2(156543.03 · cos φ / 2.6458)`.
+
+## Limitations
+
+MapLibre cannot draw some ISOM ornaments, so these symbols are simplified:
+
+- Plain line without its ornament: 104 tags, 105 dots, 201 tags, 510 pylon
+  bars, 515 dots, 516 tags, 529 tick pairs.
+- Flat fill without its pattern: 402 and 404 holes, 412 dots, 413 dot rows.
+- Dashes are not balanced per feature as ISOM asks.
+- The white core of 509 and 511 masks what lies beneath it.
+- Fill patterns (308, 407, 409) keep their density above zoom 15.
+- The map must be displayed north-up for the north-oriented patterns to be
+  correct.
+
+## Development
+
+[`isom.yaml`](isom.yaml) defines the whole style: scale, palette (referenced
+through YAML anchors), images, and the symbol stack. It is validated by
+[`isom.schema.json`](isom.schema.json), which editors with the YAML language
+server pick up automatically; the generator enforces the schema too, plus the
+cross-references it cannot express (palette colours, table and image names).
+`src/style.json`, `src/style.geojson.json` and `src/icons.json` are generated
+from it:
+
+```sh
+go generate ./...   # regenerate src/
+go test ./...       # schema, ISOM dimension and colour-order checks
+npm run build && npm test
+```
+
+The generator is also usable directly, for example to write a sprite directory
+for a tile server. It reads the definition embedded in the module unless
+`-spec` names another file:
+
+```sh
+go run github.com/MetsaApp/isom-maplibre/cmd/genstyle@latest \
+  -style style.json -geojson-style style.geojson.json -icons icons.json -sprites sprites/
+```
+
+Go programs get the parsed definition from `isomstyle.Default()` in
+`github.com/MetsaApp/isom-maplibre/pkg/isomstyle` (`Load` and `Parse` take
+another one), and render it with `Style`, `GeojsonStyle` and `Icons`.
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org);
+release-please opens the release PR, and merging it tags the release and
+publishes the package.
+
+## License
+
+MIT. ISOM is a specification of the International Orienteering Federation;
+this project is not affiliated with the IOF.

package/dist/icons.json

@@ -0,0 +1,7 @@
+{
+    "isom:111": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"5\" height=\"3\" viewBox=\"0 0 5 3\"><path d=\"M0.742 0.621A1.758 1.758 0 0 0 4.258 0.621\" fill=\"none\" stroke=\"#D15C00\" stroke-width=\"1.02\"/></svg>",
+    "isom:308": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"4\" height=\"17\" viewBox=\"0 0 4 17\"><path d=\"M0 0.85H4M0 2.55H4M0 4.25H4M0 5.95H4M0 7.65H4M0 9.35H4M0 11.05H4M0 12.75H4M0 14.45H4M0 16.15H4\" fill=\"none\" stroke=\"#00FFFF\" stroke-width=\"0.567\"/></svg>",
+    "isom:407": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"62\" height=\"4\" viewBox=\"0 0 62 4\"><path d=\"M2.385 0V4M7.154 0V4M11.923 0V4M16.692 0V4M21.462 0V4M26.231 0V4M31 0V4M35.769 0V4M40.538 0V4M45.308 0V4M50.077 0V4M54.846 0V4M59.615 0V4\" fill=\"none\" stroke=\"#3DFF17\" stroke-width=\"0.68\"/></svg>",
+    "isom:409": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"31\" height=\"4\" viewBox=\"0 0 31 4\"><path d=\"M1.192 0V4M3.577 0V4M5.962 0V4M8.346 0V4M10.731 0V4M13.115 0V4M15.5 0V4M17.885 0V4M20.269 0V4M22.654 0V4M25.038 0V4M27.423 0V4M29.808 0V4\" fill=\"none\" stroke=\"#3DFF17\" stroke-width=\"0.794\"/></svg>",
+    "isom:slope": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"3\" height=\"1\" viewBox=\"0 0 3 1\"><path d=\"M0.167 0.5H2.833\" stroke=\"#D15C00\" stroke-width=\"0.794\"/></svg>"
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { FeatureCollection } from "geojson";
+import type { Map, StyleSpecification } from "maplibre-gl";
+import geojsonStyle from "./style.geojson.json";
+/** Pattern and point-symbol SVGs keyed by style image id ("isom:111"), sized
+ * in CSS px at 1:10,000. registerIsomIcons() rasterizes them for you. */
+export declare const ICONS: Record<string, string>;
+export type IsomTable = keyof typeof geojsonStyle.sources;
+/** Source layers the style expects, in definition order; each feature carries
+ * a string `isom_code` property ("401.000", "509.000", ...) selecting the ISOM
+ * symbol. */
+export declare const DETAIL_TABLES: readonly IsomTable[];
+/** The generated GeoJSON style (one source per table, the full-detail symbol
+ * pass at every zoom, no sprite: registerIsomIcons supplies the images) with
+ * the given FeatureCollections attached. Tables left out start empty. */
+export declare function isomGeojsonStyle(data?: Partial<Record<IsomTable, FeatureCollection>>): StyleSpecification;
+/** Rasterizes the ISOM pattern/symbol images on demand at 2x (fill patterns
+ * and point symbols reference them as "isom:<id>"). Call once right after
+ * constructing the Map. */
+export declare function registerIsomIcons(map: Map): void;

package/dist/index.js

@@ -0,0 +1,45 @@
+import geojsonStyle from "./style.geojson.json" with { type: "json" };
+import icons from "./icons.json" with { type: "json" };
+/** Pattern and point-symbol SVGs keyed by style image id ("isom:111"), sized
+ * in CSS px at 1:10,000. registerIsomIcons() rasterizes them for you. */
+export const ICONS = icons;
+/** Source layers the style expects, in definition order; each feature carries
+ * a string `isom_code` property ("401.000", "509.000", ...) selecting the ISOM
+ * symbol. */
+export const DETAIL_TABLES = geojsonStyle.metadata["isom:tables"];
+/** The generated GeoJSON style (one source per table, the full-detail symbol
+ * pass at every zoom, no sprite: registerIsomIcons supplies the images) with
+ * the given FeatureCollections attached. Tables left out start empty. */
+export function isomGeojsonStyle(data) {
+    const style = structuredClone(geojsonStyle);
+    for (const t of DETAIL_TABLES) {
+        const fc = data?.[t];
+        if (fc)
+            style.sources[t].data = fc;
+    }
+    return style;
+}
+/** Rasterizes the ISOM pattern/symbol images on demand at 2x (fill patterns
+ * and point symbols reference them as "isom:<id>"). Call once right after
+ * constructing the Map. */
+export function registerIsomIcons(map) {
+    const pending = new Set();
+    map.on("styleimagemissing", async ({ id }) => {
+        const svg = ICONS[id];
+        // styleimagemissing refires every frame until the image exists.
+        if (!svg || pending.has(id) || map.hasImage(id))
+            return;
+        pending.add(id);
+        const img = new Image();
+        img.src = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(svg);
+        await img.decode();
+        const c = document.createElement("canvas");
+        c.width = img.width * 2;
+        c.height = img.height * 2;
+        const ctx = c.getContext("2d");
+        ctx.drawImage(img, 0, 0, c.width, c.height);
+        if (!map.hasImage(id)) {
+            map.addImage(id, ctx.getImageData(0, 0, c.width, c.height), { pixelRatio: 2 });
+        }
+    });
+}