Use the amazing D3 library to animate a path on a Leaflet map

Posted on by zev@zevross.com · 8 Comments

Updated December 8, 2014

Introduction: Animate a path with D3

Viewing location data that varies through time on a static map is fun, but viewing it on an animated map is a lot more fun. Recently, online map lovers were excited by Chris Whong’s Day in the Life of a NYC Taxi map in which he used D3 to animate taxi paths on a Leaflet map. Fortunately for developers, Chris was generous with his time and code. He described the approach he used in a two-part techblog. Using code snippets from Chris, Mike Bostock (D3’s creator), d3noob as well as others, we break down the process of creating an animated path in Leaflet with D3.

Here is what the finished product looks like:

1) The data: great coffee to great beer

We’re using a GeoJSON file of waypoints in the path from Gimme!, the great (and Ithaca-born) coffee shop to the source for rare and unusual beers, Proletariat.

gimmetoprol

The data was created using a combination of Google Directions, Node.js and QGIS as described in our previous post. But the file is a standard GeoJSON file of points so you can create your own file using simpler options (try, for example, geojson.io). The first bit of data looks like this (this data can be downloaded from GitHub):

{
"type": "FeatureCollection",
"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:OGC:1.3:CRS84" } },

"features": [
{ "type": "Feature", "properties": { "latitude": 40.722390, "longitude": -73.995170, "time": 1, "id": "route1", "name":"Gimme" }, "geometry": { "type": "Point", "coordinates": [ -73.99517, 40.72239 ] } },
{ "type": "Feature", "properties": { "latitude": 40.721580, "longitude": -73.995480, "time": 2, "id": "route1", "name":"Along route"  }, "geometry": { "type": "Point", "coordinates": [ -73.99548, 40.72158 ] } }}

2) Set the stage: create the basic map

We’re not doing anything fancy here, simply creating a Leaflet map and we’re using MapBox tiles. In the header we’re providing CDN links to Leaflet, D3 and MapBox. The code for creating the map looks something like this:

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7/leaflet.css" />
    <link href='https://api.tiles.mapbox.com/mapbox.js/v1.6.4/mapbox.css' rel='stylesheet' />

    <script src="http://d3js.org/d3.v3.min.js" type="text/javascript"></script>
    <script src="http://cdn.leafletjs.com/leaflet-0.7/leaflet.js"></script>
    <script src='https://api.tiles.mapbox.com/mapbox.js/v1.6.4/mapbox.js'></script>

    <style>
    html,
    body {
        height: 100%;
        width: 100%;
    }
    body {
        margin: 0;
    }
    #map {
        width: 100%;
        height: 100%;
    }
    </style>

</head>

<body>
    <div id="map"></div>

    <script type="text/javascript">
    var mapboxTiles = L.tileLayer('https://{s}.tiles.mapbox.com/v3/examples.map-zr0njcqy/{z}/{x}/{y}.png', {
        attribution: '<a href="http://www.mapbox.com/about/maps/" target="_blank">Terms &amp; Feedback</a>'
    });

    var map = L.map('map')
        .addLayer(mapboxTiles)
        .setView([40.72332345541449, -73.99], 15);
    </script>
</body>
</html>

3) Prepare the container SVG elements

Normally with D3 we would be appending an SVG container to, say, the body (i.e., d3.select("body").append("svg")). In this case we need to append to the map itself (specifically the overlayPane) and Leaflet has a handy function called getPanes to help us do this. As usual, we append a “grouping” or g element to the SVG. In this case we need to add the class leaflet-zoom-hide otherwise we will see a phantom SVG when we zoom.

var svg = d3.select(map.getPanes().overlayPane).append("svg");
var g = svg.append("g").attr("class", "leaflet-zoom-hide");

4) Use the D3 function d3.json() to read your data

Our data is conveniently in GeoJSON format so we can use d3.json() easily to read in our data. Note that this function is asynchronous so any bits of code that require the data will need to be included within this function.

d3.json("points.geojson", function(collection) {
// Do stuff here
});

5) Set up conversion and projection functions

Since SVG does not use the same coordinate system as a globe, the latitude and longitude coordinates will need to be transformed. There are two pieces of the code where we do this. The function that D3 uses to convert GeoJSON to path codes (d3.geo.path()) can include a projection function. In this case we’re using what is called a “stream transform” in D3 combined with a function (projectPoint) that makes use of a Leaflet function (latLngToLayerPoint). These pieces are used here to create (and project) the line between our points and the bounding box coordinates.

