npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

mapgl-tile-renderer

v1.1.1

Published

A tile renderer for Maplibre GL JS

Downloads

9

Readme

mapgl-tile-renderer

Publish to DockerHub

This headless Node.js MapGL renderer can be used to generate styled raster tiles in an MBTiles format. It can work with self-provided tilesets and a stylesheet, or an online API source with optional GeoJSON and OpenStreetMap data overlays.

The motivation to build this utility is to create offline background maps for use in mobile data collection applications, such as Mapeo and ODK Collect / KoboToolbox Collect, or other offline-compatible tools that can work with self-hosted maps like Terrastories. However, it can be helpful for any use case where having self-hosted raster MBTiles is a requirement.

This tool started as an extension of mbgl-renderer, which was built to export single static map images. Our thanks go out to the contributors of that project.

Usage

This tool can be used in the following ways:

  • Via CLI (npm, Node.js or Docker)
  • Using a Github template to generate tiles using a manifest.json.
  • As a task worker service to poll a queue for new requests.
    • Currently supported: Azure Storage Queue.
    • The tool may be extended with RabbitMQ for self-hosting in the future.

To install the tool using npm, run:

$ npm install -g mapgl-tile-renderer

Supported online API sources

❗️ To use these services, you are responsible for providing your own API token. In doing so, please carefully consult the terms of service and API limitations for each service.

Note that depending on your bounding box and maximum zoom level, this tool has the capability to send a lot of requests. You can use a utility like the Mapbox offline tile count estimator to ensure that your request will be reasonable, and in the case of any API sources with a freemium API limit, won't end up costing you.

CLI options

  • -s or --style: Specify the style source. Use "self" for a self-provided style or one of the following for an online source: "bing", "esri", "google", "mapbox", "mapbox-satellite", "planet", "protomaps"

If using a self-provided style (--style self):

  • --stylelocation: Location of your provided map style
  • --stylesources: Directory where any local source files (GeoJSON, XYZ directory, MBTiles) specified in your provided style are located

If using an online style (--style with any online style name):

  • -a or --overlay: (Optional) Provide a GeoJSON object for a feature layer to overlay on top of the online source
  • -k or --apikey: (Optional) API key that may be required for your online source

If using any of the imagery online styles ("bing", "esri", "google", "mapbox-satellite", or "planet"):

  • -O or --openstreetmap: (Optional) Overlay OSM vector data on top of your imagery. Currently mapped: hydrology, roads, and points of interest (with labels). This is a boolean variable; set to "true" if you want to use this.

If your style is mapbox:

  • -m or --mapboxstyle in the format <yourusername>/<styleid>

If your style is planet-monthly-visual:

  • -p or --monthyear: The month and year (in YYYY-MM format) of the Planet Monthly Visual Basemap to use

Common options:

  • -b or --bounds: Bounding box in WSEN format, comma separated (required)
  • -Z or --maxzoom: Maximum zoom level (required)
  • -z or --minzoom: Minimum zoom level (optional, 0 if not provided)
  • -r or --ratio: Output pixel ratio (optional, 1 if not provided)
  • -t or --tiletype: Output tile type (jpg, png, or webp) (optional, jpg if not provided)
  • -o or --outputdir: Output directory (optional, "outputs/" if not provided)
  • -f or --filename: Name of the output MBTiles file (optional, "output" if not provided)

CLI example usage

Using a self-provided style:

mapgl-tile-renderer --style self --stylelocation tests/fixtures/alert/style-with-geojson.json --stylesources tests/fixtures/alert/sources --bounds "-79,37,-77,38" -Z 8

From an online source (Bing), with OpenStreetMap data overlaid:

mapgl-tile-renderer --style bing --bounds "-79,37,-77,38" --openstreetmap true -Z 8 --apikey YOUR_API_KEY_HERE

From an online source (Mapbox):

