Mappa is a library to facilitate work between the <canvas> element and existing map libraries and APIs. It provides a set of tools for working with static maps, interactive tile maps and geo-data among other tools useful when building geolocation-based visual representations. Mappa was originally designed for p5.js, but it can be used with plain javascript or with other libraries that use the canvas element as the render object.

Download the full, minified or use the online version and add it to the head section of the document. Mappa will automatically load the required map libraries when necessary.

<script src="mappa.min.js" type="text/javascript"></script>

or

<script src="https://unpkg.com/mappa-mundi/dist/mappa.min.js" type="text/javascript"></script>

If you are using npm:

npm install mappa-mundi

Then create a new Mappa instance with your preferred map provider.

// API key for map provider.
var key = 'abcd'

// Create a new Mappa instance.
var mappa = new Mappa('Map-Provider', key);

Check this guide to learn how to get an API and set proper permission depending on your map provider.

For static maps, Google Maps Static API, Mapbox Static API and Mapquest Static API are supported.

For tile maps, Google Maps, Mapbox, Mapbox-GL, Mapzen, Tangram and Leaflet are supported.

Not sure what map provider to use? Check out this guide to picking a map library.

If you are new to maps, check out this basic tutorial and this glossary of terms.

// Your Mapboxgl API Key
var key = 'abcd'

// Create a new Mappa instance using Mapboxgl.
var mappa = new Mappa('Mapboxgl', key);
var myMap;
var canvas;

function setup(){
  canvas = createCanvas(640,640);
  myMap = mappa.tileMap(0,0,4); // lat 0, lng 0, zoom 4
  myMap.overlay(canvas)
}

function draw(){
  ...
}

All of the following examples are visualizing the 5000 largest meteorite landings in the world. Data from NASA's Open Data Portal.

• Static Maps

  • Google Maps (Code | Live Demo)
  • Mapbox (Code | Live Demo)
  • Mapquest (Code | Live Demo)

• Tile Maps

  • Google Maps (Code | Live Demo)
  • Mapbox (Code | Live Demo)
  • Mapbox Gl (Code | Live Demo)
  • Mapzen (Code | Live Demo)
  • Tangram (Code | Live Demo)
  • Leaflet (Code | Live Demo)
  • Using p5 in WEBGL mode (Code | Live Demo)
  • Using Three.js (Code | Live Demo)
  • Raw Canvas (Code | Live Demo)

• Basics (Tutorial | Live Demo)
• Zipdecode (Tutorial | Live Demo)
• Zipdecode with Tiles (Tutorial | Live Demo)
• Taxi Routes (Tutorial | Live Demo)
• Animated Meteorite Landings (Tutorial | Live Demo)
• CO2 Pollution Map (Tutorial | Live Demo)

• Mappa()
• staticMap()
• tileMap()
• overlay()
• latLngToPixel()
• pixelToLatlng()
• zoom()
• onChange()
• geoJSON()

Constructor to initialize a new Mappa instance with a defined provider and key. Returns an object.

This is the constructor necessary to create a valid instance of Mappa. This will also add the necessary scripts and styles from the defined map provider.

Examples:

// Google API key.
var key = 'abcd'

// Create a new Mappa instance using Google.
var mappa = new Mappa('Google', key);

// Create a new Mappa instance with Leaflet. No key is required
var mappa = new Mappa('Leaflet');

Options for providers:

• Static Maps:

  • Google
  • Mapbox
  • Mapquest

• Tile Maps:

  • Google
  • Mapbox
  • Mapboxgl
  • Mapzen
  • Tangram
  • Leaflet

Alternatively, you can add any maps provider libraries manually. Just add an id with the name of the library to the script tag:

  <script id="Leaflet" src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
  <link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css">

  <script src="mappa.js"></script>

Creates a static map image with the provided parameters. Returns an object.

Mappa provides a simple interface when working with static maps. It currently supports Google Maps Static API v2, Mapbox Static API v1 and Mapquest Static API v5.

staticMap(lat, lng, zoom, width, height, [optional]) or staticMap(parameters)

Examples:

// Create an image of New York of 500x500 with a zoom level of 10.
var myMap = mappa.staticMap(40.782, -73.967, 10, 500, 500)

var options = {
  lat: 40.782,
  lng: -73.967,
  zoom: 10,
  width: 500,
  height: 500
}
// Create an image of New York of 500x500 with a zoom level of 10.
var myMap = mappa.staticMap(options)

The resulting URL of the image will be stored inside the imgUrl value of the myMap variable. To load the image in p5 use loadImage() in preload() as with any other p5 image:

