Eric S. Bullington

Data Visualizations and Software Engineering


d3 O'Clock

Building a Virtual Analog Clock with d3.js (Part I)

I’ve noticed that tutorials to GUI toolkits often build an analog clock as a way to teach the fundamentals of the toolkit. And because a basic analogue clock is nothing but three data fields bound to an object, it occurred to me that an analog clock might be a good way to teach d3. So I put together the following tutorial. This tutorial assumes that the reader has a good understanding of basic JavaScript, and has had at least some exposure to d3.

Before we get started, let’s take a look at the final, minimally-styled clock we’re building in this tutorial. We’ll do some additional styling with Part II, so bear with the minimalist look for now:

####Making the Data Because we obviously have no precompiled “time” data to use, we must first generate our time data. Our goal is to create a function in which we can create a new Date object once a second, thus producing the time for that second and ultimately resulting in a data array containing objects for the current second, minute, and hour. We want these to be JavaScript numbers, so we use the build-in Date objects methods getSeconds(), getMinutes(), and getHours() to retrieve those units in numeric format.

var fields;

fields = function() {
  var currentTime, hour, minute, second;
  currentTime = new Date();
  second = currentTime.getSeconds();
  minute = currentTime.getMinutes();
  hour = currentTime.getHours() + minute / 60;
  return data = [
    {
      "unit": "seconds",
      "numeric": second
    }, {
      "unit": "minutes",
      "numeric": minute
    }, {
      "unit": "hours",
      "numeric": hour
    }
  ];
};

So here we fetch a Date object that represents the current time, and then we call the appropriate methods of that date object to get our current minute, hour, and second. Notice how we add the minute fraction to the hour variable. Without this little feature, the hour hand will “jump” from hour to hour each time the minute hand hits 0, instead of smoothly rotating around the clock. We could do the same for the minute hand, but most analog clocks I’ve seen feature a minute hand that “clicks” from minute to minute instead of continuously rotating like the hour hand. Add the fraction of seconds elapsed if you prefer a smooth-sweeping minute hand (i.e., + second / 60).

Next, starting on line #9, we define our data array and return it so it will be available when we call it later on. Each element of the array is a JavaScript object – this is typical of the JSON-structured data you will want to use in d3. Notice how the data keys in our objects contain no values – they are “dumb” field names. We refrained from doing something like this:

// Don't do this!!
data = [
  {
    "seconds": second
  }, {
    "minutes": minute
  }, {
    "hours": hour
  }
];

Keeping data values out of your keys is an absolute must for d3, and is analogous to good database design practices like keeping data values out of your column headers. This is something Mike Dewar stresses in Getting Started with D3 (Amazon affiliate link), his excellent – albeit brief – introduction to creating data visualizations with d3.

####Understanding d3 Scales Next, after defining the chart width and height, the radius of the clock, and the x and y offset of the clock, we define our scaling function, using d3’s built-in d3.scale.linear.

var width, height, offSetX, offSetY, pi, scaleSecs, scaleHours;
width = 400;
height = 200;
offSetX = 150;
offSetY = 100;

pi = Math.PI;
scaleSecs = d3.scale.linear().domain([0, 59 + 999/1000]).range([0, 2 * pi]);
scaleMins = d3.scale.linear().domain([0, 59 + 59/60]).range([0, 2 * pi]);
scaleHours = d3.scale.linear().domain([0, 11 + 59/60]).range([0, 2 * pi]);

Understanding scales is key to understanding d3 – they are the functions you see called “x” and “y” in so many d3 scripts. Whatever you chose to call them, understanding them is crucial to grasping what d3 is doing behind the scenes , so I’m going to take a moment here to describe what’s happening in the last three lines above.

First, on line #7, we need to define pi using JavaScript built-in Math.PI constant, since we’ll be using it in our scales. This should not come as a surprise, since a clock is a circle. We then start to define the seconds scales. I had originaly used the same scale for minutes and seconds, but since minutes are divided into 60 seconds, and seconds are divided into 1000 milliseconds, I had to use a different scale to properly account for the time that passes between 59 seconds or minutes and 0 seconds/minutes. We are using d3’s built-in d3.scale.linear() scale because our data scales linearly. If we had wanted to keep the native JavaScript Date object for use in the domain, instead of converting it to decimal numbers, we could have used d3.time.scale() method for our scales. This time scale comes in very handy when plotting out times series.

