@signalk/charts-plugin 3.0.0 → 3.1.0

package/README.md

@@ -2,7 +2,13 @@
 
 Signal K Node server plugin to provide chart metadata, such as name, description and location of the actual chart tile data.
 
-Supports both v1 and v2 Signal K resources api paths.
+Chart metadata is derived from the following supported chart file types:
+- MBTiles _(.mbtiles)_
+- TMS _(tilemapresource.xml and tiles)_
+
+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)_.
+
+Chart metadata is made available to both v1 and v2 Signal K `resources` api paths.
 
 | Server Version | API | Path |
 |--- |--- |--- |
@@ -10,44 +16,60 @@ Supports both v1 and v2 Signal K resources api paths.
 | 2.x.x | v2 | `/signalk/v2/api/resources/charts` |
 
     
-_Note: v2 resource paths will only be made available on Signal K server >= v2._
+_Note: Version 2 resource paths will only be made available on Signal K server v2.0.0 and later_
 
-### Usage
+## Usage
 
-1. Install "Signal K Charts" plugin from Signal K Appstore
+1. Install `@signalk/signalk-charts` from the Signal K Server Appstore
 
-2. Configure plugin in **Plugin Config** 
+2. Configure the plugin in the Admin UI _(**Server -> Plugin Config -> Signal K Charts**)_ 
 
-- Add "Chart paths" which are the paths to the folders where chart files are stored. Defaults to `${signalk-configuration-path}/charts`
+3. Activate the plugin
 
+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)
 
-3. Add "Chart paths" in plugin configuration. Defaults to `${signalk-configuration-path}/charts`
 
-<img src="https://user-images.githubusercontent.com/1435910/39382493-57c1e4dc-4a6e-11e8-93e1-cedb4c7662f4.png" alt="Chart paths configuration" width="450"/>
+## Configuration
 
 
-4. Put charts into selected paths
+### Local Chart Files
 
-5. Add optional online chart providers
+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.
 
-<img src="https://user-images.githubusercontent.com/1435910/45048136-c65d2e80-b083-11e8-99db-01e8cece9f89.png" alt="Online chart providers configuration" width="450"/>
+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)_ 
 
 
-_WMS example:_
+### Online chart providers
 
-<img src="https://user-images.githubusercontent.com/38519157/102832518-90077100-443e-11eb-9a1d-d0806bb2b10b.png" alt="server type configuration" width="450"/>
+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.
 
-6. Activate plugin
+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"/>
 
