DEV Community: Olivia Guyot

Printing maps in the browser, a story

Olivia Guyot — Tue, 30 Mar 2021 12:54:41 +0000

An introduction

Maps are common on the web, whether interactive (think Google Maps) or static images. There are times though, when someone might need to transfer such a map into the real world. Yes, you guessed it! That is called printing.

To make this article more engaging, let us paint the scene of an imaginary situation: you are planning a hiking trip through Switzerland, and you want to print a map of the trails in a specific region. Being able to measure distances on paper is key, obviously.

Armed with courage and determination, you set out to print your own hiking map! And because you are not afraid of challenges, you are going to build a very simple web application to help you do that.

Some considerations on printed maps

Paper maps share a lot with their digital counterparts, and it would be tempting to just copy-paste or screenshot a map on the web and then simply put it in a word document, for instance. This approach works but has substantial limitations, and it all revolves around one thing...

The infamous DPI

DPI stands for dot per inch. A dot designates the smallest drawable unit, either ink (for printers) or pixel (for screens). A DPI value is a ratio that basically expresses how many small dots can be drawn inside an inch.

Higher means more detail, and it is generally assumed that a DPI value of 300 produces the best print quality you can expect. The DPI value of computer screens is usually much lower than 300 though, and there is no way to reliably know it beforehand.

As such, a copy-pasted image will inevitably look blurry once on paper. Besides, we will have no indication of scale.

Specialized software is here to help

There are a few dedicated software for printing high-definition maps, such as Mapfish Print which functions as a backend API. Given a data source, a geographic position, a scale, a paper size and DPI, Mapfish Print will generate a full PDF document (including legends!) and send it back to you. All good!

In this article though, we will take a closer look at inkmap, a library that generates printable maps all inside the browser, thus eliminating the need for remote APIs.

Now, let's get back on trail!

An application for printing hike trails (if you remember what hiking means anyway)

Before starting to write any kind of code, we need a data source, in this case: hike trails. Luckily for us, the Swiss federal topographic agency freely publishes this data online: Swisstopo tiled map services

We have everything we need, let's create the application!

General approach

We probably should not get too carried away and stick to a very simple concept: our application will only contain an interactive map and a "print" button. On the interactive map we will draw a rectangle representing the area that will be printed. And finally we will give the user the possibility to move and resize this area.

When the "print" button is clicked we will call inkmap's print method and eventually generate a ready-to-print PDF document. Easy!

First draft

I will not go into too much details regarding the application scaffolding, you can take a look at the final project here if you need inspiration.

To sum things up, you will need to initialize your project with npm and install Webpack and friends™ in order to setup the app:

$ npm init
$ npm install --save-dev webpack webpack-cli webpack-dev-server babel-loader @babel/core @babel/preset-env style-loader css-loader

The webpack configuration that I used is here.

Note that I would have preferred to use Parcel for bundling as it is much easier to setup, but unfortunately this will fail because of the dependencies used in the project

Next, add OpenLayers as a runtime dependency:

$ npm install --save ol

We are then going create two files in the project directory:

`index.html`

<!DOCTYPE html>
<html>
<head>
  <title>hiking trails map generator</title>
  <style>
      html {
          height: 100%;
      }
      body {
          height: 100%;
          margin: 0;
          background: #f6f6f6;
          display: flex;
          flex-direction: column;
          justify-content: center;
          align-items: center;
      }
      #map-root {
          width: 800px;
          height: 600px;
          margin-bottom: 20px;
          border-radius: 3px;
          border: 1px solid grey;
      }
  </style>
</head>
<body>
  <p>
    Use the map to select an area and click the button to print it.
  </p>
  <div id="map-root"></div>
  <button type="button" id="print-btn">Print</button>

  <!-- include the script at the end
       to make sure the page is loaded -->
  <script src="./app.js"></script>
</body>
</html>

`app.js`

import { fromLonLat } from 'ol/proj';
import Map from 'ol/Map';
import View from 'ol/View';
import TileLayer from 'ol/layer/Tile';
import OSM from 'ol/source/OSM';

// imports the OL stylesheet for nicer buttons!
import 'ol/ol.css';

// compute the map center from longitude and latitude
const mapCenter = fromLonLat([8.32, 46.90]);

// a simple OpenStreetMap layer (for development purposes)
const osmLayer = new TileLayer({
  source: new OSM()
});

// create the interactive map
const map = new Map({
  target: 'map-root',
  view: new View({
    zoom: 7,
    center: mapCenter,
    constrainResolution: true
  }),
  layers: [osmLayer]
});

Now you should be able to run webpack serve --open and see your app magically appear in your browser!

It all happened so fast!

Behold! Interactivity.

Using the OpenLayers API we are going to add an object on the map, shaped as a rectangle that matches the aspect of DIN paper formats (you know, the A-series).

To make it easily modifiable we are going to use a wonderful extension library called ol-ext, and more specifically its Transform interaction. To install it:

$ npm install --save ol-ext

