@signalk/charts-plugin 2.3.1 → 3.1.0

package/README.md

@@ -1,49 +1,112 @@
-# Signal K Node server Charts plugin
+# Signal K server Charts plugin
 
 Signal K Node server plugin to provide chart metadata, such as name, description and location of the actual chart tile data.
 
-### Usage
+Chart metadata is derived from the following supported chart file types:
+- MBTiles _(.mbtiles)_
+- TMS _(tilemapresource.xml and tiles)_
 
-1. Install "Signal K Charts" plugin from Signal K Appstore
+Additionally, chart metadata can be entered via the plugin configuration for other chart sources and types _(e.g. WMS, WMTS, S-57 tiles and tilejson)_.
 
-2. Add "Chart paths" in plugin configuration. Defaults to `${signalk-configuration-path}/charts`
+Chart metadata is made available to both v1 and v2 Signal K `resources` api paths.
 
-<img src="https://user-images.githubusercontent.com/1435910/39382493-57c1e4dc-4a6e-11e8-93e1-cedb4c7662f4.png" alt="Chart paths configuration" width="450"/>
+| Server Version | API | Path |
+|--- |--- |--- |
+| 1.x.x | v1 | `/signalk/v1/api/resources/charts` |
+| 2.x.x | v2 | `/signalk/v2/api/resources/charts` |
 
-3. Put charts into selected paths
+    
+_Note: Version 2 resource paths will only be made available on Signal K server v2.0.0 and later_
 
-4. Add optional online chart providers
+## Usage
 
-<img src="https://user-images.githubusercontent.com/1435910/45048136-c65d2e80-b083-11e8-99db-01e8cece9f89.png" alt="Online chart providers configuration" width="450"/>
+1. Install `@signalk/signalk-charts` from the Signal K Server Appstore
 