Next, we move to the scale’s domain. In any d3 scale you define (and there are several different types), it’s important to understand that the domain is the input – it’s the data you’re putting into the chart. The range, on the other hand, is the output – it’s the scale onto which your data will be plotted on your chart. Here, our input domain is the minimum and maximum value of the seconds we are putting in: 0 and 59 (yes, a robust clock would take into account leap seconds, but let’s not go there). If you’re plotting a time-series bar chart, your domain would be your first and last dates (for your x scale) and the minimum and maximum of your series data (for your y scale).

Finally, we define the scale’s range. As mentioned above, the range is the output onto which your data is mapped. Here’s that’s a perfect circle, so we define or range as the circle’s circumference (all the way around the circle). We use radians instead of degrees because d3’s arc function uses radians, and it’s easier to use radians here than to convert angles to radians further down in the script.

We then do the same thing for the hour scale, only the domain goes from 0 to 11, plus 59/60 to account for the minute fraction we are adding to each hour.

Phew! That was a lot of words to describe not much code. Congratulations for reading this far. We’re a little over halfway through.

####Putting Down the SVG Next we lay down our base svg element and a svg group and append to that group our outer svg circle, which allows us to create the outline of the clock face, and the inner svg circle, which creates a nice little visual origin for the clock hands. Does that part of a clock have a name? Anyway, here’s the code:

var vis, clockGroup;

vis = d3.selectAll(".chart")
  .append("svg:svg")
  .attr("width", width)
  .attr("height", height);

clockGroup = vis.append("svg:g")
  .attr("transform", "translate(" + offSetX + "," + offSetY + ")");

clockGroup.append("svg:circle")
  .attr("r", 80).attr("fill", "none")
  .attr("class", "clock outercircle")
  .attr("stroke", "black")
  .attr("stroke-width", 2);

clockGroup.append("svg:circle")
  .attr("r", 4)
  .attr("fill", "black")
  .attr("class", "clock innercircle");

This is all basic SVG manipulation, so I’m not going to go into detail. If this portion of the script is confusing, I highly recommend going through Scott Murray’s d3 tutorials at aligned left, particularly tutorials no. 10 and 11 (in that order). By the way, Scott is said to be working on a d3 book for beginners, which to the best of my knowledge will only be the second d3 book in existence, after the book by Mike Dewey I mention above. Given the excellent quality of Scott’s tutorials, I’m looking forward to reading and recommending his book.

So at this point, our clock at this point should look like this:

But something seems to be missing…hmmm. Ah yes, the hands! So now we reach for a render function that we will be able to call again and again, once time every second. You will often see these types of functions that are called to re-plot data with names like render(), redraw() and plot(). In our script, this is the function that ties everything together, and with the exception of one last little timer function to call this render function, it wraps up this tutorial. Let’s take a look:

var render;

render = function(data) {

  var hourArc, minuteArc, secondArc;

  clockGroup.selectAll(".clockhand").remove();

  secondArc = d3.svg.arc()
    .innerRadius(0)
    .outerRadius(70)
    .startAngle(function(d) {
    return scaleSecs(d.numeric);
  })
    .endAngle(function(d) {
    return scaleSecs(d.numeric);
  });

  minuteArc = d3.svg.arc()
    .innerRadius(0)
    .outerRadius(70)
    .startAngle(function(d) {
    return scaleMins(d.numeric);
  })
    .endAngle(function(d) {
    return scaleMins(d.numeric);
  });

  hourArc = d3.svg.arc()
    .innerRadius(0)
    .outerRadius(50)
    .startAngle(function(d) {
    return scaleHours(d.numeric % 12);
  })
    .endAngle(function(d) {
    return scaleHours(d.numeric % 12);
  });

  clockGroup.selectAll(".clockhand")
    .data(data)
    .enter()
    .append("svg:path")
    .attr("d", function(d) {
      if (d.unit === "seconds") {
        return secondArc(d);
      } else if (d.unit === "minutes") {
        return minuteArc(d);
      } else if (d.unit === "hours") {
        return hourArc(d);
      }
    })
    .attr("class", "clockhand")
    .attr("stroke", "black")
    .attr("stroke-width", function(d) {
      if (d.unit === "seconds") {
        return 2;
      } else if (d.unit === "minutes") {
        return 3;
      } else if (d.unit === "hours") {
        return 3;
      }
    })
    .attr("fill", "none");
};