Finally, we will bind an event handler on the "print" button to output the rectangle coordinates (in preparation for what's next).

`app.js`

// add these at the top of the file
import VectorLayer from 'ol/layer/Vector';
import VectorSource from 'ol/source/Vector';
import Feature from 'ol/Feature';
import { Polygon } from 'ol/geom';
import { always as conditionAlways } from 'ol/events/condition';
import TransformInteraction from 'ol-ext/interaction/Transform';

// ...

// our rectangle (width to height ratio is √2
// as per DIN paper formats)
const rectWidth = 100000;
const rectHeight = rectWidth / Math.sqrt(2);
const rectangle = new Feature({
  geometry: new Polygon([[
    [mapCenter[0] - rectWidth, mapCenter[1] + rectHeight],
    [mapCenter[0] + rectWidth, mapCenter[1] + rectHeight],
    [mapCenter[0] + rectWidth, mapCenter[1] - rectHeight],
    [mapCenter[0] - rectWidth, mapCenter[1] - rectHeight],
  ]])
});

// this vector layer will contain our rectangle
const vectorLayer = new VectorLayer({
  source: new VectorSource({
    features: [rectangle]
  })
});

// this will give the user the possibility to move the
// rectangle around and resize it by dragging its corners
const transform = new TransformInteraction({
  layers: vectorLayer,
  stretch: false,
  keepAspectRatio: conditionAlways,
  rotate: false
});

// create the interactive map
const map = new Map({
  // ...
  layers: [osmLayer, vectorLayer]
});

map.addInteraction(transform);

// bind the print button click handler
document.getElementById('print-btn')
  .addEventListener('click', () => {
    const rectangleCoords = JSON.stringify(
      rectangle.getGeometry().getCoordinates()
    );
    console.log(rectangleCoords);
  });

Great! If everything went right you should be able to move the rectangle around and, when clicking "Print", you should see the modified coordinates appear in the console.

Did I just play with this for 10 minutes?

Note that these coordinates are expressed in Web Mercator projection and will have to be translated to latitude and longitude values later on.

Here comes the tricky part: printing what's inside the rectangle.

Mild mathematics coming up

Time to install our printing companion, inkmap:

$ npm install --save @camptocamp/inkmap

inkmap offers a simple API in the form of the print function, which needs a JSON spec to do its job. The JSON spec will look like this:

{
  "layers": [
    // a list of data sources
  ],
  "size": [
    // expected map size
  ],
  "center": [
    // map center as longitude, latitude
  ],
  "dpi": // ever heard about this one?
  "scale": // this is the scale denominator
  "projection": // the map projection to use
}

Let's create a new module for encapsulating the computations that will be needed to produce the spec. The module will expose a printAndDownload function which takes the rectangle geometry, triggers a print of the area and download the result automatically:

`print.js`

import { toLonLat } from "ol/proj";
import { getDistance } from "ol/sphere";
import { downloadBlob, print } from "@camptocamp/inkmap";

// more details on layers configuration later on
const bgLayer = {
  // ...
};

const trailsLayer = {
  // ..
};

/**
 * Requests a print from inkmap, download the resulting image
 * @param {Polygon} rectangleGeometry
 */
export function printAndDownload(rectangleGeometry) {
  // first get the geometry center in longitude/latitude
  const geomExtent = rectangleGeometry.getExtent();
  const center = toLonLat(
    rectangleGeometry.getInteriorPoint().getCoordinates()
  );

  // let's target a final format of A4:
  // the map will be 277 x 170 millimeters
  const size = [277, 170, 'mm'];

  // now the hard part: compute the scale denominator, which
  // is the ratio between the rectangle size in real world units
  // and the final printed size in the same units;
  // to do this we measure the width of the rectangle in
  // meters and compare it to the desired paper size
  const lowerLeft = toLonLat([geomExtent[0], geomExtent[1]]);
  const lowerRight = toLonLat([geomExtent[2], geomExtent[1]]);
  const geomWidthMeters = getDistance(lowerLeft, lowerRight);
  // paper size is in mm so we need to multiply by 1000!
  const scale = geomWidthMeters * 1000 / size[0];

  // let's print!
  print({
    layers: [bgLayer, trailsLayer],
    dpi: 150,
    size,
    center,
    scale,
    projection: 'EPSG:2056',
    scaleBar: true,
    northArrow: true
  }).then(imageBlob =>
    downloadBlob(imageBlob, 'hiking-trails.png')
  );
}

See how we computed the scale parameter of the spec sent to inkmap? This parameter is actually the scale denominator, in other words the ratio between the rectangle real world size (probably several hundred meters) and the final printed size (an A4 paper).

Once we have computed the scale, the rest is easy work. But, wait, haven't we missed something? Ah, yes, the layers! I have omitted them in the previous listing, let's talk about them now.

Configuring data sources

Swisstopo publish their geospatial data through several formats, including WMTS (Web Map Tile Service). This format is not very easy to work with but it allows us to query the data in a proper Swiss projection instead of the highly-distorting Web Mercator.

See the previous paragraph? We specified projection: 'EPSG:2056' in the print spec, just for that. inkmap will do the rest and download the projection definition on its own.

Configuring the layers is done like this:

`print.js`

// ...

// there are shared parameters for both layers
// including resolutions, tile grid origin and matrix set
const genericLayer = {
  type: 'WMTS',
  requestEncoding: 'REST',
  matrixSet: 'EPSG:2056',
  projection: 'EPSG:2056',
  tileGrid: {
    resolutions: [
      4000, 3750, 3500, 3250, 3000, 2750, 2500, 2250, 2000,
      1750, 1500, 1250, 1000, 750, 650, 500, 250, 100, 50, 20
    ],
    origin: [2420000, 1350000]
  },
  attribution: '© Swisstopo'
};

// use the parameters above and target a background layer
const bgLayer = {
  ...genericLayer,
  url: 'https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.pixelkarte-farbe/default/current/2056/{TileMatrix}/{TileCol}/{TileRow}.jpeg',
  opacity: 0.4,
};

// this targets specifically the hiking trails layer
const trailsLayer = {
  ...genericLayer,
  url: 'https://wmts.geo.admin.ch/1.0.0/ch.swisstopo.swisstlm3d-wanderwege/default/current/2056/{TileMatrix}/{TileCol}/{TileRow}.png',
};

// ...

WMTS layers need a proper tile grid configuration to be displayed correctly, including: an array of resolutions for each zoom level, a tile grid origin, a matrix set id, and sometimes other parameters. Setting this up is non trivial and for the purpose of this article I have gotten inspiration from existing examples (gotten from the geo.admin.ch API doc).

Binding it together

We're almost there! Let's use our shiny new printAndDownload function in the main module:

`app.js`

// add this import at the top
import { printAndDownload } from './print';

// ...

// bind the print button click handler
document.getElementById('print-btn')
  .addEventListener('click', () => {
    printAndDownload(rectangle.getGeometry());
  });

And now, back to the application. Nothing has changed visually, but if you click the "print" button and wait a few seconds... Bam! You received the printed map, which should look like this:

Spaghetti alla matriciana

Not very readable as it covers a large part of the country, but you can definitely select a smaller region and print it again! And lo and behold, in the lower left corner: a scale bar!!

Having an image is great but... could we maybe have an actual PDF document to print instead? That would be nice!

Finishing the job

To generate a PDF document we will bring in another runtime dependency (hopefully the last), jsPDF:

$ npm install --save jspdf

Let's use this new toy in the print module:

`print.js`

// add this import at the top
import { jsPDF } from "jspdf";

// ...

export function printAndDownload(rectangleGeometry) {

  // ...

  // let's print!
  print({
    // ...
  }).then(imageBlob => {
    // initializes the PDF document
    const doc = new jsPDF({
      orientation: 'landscape',
      unit: 'mm',
      format: 'a4',
      putOnlyUsedFonts: true,
    });

    // create an Object URL from the map image blob
    // and add it to the PDF
    const imgUrl = URL.createObjectURL(imageBlob);
    doc.addImage(imgUrl, 'JPEG', 10, 30, size[0], size[1]);

    // add a title
    doc.setFont('times', 'bold');
    doc.setFontSize(20);
    doc.text('This is going to be great.', 148.5, 15, null, null, 'center');

    // download the result
    doc.save('hiking-trails.pdf');
  });
}

Now you can click "print" and you will receive an actual PDF document!

Spoilt for choice.

The only thing left for you is to print this on an A4, pack up your bags and go wandering towards your destiny. Or... the nearest bus stop.

Conclusion

I hope this article made sense and that you had fun reading it and experimenting. Printing maps is not straightforward, but it all makes sense when using the right tools for the right job.

Also, all the software used in the article are opensource, so please don't hesitate to reach the communities and contribute if you feel like it! Even a well-written bug report helps a lot.

Note that the project showcased in the article can be found here, and it even has a live demo if you want to spoil yourself!

Thanks, happy coding!

Integrating an OpenLayers map in Vue.js, a step-by-step guide

Olivia Guyot — Tue, 08 Sep 2020 12:05:54 +0000

Cover art by Donato Giacola.

Introduction

Hi! Chances are, you have at least heard of Vue.js, the very popular frontend JavaScript framework. It has a reputation of being accessible, well documented and easily understandable.

On the other hand, you may or may not have heard about OpenLayers, one of the oldest web mapping libraries around. That’s OK, maps can be surprisingly complex at times and not everyone is eager to dive into this complexity when services like the Google Maps API make things much simpler. But keep in mind that there are many, many more things that a web mapping library can do for you besides showing a marker on a map!

Note that there are other similar libraries around (see this article for a quick tour). We will stick with OpenLayers since it offers the most possibilities in the long run.

In this article we will dive into how both Vue.js and OpenLayers work, and how to put an interactive map in a Vue app and make it actually useful! At the end of this article we will have built a simple geospatial object editor which will allow us to:

modify an object in GeoJSON format and see it appear on the map
edit an object geometry directly on the map

You can take a look at a running instance of the project here. Sources are available here.

Set up the application

There are already numerous tutorials on how to scaffold a Vue application out there, so we’re going to jump that part. Using the Vue CLI is very straightforward anyway, and calling vue create my-app will get you most of the way.

From now on let’s assume we have a simple application with the main page divided into three frames:

`App.vue`



<template>
  <div id="app">
    <div class="cell cell-map">
      Map
    </div>
    <div class="cell cell-edit">
      Edit
    </div>
    <div class="cell cell-inspect">
      Inspect
    </div>
  </div>
</template>

<script>
  export default {
    name: 'App'
  }
</script>

<style>
  html, body {
    height: 100%;
    margin: 0;
  }

  #app {
    font-family: Avenir, Helvetica, Arial, sans-serif;
    height: 100%;
    display: grid;
    grid-template-columns: 100vh;
    grid-auto-rows: 1fr;
    grid-gap: 1rem;
    padding: 1rem;
    box-sizing: border-box;
  }

  .cell {
    border-radius: 4px;
    background-color: lightgrey;
  }

  .cell-map {
    grid-column: 1;
    grid-row-start: 1;
    grid-row-end: 3;
  }

  .cell-edit {
    grid-column: 2;
    grid-row: 1;
  }

  .cell-inspect {
    grid-column: 2;
    grid-row: 2;
  }
