torque/doc/API.md

Torque API

Torque provides two kinds of visualizations.

• static: provides a way to create heatmap like visualizations (note for Andrew: fon). see TorqueLayer
• dynamic: animate points over a map (note for Andrew: Navy) see TiledTorqueLayer

depending on the map provider you are using you need to use different layer type. Currently we provide layers for Google Maps and Leaflet.

L.TorqueLayer(options)

One of two core classes for the Torque library - it is used to create an animated torque layer with custom settings.

Usage example

  // initialize a torque layer that uses the CartoDB account details and SQL API to pull in data
  var torqueLayer = new L.TorqueLayer({
    user       : 'viz2',
    table      : 'ow',
    column     : 'date',
    countby    : 'count(cartodb_id)',
    resolution : 1,
    steps      : 750,
    pixel_size : 3,
    blendmode  : 'lighter'
  });

Options

Provider options

Option	type	Default	Description
provider	string	sql_api	Where is the data coming from? Alternative is 'url_template'

CartoDB data options

Option	type	Default	Description
user	string	null	CartoDB account name. Found as, accountname.cartodb.com
table	string	null	CartoDB table name where data is found
column	string	null	CartoDB table's column name where date information is found (for dynamic type torque layer only)
countby	string	null	The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function

Display options

Option	type	Default	Description
resolution	numeric	2	The x and y dimensions of each pixel as returned by the data
blendmode	boolean	source-over	The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas

Time options

Option	type	Default	Description
steps	integer	100	The maximun number of steps to divide the data into for animated renderings
animationDuration	integer	null	time in seconds the animation last

Time methods

Method	options	returns	Description
setStep(step)	time numeric	this	sets the animation to the step indicated by step, must be between 0 and steps
play		this	starts the animation
stop		this	stops the animation and set time to step 0
pause		this	stops the animation but keep the current time (play enables the animation again)

Style methods

Method	options	returns	Description
setCartoCSS(cartocss)	cartocss string	this	style the map rendering using client-side cartocss

The full CartoCSS spec is not supported by Torque but instead only a limited subset with some additions related to torque rendering. To see the full list of supported parameters, read the Torque CartoCSS documentation here. value and zoom variables can be used. value is the value of aggregation (see countby constructor option). zoom is the current zoom being rendered

TorqueLayer currently expects marker styling

CartoCSS Example

This should be string encoded in Javascript

#layer {,
  marker-fill: #662506;
  marker-width: 20;
  [value > 1] { marker-fill: #FEE391; }
  [value > 2] { marker-fill: #FEC44F; }
  [value > 3] { marker-fill: #FE9929; }
  [value > 4] { marker-fill: #EC7014; }
  [value > 5] { marker-fill: #CC4C02; }
  [value > 6] { marker-fill: #993404; }
  [value > 7] { marker-fill: #662506; }
  [frame-offset = 1] {  marker-width: 20; marker-fill-opacity: 0.05;}', // renders the previos frame
  [frame-offset = 2] {  marker-fill: red; marker-width: 30; marker-fill-opacity: 0.02;}', // renders two frames ago from the current being rendered
}

L.TiledTorqueLayer(options)

One of two core classes for the Torque library - it is used to create a static torque layer with client side filtering.

Provider options

Option	type	Default	Description
provider	string	sql_api	Where is the data coming from? Alternative is 'url_template'
url	string	null	Tile template URL for fetching data e.g 'http://host.com/{z}/{x}/{y}.json'

CartoDB data options (Note to Santana: are these really here?)

Option	type	Default	Description
user	string	null	CartoDB account name. Found as, accountname.cartodb.com
table	string	null	CartoDB table name where data is found
column	string	null	CartoDB table's column name where date information is found (for dynamic type torque layer only)
countby	string	null	The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function

Display options (Note to Santana: is blendmode here? or above even?)

Option	type	Default	Description
resolution	numeric	2	The x and y dimensions of each pixel as returned by the data
blendmode	boolean	source-over	The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas

Filtering options

Method	options	returns	Description
setKey(keys)	keys numeric/array	this	which data categories to display on the map
setSQL(sql)	sql string	this	by default sql torque layer uses is
"select * from table", this method changes the sql query torque uses to fetch the data

Style options

Method	options	returns	Description
setCartoCSS(cartocss)	cartocss string	this	style the map rendering using client-side cartocss

value and zoom variables can be used. only polygon-fill and polygon-opacity properties are supported currently. To see the full list of supported parameters, read the Torque CartoCSS documentation here.

TorqueLayer currently expects polygon styling

CartoCSS Example

This should be string encoded in Javascript

#layer {
  polygon-fill: #FFFF00;
  [value >= 10] { polygon-fill: #FFCC00; }
  [value >= 100] { polygon-fill: #FF9900; }
  [value >= 1000] { polygon-fill: #FF6600; }
  [value >= 10000] { polygon-fill: #FF3300; }
  [value > 100000] { polygon-fill: #C00; }
}

Google Maps Layers

GMapsTorqueLayer(options)

This class does exactly the same than L.TorqueLayer but using Google Maps. The main difference is that this class is not a layer is a overlay so in order to add it to the map use layer.setMap instead of overlayMapTypes. See Overlay view reference in Google Maps API doc.

Options

options

Option	type	Default	Description
map	google.maps.Map		google.maps.Map instance

see L.TorqueLayer for the rest of the options.

GMapsTiledTorqueLayer(options)

creates a static overlay to use it with google maps.

  var torqueLayer = new torque.GMapsTiledTorqueLayer({
    provider: 'url_template',
    url: GBIF_URL,
    resolution: 4,
  });

  torqueLayer.setMap(map);

  torqueLayer.setKey([10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]);

see L.TiledTorqueLayer for options reference