var transform = d3.geo.transform({
    point: projectPoint
});
var d3path = d3.geo.path().projection(transform);

function projectPoint(x, y) {
    var point = map.latLngToLayerPoint(new L.LatLng(y, x));
    this.stream.point(point.x, point.y);
} 
    });

We also need to a function to convert our points to a line (and project the points in the process). D3 has the function to create the line (d3.svg.line()) and we use a custom function to do the projection.

var toLine = d3.svg.line()
    .interpolate("linear")
    .x(function(d) {
        return applyLatLngToLayer(d).x
    })
    .y(function(d) {
        return applyLatLngToLayer(d).y
    });

function applyLatLngToLayer(d) {
    var y = d.geometry.coordinates[1]
    var x = d.geometry.coordinates[0]
    return map.latLngToLayerPoint(new L.LatLng(y, x))
}

6) Create the points and lines we need

We have several elements we will be adding. These include the path itself (as a line), the yellow traveling circle, the points themselves (which we will use in a future post but for now are transparent), the red origin and destination points and the text. They all get added using a similar approach and one that is described in numerous other posts (here is a simple one from Mike Bostock).

// here is the line between points
var linePath = g.selectAll(".lineConnect")
    .data([featuresdata])
    .enter()
    .append("path")
    .attr("class", "lineConnect");

// This will be our traveling circle
var marker = g.append("circle")
    .attr("r", 10)
    .attr("id", "marker")
    .attr("class", "travelMarker");

// if you want the actual points change opacity
var ptFeatures = g.selectAll("circle")
    .data(featuresdata)
    .enter()
    .append("circle")
    .attr("r", 3)
    .attr("class", function(d){
        return "waypoints " + "c" + d.properties.time
    })      
    .style("opacity", 0);

// I want the origin and destination to look different
var originANDdestination = [featuresdata[0], featuresdata[17]]

var begend = g.selectAll(".drinks")
    .data(originANDdestination)
    .enter()
    .append("circle", ".drinks")
    .attr("r", 5)
    .style("fill", "red")
    .style("opacity", "1");

    // I want names for my coffee and beer
var text = g.selectAll("text")
    .data(originANDdestination)
    .enter()
    .append("text")
    .text(function(d) {
        return d.properties.name
    })
    .attr("class", "locnames")
    .attr("y", function(d) {
        return -10 //I'm moving the text UP 10px
    })

7) Add our items to the actual map (and account for zooming)

Using Leaflet’s viewreset method and our reset function we can tell our app to re-compute the SVG coordinates and the coordinates of our map elements when the user repositions the map. We also run the reset function initially to put our SVG elements on the map.

map.on("viewreset", reset);

// this puts stuff on the map! 
reset();

8) The function to reset the SVG elements if the user repositions the map

For the point-related elements of our SVG we can use the applyLatLngToLayer function combined with the CSS transform property to convert latitude and longitude to the current map view coordinates. You’ll note that for the SVG were adding 120 px to the width and height. This is because the bounds would otherwise perfectly fit our features and, as a result, your circles that represent points will get cut off.

function reset() {
    var bounds = d3path.bounds(collection),
        topLeft = bounds[0],
        bottomRight = bounds[1];


    begend.attr("transform",
        function(d) {
            return "translate(" +
                applyLatLngToLayer(d).x + "," +
                applyLatLngToLayer(d).y + ")";
        });

    //...do same thing to text, ptFeatures and marker...
    
        });

    svg.attr("width", bottomRight[0] - topLeft[0] + 120)
        .attr("height", bottomRight[1] - topLeft[1] + 120)
        .style("left", topLeft[0] - 50 + "px")
        .style("top", topLeft[1] - 50 + "px");


    linePath.attr("d", toLine)
    g.attr("transform", "translate(" + (-topLeft[0] + 50) + "," + (-topLeft[1] + 50) + ")");


} // end reset

9) The animation special sauce: two functions that do the D3 magic