</style>

The three frames are named Map, Edit and Inspect. Notice how we used CSS Grid to get the layout done? This is the result:

Nice! This is how we’ll proceed next: create the Map component, then the Edit one and finally the Inspect one.

Give me the map!

Let’s create a MapContainer component, and include it in the main app. This is where we will need OpenLayers, so remember to install it first:



npm install --save ol

Then create the Vue component:

`MapContainer.vue`



<template>
  <div ref="map-root"
       style="width: 100%; height: 100%">
  </div>
</template>

<script>
  import View from 'ol/View'
  import Map from 'ol/Map'
  import TileLayer from 'ol/layer/Tile'
  import OSM from 'ol/source/OSM'

  // importing the OpenLayers stylesheet is required for having
  // good looking buttons!
  import 'ol/ol.css'

  export default {
    name: 'MapContainer',
    components: {},
    props: {},
    mounted() {
      // this is where we create the OpenLayers map
      new Map({
        // the map will be created using the 'map-root' ref
        target: this.$refs['map-root'],
        layers: [
          // adding a background tiled layer
          new TileLayer({
            source: new OSM() // tiles are served by OpenStreetMap
          }),
        ],

        // the map view will initially show the whole world
        view: new View({
          zoom: 0,
          center: [0, 0],
          constrainResolution: true
        }),
      })
    },
  }
</script>

This is getting interesting. See, creating a map with OpenLayers isn’t done in one line: you have to give it one or several Layer objects and also assign it a View. Have you noticed the constrainResolution: true option for the map view? This simply is to make sure that the map zoom snaps at the correct levels to have the OSM tiles looking crisp (see the API doc for more info).

Also notice that we kept a reference to the map root using the ref Vue directive like so:



<div ref="map-root"

