Serve map tiles from url that is not under resources/charts API endpoint (#37)

To better support the use of multiple chart providers with the Signal K v2 Resources API, this PR moves the endpoint that serves tile images out from under the path /signalk/{v1 | v2}/api/resources/charts to /signalk/chart-tiles.

This provides more flexibility for chart providers and also moves the serving of tile images out from under the Resources API which is based on JSON formatted responses.

Author: panaaj

README.md

@@ -2,52 +2,74 @@
 
 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 |
 |--- |--- |--- |
 | 1.x.x | v1 | `/signalk/v1/api/resources/charts` |
 | 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.json

@@ -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.19.2",
-    "mocha": "5.0.0",
+    "express": "^4.19.2",
+    "mocha": "^11.7.1",
     "prettier": "^2.8.4",
     "typescript": "^4.5.4"
   }

src/charts.ts

@@ -80,13 +80,13 @@ function openMbtilesFile(file: string, filename: string) {
           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,11 +133,11 @@ function directoryToMapInfo(file: string, identifier: string) {
         ;(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: []
         }
 

src/index.ts

@@ -9,27 +9,19 @@ import { Request, Response, Application } from 'express'
 import { OutgoingHttpHeaders } from 'http'
 import {
   Plugin,
-  PluginServerApp,
+  ServerAPI,
   ResourceProviderRegistry
 } from '@signalk/server-api'
 
-const MIN_ZOOM = 1
-const MAX_ZOOM = 24
-
 interface Config {
   chartPaths: string[]
   onlineChartProviders: OnlineChartProvider[]
 }
 
 interface ChartProviderApp
-  extends PluginServerApp,
+  extends ServerAPI,
     ResourceProviderRegistry,
     Application {
-  statusMessage?: () => string
-  error: (msg: string) => void
-  debug: (...msg: unknown[]) => void
-  setPluginStatus: (pluginId: string, status?: string) => void
-  setPluginError: (pluginId: string, status?: string) => void
   config: {
     ssl: boolean
     configPath: string
@@ -38,6 +30,10 @@ interface ChartProviderApp
   }
 }
 
+const MIN_ZOOM = 1
+const MAX_ZOOM = 24
+const chartTilesPath = '/signalk/chart-tiles'
+
 module.exports = (app: ChartProviderApp): Plugin => {
   let chartProviders: { [key: string]: ChartProvider } = {}
   let pluginStarted = false
@@ -47,7 +43,9 @@ module.exports = (app: ChartProviderApp): Plugin => {
   }
   const configBasePath = app.config.configPath
   const defaultChartsPath = path.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 *******
@@ -99,7 +97,14 @@ module.exports = (app: ChartProviderApp): Plugin => {
               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.)'
             },
@@ -157,7 +162,7 @@ module.exports = (app: ChartProviderApp): Plugin => {
   }
 
   const doStartup = (config: Config) => {
-    app.debug('** loaded config: ', config)
+    app.debug(`** loaded config: ${config}`)
     props = { ...config }
 
     const chartPaths = _.isEmpty(props.chartPaths)
@@ -185,7 +190,7 @@ module.exports = (app: ChartProviderApp): Plugin => {
     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
@@ -214,7 +219,7 @@ module.exports = (app: ChartProviderApp): Plugin => {
     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]*)`,
+      `${chartTilesPath}/:identifier/:z([0-9]*)/:x([0-9]*)/:y([0-9]*)`,
       async (req: Request, res: Response) => {
         const { identifier, z, x, y } = req.params
         const provider = chartProviders[identifier]
@@ -286,15 +291,15 @@ module.exports = (app: ChartProviderApp): Plugin => {
           listResources: (params: {
             [key: string]: number | string | object | null
           }) => {
-            app.debug(`** listResources()`, params)
+            app.debug(`** listResources() ${params}`)
             return Promise.resolve(
               _.mapValues(chartProviders, (provider) =>
                 sanitizeProvider(provider, 2)
               )
             )
           },
           getResource: (id: string) => {
-            app.debug(`** getResource()`, id)
+            app.debug(`** getResource() ${id}`)
             const provider = chartProviders[id]
             if (provider) {
               return Promise.resolve(sanitizeProvider(provider, 2))
@@ -364,10 +369,10 @@ const sanitizeProvider = (provider: ChartProvider, version = 1) => {
   let v
   if (version === 1) {
     v = _.merge({}, provider.v1)
-    v.tilemapUrl = v.tilemapUrl.replace('~basePath~', 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~', apiRoutePrefix[2]) : ''
+    v.url = v.url ? v.url.replace('~tilePath~', chartTilesPath) : ''
   }
   provider = _.omit(provider, [
     '_filePath',

src/types.ts

@@ -1,4 +1,10 @@
-type MapSourceType = 'tilelayer' | 'S-57' | 'WMS' | 'WMTS' | 'mapstyleJSON' | 'tileJSON'
+type MapSourceType =
+  | 'tilelayer'
+  | 'S-57'
+  | 'WMS'
+  | 'WMTS'
+  | 'mapstyleJSON'
+  | 'tileJSON'
 
 export interface ChartProvider {
   _fileFormat?: 'mbtiles' | 'directory'
@@ -13,11 +19,11 @@ export interface ChartProvider {
   scale: number
   v1?: {
     tilemapUrl: string
-    chartLayers: string[]
+    chartLayers?: string[]
   }
   v2?: {
     url: string
-    layers: string[]
+    layers?: string[]
   }
   bounds?: number[]
   minzoom?: number

test/expected-charts.json

@@ -14,7 +14,7 @@
     "minzoom": 3,
     "name": "MBTILES_19",
     "scale": 250000,
-    "tilemapUrl": "/signalk/v1/api/resources/charts/test/{z}/{x}/{y}",
+    "tilemapUrl": "/signalk/chart-tiles/test/{z}/{x}/{y}",
     "type": "tilelayer"
   },
   "tms-tiles": {
@@ -32,7 +32,7 @@
     "minzoom": 4,
     "name": "Översikt Svenska Sjökort",
     "scale": 4000000,
-    "tilemapUrl": "/signalk/v1/api/resources/charts/tms-tiles/{z}/{x}/{y}",
+    "tilemapUrl": "/signalk/chart-tiles/tms-tiles/{z}/{x}/{y}",
     "type": "tilelayer"
   },
   "unpacked-tiles": {
@@ -50,7 +50,7 @@
     "minzoom": 3,
     "name": "NOAA MBTiles test file",
     "scale": 250000,
-    "tilemapUrl": "/signalk/v1/api/resources/charts/unpacked-tiles/{z}/{x}/{y}",
+    "tilemapUrl": "/signalk/chart-tiles/unpacked-tiles/{z}/{x}/{y}",
     "type": "tilelayer"
   }
 }