OK, for a d3 beginner, that surely looks intimidating, but there are actually only two challenging ideas to grasp in the code above:

  1. path generators
  2. data joins and their use

####Data Joins

Even though data joins are featured in the last code block above (starting on line 22), I’m going to discuss them first, since data joins lie at the core of d3’s power and flexibility. Plus the path generators won’t make sense unless we first go over the data joins.

Data joins are discussed at length in Mike Bostock’s piece Thinking in Joins, as well as in one of Scott Murray’s highly-recommended d3 tutorials, so I’m not going to go over the fundamentals again here. Suffice it to say that we have three objects in our data (seconds, minutes, and hours), and we want to create three corresponding SVG objects (the second, minute, and hour hands on the clock). So what do we do? We join them together by calling data() followed by enter(). At this point, our data is ready and available for binding, and we proceed to build the hands of the block using the arc path generator.

Path generators

SVG paths are one of the technologies most flexible features. Anytime you see a complex shape or object rendered with svg – think flags, countries, complex symbols, and the like – there is a mini-language called svg path behind that image. Basically, path data tells svg to start here, draw there, then there, then there. If you’ve ever used Turtle graphics to draw something, you know the basic idea. Not surprisingly, d3 makes frequent use of svg paths, primarily through a feature called path generators. Think of path generators as the mold needed to form paths. First you use a path generator to produce the path data you’ll need to draw the path, then you append svg paths like you would any other svg element (such as circles, rects, or lines). Only you include an extra .attr method with a d attribute, followed by a reference to your path generator.

And that’s exactly what we’ve done above with the d3.svg.arc path generator, only we’ve done it three times: once for each of the clocks hands. So on line #7 above, we build our second hand arc path generator, setting its inner radius at 0 and outer radius at 70, which means that the hand will start at the center of the circle and measure some 70 pixels long. And now for the trickiest part of the whole program. In order to emulate the clock hand as it sweeps around the clock, we map the current second onto the arc’s angle value. We give the starting and ending angle the same value, which means that it has an angle of 0, but an angle of 0 at the part of the clock that corresponds to the second value. You’ll note that here is where we finally use our scaleSecs d3.scale.linear function and change the decimal value of the current second to the appropriate angle value in radians.

We do the same thing for the minute and hour arcs, with the only difference being the scale used (scaleSecs for second and minute – since both are based on 60 – and scaleHours for the hour), as well as the length of the radius (I made the hour hand shorter for obvious reasons). We could have easily done this using one path generator instead of three and ample use of if statements in the accessor functions, but for the sake of clarity I split it up into three.

Returning down to line #43, 45, and 47 in the code above, you’ll see that we then call these path generators as we’re defining the each svg path’s d values. We then assign appropriate stroke-width values to the three svg objects, which is how an angle of 0 can be seen at all.

One final thing to cover in the code above is the very first d3 operation in the render() function, on line #5 above. Here, we remove the existing clock hands to make room for the clock hands about to be rendered. This should all make sense once we go over the final – and mercifully short – segment of the script, which is the timer that wraps it all together.

####Wrapping Up

So at this point, we obviously need to render our clock hands, and we need to do so every second, as the time values change. As it so happens, JavaScript has a very nice built-in function to call functions at a given interval, called (not inappropriately) setInterval(). So you’ll see how we use this function to both fetch our data (generated dynamically) and pass it to our render function, both every 1 second (time intervals must be specified here in milliseconds).

setInterval(function() {
  var data;
  data = fields();
  return render(data);
}, 1000);

And so it should all make sense. At this point, our clock looks somewhat realistic:

Congratulations on finishing the tutorial. The full script is available here (JavaScript) and here (CoffeeScript). Tune in soon for the second part, which will cover using d3 and svg styling to turn this very basic analog clock into a much more stylish and attractive timepiece.

Addendum: I should add that this is not the only way a tool as flexible as d3 can make three hands go around a clock. Notably, it would also be easy to use d3 along with svg transforms to achieve the same effect. I chose the approach described above because I felt provided the best introduction to d3 for users who know the very basics but want to learn how to build visualizations.