The Map constructor can either take a CSS selector or an actual HTML element, so we then just have to fetch the map root element using this.$refs['map-root'].

The result should look like this:

Ok, we have a map, it’s interactive, but there’s not much more to it. Well of course it contains the whole world, but apart from that… How about we add an object on it?

`MapContainer.vue`



<script>
  // ...

  // we’ll need these additional imports
  import VectorLayer from 'ol/layer/Vector'
  import VectorSource from 'ol/source/Vector'
  import GeoJSON from 'ol/format/GeoJSON'

  // this is a simple triangle over the atlantic ocean
  const data = {
    type: 'Feature',
    properties: {},
    geometry: {
      type: 'Polygon',
      coordinates: [
        [
          [
            -27.0703125,
            43.58039085560784
          ],
          [
            -28.125,
            23.563987128451217
          ],
          [
            -10.8984375,
            32.84267363195431
          ],
          [
            -27.0703125,
            43.58039085560784
          ]
        ]
      ]
    }
  };

  export default {
    // ...

    mounted() {
      // a feature (geospatial object) is created from the GeoJSON
      const feature = new GeoJSON().readFeature(data, {
        // this is required since GeoJSON uses latitude/longitude,
        // but the map is rendered using “Web Mercator”
        featureProjection: 'EPSG:3857'
      });

      // a new vector layer is created with the feature
      const vectorLayer = new VectorLayer({
        source: new VectorSource({
          features: [feature],
        }),
      })

      new Map({
        // ...
        layers: [
          new TileLayer({
            source: new OSM(),
          }),
          // the vector layer is added above the tiled OSM layer
          vectorLayer
        ],
        // ...
      })
    }
  }
</script>

Simple!

Modifying the object

The object we’re currently showing is expressed in GeoJSON. Good thing is, this format is easily edited by hand! Let’s create a new component for doing just that.

`Edit.vue`



<template>
  <textarea v-model="geojsonEdit"></textarea>
</template>

<script>
  export default {
    name: 'Edit',
    props: {
      geojson: Object
    },
    computed: {
      geojsonEdit: {
        set(value) {
          // when the text is modified, a `change` event is emitted
          // note: we’re emitting an object from a string
          this.$emit('change', JSON.parse(value))
        },
        get() {
          // the text content is taken from the `geojson` prop
          // note: we’re getting a string from an object
          return JSON.stringify(this.geojson, null, ' ')
        }
      }
    }
  }
</script>

<style>
  textarea {
    width: 100%;
    height: 100%;
    resize: none;
  }
</style>

This component takes a geojson prop as input, which will be the same as the one given to the MapContainer component.

OK, let's have a quick look at some Vue logic now.

The v-model="geojsonEdit" attribute in the component template is a Vue directive commonly used for form inputs. It defines a two-way data binding with the geojsonEdit local property, meaning any input by the user will be saved in the property and any change to the property will be reflected on the screen.

For this component to have any effect we want to inform the parent component whenever the GeoJSON text was modified. To do that, we'll dispatch an event, which is done in Vue like so:



this.$emit('change', JSON.parse(value))

Such an event can be captured in a parent component using the v-on directive:



v-on:change="doSomethingWithData($event)"

Note that v-on is useful for both custom-defined events and standard HTML5 events. Take a look at the Vue events guide for more details.

Now, how are we going to know when to emit that change event? The immediate response would be to set up a watcher on geojsonEdit and trigger an event whenever it changes.

In the code above we went with another solution: defining a computed property. Using a computed property is very helpful in this case as it allows us to specify two different behaviours (read and write) without resorting to watchers. This way, we simply have to emit the event on the set() method, and read from the input data on the get() method. As an added bonus, we're not maintaining any internal state on the component, which is always a good thing in the long run.

Let's get back on track now. The other components cannot yet handle an update of the spatial object as it’s currently hardcoded in the MapContainer component.

We're going to modify both the MapContainer as well the App components to handle varying data:

`MapContainer.vue`



<script>
  // ...

  export default {
    name: 'MapContainer',
    components: {},
    props: {
      // the GeoJSON data is now taken as an input
      geojson: Object
    },
    data: () => ({
      // store OL objects on the component instance
      olMap: null,
      vectorLayer: null
    }),
    mounted() {
      this.vectorLayer = new VectorLayer({
        source: new VectorSource({
          features: [], // the vector layer is now created empty
        }),
      })

      this.olMap = new Map({
        // ..
      })

      // we’re calling `updateSource` to show the object initially
      this.updateSource(this.geojson)
    },
    watch: {
      geojson(value) {
        // call `updateSource` whenever the input changes as well
        this.updateSource(value)
      }
    },
    methods: {
      // this will parse the input data and add it to the map
      updateSource(geojson) {
        const view = this.olMap.getView()
        const source = this.vectorLayer.getSource()

        const features = new GeoJSON({
          featureProjection: 'EPSG:3857',
        }).readFeatures(geojson)

        source.clear();
        source.addFeatures(features);

        // this zooms the view on the created object
        view.fit(source.getExtent())
      }
    }
  }
</script>

`App.vue`



<template>
  <div id="app">
    <div class="cell cell-map">
      <!-- the GeoJSON data is now given as input -->
      <MapContainer :geojson="geojson"></MapContainer>
    </div>
    <div class="cell cell-edit">
      <!-- update the app state on `change` events -->
      <Edit :geojson="geojson" v-on:change="geojson = $event">
      </Edit>
    </div>
    <div class="cell cell-inspect">
     Inspect
    </div>
  </div>
</template>

<script>
  import MapContainer from './components/MapContainer'
  import Edit from './components/Edit'
  export default {
    name: 'App',
    components: {
      Edit,
      MapContainer
    },
    data: () => ({
      // this is the initial GeoJSON data
      geojson: {
        type: 'Feature',
        properties: {},
        geometry: {
          type: 'Polygon',
          coordinates: [
            [
              [
                -27.0703125,
                43.58039085560784
              ],
              [
                -28.125,
                23.563987128451217
              ],
              [
                -10.8984375,
                32.84267363195431
              ],
              [
                -27.0703125,
                43.58039085560784
              ]
            ]
          ]
        }
      }
    })
  }
