torque/README.md

Torque
==

[![Build Status](https://travis-ci.org/CartoDB/torque.svg)](https://travis-ci.org/CartoDB/torque)

Render big, timeseries data in the client. Uses CartoDB to generate a datacube format. For a brief introduction to the format and methods, see our [presentation slides](http://gijs.github.com/images/cartodb_datacubes.pdf)

CartoDB users can use this code right away. Specify your username/tablename and datecolumn to get mapping time immediatley.

Have fun!

* Play with your own data: http://cartodb.github.com/torque/
* The Guardian's Data Blog write-up of Royal Navy ships in WWI: http://www.guardian.co.uk/news/datablog/interactive/2012/oct/01/first-world-war-royal-navy-ships-mapped
* A car in Nürburgring track: http://cartodb.github.com/torque/examples/car.html

## Torque library reference

Torque lets you render big, timeseries or categorical data in the client. This is useful for many modern applications that need more than just a static map. Early versions of Torque have been used to visualize human movement, Twitter activity, biodiversity data, and many more large-scale datasets.

The library uses CartoDB to generate a [layercube](https://github.com/CartoDB/tilecubes/blob/master/2.0/spec.md) format. For a brief introduction to the format and methods, see our [presentation slides](http://gijs.github.com/images/cartodb_datacubes.pdf). If you are not using CartoDB to host your data, you can modify the input parameters to point toward any layercube service.

### Getting started

The simplest way to use a visualization with Torque is...

<div class="margin20"></div>
<div class="code_title">Create a simple Torque visualization</div>
  ``` javascript
      ...
        <body>
          <div id="map"></div>
        </body>
      ...
      // define the torque layer style using cartocss
      var CARTOCSS = [
          'Map {',
          '-torque-time-attribute: "date";',
          '-torque-aggregation-function: "count(cartodb_id)";',
          '-torque-frame-count: 760;',
          '-torque-animation-duration: 15;',
          '-torque-resolution: 2',
          '}',
          '#layer {',
          '  marker-width: 3;',
          '  marker-fill-opacity: 0.8;',
          '  marker-fill: #FEE391; ',
          '  comp-op: "lighten";',
          '  [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: 10; marker-fill-opacity: 0.05;}',
          '  [frame-offset = 2] { marker-width: 15; marker-fill-opacity: 0.02;}',
          '}'
      ].join('\n');

        
      var map = new L.Map('map', {
        zoomControl: true,
        center: [40, 0],
        zoom: 3
      });

      L.tileLayer('http://{s}.api.cartocdn.com/base-dark/{z}/{x}/{y}.png', {
        attribution: 'CartoDB'
      }).addTo(map);

      var torqueLayer = new L.TorqueLayer({
        user       : 'viz2',
        table      : 'ow',
        cartocss: CARTOCSS
      });
      torqueLayer.addTo(map);
      torqueLayer.play()

    <script>
  ```
[Grab the complete example source code](https://github.com/CartoDB/torque/blob/master/examples/navy_leaflet.html)
<div class="margin20"></div>

### API
[see reference](https://github.com/CartoDB/torque/blob/master/doc/API.md)
readme 2012-10-01 07:46:11 +08:00			`Torque`
reindent all code 2012-10-01 07:41:39 +08:00			`==`

Adds travis badge 2014-12-10 17:52:01 +08:00			`[![Build Status](https://travis-ci.org/CartoDB/torque.svg)](https://travis-ci.org/CartoDB/torque)`

Updated presentation link Not on Dropbox anymore 2013-02-12 21:30:26 +08:00			`Render big, timeseries data in the client. Uses CartoDB to generate a datacube format. For a brief introduction to the format and methods, see our [presentation slides](http://gijs.github.com/images/cartodb_datacubes.pdf)`
readme 2012-10-01 07:46:11 +08:00
readme 2012-10-01 15:37:20 +08:00			`CartoDB users can use this code right away. Specify your username/tablename and datecolumn to get mapping time immediatley.`
readme 2012-10-01 07:48:30 +08:00
			`Have fun!`

readme 2013-09-30 23:01:56 +08:00			`* Play with your own data: http://cartodb.github.com/torque/`
Updated presentation link Not on Dropbox anymore 2013-02-12 21:30:26 +08:00			`* The Guardian's Data Blog write-up of Royal Navy ships in WWI: http://www.guardian.co.uk/news/datablog/interactive/2012/oct/01/first-world-war-royal-navy-ships-mapped`
readme 2013-09-30 23:01:56 +08:00			`* A car in Nürburgring track: http://cartodb.github.com/torque/examples/car.html`
Update README.md first piece of documentation :) 2013-08-19 22:39:42 +08:00
			`## Torque library reference`

			`Torque lets you render big, timeseries or categorical data in the client. This is useful for many modern applications that need more than just a static map. Early versions of Torque have been used to visualize human movement, Twitter activity, biodiversity data, and many more large-scale datasets.`

updated link to torque cubes reference, fixes #50 2015-08-25 16:06:01 +08:00			`The library uses CartoDB to generate a [layercube](https://github.com/CartoDB/tilecubes/blob/master/2.0/spec.md) format. For a brief introduction to the format and methods, see our [presentation slides](http://gijs.github.com/images/cartodb_datacubes.pdf). If you are not using CartoDB to host your data, you can modify the input parameters to point toward any layercube service.`
Update README.md first piece of documentation :) 2013-08-19 22:39:42 +08:00
			`### Getting started`

			`The simplest way to use a visualization with Torque is...`

			`<div class="margin20"></div>`
			`<div class="code_title">Create a simple Torque visualization</div>`
			``` javascript
updated readme example 2013-11-27 18:06:48 +08:00			`...`
			`<body>`
			`<div id="map"></div>`
			`</body>`
			`...`
			`// define the torque layer style using cartocss`
			`var CARTOCSS = [`
			`'Map {',`
			`'-torque-time-attribute: "date";',`
			`'-torque-aggregation-function: "count(cartodb_id)";',`
			`'-torque-frame-count: 760;',`
			`'-torque-animation-duration: 15;',`
			`'-torque-resolution: 2',`
			`'}',`
			`'#layer {',`
			`' marker-width: 3;',`
			`' marker-fill-opacity: 0.8;',`
			`' marker-fill: #FEE391; ',`
			`' comp-op: "lighten";',`
			`' [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: 10; marker-fill-opacity: 0.05;}',`
			`' [frame-offset = 2] { marker-width: 15; marker-fill-opacity: 0.02;}',`
			`'}'`
			`].join('\n');`


			`var map = new L.Map('map', {`
			`zoomControl: true,`
			`center: [40, 0],`
			`zoom: 3`
			`});`

			`L.tileLayer('http://{s}.api.cartocdn.com/base-dark/{z}/{x}/{y}.png', {`
			`attribution: 'CartoDB'`
			`}).addTo(map);`

			`var torqueLayer = new L.TorqueLayer({`
			`user : 'viz2',`
			`table : 'ow',`
			`cartocss: CARTOCSS`
			`});`
			`torqueLayer.addTo(map);`
			`torqueLayer.play()`

Update README.md first piece of documentation :) 2013-08-19 22:39:42 +08:00			`<script>`
			```
fixed readme 2013-09-30 23:00:25 +08:00			`[Grab the complete example source code](https://github.com/CartoDB/torque/blob/master/examples/navy_leaflet.html)`
Update README.md first piece of documentation :) 2013-08-19 22:39:42 +08:00			`<div class="margin20"></div>`

added api links to read me 2013-09-30 22:39:28 +08:00			`### API`
			`[see reference](https://github.com/CartoDB/torque/blob/master/doc/API.md)`