SignalK Seamap Plugin

Global sea charts based on OSM/Gebco/Emod for SignalK with online and offline capabilities.

Note: This plugin is a work in progress — help and feedback are highly appreciated!

Overview

This plugin provides offline-first map tile serving for SignalK with intelligent fallback strategies. It supports both vector tiles (MVT/PBF) and raster tiles (PNG/JPEG/WebP) from multiple sources. This project is in alpha stage but should be functional.

Features

• Offline PMTiles Support: Download and serve map tiles from sector-based PMTiles archives
• Online Fallback: Automatically fetch tiles from remote sources when internet is available
• Smart Caching: Filesystem-based tile cache with 7-day retention
• Multiple Sources: Support for OSM, Seamap, Gebco, Emod, and Mapterhorn
• Tile Formats: Vector (MVT/PBF) and Raster (PNG, JPEG, WebP)
• Sprites & Glyphs: MapLibre GL compatible sprite sheets and font glyphs
• Custom Styles: MapLibre GL style definitions
• On-Demand Contour Lines: Dynamically generates contour and bathymetry lines with filesystem caching

Screenshots

Download Management Interface

The web application provides a user-friendly interface for managing PMTiles downloads and viewing offline-available regions.

Interactive Map Demo

The web application includes a basic MapLibre GL map that integrates all tile sources from this plugin combined with SignalK vessel data.

Architecture

File Structure

signalk-seamap-plugin/
├── index.js                # Plugin entry point and configuration
├── package.json            # NPM package configuration
├── openApi.json            # OpenAPI specification
├── src/
│   ├── tiles.js            # Tile serving with multi-strategy fallback
│   ├── pmtiles.js          # PMTiles download and sector management
│   ├── contours.js         # Contour line generation and processing
│   ├── soundings.js        # Depth sounding data handling
│   ├── styles.js           # MapLibre GL style serving
│   ├── sprites.js          # Sprite sheet serving
│   ├── glyphs.js           # Font glyph serving
│   └── maplibre-contour/   # MapLibre contour library
├── sprites/                # Sprite images and metadata
├── glyphs/                 # Font PBF files
├── styles/                 # Map style definitions
└── public/                 # Web interface for tile management

Installation

Prerequisites

The PMTiles CLI tool is required for downloading offline map sectors:

macOS:

brew install pmtiles

Linux:

# Download latest release from GitHub
wget https://github.com/protomaps/go-pmtiles/releases/latest/download/go-pmtiles_$(uname -s)_$(uname -m).tar.gz
tar -xzf go-pmtiles_*.tar.gz
sudo mv pmtiles /usr/local/bin/

Docker/Raspberry Pi:

# ARM64
wget https://github.com/protomaps/go-pmtiles/releases/latest/download/go-pmtiles_Linux_arm64.tar.gz
tar -xzf go-pmtiles_Linux_arm64.tar.gz
sudo mv pmtiles /usr/local/bin/

Verify installation:

pmtiles --version

Plugin Installation

Option 1: Via npm (Recommended)

cd ~/.signalk
npm install signalk-seamap-plugin

Option 2: Via SignalK App Store Search for "Seamap Charts" in the SignalK plugin manager.

Option 3: Manual Installation

cd ~/.signalk/node_modules
git clone https://github.com/maptoolkit/signalk-seamap-plugin.git
cd signalk-seamap-plugin
npm install

Configuration

The plugin can be configured through SignalK's plugin configuration interface:

{
  pmtilesPath: '/path/to/pmtiles',           // Offline PMTiles storage (default: ~/.signalk/seamap/pmtiles)
  stylesPath: '/path/to/styles',             // MapLibre GL stylesheets (default: ~/.signalk/seamap/styles)
  tilesPath: '/path/to/tiles-cache',         // Tile cache directory (default: ~/.signalk/seamap/tiles)
  bathymetryDepthLevels: '2,5,10,20,50'      // Comma-separated depth levels for bathymetry contours (default: '2,5,10,20,50')
}

---

Tile Serving

Multi-Strategy Tile Retrieval

The plugin implements a multi-tier fallback strategy to ensure tiles are always available when possible:

1. Check File Cache & Offline PMTiles
   - Cached tile (if exists and < 7 days old)
   - Offline PMTiles sector (if newer than cache)
   ↓ (if not found or older than 7 days)

2. Online Fetch (if internet available)
   - Fetch from online PMTiles archive via HTTP Range requests
   - Save to file cache for future use
   ↓ (if not available or fails)

3. Return 204 No Content

Strategy Details

1. File Cache Check

• Location: {tilesPath}/tiles/{source}/{z}/{x}/{y}
• Example: ~/.signalk/seamap/tiles/tiles/osm/8/132/88
• Used when: Cached file exists and is fresher than 7 days old
• Contains tiles previously fetched from online or offline PMTiles
• Includes modification timestamp for age comparison