</script>

The modification to the App component was pretty straightforward. We’re really just storing the data on this level instead of on the MapContainer one, and passing it as input to the two child components.

As for MapContainer, the modification was a bit more involved but not by much: by watching the geojson input prop, we’re making sure the OpenLayers map stays in sync with the Vue component state.

The result should look like this:

As an added bonus, the map view now automatically zooms into the displayed object! But the best part is that if you change the GeoJSON definition on the right… the object is modified in real time! Pretty nice right?

Time for inspection

Spatial features often hold a series of so-called attributes, essentially key-value pairs. In GeoJSON you add some in the properties field of a feature. These are sometimes displayed on-screen (eg. labels) but often most of them are "hidden" and only shown in a tooltip or similar.

To push the exercise a bit further, let’s create a new Inspect component which will show all the attributes of the feature that’s currently beneath the pointer.

We’ll start by making it so that the MapContainer component emits a select event whenever a feature is found under the pointer:

`MapContainer.vue`



<script>
  // ...

  export default {
    // ...
    mounted() {
      // ...

      this.olMap = new Map({
        // ...
      })

      // this binds a callback to the `pointermove` event
      this.olMap.on('pointermove', (event) => {
        // will return the first feature under the pointer
        const hovered = this.olMap.forEachFeatureAtPixel(
          event.pixel,
          (feature) => feature
        )

        // emit a `select` event, either with a feature or without
        this.$emit('select', hovered)
      })

      this.updateSource(this.geojson)
    },
    // ...
  }
</script>

Again, we're emitting a custom event which will then be capture using v-on:select="..." on the parent component.

Also, we’re using the forEachFeatureAtPixel method for finding out features under the cursor, which looks for all features in any layer at a certain pixel, and applies the given callback for each of them. In this case we only want one feature, so we exit after the first match (since the callback (feature) => feature returns a truthy value).

We can then proceed to create the Inspect component, which will simply show all the feature’s attributes:

`Inspect.vue`



<template>
  <ul>
    <!-- loop on the feature’s attributes -->
    <li :key="prop" v-for="prop in props">
      <b>{{prop}}:</b> {{feature.get(prop)}}
    </li>
  </ul>
</template>

<script>
  import Feature from 'ol/Feature'
  export default {
    name: 'Inspect',
    props: {
      // the only input is an OpenLayers Feature instance
      feature: Feature
    },
    computed: {
      // this will return an empty array if no feature available
      props() {
        return this.feature
          ? this.feature
              .getKeys()
              .filter(key => key !== this.feature.getGeometryName())
          : []
      }
    }
  }
</script>

<style>
  ul {
    list-style: none;
  }
</style>

Notice the line this.feature.getKeys().filter(key => key !== this.feature.getGeometryName())? This will return the key of all the feature’s attributes, except the one that holds the geometry (because that would render things unreadable, you’re welcome to try). See the OpenLayers Feature API doc for more info.

Finally, let’s glue everything together in the App component:

`App.vue`



<template>
  <div id="app">
    <div class="cell cell-map">
      <!-- update app state when a feature is selected -->
      <MapContainer :geojson="geojson"
                    v-on:select="selected = $event">
      </MapContainer>
    </div>
    <div class="cell cell-edit">
      <Edit :geojson="geojson" v-on:change="geojson = $event">
      </Edit>
    </div>
    <div class="cell cell-inspect">
      <!-- give the selected feature as input -->
      <Inspect :feature="selected"></Inspect>
    </div>
  </div>
</template>

<script>
  import MapContainer from './components/MapContainer'
  import Edit from './components/Edit'
  import Inspect from './components/Inspect'

  export default {
    name: 'App',
    components: {
      Inspect,
      Edit,
      MapContainer
    },

    data: () => ({
      // the selected feature is part of the app state
      selected: undefined,
      geojson: {
        // ...
      }
    })
  }
</script>

Well, that’s pretty much it. Now hovering your cursor over a spatial object will give you the list of properties from that object:

You can try and add attributes to the GeoJSON object definition and see how they show up in the inspect frame!

If you want to, you can also try and copy-paste a GeoJSON file like this one (containing all countries with simplified shapes). After all, we’re not making any assumptions on what the GeoJSON data contains!

Note that there are optimizations to be made for better performance, especially making sure that the MapContainer component only emits an event when necessary (i.e. not emitting the same feature on every pointermove event).

Conclusion

Throughout this tutorial we managed to create a simple app that allows both editing and inspecting spatial objects. This wasn’t so hard considering we only needed three components, each of them with limited responsibility, and one root component for storing the application state.

Hopefully this helped shed some light both on some core Vue.js concepts, as well as OpenLayers ones.

You can take a look at the final source code here, which contains a few improvements over this tutorial.

I hope you enjoyed this tutorial, there are many other things we could do to expand on this basis, let me know if you have any ideas! Thanks for reading!

Dataviz with OpenLayers: let’s plot some graphs!

Olivia Guyot — Thu, 03 Sep 2020 14:01:17 +0000

Introduction

Web mapping is great because we get nice interactive maps, smoothly zooming in/out and showing us data with slick styling and interactivity.

Only sometimes just looking at the data is not enough: what is the point of staring at thousands of points spread on a map, without more ways of understanding what they mean? For instance, if these points each represent an event in time, maybe having a way to show only the ones in a given time range would be of interest… there you have it: dataviz comes into play!

What next?

Admittedly, this introduction was a bit over-simplistic. What is usually called dataviz may include many fields and questions, from data preparation and processing to final visualization.

In this article we will take a look at the Airship UI components made by Carto, and how to couple these to an OpenLayers map. More specifically, we will use a time series chart to explore a rich dataset of earthquakes in its temporal dimension.

This is what the chart looks like:

And a live example here: https://carto.com/developers/airship/examples/#example-time-series-bridge

As you can see, Carto did a pretty good job! The chart is nice and tidy, allows animating in time, selecting a range, etc. It is based on d3.js which we all know and love.

