KeyLines tutorial: presenting graphs on images

11th March, 2019

Understanding map-based connections has always been a key graph visualization technique. Those maps can take many forms – from traditional geographic views of the world to city subway systems or nautical charts.

But KeyLines geospatial, our toolkit’s powerful mapping feature, isn’t just for viewing links between nodes with latitude and longitude properties.

Since version 5.0, KeyLines offers the flexibility to position graph items on any kind of background image. You can choose the view that will make most sense for your users: floor plans, building layouts, virtual representations, IT infrastructures – simply select your image backdrop and map your graph data to it. Better still, you can also transition seamlessly between images and traditional geospatial maps, creating a graph visualization to better convey useful insight.

Adding an image as a backdrop to your KeyLines visualizations is easy
Adding an image as a backdrop to your KeyLines visualizations is easy

This developer tutorial demonstrates how to use images as backdrops. With detailed code examples throughout, you’ll see how easy it is to provide custom context for your visualizations.

Mapping a virtual private network (VPN)

We’ve chosen to visualize a fictional organization’s IT infrastructure, with two physical sites connected to a central server via a VPN. Each site contains a number of terminals and factory machines which regularly communicate with each other.

We’ll use a simple data structure to manage the different background images that we’ll present data on. As you can see, KeyLines supports both SVG and JPG images.

const images = {
  Bangalore: {
    url: 'images/imagemaps/factory2.jpg',
    width: 2058,
    height: 1050,

  // ...

  'Central Server': {
    url: 'images/imagemaps/webserver.svg',
    width: 2058,
    height: 1050,

Configuring the map and loading chart data

KeyLines uses the popular Leaflet mapping component to implement its geospatial feature. By default, this shows graph nodes at defined geographic positions with a standard map appearance. This means you simply need to specify the latitude and longitude for your nodes, switch into map mode, and KeyLines does the rest.

Leaflet’s default map tile layer in KeyLines
Leaflet’s default map tile layer in KeyLines

With a little configuration, we can tell KeyLines to use one of our specified images instead of its default map

First we set some options, load the chart data, and display the map with its custom background:

    leaflet: {
      crs: L.CRS.Simple
    tiles: null,
  await loadMapData();

A few things are happening here:

  • the call specifies options to pass to the Leaflet mapping component.
  • the CRS setting specifies which Coordinate Reference System to use – this tells Leaflet how to map from latitude and longitude to positions on the map tiles. With an image background, we use CRS.Simple – which just maps latitude and longitude directly to x, y positions on the image.
  • the tiles: null setting tells map mode not to display the standard map tiles – we’ll add a background image to the map instead.
async function loadMapData() {

Once the map options are set, we call chart.load to add nodes and links to the chart. This uses a simple JSON-based format to specify how the nodes and links are connected, and what they look like.

Next, we switch KeyLines into map mode with, and then call setBackground to display one of our set of background images.

Creating and adding the image overlay

In setBackground , we create an image overlay and add it to the map, removing any previous image overlay:

function setBackground(imageId) {
  const data = images[imageId];
  const bounds = [[0, 0], [data.height, data.width]];

  if (backgroundOverlay) {

  backgroundOverlay = L.imageOverlay(data.url, bounds);

Let’s break down what’s happening here:

  • the data for the image we want to use comes from the images object we defined earlier.
  • the bounds array specifies the coordinate range that we can use to position items on the image.
  • we remove any previous image overlay, then create a new one with the specified image url, and add it to the Leaflet map.

KeyLines makes the leaflet map object available so we can use it directly with standard Leaflet functions. Later we can call setBackground again to change the background to a different image dynamically as the user navigates through the data.

Using an image as a backdrop brings the IT network to life
Using an image as a backdrop brings the IT network to life

To position nodes on the background image, we simply use the pixel position as their latitude and longitude. In the data object, the nodes will look something like this:

  "type": "node",
  "id": "srv001",
  "c": "rgb(0,150,255)",
  "t": "Central Server",
  "pos": {
    "lng": 800,
    "lat": 200

Once the chart data is loaded, we can use the KeyLines API to change the node position and appearance, and respond to any user interaction you like. For example, when users double-click on an item, we can update the display to drill down into specific parts of the network.

Ready to try KeyLines graphs on images?

Visualizing graph data in context with background images is a great way to understand at a glance what’s really going on in your data.

The full source code for this example is available from our SDK site along with over 80 other demonstrations. To get access, request a free trial or get in touch.

More from our blog

Visit our blog