We are using a D3 transition to create the effect of a smooth line between points and the transition makes use of a function called tweenDash. This is a very clever approach to animating the path and I think Mike Bostock was the one to first show the example. The basic idea is this: SVG has a style property called stroke-dasharray which can be used to specify lengths of the alternating dashes and gaps that make up a line. So if you specify “5,5” you would have a line 5px long and then a gap 5px long and this pattern would be repeated. But what if you had an overall line/path that is 100px long and you specify “0,100”? You would have no line and a gap of 100px meaning — no line! How about if you specified an array of “1,100”? This would give you a line 1px long and a gap of 100px — since your line is only 100px long, though, in practice this would yield a gap of 99px. Then you can use “2,100”, “3,100” and so on to smoothly fill in the line. This is the idea behind these functions.

The transition function adds a transition to our path (linePath) and the transition is being applied to the stroke-dasharray style. The stoke-gap numbers (e.g, “3,100”) are being fed in from our tweenDash function.

function transition(path) {
    linePath.transition()
        .duration(7500)
        .attrTween("stroke-dasharray", tweenDash)
        .each("end", function() {
            d3.select(this).call(transition);// infinite loop
            ptFeatures.style("opacity", 0)
        }); 


} 
function tweenDash() {

    return function(t) {
        // In original version of this post the next two lines of JS were
        // outside this return which led to odd behavior on zoom
        // Thanks to Martin Raifer for the suggested fix.

        //total length of path (single value)
        var l = linePath.node().getTotalLength(); 
        interpolate = d3.interpolateString("0," + l, l + "," + l); 

        //t is fraction of time 0-1 since transition began
        var marker = d3.select("#marker");
        
        // p is the point on the line (coordinates) at a given length
        // along the line. In this case if l=50 and we're midway through
        // the time then this would 25.
        var p = linePath.node().getPointAtLength(t * l);

        //Move the marker to that point
        marker.attr("transform", "translate(" + p.x + "," + p.y + ")"); //move marker
        return interpolate(t);
    }
}

And you’re done. One small issue.

In the sample code I run the transition function from within the reset function. As a result, each time the user zooms the path resets. I would prefer to have the path continue if the user zooms and I thought that taking transition out of the reset function would work. But if you try zooming mysterious things happen. See the maps below. If you have a solution to the zooming issue, please let me know.

It is lovely when someone, out of the blue, suggests a code fix. I want to thank Martin Raifer for his fix to this issue. The fix involved simply taking two lines of JS code in the tweenDash() function and moving them into the return as noted in the code snippet above.

Final map:
The Gist for this one is here.