Now, Carto provides so-called bridge components to easily connect this kind of widget (which has absolutely no knowledge of any map) to a Mapbox-gl-js map as demonstrated in the live example above.

How awesome would it be to write our own bridge, for OpenLayers this time? Let me tell you: pretty damn awesome. And maybe less of a headache that you might think!

Start small… or not

Let's commit to a first achievable goal: set up a super simple OpenLayers map with a dataset of time stamped events in it, possibly a lot.

As always, setting up a Javascript application from scratch is boring at best, so I'm going to focus on the interesting bits from there on. As a rule of thumb, this is a quick recap of what was used for the project structure:

Building & bundling is done with Webpack and Babel (see the configuration here)
All code written in ES6 and formatted using Prettier
Local development made using webpack-dev-server

These are the three first files we need for the project:

`public/index.html`

<html>
<head>
  <title>OL Airship bridge test</title>
  <link href="https://fonts.googleapis.com/css?family=Open+Sans&display=swap" rel="stylesheet">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/openlayers/openlayers.github.io@master/en/v6.1.1/css/ol.css" type="text/css">
  <style>
    html, body {
      height: 100%;
      width: 100%;
      margin: 0;
      padding: 0;
      font-family: "Open Sans";
      font-size: 14px;
    }
    #map {
      position: absolute;
      width: 100%;
      height: 100%;
    }
  </style>
</head>
<body>
  <div id="map"></div>
  <script src="main.js"></script>
</body>
</html>

`src/app.js`

import Map from 'ol/Map'
import View from 'ol/View'
import TileLayer from 'ol/layer/Tile'
import XYZ from 'ol/source/XYZ'
import { fromLonLat } from 'ol/proj'

export function init() {
  const view = new View({
    center: fromLonLat([-122.297374, 37.355579]),
    zoom: 5.55,
  })
  const olMap = new Map({
    view,
    target: 'map',
    layers: [
      new TileLayer({
        source: new XYZ({
          urls: [
            'https://a.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png',
            'https://b.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png',
            'https://c.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png'
          ],
          crossOrigin: 'anonymous',
        }),
      })
    ],
  })
}

`src/index.js`

import { init } from './app'

window.addEventListener('load', init)

Simple enough! That should give us a simple interactive map centered on California (earthquakes, remember?) with a sweet grayscale base layer.

The perfect canvas!

Right, now let's put some data into this.

For the following part I took my inspiration from this live example by kepler.gl showing more than 50,000 earthquakes styled by magnitude in California. The dataset used in this map is quite rich so it will be a good opportunity to test the performance of our experiment. Also the example already showcases a time slider widget, we might compare it with the result we obtain eventually!

Ok, let's load the data, parse it (it's a CSV file) and put it in a vector layer:

`src/app.js`

// add import
import WebGLPointsLayer from 'ol/layer/WebGLPoints'

  // ...

  // create style & vector layer
  const layerStyle = {
    symbol: {
      symbolType: 'circle',
      size: [
        'interpolate',
        ['linear'],
        ['get', 'magnitude'],
        2.5, 4,
        5, 20,
      ],
      color: [
        'case',
        ['<', ['get', 'depth'], 0], 'rgb(223,22,172)',
        'rgb(223,113,7)',
      ],
      opacity: 0.5,
    }
  }
  const vectorLayer = new WebGLPointsLayer({
    source: new VectorSource({ attributions: 'USGS', }),
    style: layerStyle,
  })

  // ...

  // put it in the map
  const olMap = new Map({
    view,
    target: 'map',
    layers: [
      // ...
      vectorLayer
    ],
  })

  // ...

  // load CSV data & put features in the vector source
  fetch('https://raw.githubusercontent.com/uber-web/kepler.gl-data/master/earthquakes/data.csv')
    .then(response => response.text())
    .then(csv => {
      var features = []
      var prevIndex = csv.indexOf('\n') + 1 // scan past the header line
      var curIndex

      while ((curIndex = csv.indexOf('\n', prevIndex)) !== -1) {
        var line = csv.substr(prevIndex, curIndex - prevIndex).split(',')
        prevIndex = curIndex + 1

        var coords = fromLonLat([parseFloat(line[2]), parseFloat(line[1])])

        features.push(
          new Feature({
            date: new Date(line[0]),
            depth: parseInt(line[3]),
            magnitude: parseInt(line[4]),
            geometry: new Point(coords),
            eventId: parseInt(line[11]),
          })
        )
      }

      vectorLayer.getSource().addFeatures(features)
    })

The result should look like this:

That's a lot of earthquakes

A WebGL-accelerated vector layer with all points, nice! Notice how the layer has a style where the size varies according to magnitude, and a color which is violet in case the earthquake was recorded as "above ground" (i.e. depth below 0), which is most likely an artefact of the data.

To learn more about WebGL layers and their styles in OpenLayers, take a look at this example (these features are still experimental and not part of the official API yet).

To keep it short, let’s just say these styles are plain JSON objects which can contain expressions quite similar to the Mapbox Style Spec ones.

These expressions allow reading feature attributes, comparing values, interpolating between steps, etc. Quite powerful, but keep in mind they still are experimental and subject to change.

Next step: adding some widget!

Everybody loves aggregations

Airship UI components are available as WebComponents. Adding them to the project is straightforward in our case: we will simply add the necessary CSS and JS files in the HTML template.

Let’s modify our code to do just that:

`public/index.html`

<html>
<head>
  <title>OL Airship bridge test</title>
  ...
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-style/v2.1.1/airship.css">
  <script src="https://libs.cartocdn.com/airship-components/v2.1.1/airship.js"></script>
  <script src="https://libs.cartocdn.com/airship-bridge/v2.1.1/asbridge.js"></script>
  <style>
    html, body {
      height: 100%;
      width: 100%;
      margin: 0;
      padding: 0;
      font-family: "Open Sans";
      font-size: 14px;
    }
    #map {
      position: absolute;
      width: 100%;
      height: 100%;
    }
    /* new styling for the widget container */
    .dataviz-container {
      position: absolute;
      background-color: white;
      box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.11);
      right: 1.6em;
      bottom: 1.6em;
      padding: 0.8em;
      width: 40%;
    }
  </style>