var img;

function preload(){
  img = loadImage(myMap.imgUrl);
}

Required parameters:

• lat: latitude for the center of the image.
• lng: longitude for the center of the image.
• zoom: zoom of the image. Min 1. Max 16.
• width: width in pixels.
• height: height in pixels.

Optional:

• Google:
  • scale: number of pixels returned. Defaults to 1.
  • format: gif, png or jpg. Defaults to png.
  • language: language of the map. Defaults to english.
  • maptype: Type of map used. Defaults to roadmap.

For a complete reference visit Google Maps Static API Documentation.

• Mapbox:
  • scale: number of pixels returned. Defaults to 1.
  • pitch: tilts the map. Defaults to 0.
  • bearing: rotates the map around its center. Defaults to 0.
  • style: mapbox styles. default to satellite-streets-v10.
  • attribution: boolean value to show map attribution. Defaults to true.
  • logo: boolean value to show mapbox logo on the image; defaults to true.

For a complete reference visit Mapbox Static API Documentation.

• Mapquest:
  • scale: number of pixels returned. Defaults to 1.
  • type: Type of map used. Defaults to hyb.
  • scalebar: boolean value to show a scale. Defaults to false.
  • traffic: boolena to show traffic flow. Defaults to false.
  • banner: add a custom banner.

For a complete reference visit Mapquest Static API Documentation.

// Your Google Maps API Key
var key = 'abcd'

// Create a new Mappa instance using Google.
var mappa = new Mappa('Google', key);

// Map options
var options = {
  lat: -26.658045,
  lng: -68.512952,
  zoom: 10,
  width: 640,
  height: 640,
  scale: 1,
  format: 'PNG',
  language: 'en',
  maptype: 'satellite'
}
var img;

// Create a map image of the Chilean Dessert
var myMap = mappa.staticMap(options);

// Load the image from the mappa instance as any other p5 image.
function preload(){
  img = loadImage(myMap.imgUrl);
}

function setup(){
  createCanvas(640,640);
  image(img, 0, 0);
}

This will render the following image:

Here are more complete examples when working with Google Maps, Mapbox and Mapquest.

Creates a tile map with the provided parameters. This method needs to be called inside setup(). It needs to be used together with overlay() to display a map.

Mappa allows to overlay a canvas element in top of tile maps. This is useful for interactive geolocation-based visual sketches. It currently supports Google Maps v3.28, Mapbox v3.1.1, Mapbox-GL v0.37.0, Mapzen v0.12.5 and Tangram v0.12.5 as map providers. It also supports Leaflet v1.0.3 with any custom set of tiles. tileMap() will only create the reference to a tile map. In order to visualize the map, overlay() must be used.

tileMap(lat, lng, zoom, [optional]) or tileMap(parameters)

Examples:

var canvas;
var myMap;

function setup(){
  canvas = createCanvas(800, 700);
  // Create a tile map centered in New York with an initial zoom level of 10.
  myMap = mappa.tileMap(40.782, -73.967, 10);
}

var canvas;
var myMap;

var options = {
  lat: 40.782,
  lng: -73.967,
  zoom: 10,
}
function setup(){
  canvas = createCanvas(800, 700);
  // Create a tile map centered in New York with an initial zoom level of 10.
  myMap = mappa.tileMap(options)
}

Required parameters:

• lat: initial center latitude of the map.
• lng: initial center longitude of the map.
• zoom: initial zoom of map. Min: 1 - Max: 16.

Optional:

• Google:

  • mapTypeId: type of map. Defaults to terrain.
  • styles: custom map styles. See Google Maps Style Reference.

  For a complete reference visit Google Maps Documentation.

• Mapbox:

  • studio: boolean to set if the custom style where made in Mapbox Studio. Defaults to false.
  • style: map style. Defaults to mapbox.satellite. If studio is set to true you can use styles like this 'mapbox://styles/username/mapid' to use Mapbox Studio styles.

  For a complete reference visit Mapbox Documentation.

• Mapbox-GL:

  • style: map style. Defaults to mapbox://styles/mapbox/satellite-streets-v10.
  • minZoom: map min zoom. Defaults to 0.
  • maxZoom: map max zoom. Defaults to 22.
  • bearing: rotation of the map around its center. Defaults to 0.
  • pitch: tilts the map. Defaults to 0.
  • renderWorldCopies: render multiple copies of the map. Defaults to true.
  • maxBounds: maps max bounds. Defaults to undefined.

  For a complete reference visit Mapbox GL Documentation.

