190 lines
8.8 KiB
Markdown
190 lines
8.8 KiB
Markdown
|
|
# 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
|
|
|
|
```js
|
|
// 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](CartoCSS.md). ``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
|
|
|
|
```css
|
|
#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](CartoCSS.md).
|
|
|
|
TorqueLayer currently expects ```polygon``` styling
|
|
|
|
##### CartoCSS Example
|
|
|
|
This should be ```string``` encoded in Javascript
|
|
|
|
```css
|
|
#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](https://developers.google.com/maps/documentation/javascript/reference#OverlayView) 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.
|
|
|
|
```js
|
|
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
|