</head>
<body>
  <div id="map"></div>
  <!-- this contains the dataviz widget and is styled to be positioned above the map -->
  <div class="dataviz-container">
    <!-- this is the Airship web component -->
    <as-time-series-widget
      animated
      responsive
      heading="Animation"
      time-format="%x"
    >
    </as-time-series-widget>
  </div>
  <script src="main.js"></script>
</body>
</html>

The widget should show up but be completely empty! That's OK, we haven't given it any data.

Its API reference is here. It actually works just like a histogram widget (reference here) but with added functionality.

A first step would be to give the widget some data on the features in the source, in the form of an array of objects looking like { start: startTime, end: endTime, value: amountOfFeatures }.

Let's create a new file with a utility to compute such data from a collection of features:

`src/aggregation.js`

/**
 * Generates a list of buckets describing the repartition of features.
 * @param {Feature[]} features
 * @param {string} attributeName
 * @param {number} bucketCount
 * @returns {{start: number, end: number, value: number}[]}
 */
export function generateBuckets(features, attributeName, bucketCount) {
  let buckets
  let min = Infinity
  let max = -Infinity
  for (let i = 0; i < features.length; i++) {
    const attr = features[i].get(attributeName)
    if (attr > max) max = attr.valueOf()
    if (attr < min) min = attr.valueOf()
  }
  buckets = new Array(bucketCount).fill(0).map((value, index, arr) => {
    const ratioStart = index / arr.length
    const ratioEnd = (index + 1) / arr.length
    return {
      start: ratioStart * (max - min) + min,
      end: ratioEnd * (max - min) + min,
      value: 0,
    }
  })

  // count features
  for (let i = 0; i < features.length; i++) {
    const attr = features[i].get(attributeName)
    for (let j = 0; j < buckets.length; j++) {
      if (attr >= buckets[j].start && attr <= buckets[j].end) {
        buckets[j].value++
        break
      }
    }
  }

  return buckets
}

And then use this handy tool right after the features get loaded:

`src/app.js`

import { generateBuckets } from './aggregation'

  // ...

  // reference the widget using a query
  const timeWidget = document.querySelector('as-time-series-widget')

  // load map data
  fetch('https://raw.githubusercontent.com/uber-web/kepler.gl-data/master/earthquakes/data.csv')
    .then(response => response.text())
    .then(csv => {

      // ...

      vectorLayer.getSource().addFeatures(features)

      // generate the widget data
      timeWidget.data = generateBuckets(features, 'date', 20)
    })

A wild chart appears

This widget does work well! For instance, selecting a time range is super easy, simply a matter of clicking and dragging on it:

How far we've come.

Hold on… Nothing on the map is happening on the map if I'm doing this!

That makes sense, we update the widget once with static data from the map but haven't really built a bridge per se: there is no interaction between the widget and the map.

Let's address this in the next section.

Bridging the gap

Now, what are our options for dynamically hiding/showing points based on the selected time range in the widget?

Adding/removing features in real time: considering how OpenLayers has to rebuild rendering buffers on each addition/deletion in the vector source, this would rapidly become impractical; besides, that would require to loop constantly on the features and recreate a new array, probably putting a lot of burden on the garbage collector. Clearly not the best way!
Changing the style of each feature to reflect their state: sadly, handling individual feature styles is not possible with the WebGL-accelerated layer; it would be possible with a standard vector layer, but this wouldn’t allow us to have smooth rendering of the points like we have now. Still not good!
Defining a filter expression on the points layer style to exclude features out of the range: that sounds better! Let’s try that.

Remember the style we gave initially to the points layer? We are going to use the variables and filter options to have a bit more control on it:

`src/app.js`

  const layerStyle = {
    // variables can be mutated by others!
    variables: {
      min: -Infinity,
      max: Infinity,
    },
    // if this resolves to false, the features are not drawn
    filter: ['between', ['get', 'date'], ['var', 'min'], ['var', 'max']],
    symbol: {
      // ...
    },
  }

Again, we are using expressions, this time the between operator which does pretty much what it says.

Notice how we use the get operator to read a feature attribute, but the var operator to read from the variables dictionary.

Now, mutating layerStyle.variables should update the points visibility while keeping good performance (i.e. not rebuilding rendering buffers).

`src/bridge.js`

import { generateBuckets } from './aggregation'
/**
 * @param {Map} map
 * @param {VectorSource} source
 * @param {TimeSeriesWidget} widget
 * @param {string} attributeName
 * @param {function(min, max):void} updateSelection
 */
export function bindMapToTimeWidget(map, source, widget, attributeName, updateSelection) {
  let playing = false
  let currentSelection = null

  widget.data = generateBuckets(source.getFeatures(), attributeName, 20)

  // bind time widget to layer style
  widget.addEventListener('selectionInput', event => {
    currentSelection = event.detail === null ? null : event.detail.selection
    if (currentSelection !== null) {
      updateSelection(currentSelection[0], currentSelection[1])
    } else {
      updateSelection(null, null)
    }
  })
}

This utility is super simple for now. It feeds the widget with the content of the vector source only once, and calls an updateSelection callback when the selected time range changes. Note that we take in a map argument which we don’t use yet… that will come later. We can the use this in our main file instead of generating the buckets ourselves:

`src/app.js`

import { bindMapToTimeWidget } from './bridge'

// ...

  // load map data
  fetch('https://raw.githubusercontent.com/uber-web/kepler.gl-data/master/earthquakes/data.csv')
    .then(response => response.text())
    .then(csv => {
      // ...

      vectorLayer.getSource().addFeatures(features)

      // we update the vector style variables on time selection change, and voila!
      bindMapToTimeWidget(
        olMap,
        vectorLayer.getSource(),
        timeWidget,
        'date',
        (min, max) => {
          layerStyle.variables.min = min || -Infinity
          layerStyle.variables.max = max || Infinity
          olMap.render()
        }
      )
    })

