Using Torque Outside of CartoDB

Animation GIF

Talk at FOSS4G NA 2015

Kathryn Killebrew | Software Developer

Azavea Logo

What is Torque?

Torque is an open-source JavaScript library from CartoDB for time series map visualization.


How are Torque Visualizations Created?

The simplest way to create a Torque time-lapse animation is to upload the data to a CartoDB account, then select the Torque option from the visualization wizard. Here’s an example of L.A. rapid buses.

LA Metro GIF

CartoDB visualizations can also be embedded on other pages. The CartoDB Torque tutorial page contains an embedded Torque animation.

Torque in the Wizard

Torque Wizard GIF

Here’s a heatmap version of the SEPTA real-time bus data, in a CartoDB visualization.

SEPTA visualization screenshot

How is Torque JS designed to be used?

The Torque JavaScript library will let you create a Torque map layer that can be added to a Leaflet or Google Maps base layer on your own web page.

The layer is defined with the user name of a CartoDB account to use, the name of the table to visualize from the CartoDB account, and some special CartoCSS to define aspects of the animation. Here’s an example from the Torque project GitHub Pages. The source is under the project’s examples directory.

Navy demo GIF

Can Torque be used without uploading the data to CartoDB?

A third option for using Torque, which we will explore today, is to use the library in conjunction with two other CartoDB JavaScript libraries to connect to data that is not uploaded to a CartoDB account, but is rather in our own PostGIS-enabled PostgreSQL database.

This presentation walks through setting up a stand-alone Torque animation.

CyclePhilly GIF

How Does Torque Work?

Torque is part of the suite of projects that make up the CartoDB web service. It’s designed to work with the other projects, particularly the Windshaft tiler and SQL API service. Torque queries the SQL API when initializing to get metadata about the table, such as the time period covered and bounding box for the points, then fetches the animation from Windshaft.

The Torque animation is configured using special CartoCSS, defining aspects such as frame count, animation duration, and the color and size of the markers used at different frame offsets. Screenshot

Okay, How Does CartoDB Work?

CartoDB has several open-source components:

Um, Why Are You Doing This?

Lightbulb-Fixing GIF

Working on a volunteer project, CyclePhilly. Already had a Windshaft server with PostGIS-enabled database displaying trips; wanted to add Torque animations.

CyclePhilly Trips

So How Do I Use Torque Without the Other Stuff?

Torque only really needs the Windshaft tiler and SQL API CartoDB projects to work. The Torque and Windshaft projects can be used without modification.

The SQL API will need to be set up to operate without user credentials from the CartoDB web app. I’ll share a fork of the project I’ve configured to work as a stand-alone SQL API.

Note that redis is a dependency of both Windshaft and the SQL API; it’s used for caching.

The database is the one other component we’ll need.

How Do I Set Up the Database?

How Do I Set Up the Database Table?

Four columns are needed:

Setting up Windshaft

Setting up the SQL API

Once the SQL API is set up to operate without user credentials from Redis or user and database names from the subdomain, we’re ready to go! Here’s a fork of the SQL API that has the authentication parts removed. For permissions, we can rely on using a database role that has read-only access to just the table with our data for Torque.

The SQL API configuration files live in config/environments. Copy development.js.example to development.js, and edit:

To run: node app.js from the project top-level directory.

Okay, cool! Show me some examples!


Also helpful

CartoDB Torque Demo Site

-torque-data-aggregation to cumulative. (By default, previous values are discarded.)


Kathryn Killebrew


Animation GIF