• Mapzen:

  • BasemapStyles: boolean to set the use of custom Tangram Play styles. Defaults to false.
  • scene: custom style. Defaults to tron. Use BasemapStyles as true to set a scene as a .yaml file.

  For a complete reference visit Mapzen Documentation.

• Tangram:

  • scene: File to load scene in .yaml format.

  For a complete reference visit Tangram Documentation.

• Leaflet:

  • style: tile style to be used. Defaults to http://{s}.tile.osm.org/{z}/{x}/{y}.png.

Overlays a canvas to a tile map. This method needs to be called inside setup(). It needs to be used together with tileMap() to display a map.

This method will actually create the tile map referenced in tileMap() and overlay the selected canvas on top of it, allowing to control and move the map while maintaining the canvas position and relationship. The tile map generated is a separate DOM element that is displayed behind the canvas and is the same size of the canvas.

Since this map has no relationship with the elements drawn on the canvas, no background color needs to be used in the sketch in order to see the map. Alternatively, using p5 clear() function in the draw() method will allow to clear the canvas each frame. This is useful when displaying geolocated elements and moving the map.

apennd(canvas)

Example:

var canvas;
var myMap;

function setup(){
  canvas = createCanvas(800, 700);
  // Create a tile map center in New York with an initial zoom level of 10.
  myMap = mappa.tileMap(40.782, -73.967, 10);
  // Overlay the canvas to the new tile map created.
  myMap.overlay(canvas);
}

Once overlay() is used, a complete access to the base map library and its original properties and methods can be found in the map method. This allows to call any of the maps original properties or methods.

For example, calling flyTo in a Leaflet Map:

myMap.map.flyTo([-33.448890, -70.669265], 9)

// Your Mapboxgl API Key
var key = 'abcd'

// Create a new Mappa instance using Mapboxgl.
var mappa = new Mappa('Mapboxgl', key);
var myMap;
var canvas;

// Map options
var options = {
  lat: 40.782,
  lng: -73.967,
  zoom: 4,
  style: 'mapbox://styles/mapbox/dark-v9'
}

function setup(){
  canvas = createCanvas(800, 700);
  // Create a tile map centered in New York with an initial zoom level of 4.
  myMap = mappa.tileMap(options);
  // Overlay the tile map to the p5 canvas. This will display the map.
  myMap.overlay(canvas);
}

function draw(){
  // Clear the background so the map is clearly seen at each frame.
  clear();
  ellipse(mouseX, mouseY, 40, 40);
}

This will render the following sketch:

Get pixel position (x,y) for latitude and longitude coordinates. Returns an object with x and y position.

This method allows to get the pixel position of latitude and longitude coordinates in relationship to a staticMap() or a tileMap(). The pixel position will be stored as x and y.

latLngToPixel(lat, lng)

Example:

// Get the pixel position for Central Park.
var pos = myMap.latLngToPixel(40.782, -73.967);
// Draw an ellipse using pos
ellipse(pos.x, pos.y, 10, 10);

See onChange() for a Complete Example.

Get the latitude and longitude coordinates for a (x,y) pixel position. Returns an object with lat and lng.

pixelToLatlng(x, y)

This method returns the latitude and longitude of a point in the canvas in reference of a tileMap().

Example:

if (mouseIsPressed) {
  // Store the current latitude and longitude of the mouse position
  var position = myMap.pixelToLatlng(mouseX, mouseY);
}

// Your Google Maps API Key
var key = 'abcd'

var options = {
  lat: 36.964241,
  lng: -122.013963,
  zoom: 18,
}

// Create a new Mappa instance using Google.
var mappa = new Mappa('Google', key);
var myMap;

var canvas;
var points = []

function setup(){
  canvas = createCanvas(800, 700);
  myMap = mappa.tileMap(options);
  myMap.overlay(canvas);
  noFill();
  stroke('#08306b');
}

function draw(){
  clear();

  // Draw a line using latLngToPixel() with all the points in the points array.
  beginShape();
  for(var i = 0; i < points.length; i++){
    var pos = myMap.latLngToPixel(points[i])
    vertex(pos.x, pos.y);
  }
  endShape();

  // If the mouse right button is pressed, store the current mouse position in an array of points.
  if (mouseIsPressed) {
    if (mouseButton == RIGHT){
      var point = myMap.pixelToLatlng(mouseX, mouseY);
      points.push(point)
    }
  }
}

This will render the following sketch:

Get the map current zoom level. Returns a number.