Sure enough, this is working fine!

Real-time filtering

Notice how we call olMap.render() after a time selection change? Without this, the map would not re-render automatically and nothing would update visually. See, OpenLayers does not redraw the map continuously: it only does so when the view is animating, or when something in the map changed (a source, a layer, etc.).

Our small app is now looking and feeling good, no one would deny that. Still, there is one step further we can take: updating the graph according to what is inside the viewport.

This is something commonly seen in dataviz applications, as using the viewport as a spatial filter is both intuitive and easily done. Only, recomputing the buckets 60 times per second and more importantly filtering out features out of view is going to be taxing on the CPU…

Fortunately, we have an amazing tool for that: WebWorkers.

Workers, unite!

This section is going to be the last and probably the most complex. For those who are not interested in this, I invite you to take a look at the final source code and the live example.

Back on track: WebWorkers are objects created with a given source code, which will run in a separate thread and as such not block the execution of the main thread. Both threads will communicate using messages. Simple!

Simple, only… we want a worker to compute the features in the current view extent as well as regenerate the graph buckets, but the worker will not have access to the vector source as it is part of the main thread! We will have to somehow transfer the features to the worker so that it has a mirror copy of the vector source in the map and use it for its computations.

OK, the first step is writing the worker code. This will not be that hard: the worker will expect two kinds of messages, either one containing a list of features (in GeoJSON) to initialize its internal collection, or one containing an extent to do its computations on. The first one will have a type property of 'features', and the second one 'buckets'.

`src/aggregation.worker.js`

import GeoJSON from 'ol/format/GeoJSON'
import VectorSource from 'ol/source/Vector'
import { generateBuckets } from './aggregation'

// this should be a mirror of the vector source in the main thread
let vectorSource = new VectorSource()

// this is used to decode the GeoJSON received from the main thread
const geojson = new GeoJSON({
  dataProjection: 'EPSG:4326',
  featureProjection: 'EPSG:4326',
})

self.onmessage = event => {
  const type = event.data.type
  const data = event.data

  switch (type) {
    case 'features':
      // here we’re simply filling our source with features
      vectorSource.addFeatures(geojson.readFeaturesFromObject(data.features))
      break
    case 'buckets':
      // this is the aggregation part: we’re looking for features
      // in the given extent and recomputing the buckets on these
      const features = vectorSource.getFeaturesInExtent(data.extent)
      const buckets = generateBuckets(features, data.attributeName, 20)

      // then we’re sending back the buckets to the main thread
      self.postMessage({
        type: 'buckets',
        buckets,
      })
      break
  }
}

Great! Let's modify our bridge utility a bit to leverage this obedient worker:

`src/bridge.js`

import { throttle } from 'throttle-debounce'
import AggregationWorker from './aggregation.worker'
import GeoJSON from 'ol/format/GeoJSON'
import { transformExtent } from 'ol/proj'

// used to encode features before sending them to the worker
const geojson = new GeoJSON({
  featureProjection: 'EPSG:3857',
  dataProjection: 'EPSG:4326',
})

/**
 * @param {Map} map
 * @param {VectorSource} source
 * @param {TimeSeriesWidget} widget
 * @param {string} attributeName
 * @param {function(min, max):void} updateSelection
 */
export function bindMapToTimeWidget(
  map,
  source,
  widget,
  attributeName,
  updateSelection
) {
  const worker = new AggregationWorker()

  // send full source content to worker
  worker.postMessage({
    type: 'features',
    features: geojson.writeFeaturesObject(source.getFeatures()),
  })

  // worker messages trigger a `message` event
  worker.addEventListener('message', event => {
    const type = event.data.type
    const data = event.data
    switch (type) {
      // the worker is sending us buckets! give them to the time series widget
      case 'buckets':
        widget.data = data.buckets
        if (!widget.backgroundData.length) {
          widget.backgroundData = widget.data
        }
    }
  })

  function updateTimeWidget() {
    worker.postMessage({
      type: 'buckets',
      extent: transformExtent(
        map.getView().calculateExtent(),
        'EPSG:3857',
        'EPSG:4326'
      ),
      attributeName: 'date',
    })
  }

  // do the initial computation
  updateTimeWidget()

  // on view change ask the worker to recompute the buckets
  // note: this is throttled so that the message is not be sent more that once every 500ms
  map
    .getView()
    .on(['change:center', 'change:resolution'], throttle(500, updateTimeWidget))

  let currentSelection = null

  // bind time widget to layer style
  widget.addEventListener('selectionInput', event => {
    currentSelection = event.detail === null ? null : event.detail.selection
    if (currentSelection !== null) {
      updateSelection(currentSelection[0], currentSelection[1])
    } else {
      updateSelection(null, null)
    }
  })
}

Easy enough! Now the graph updates in real time when the view changes, and with no locking (although the recomputation can take up to 300ms).

This was the plan all along

Notice how we have access to the worker class using import AggregationWorker from './aggregation.worker'? This is using a Webpack utility called worker-loader which hides a bit of the complexity from us. Behind the scenes, the worker code is actually squashed into a very long string (we could also compile it as a separate JS file but that may cause other issues). Then it is just a matter of calling const worker = new AggregationWorker() and the worker is up and running!

We could also have several identical workers organized in a pool and use a different one each time to prevent tasks stacking up in the worker thread.

Well, looking back at where we started, the result is not so bad,is it? Performance should be more than acceptable and the interactivity of the graph allows for interesting analysis.

Now, considering we could use these utilities for any kind of data source (well… provided it contains only points!), and with a bit more work on the styling, there sure are many possibilities to explore. Dataviz is also about being creative with the raw material and turning a big chunk of static data into a powerful interactive tool for analysis and decision making.

This is where this tutorial ends. Again, I invite you to take a look at the final source code and the live example which contains a bit more than what we have seen here, namely: animation of the time range and usage of the backgroundData property on the graph. If you have any questions or suggestions, please feel free to get in contact with us!

Thanks a lot for reading and happy coding!

This blog post was originally published on camptocamp.com