This is the final code from GitHub.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7/leaflet.css" />
<script src="http://d3js.org/d3.v3.min.js" type="text/javascript"></script>
<script src="http://cdn.leafletjs.com/leaflet-0.7/leaflet.js"></script>
<script src='https://api.tiles.mapbox.com/mapbox.js/v1.6.4/mapbox.js'></script>
<link href='https://api.tiles.mapbox.com/mapbox.js/v1.6.4/mapbox.css' rel='stylesheet' />
<style>
html,
body {
height: 100%;
width: 100%;
}
body {
margin: 0;
}
#map {
width: 100%;
height: 100%;
}
svg {
position: relative;
}
path {
fill: yellow;
stroke-width: 2px;
stroke: red;
stroke-opacity: 1;
}
.travelMarker {
fill: yellow;
opacity: 0.75;
}
.waypoints {
fill: black;
opacity: 0;
}
}
.drinks {
stroke: black;
fill: red;
}
.lineConnect {
fill: none;
stroke: black;
opacity: 1;
}
.locnames {
fill: black;
text-shadow: 1px 1px 1px #FFF, 3px 3px 5px #000;
font-weight: bold;
font-size: 13px;
}
</style>
</head>
<body>
<div id="demo"></div>
<div id="map"></div>
<script type="text/javascript">
var mapboxTiles = L.tileLayer('https://{s}.tiles.mapbox.com/v3/examples.map-zr0njcqy/{z}/{x}/{y}.png', {
attribution: '<a href="http://www.mapbox.com/about/maps/" target="_blank">Terms &amp; Feedback</a>'
});
var map = L.map('map')
.addLayer(mapboxTiles)
.setView([40.72332345541449, -73.99], 14);
// we will be appending the SVG to the Leaflet map pane
// g (group) element will be inside the svg
var svg = d3.select(map.getPanes().overlayPane).append("svg");
// if you don't include the leaflet-zoom-hide when a
// user zooms in or out you will still see the phantom
// original SVG
var g = svg.append("g").attr("class", "leaflet-zoom-hide");
//read in the GeoJSON. This function is asynchronous so
// anything that needs the json file should be within
d3.json("points.geojson", function(collection) {
// this is not needed right now, but for future we may need
// to implement some filtering. This uses the d3 filter function
// featuresdata is an array of point objects
var featuresdata = collection.features.filter(function(d) {
return d.properties.id == "route1"
})
//stream transform. transforms geometry before passing it to
// listener. Can be used in conjunction with d3.geo.path
// to implement the transform.
var transform = d3.geo.transform({
point: projectPoint
});
//d3.geo.path translates GeoJSON to SVG path codes.
//essentially a path generator. In this case it's
// a path generator referencing our custom "projection"
// which is the Leaflet method latLngToLayerPoint inside
// our function called projectPoint
var d3path = d3.geo.path().projection(transform);
// Here we're creating a FUNCTION to generate a line
// from input points. Since input points will be in
// Lat/Long they need to be converted to map units
// with applyLatLngToLayer
var toLine = d3.svg.line()
.interpolate("linear")
.x(function(d) {
return applyLatLngToLayer(d).x
})
.y(function(d) {
return applyLatLngToLayer(d).y
});
// From now on we are essentially appending our features to the
// group element. We're adding a class with the line name
// and we're making them invisible
// these are the points that make up the path
// they are unnecessary so I've make them
// transparent for now
var ptFeatures = g.selectAll("circle")
.data(featuresdata)
.enter()
.append("circle")
.attr("r", 3)
.attr("class", "waypoints");
// Here we will make the points into a single
// line/path. Note that we surround the featuresdata
// with [] to tell d3 to treat all the points as a
// single line. For now these are basically points
// but below we set the "d" attribute using the
// line creator function from above.
var linePath = g.selectAll(".lineConnect")
.data([featuresdata])
.enter()
.append("path")
.attr("class", "lineConnect");
// This will be our traveling circle it will
// travel along our path
var marker = g.append("circle")
.attr("r", 10)
.attr("id", "marker")
.attr("class", "travelMarker");
// For simplicity I hard-coded this! I'm taking
// the first and the last object (the origin)
// and destination and adding them separately to
// better style them. There is probably a better
// way to do this!
var originANDdestination = [featuresdata[0], featuresdata[17]]
var begend = g.selectAll(".drinks")
.data(originANDdestination)
.enter()
.append("circle", ".drinks")
.attr("r", 5)
.style("fill", "red")
.style("opacity", "1");
// I want names for my coffee and beer
var text = g.selectAll("text")
.data(originANDdestination)
.enter()
.append("text")
.text(function(d) {
return d.properties.name
})
.attr("class", "locnames")
.attr("y", function(d) {
return -10
})
// when the user zooms in or out you need to reset
// the view
map.on("viewreset", reset);
// this puts stuff on the map!
reset();
transition();
// Reposition the SVG to cover the features.
function reset() {
var bounds = d3path.bounds(collection),
topLeft = bounds[0],
bottomRight = bounds[1];
// here you're setting some styles, width, heigh etc
// to the SVG. Note that we're adding a little height and
// width because otherwise the bounding box would perfectly
// cover our features BUT... since you might be using a big
// circle to represent a 1 dimensional point, the circle
// might get cut off.
text.attr("transform",
function(d) {
return "translate(" +
applyLatLngToLayer(d).x + "," +
applyLatLngToLayer(d).y + ")";
});
// for the points we need to convert from latlong
// to map units
begend.attr("transform",
function(d) {
return "translate(" +
applyLatLngToLayer(d).x + "," +
applyLatLngToLayer(d).y + ")";
});
ptFeatures.attr("transform",
function(d) {
return "translate(" +
applyLatLngToLayer(d).x + "," +
applyLatLngToLayer(d).y + ")";
});
// again, not best practice, but I'm harding coding
// the starting point
marker.attr("transform",
function() {
var y = featuresdata[0].geometry.coordinates[1]
var x = featuresdata[0].geometry.coordinates[0]
return "translate(" +
map.latLngToLayerPoint(new L.LatLng(y, x)).x + "," +
map.latLngToLayerPoint(new L.LatLng(y, x)).y + ")";
});
// Setting the size and location of the overall SVG container
svg.attr("width", bottomRight[0] - topLeft[0] + 120)
.attr("height", bottomRight[1] - topLeft[1] + 120)
.style("left", topLeft[0] - 50 + "px")
.style("top", topLeft[1] - 50 + "px");
// linePath.attr("d", d3path);
linePath.attr("d", toLine)
// ptPath.attr("d", d3path);
g.attr("transform", "translate(" + (-topLeft[0] + 50) + "," + (-topLeft[1] + 50) + ")");
} // end reset
// the transition function could have been done above using
// chaining but it's cleaner to have a separate function.
// the transition. Dash array expects "500, 30" where
// 500 is the length of the "dash" 30 is the length of the
// gap. So if you had a line that is 500 long and you used
// "500, 0" you would have a solid line. If you had "500,500"
// you would have a 500px line followed by a 500px gap. This
// can be manipulated by starting with a complete gap "0,500"
// then a small line "1,500" then bigger line "2,500" and so
// on. The values themselves ("0,500", "1,500" etc) are being
// fed to the attrTween operator
function transition() {
linePath.transition()
.duration(7500)
.attrTween("stroke-dasharray", tweenDash)
.each("end", function() {
d3.select(this).call(transition);// infinite loop
});
} //end transition
// this function feeds the attrTween operator above with the
// stroke and dash lengths
function tweenDash() {
return function(t) {
//total length of path (single value)
var l = linePath.node().getTotalLength();
// this is creating a function called interpolate which takes
// as input a single value 0-1. The function will interpolate
// between the numbers embedded in a string. An example might
// be interpolatString("0,500", "500,500") in which case
// the first number would interpolate through 0-500 and the
// second number through 500-500 (always 500). So, then
// if you used interpolate(0.5) you would get "250, 500"
// when input into the attrTween above this means give me
// a line of length 250 followed by a gap of 500. Since the
// total line length, though is only 500 to begin with this
// essentially says give me a line of 250px followed by a gap
// of 250px.
interpolate = d3.interpolateString("0," + l, l + "," + l);
//t is fraction of time 0-1 since transition began
var marker = d3.select("#marker");
// p is the point on the line (coordinates) at a given length
// along the line. In this case if l=50 and we're midway through
// the time then this would 25.
var p = linePath.node().getPointAtLength(t * l);
//Move the marker to that point
marker.attr("transform", "translate(" + p.x + "," + p.y + ")"); //move marker
console.log(interpolate(t))
return interpolate(t);
}
} //end tweenDash
// Use Leaflet to implement a D3 geometric transformation.
// the latLngToLayerPoint is a Leaflet conversion method:
//Returns the map layer point that corresponds to the given geographical
// coordinates (useful for placing overlays on the map).
function projectPoint(x, y) {
var point = map.latLngToLayerPoint(new L.LatLng(y, x));
this.stream.point(point.x, point.y);
} //end projectPoint
});
// similar to projectPoint this function converts lat/long to
// svg coordinates except that it accepts a point from our
// GeoJSON
function applyLatLngToLayer(d) {
var y = d.geometry.coordinates[1]
var x = d.geometry.coordinates[0]
return map.latLngToLayerPoint(new L.LatLng(y, x))
}
</script>
</body>
</html>
view raw index.html hosted with ❤ by GitHub

8 responses

  1. Can the yellow circle travel in linear line from origin point (Gimme) to destination point(Proletariat) without turning left /right / passing through other points (Along route)?

    Reply

  6. This is excellent and easy to use! I am having a hard time figuring out how to make the animation stop. I can see how I could add logic in the .each method to make it only do another transition if some external variable is set to true. But how can I abruptly make it stop?
    My attempts at removing all svg, g, lineconnect elements don’t stop it.
    I’m a d3 noob, maybe I need to store the feature data in a global variable so I can perform a d3.data.exit after an event.

    There are a lot of things for me to try out so I figured I would ask if you know the best way.

    Reply

  7. Hello,

    What changes you need to use multiple json files?

    With the function ”

    d3
    .queue()
    .defer(d3.json, “data/01”)
    .defer(d3.json, “data/02”)
    .defer(d3.json, “data/03”)
    .await(function(err,m1,m2,m3) { … }
    “

    Reply

Leave a Reply to José Ricardo Cancel reply

Your email address will not be published. Required fields are marked *