mapgl-tile-renderer --style mapbox --mapboxstyle YOUR_USERNAME/YOUR_MAPBOX_STYLE_ID --apikey YOUR_API_KEY_HERE --bounds "-79,37,-77,38" -Z 8

From an online source (Planet):

mapgl-tile-renderer --style planet --monthyear 2013-12 --apikey YOUR_API_KEY_HERE --bounds "-54,3,-53,4" -Z 8

Online source (Esri) with GeoJSON overlay:

mapgl-tile-renderer --style esri --apikey YOUR_API_KEY_HERE --bounds "-54,3,-53,4" -Z 8 --overlay '{"type": "FeatureCollection", "features": [{"geometry": {"coordinates": [[[-54.25348208981326, 3.140689896338671], [-54.25348208981326, 3.140600064810259], [-54.253841415926914, 3.140600064810259], [-54.25348208981326, 3.140689896338671]]], "geodesic": false, "type": "Polygon"}, "id": "-603946+34961", "properties": {"month": "09", "year": "2023"}, "type": "Feature"}]}'

Inspect the outputs

Three easy ways to examine and inspect the MBTiles:

  1. Upload them to a Felt map.
  2. Use the mbview tool to view them in the browser.
  3. Load them in QGIS.

Formats other than MBTiles

In the future, we may decide to extend this tool to support creating raster tiles in a different format, such as PMTiles. However, for the time being, you can use tools like go-pmtiles to convert the MBTiles outputs generated by this tool.

Docker

To run the tool with Docker, run:

docker run -it --rm -v "$(pwd)":/app/outputs communityfirst/mapgl-tile-renderer --style "mapbox" --bounds "-79,37,-77,38" -Z 8 --mapboxstyle YOUR_USERNAME/YOUR_MAPBOX_STYLE_ID --apikey YOUR_API_KEY_HERE

This automatically pulls the latest image from Docker hub. The docker run command is used to execute the mapgl-tile-renderer tool with a set of options that define how the map tiles will be rendered and saved. Here's a breakdown of the command and its variables:

  • -it: This option ensures that the Docker container runs in interactive mode, allowing you to interact with the command-line interface.
  • --rm: This option automatically removes the container when it exits, which helps to clean up and save disk space.
  • -v "$(pwd)":/app/outputs: This mounts the current working directory ($(pwd)) to the /app/outputs directory inside the container, allowing the container to write the output files to your local file system.
  • communityfirst/mapgl-tile-renderer: This is the name of the Docker image that contains the mapgl-tile-renderer tool. Make sure to replace the placeholder values with your actual information before running the command.

To run locally first build the Docker image:

docker build -t mapgl-tile-renderer .

Then run:

docker run -it --rm -v "$(pwd)":/app/outputs/ mapgl-tile-renderer --style "mapbox" --bounds "-79,37,-77,38" -Z 8 --mapboxstyle YOUR_USERNAME/YOUR_MAPBOX_STYLE_ID --apikey YOUR_API_KEY_HERE

Azure Storage Queue example usage

For Azure Storage Queue (and other queue services in the future), mapgl-tile-renderer expects a message with a JSON body, composed of the input options:

{
  "style": "bing",
  "apiKey": "bing-api-key",
  "bounds": "-79,37,-77,38",
  "minZoom": 0,
  "maxZoom": 8,
  "output": "bing"
}

For developers

Mapgl-tile-renderer uses Maplibre-GL Native to render tiles, Sharp to save them as an image, and Mapbox's mbtiles Node package to compile them into an MBTiles database (which is a SQLite file).

Node installation requirements

Node version: 18.17.0 to 20.x.x.

(Sharp requires 18.17.0 at minimum, and MapLibre Native is currently only supported on stable releases of Node, 20 being the latest)

Tests

To run tests and view coverage, run:

npm run test

To run tests that require a Mapbox or Planet access token, create a .env.test file and add MAPBOX_TOKEN, PLANET_TOKEN, and PROTOMAPS_TOKEN vars with your own token. (If not provided, tests requiring these will be skipped.)