How it works:

1. Check if cached tile file exists
2. Compare file modification time with current time
3. If file exists and is less than 7 days old, serve from cache
4. Cache is organized by source and tile coordinates

2. Offline PMTiles Sectors

• Location: {pmtilesPath}/{z6}_{x6}_{y6}/{source}.pmtiles
• Example: ~/.signalk/seamap/pmtiles/6_33_22/osm.pmtiles
• Tile coordinates are automatically reduced from requested zoom to zoom level 6 to locate the correct PMTiles archive
• Used when: PMTiles file exists and is newer than cached file

How it works: When you request tile 8/132/88, the system:

1. Calculates parent tile at zoom 6: 6/33/22
2. Looks for {pmtilesPath}/6_33_22/osm.pmtiles
3. Compares PMTiles file timestamp with cached tile timestamp
4. Serves the newest version from either cache

3. Online Fetch

• Only attempted when: Cache and offline PMTiles are older than 7 days OR not found
• Connectivity check: System checks internet availability every 10 seconds
• Fetches directly from source PMTiles URL using HTTP Range requests
• Downloads only the requested tile, not the entire archive
• Automatically saves to file cache with current timestamp

Tile Cache Directory

Tiles are cached in the filesystem using the directory specified in plugin options. The filesystem-based approach was chosen because SQLite databases continuously grow with every insert/update operation. Running VACUUM operations to reclaim space is computationally expensive on embedded systems.

API Endpoints

Overview of API endpoints for MapLibre sources:

Complete API documentation available in openApi.json

Styles & Assets

• GET /styles/{name}.json - MapLibre GL styles
• GET /sprites/{name}.json|.png|@2x.json|@2x.png - Sprite sheets
• GET /glyphs/{fontstack}/{range}.pbf - Font glyphs

Available Sources: seamap, osm, mapterhorn, gebco, emod

Tiles

• GET /tiles/{name}.json - TileJSON metadata
• GET /tiles/{name}/{z}/{x}/{y}.{format} - Map tiles (pbf, webp)

Contours & Bathymetry Tiles

• GET /contours/{name}.json - Contour lines TileJSON
• GET /contours/{name}/{z}/{x}/{y}.pbf - Contour tiles
• GET /bathymetry/{name}.json - Bathymetry TileJSON
• GET /bathymetry/{name}/{z}/{x}/{y}.pbf - Bathymetry tiles
• GET /soundings/{name}.json - Soundings TileJSON
• GET /soundings/{name}/{z}/{x}/{y}.pbf - Soundings tiles

---

PMTiles Management

Sector-Based Download System

Instead of downloading entire global PMTiles archives (hundreds of GB), the plugin downloads only specific geographic sectors at zoom level 6.

Why Zoom Level 6?

• Balances coverage area and file size
• Each ZL6 tile covers approximately 350km × 350km at the equator
• Typical sector download size: 50-1000 MB
• Enables efficient offline operation for specific regions

Available Sources

Source	Type	Description	Max Zoom
mapterhorn	Vector	Global basemap	10
osm	Vector	OpenStreetMap features	14
seamap	Vector	Nautical chart data	14
gebco	Raster	Bathymetry (ocean depth)	14
emod	Raster	European bathymetry	14

Download Process

The download is done via the pmtiles cmdline utility. This commandline utility is not part of this plugin, and has to be installed separately.

Installing PMTiles CLI

macOS:

brew install pmtiles

Linux:

# Download latest release from GitHub
wget https://github.com/protomaps/go-pmtiles/releases/latest/download/go-pmtiles_$(uname -s)_$(uname -m).tar.gz
tar -xzf go-pmtiles_*.tar.gz
sudo mv pmtiles /usr/local/bin/

Docker/Raspberry Pi (ARM64):

wget https://github.com/protomaps/go-pmtiles/releases/latest/download/go-pmtiles_Linux_arm64.tar.gz
tar -xzf go-pmtiles_Linux_arm64.tar.gz
sudo mv pmtiles /usr/local/bin/

Verify installation:

pmtiles --version

Styles

MapLibre GL Style Serving

Serves complete MapLibre GL style definitions for rendering maps.

Directory: styles/

Example:

GET /styles/seamap.json

Features:

• Complete style definitions referencing local tile sources
• Sprite and glyph URL templates
• Layer styling for map rendering
• 24-hour cache headers for performance

---

Sprites

Directory: sprites/

Provides sprite sheets for map icons and symbols in MapLibre GL format.

Glyphs

Directory: glyphs/

Currently only Noto Sans fonts are included with this plugin.

Credits

• Maptoolkit.net - For supporting this project and providing hardware resources
• PMTiles - Cloud-optimized tile archives
• MapLibre GL - Open-source map rendering
• OpenStreetMap - Map data
• GEBCO - Bathymetry data