Skip to content
A D3 library to create maps with Canvas
JavaScript HTML
Branch: master
Clone or download
Latest commit 48cc0d3 May 26, 2017

README.md

spam

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, TopoJSON and rbush and it's available on npm (npm install spamjs, Browserify example), bower (bower install spam) and with a normal script tag.

Clone the repository (or download the zip) and include spam.js after D3, TopoJSON and rbush in your website.

<script src="//d3js.org/d3.v3.min.js"></script>
<script src="//d3js.org/topojson.v1.min.js"></script>
<script src="//cdn.rawgit.com/mourner/rbush/master/rbush.js"></script>
<script src="//cdn.rawgit.com/newsappsio/spam/master/spam.min.js"></script>

Here's the most basic map you can do:

d3.json("map.json", function(error, d) {
    topojson.presimplify(d)

    var map = new StaticCanvasMap({
        element: "body",
        data: [
            {
                features: topojson.feature(d, d.objects["map"]),
                static: {
                    paintfeature: function(parameters, d) {
                        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.

API

Check the API docs on the wiki for more information.

License

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

You can’t perform that action at this time.