-_WMS example:_
-![image](https://user-images.githubusercontent.com/38519157/102832518-90077100-443e-11eb-9a1d-d0806bb2b10b.png)
+2. Configure the plugin in the Admin UI _(**Server -> Plugin Config -> Signal K Charts**)_ 
 
-5. Activate plugin
+3. Activate the plugin
 
-6. Use one of the client apps supporting Signal K charts, for example:
+Chart metadata will then be available to client apps via the resources api `/resources/charts` for example:
 - [Freeboard SK](https://www.npmjs.com/package/@signalk/freeboard-sk)
 - [Tuktuk Chart Plotter](https://www.npmjs.com/package/tuktuk-chart-plotter)
 
+
+## Configuration
+
+
+### Local Chart Files
+
+To use chart files stored on the Signal K Server the plugin needs to know where your local chart files
+are stored to generate the chart metadata.
+
+You can either:
+1. Put the chart files in the default location _(`/home/<user>/.signalk/charts`)_ 
+2. Add configuration entries for the folders where the chart files are stored. 
+
+<img src="https://user-images.githubusercontent.com/1435910/39382493-57c1e4dc-4a6e-11e8-93e1-cedb4c7662f4.png" alt="Chart paths configuration" width="450"/>
+
+>**Note:** After chart files have been added to folders they will be processed after the plugin has been restarted! _(disable / enable the plugin)_ 
+
+
+### Online chart providers
+
+If your chart source is not local to the Signal K Server you can add "Online Chart Providers" and enter the required charts metadata for the source.
+
+You will need to provide the following information:
+1. A chart name for client applications to display
+2. The URL to the chart source
+3. Select the chart image format
+4. The minimum and maximum zoom levels where chart data is available.
+
+You can also provide a description detailing the chart content.
+
+<img src="https://github.com/user-attachments/assets/77cb3aaf-5471-4e55-b05d-aad70cacab6a" alt="Online chart providers configuration" width="450"/>
+
+For WMS & WMTS sources you can specify the layers you wish to display.
+
+<img src="https://github.com/user-attachments/assets/b9bfba38-8468-4eca-aeb3-96a80fcbc7a6" alt="Online chart provider layers" width="450"/>
+
+
 ### Supported chart formats
 
-- [MBTiles](https://github.com/mapbox/mbtiles-spec) file
+- [MBTiles](https://github.com/mapbox/mbtiles-spec) files
 - Directory with cached [TMS](https://wiki.osgeo.org/wiki/Tile_Map_Service_Specification) tiles and `tilemapresource.xml`
 - Directory with XYZ tiles and `metadata.json`
 - Online [TMS](https://wiki.osgeo.org/wiki/Tile_Map_Service_Specification)
 
 Publicly available MBTiles charts can be found from:
-- [NOAA Nautical charts](http://tileservice.charts.noaa.gov/), quick download [cheat-sheet](https://github.com/vokkim/noaa-nautical-charts)
+- [NOAA Nautical charts](https://distribution.charts.noaa.gov/ncds/index.html)
 - [Finnish Transport Agency nautical charts](https://github.com/vokkim/rannikkokartat-mbtiles)
 - [Signal K World Coastline Map](https://github.com/netAction/signalk-world-coastline-map), download [MBTiles release](https://github.com/netAction/signalk-world-coastline-map/releases/download/v1.0/signalk-world-coastline-map-database.tgz)
 
+
+---
+
 ### API
 
 Plugin adds support for `/resources/charts` endpoints described in [Signal K specification](http://signalk.org/specification/1.0.0/doc/otherBranches.html#resourcescharts):
 
-- `GET /signalk/v1/api/resources/charts/` returns metadata for all available charts
-- `GET /signalk/v1/api/resources/charts/${identifier}/` returns metadata for selected chart
-- `GET /signalk/v1/api/resources/charts/${identifier}/${z}/${x}/${y}` returns a single tile for selected offline chart. As charts-plugin isn't proxy, online charts is not available via this request. You should look the metadata to find proper request.
+#### List available charts
+
+```bash
+GET /signalk/v2/api/resources/charts/` 
+```
+
+#### Return metadata for selected chart
+
+```bash
+
+GET /signalk/v2/api/resources/charts/${identifier}` 
+```
+
+#### Chart Tiles
+Chart tiles are retrieved using the url defined in the chart metadata.
+
+For local chart files located in the Chart Path(s) defined in the plugin configuration, the url will be:
+
+```bash
+/signalk/chart-tiles/${identifier}/${z}/${x}/${y}
+```
 
 License
 -------

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "@signalk/charts-plugin",
-  "version": "2.3.1",
+  "version": "3.1.0",
   "description": "Signal K plugin to provide chart support for Signal K server",
-  "main": "index.js",
+  "main": "plugin/index.js",
   "scripts": {
+    "build": "tsc",
+    "build-declaration": "tsc --declaration --allowJs false",
+    "watch": "npm run build -- -w",
+    "start": "npm run build -- -w",
+    "prepare": "tsc",
+    "prettier": "prettier -w src/",
+    "lint": "eslint -c .eslintrc.js --ext .ts --ext .js --fix src/",
+    "format": "npm run prettier && npm run lint",
+    "ci-lint": "eslint -c .eslintrc.js --ext .ts --ext .js src/ && prettier --check src/",
     "test": "mocha",
-    "deploy": "npm test && git tag -a v$npm_package_version -m 'Release v$npm_package_version'; git push --tags; npm publish --access public --scope @signalk ."
+    "deploy": "npm build && npm test && git tag -a v$npm_package_version -m 'Release v$npm_package_version'; git push --tags; npm publish --access public --scope @signalk ."
   },
   "license": "Apache-2.0",
   "keywords": [
@@ -22,20 +31,30 @@
   },
   "dependencies": {
     "@mapbox/mbtiles": "^0.12.1",
-    "baconjs": "1.0.1",
+    "@signalk/server-api": "^2.0.0",
     "bluebird": "3.5.1",
     "lodash": "^4.17.11",
-    "xml2js": "0.4.19"
+    "xml2js": "0.6.2"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/SignalK/charts-plugin"
   },
   "devDependencies": {
-    "body-parser": "1.18.2",
+    "@types/baconjs": "^0.7.34",
+    "@types/express": "^4.17.17",
+    "@types/lodash": "^4.14.191",
+    "@types/node": "^18.14.4",
+    "@typescript-eslint/eslint-plugin": "^5.52.0",
+    "@typescript-eslint/parser": "^5.52.0",
+    "body-parser": "^1.18.2",
     "chai": "4.1.2",
     "chai-http": "^4.2.1",
-    "express": "4.16.2",
-    "mocha": "5.0.0"
+    "eslint": "^8.34.0",
+    "eslint-config-prettier": "^8.6.0",
+    "express": "^4.19.2",
+    "mocha": "^11.7.1",
+    "prettier": "^2.8.4",
+    "typescript": "^4.5.4"
   }
 }

package/plugin/charts.d.ts

@@ -0,0 +1 @@
+export declare function findCharts(chartBaseDir: string): Promise<any>;

package/plugin/charts.js

@@ -0,0 +1,243 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findCharts = void 0;
+const bluebird = __importStar(require("bluebird"));
+const path_1 = __importDefault(require("path"));
+const mbtiles_1 = __importDefault(require("@mapbox/mbtiles"));
+const xml2js = __importStar(require("xml2js"));
+const fs_1 = require("fs");
+const _ = __importStar(require("lodash"));
+function findCharts(chartBaseDir) {
+    return fs_1.promises
+        .readdir(chartBaseDir, { withFileTypes: true })
+        .then((files) => {
+        return bluebird.mapSeries(files, (file) => {
+            const isMbtilesFile = file.name.match(/\.mbtiles$/i);
+            const filePath = path_1.default.resolve(chartBaseDir, file.name);
+            const isDirectory = file.isDirectory();
+            if (isMbtilesFile) {
+                return openMbtilesFile(filePath, file.name);
+            }
+            else if (isDirectory) {
+                return directoryToMapInfo(filePath, file.name);
+            }
+            else {
+                return Promise.resolve(null);
+            }
+        });
+    })
+        .then((result) => _.filter(result, _.identity))
+        .then((charts) => _.reduce(charts, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (result, chart) => {
+        result[chart.identifier] = chart;
+        return result;
+    }, {}))
+        .catch((err) => {
+        console.error(`Error reading charts directory ${chartBaseDir}:${err.message}`);
+    });
+}
+exports.findCharts = findCharts;
+function openMbtilesFile(file, filename) {
+    return (new Promise((resolve, reject) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        new mbtiles_1.default(file, (err, mbtiles) => {
+            if (err) {
+                return reject(err);
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mbtiles.getInfo((err, metadata) => {
+                if (err) {
+                    return reject(err);
+                }
+                return resolve({ mbtiles, metadata });
+            });
+        });
+    })
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .then((res) => {
+        if (_.isEmpty(res.metadata) || res.metadata.bounds === undefined) {
+            return null;
+        }
+        const identifier = filename.replace(/\.mbtiles$/i, '');
+        const data = {
+            _fileFormat: 'mbtiles',
+            _filePath: file,
+            _mbtilesHandle: res.mbtiles,
+            _flipY: false,
+            identifier,
+            name: res.metadata.name || res.metadata.id,
+            description: res.metadata.description,
+            bounds: res.metadata.bounds,
+            minzoom: res.metadata.minzoom,
+            maxzoom: res.metadata.maxzoom,
+            format: res.metadata.format,
+            type: 'tilelayer',
+            scale: parseInt(res.metadata.scale) || 250000,
+            v1: {
+                tilemapUrl: `~tilePath~/${identifier}/{z}/{x}/{y}`,
+                chartLayers: res.metadata.vector_layers
+                    ? parseVectorLayers(res.metadata.vector_layers)
+                    : []
+            },
+            v2: {
+                url: `~tilePath~/${identifier}/{z}/{x}/{y}`,
+                layers: res.metadata.vector_layers
+                    ? parseVectorLayers(res.metadata.vector_layers)
+                    : []
+            }
+        };
+        return data;
+    })
+        .catch((e) => {
+        console.error(`Error loading chart ${file}`, e.message);
+        return null;
+    }));
+}
+function parseVectorLayers(layers) {
+    return layers.map((l) => l.id);
+}
+function directoryToMapInfo(file, identifier) {
+    async function loadInfo() {
+        const tilemapResource = path_1.default.join(file, 'tilemapresource.xml');
+        const metadataJson = path_1.default.join(file, 'metadata.json');
+        try {
+            await fs_1.promises.stat(tilemapResource);
+            return parseTilemapResource(tilemapResource);
+        }
+        catch {
+            try {
+                await fs_1.promises.stat(metadataJson);
+                return parseMetadataJson(metadataJson);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return loadInfo()
+        .then((info) => {
+        if (info) {
+            if (!info.format) {
+                console.error(`Missing format metadata for chart ${identifier}`);
+                return null;
+            }
+            info.identifier = identifier;
+            (info._fileFormat = 'directory'),
+                (info._filePath = file),
+                (info.v1 = {
+                    tilemapUrl: `~tilePath~/${identifier}/{z}/{x}/{y}`,
+                    chartLayers: []
+                });
+            info.v2 = {
+                url: `~tilePath~/${identifier}/{z}/{x}/{y}`,
+                layers: []
+            };
+            return info;
+        }
+        return null;
+    })
+        .catch((e) => {
+        console.error(`Error getting charts from ${file}`, e.message);
+        return undefined;
+    });
+}
+function parseTilemapResource(tilemapResource) {
+    return (fs_1.promises
+        .readFile(tilemapResource)
+        .then(bluebird.promisify(xml2js.parseString))
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .then((parsed) => {
+        const result = parsed.TileMap;
+        const name = _.get(result, 'Title.0');
+        const format = _.get(result, 'TileFormat.0.$.extension');
+        const scale = _.get(result, 'Metadata.0.$.scale');
+        const bbox = _.get(result, 'BoundingBox.0.$');
+        const zoomLevels = _.map(_.get(result, 'TileSets.0.TileSet') || [], (set) => parseInt(_.get(set, '$.href')));
+        const res = {
+            _flipY: true,
+            name,
+            description: name,
+            bounds: bbox
+                ? [
+                    parseFloat(bbox.minx),
+                    parseFloat(bbox.miny),
+                    parseFloat(bbox.maxx),
+                    parseFloat(bbox.maxy)
+                ]
+                : undefined,
+            minzoom: !_.isEmpty(zoomLevels) ? _.min(zoomLevels) : undefined,
+            maxzoom: !_.isEmpty(zoomLevels) ? _.max(zoomLevels) : undefined,
+            format,
+            type: 'tilelayer',
+            scale: parseInt(scale) || 250000,
+            identifier: '',
+            _filePath: ''
+        };
+        return res;
+    }));
+}
+function parseMetadataJson(metadataJson) {
+    return fs_1.promises
+        .readFile(metadataJson, { encoding: 'utf8' })
+        .then((txt) => {
+        return JSON.parse(txt);
+    })
+        .then((metadata) => {
+        function parseBounds(bounds) {
+            if (_.isString(bounds)) {
+                return _.map(bounds.split(','), (bound) => parseFloat(_.trim(bound)));
+            }
+            else if (_.isArray(bounds) && bounds.length === 4) {
+                return bounds;
+            }
+            else {
+                return undefined;
+            }
+        }
+        const res = {
+            _flipY: false,
+            name: metadata.name || metadata.id,
+            description: metadata.description || '',
+            bounds: parseBounds(metadata.bounds),
+            minzoom: parseIntIfNotUndefined(metadata.minzoom),
+            maxzoom: parseIntIfNotUndefined(metadata.maxzoom),
+            format: metadata.format,
+            type: metadata.type,
+            scale: parseInt(metadata.scale) || 250000,
+            identifier: '',
+            _filePath: ''
+        };
+        return res;
+    });
+}
+function parseIntIfNotUndefined(val) {
+    const parsed = parseInt(val);
+    return _.isFinite(parsed) ? parsed : undefined;
+}

package/plugin/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const apiRoutePrefix: {
+    1: string;
+    2: string;
+};

package/plugin/constants.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiRoutePrefix = void 0;
+exports.apiRoutePrefix = {
+    1: '/signalk/v1/api/resources',
+    2: '/signalk/v2/api/resources'
+};

package/plugin/index.d.ts

@@ -0,0 +1 @@
+export {};