lukasappelhans/spam

A D3 library to create maps with Canvas

Spam is a small library to create modern Canvas maps with D3. It makes it easy to create static or zoomable maps with automatic projection and retina resolution.

Custom projections, click/hover events,d3.geo path generators and multiple map features are supported.

Check the API docs or continue reading for examples.

Introduction

When using Spam you are still in charge of painting everything. However the library creates the canvas boilerplate and tries to handle as much as possible without putting constraints on the user.

In order to improve performance, Spam uses two painting phases. The 'static' layer is created once (for every zoom level) and should contain the majority of operations. After these operations complete, the canvas is saved into a picture.

Now every time the canvas needs a repaint (e.g. for hover effects), Spam enters the 'dynamic' painting phase. Here we provide the option to draw dynamic content, while painting the 'static' image in the background.

In order to get the most out of Spam, we encourage you to think about which parts of your map are static and dynamic beforehand and then use the appropriate callbacks. The more code runs in the 'static' functions, the faster Spam will become.

Getting started

Spam depends on D3 and TopoJSON and it's available on npm and with a normal script tag.

If you use NPM, you can do npm install spamjs and include it in your project:

import Spam from "spamjs";

Otherwise, download the latest release and add a script tag in your site (don't forget to include D3 and TopoJSON).

<script src="https://d3js.org/d3.v5.min.js"></script>
<script src="https://d3js.org/topojson.v3.min.js"></script>
<script src="spam.js"></script>

Here's the most basic map you can do:

d3.json("map.json").then(d => {
  topojson.presimplify(d);

  const map = new Spam.StaticCanvasMap({
    element: "body",
    data: [
      {
        features: topojson.feature(d, d.objects["map"]),
        static: {
          paintfeature: parameters => {
            parameters.context.stroke();
          }
        }
      }
    ]
  });

  map.init();
});

And that's it! A simple, static map in just a few lines of code! It will be automagically projected and centered in your container, nothing else needed.

Examples

The best way to start making maps with Spam is reading the examples. You can use the same structure in your maps and fork them with your own TopoJSON.

• Basic static map
• Basic zoomable map
• Static map with labels
• Static data visualization
• Custom projection
• Canvas globe
• Static choropleth
• Zoomable choropleth

API

Check the API docs on the wiki for more information.

License

MIT © Lukas Appelhans, Martín González.