This method allows to get a tileMap() current zoom level.

zoom()

Example:

// Get the pixel position for Central Park.
var zoom = myMap.zoom();
// Change the size of an ellipse depending on the map zoom.
ellipse(20, 20 , zoom, zoom);

Executes a function only when the map changes (ie: zoom, panned, flyTo or moved). Useful when visualizing lots of data points.

This method allows to trigger a function whenever a tileMap() has been moved or scaled. This is useful to redraw things on the canvas only when it is necessary (the map has changed) and not every frame.

onChange(myFunction)

Example:

function setup(){
  canvas = createCanvas(800, 700);
  myMap = mappa.tileMap(options);
  myMap.overlay(canvas);
  myMap.onChange(myCustomFunction);
}

// Your Google Maps API Key
var key = 'abcd'

var options = {
  lat: 40.7828647,
  lng: -73.9675438,
  zoom: 4,
  mapTypeId: 'satellite'
}

var colors = ['#fff5f0','#fee0d2','#fcbba1','#fc9272','#fb6a4a','#ef3b2c','#cb181d','#a50f15','#67000d'];

var mappa = new Mappa('Mapboxgl', key);
var myMap;

var canvas;
var dots;

function setup(){
  canvas = createCanvas(800, 700);
  myMap = mappa.tileMap(options);
  myMap.overlay(canvas);
  // Load a file with lat-lng coordinates.
  dots = loadStrings('../../data/dots.csv');
  myMap.onChange(circles);
}

function draw(){

}

function circles(){
  clear();
  var size = myMap.zoom() * 2;
  for (var i = 1; i < dots.length; i++) {
    var data = dots[i].split(/,/);
    fill(random(colors))
    var pos = myMap.latLngToPixel(data[9], data[8]);
    ellipse(pos.x, pos.y, size, size);
  }
}

This will render the following sketch:

Parses a geoJSON file and store all coordinates in an array. Returns an array.

This method is useful when loading GeoJSON files. It will return an array with the specified GeoJSON features. It can be used with staticMap() and tileMap().

Types of Feature:

• Point
• LineString
• Polygon
• MultiPoint
• MultiLineString
• MultiPolygon
• GeometryCollection

Example:

var data;
var polygons;

function preload(){
  // Load a GeoJSON file using p5 loadJSON.
  data = loadJSON('world.geojson');
}

function setup(){
  createCanvas(640, 640);
  // Store all Polygons features in an array called polygons.
  polygons = myMap.geoJSON(data, 'Polygon')
}

// Your Google Maps API Key
var key = 'abcd';

// Options for map
var options = {
  lat: 0,
  lng: 0,
  zoom: 2,
  width: 940,
  height: 800,
  scale: 1,
  format: 'PNG',
  language: 'en',
  maptype: 'satellite'
}

var colors = ["#fff7fb", "#ece7f2", "#d0d1e6", "#a6bddb", "#74a9cf", "#3690c0", "#0570b0", "#045a8d", "#023858"];

var mappa = new Mappa('Google', key);
var myMap = mappa.staticMap(options);

var data;
var polygons;
var multiPolygons;

function preload(){
  img = loadImage(myMap.imgUrl);
  // A geoJSON file with world coordinates for all countries.
  data = loadJSON('data/world.geojson');
}

function setup(){
  canvas = createCanvas(640, 640);
  // Load all polygons and multipolygons in a geoJSON file in two arrays.
  polygons = myMap.geoJSON(data, 'Polygon');
  multiPolygons = myMap.geoJSON(data, 'MultiPolygon');
  // Display the static map image.
  image(img, 0, 0);

  // For all polygons loop through the array and create a new Shape.
  for(var i = 0; i < polygons.length; i++){
    beginShape();
    fill(random(colors));
    for (var j = 0; j < polygons[i][0].length; j ++){
      var pos = myMap.latLngToPixel(polygons[i][0][j][1], polygons[i][0][j][0]);
      vertex(pos.x, pos.y);
    }
    endShape();
  }

// For all multiPolygons loop through the array and create a new Shape.
  for(var i = 0; i < multiPolygons.length; i++){
    for(var k = 0; k < multiPolygons[i].length; k++){
      beginShape();
      fill(random(colors));
      for (var j = 0; j < multiPolygons[i][k][0].length; j ++){
        var pos = myMap.latLngToPixel(multiPolygons[i][k][0][j][1], multiPolygons[i][k][0][j][0]);
        vertex(pos.x, pos.y);
      }
      endShape();
    }
  }

}

This will render the following sketch:

MIT