-7. Use one of the client apps supporting Signal K charts, for example:
-- [Freeboard SK](https://www.npmjs.com/package/@signalk/freeboard-sk)
-- [Tuktuk Chart Plotter](https://www.npmjs.com/package/tuktuk-chart-plotter)
 
 ### 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)
@@ -57,13 +79,34 @@ Publicly available MBTiles charts can be found from:
 - [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,6 +1,6 @@
 {
   "name": "@signalk/charts-plugin",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Signal K plugin to provide chart support for Signal K server",
   "main": "plugin/index.js",
   "scripts": {
@@ -31,29 +31,29 @@
   },
   "dependencies": {
     "@mapbox/mbtiles": "^0.12.1",
-    "@signalk/server-api": "^2.0.0-beta.3",
-    "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": {
+    "@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",
+    "body-parser": "^1.18.2",
     "chai": "4.1.2",
     "chai-http": "^4.2.1",
     "eslint": "^8.34.0",
     "eslint-config-prettier": "^8.6.0",
-    "express": "4.16.2",
-    "mocha": "5.0.0",
+    "express": "^4.19.2",
+    "mocha": "^11.7.1",
     "prettier": "^2.8.4",
     "typescript": "^4.5.4"
   }

package/plugin/charts.js

@@ -22,15 +22,6 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -110,13 +101,13 @@ function openMbtilesFile(file, filename) {
             type: 'tilelayer',
             scale: parseInt(res.metadata.scale) || 250000,
             v1: {
-                tilemapUrl: `~basePath~/charts/${identifier}/{z}/{x}/{y}`,
+                tilemapUrl: `~tilePath~/${identifier}/{z}/{x}/{y}`,
                 chartLayers: res.metadata.vector_layers
                     ? parseVectorLayers(res.metadata.vector_layers)
                     : []
             },
             v2: {
-                url: `~basePath~/charts/${identifier}/{z}/{x}/{y}`,
+                url: `~tilePath~/${identifier}/{z}/{x}/{y}`,
                 layers: res.metadata.vector_layers
                     ? parseVectorLayers(res.metadata.vector_layers)
                     : []
@@ -133,24 +124,22 @@ function parseVectorLayers(layers) {
     return layers.map((l) => l.id);
 }
 function directoryToMapInfo(file, identifier) {
-    function loadInfo() {
-        return __awaiter(this, void 0, void 0, function* () {
-            const tilemapResource = path_1.default.join(file, 'tilemapresource.xml');
-            const metadataJson = path_1.default.join(file, 'metadata.json');
+    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 {
-                yield fs_1.promises.stat(tilemapResource);
-                return parseTilemapResource(tilemapResource);
+                await fs_1.promises.stat(metadataJson);
+                return parseMetadataJson(metadataJson);
             }
-            catch (_a) {
-                try {
-                    yield fs_1.promises.stat(metadataJson);
-                    return parseMetadataJson(metadataJson);
-                }
-                catch (_b) {
-                    return null;
-                }
+            catch {
+                return null;
             }
-        });
+        }
     }
     return loadInfo()
         .then((info) => {
@@ -163,11 +152,11 @@ function directoryToMapInfo(file, identifier) {
             (info._fileFormat = 'directory'),
                 (info._filePath = file),
                 (info.v1 = {
-                    tilemapUrl: `~basePath~/charts/${identifier}/{z}/{x}/{y}`,
+                    tilemapUrl: `~tilePath~/${identifier}/{z}/{x}/{y}`,
                     chartLayers: []
                 });
             info.v2 = {
-                url: `~basePath~/charts/${identifier}/{z}/{x}/{y}`,
+                url: `~tilePath~/${identifier}/{z}/{x}/{y}`,
                 layers: []
             };
             return info;

package/plugin/index.js

@@ -22,15 +22,6 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -43,6 +34,7 @@ const charts_1 = require("./charts");
 const constants_1 = require("./constants");
 const MIN_ZOOM = 1;
 const MAX_ZOOM = 24;
+const chartTilesPath = '/signalk/chart-tiles';
 module.exports = (app) => {
     let chartProviders = {};
     let pluginStarted = false;
@@ -52,7 +44,9 @@ module.exports = (app) => {
     };
     const configBasePath = app.config.configPath;
     const defaultChartsPath = path_1.default.join(configBasePath, '/charts');
-    const serverMajorVersion = app.config.version ? parseInt(app.config.version.split('.')[0]) : '1';
+    const serverMajorVersion = app.config.version
+        ? parseInt(app.config.version.split('.')[0])
+        : '1';
     ensureDirectoryExists(defaultChartsPath);
     // ******** REQUIRED PLUGIN DEFINITION *******
     const CONFIG_SCHEMA = {
@@ -103,7 +97,14 @@ module.exports = (app) => {
                             type: 'string',
                             title: 'Map source / server type',
                             default: 'tilelayer',
-                            enum: ['tilelayer', 'S-57', 'WMS', 'WMTS', 'mapstyleJSON', 'tileJSON'],
+                            enum: [
+                                'tilelayer',
+                                'S-57',
+                                'WMS',
+                                'WMTS',
+                                'mapstyleJSON',
+                                'tileJSON'
+                            ],
                             description: 'Map data source type served by the supplied url. (Use tilelayer for xyz / tms tile sources.)'
                         },
                         format: {
@@ -153,8 +154,8 @@ module.exports = (app) => {
         }
     };
     const doStartup = (config) => {
-        app.debug('** loaded config: ', config);
-        props = Object.assign({}, config);
+        app.debug(`** loaded config: ${config}`);
+        props = { ...config };
         const chartPaths = _.isEmpty(props.chartPaths)
             ? [defaultChartsPath]
             : resolveUniqueChartPaths(props.chartPaths, configBasePath);
@@ -168,7 +169,7 @@ module.exports = (app) => {
         pluginStarted === false && registerRoutes();
         pluginStarted = true;
         const urlBase = `${app.config.ssl ? 'https' : 'http'}://localhost:${'getExternalPort' in app.config ? app.config.getExternalPort() : 3000}`;
-        app.debug('**urlBase**', urlBase);
+        app.debug(`**urlBase** ${urlBase}`);
         app.setPluginStatus('Started');
         const loadProviders = bluebird
             .mapSeries(chartPaths, (chartPath) => (0, charts_1.findCharts)(chartPath))
@@ -186,7 +187,7 @@ module.exports = (app) => {
     };
     const registerRoutes = () => {
         app.debug('** Registering API paths **');
-        app.get(`/signalk/:version(v[1-2])/api/resources/charts/:identifier/:z([0-9]*)/:x([0-9]*)/:y([0-9]*)`, (req, res) => __awaiter(void 0, void 0, void 0, function* () {
+        app.get(`${chartTilesPath}/:identifier/:z([0-9]*)/:x([0-9]*)/:y([0-9]*)`, async (req, res) => {
             const { identifier, z, x, y } = req.params;
             const provider = chartProviders[identifier];
             if (!provider) {
@@ -201,7 +202,7 @@ module.exports = (app) => {
                     console.log(`Unknown chart provider fileformat ${provider._fileFormat}`);
                     res.status(500).send();
             }
-        }));
+        });
         app.debug('** Registering v1 API paths **');
         app.get(constants_1.apiRoutePrefix[1] + '/charts/:identifier', (req, res) => {
             const { identifier } = req.params;
@@ -231,11 +232,11 @@ module.exports = (app) => {
                 type: 'charts',
                 methods: {
                     listResources: (params) => {
-                        app.debug(`** listResources()`, params);
+                        app.debug(`** listResources() ${params}`);
                         return Promise.resolve(_.mapValues(chartProviders, (provider) => sanitizeProvider(provider, 2)));
                     },
                     getResource: (id) => {
-                        app.debug(`** getResource()`, id);
+                        app.debug(`** getResource() ${id}`);
                         const provider = chartProviders[id];
                         if (provider) {
                             return Promise.resolve(sanitizeProvider(provider, 2));
@@ -297,11 +298,11 @@ const sanitizeProvider = (provider, version = 1) => {
     let v;
     if (version === 1) {
         v = _.merge({}, provider.v1);
-        v.tilemapUrl = v.tilemapUrl.replace('~basePath~', constants_1.apiRoutePrefix[1]);
+        v.tilemapUrl = v.tilemapUrl.replace('~tilePath~', chartTilesPath);
     }
     else if (version === 2) {
         v = _.merge({}, provider.v2);
-        v.url = v.url ? v.url.replace('~basePath~', constants_1.apiRoutePrefix[2]) : '';
+        v.url = v.url ? v.url.replace('~tilePath~', chartTilesPath) : '';
     }
     provider = _.omit(provider, [
         '_filePath',

package/plugin/types.d.ts

@@ -11,11 +11,11 @@ export interface ChartProvider {
     scale: number;
     v1?: {
         tilemapUrl: string;
-        chartLayers: string[];
+        chartLayers?: string[];
     };
     v2?: {
         url: string;
-        layers: string[];
+        layers?: string[];
     };
     bounds?: number[];
     minzoom?: number;