Merge branch 'new_torque' of github.com:CartoDB/torque into new_torque
This commit is contained in:
javi
commit
6956acd9b8
181
doc/API.md
181
doc/API.md
@ -1,78 +1,153 @@
|
||||
|
||||
# Torque API
|
||||
|
||||
Torque provides two kinds of visulizations.
|
||||
Torque provides two kinds of visualizations.
|
||||
|
||||
- static: provides a way to create heatmap like visualizations (note for Andrew: fon). see ``TorqueLayer``
|
||||
- dinamyc: animate points over a map (note for Andrew: Navy) see ``TiledTorqueLayer``
|
||||
- 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)
|
||||
|
||||
_Arguments_:
|
||||
* options: object that contains the following attributes:
|
||||
- user: cartodb username
|
||||
- table: table name
|
||||
- column: time column
|
||||
- countby: aggregation per pixel, e.g: 'count(cartodb_id)',
|
||||
- resolution: pixel resolution,
|
||||
- is_time: true or false,
|
||||
- steps: animation steps, e.g: 750,
|
||||
- blendmode: canvas blend mode 'lighter'
|
||||
One of two core classes for the Torque library - it is used to create an animated torque layer with custom settings.
|
||||
|
||||
## L.TorqueLayer.setKey(time: number)
|
||||
### Usage example
|
||||
|
||||
_Arguments_
|
||||
* time: set time to be displayed. Should be a number between [0, steps)
|
||||
## L.TorqueLayer.setCartoCSS(cartocss: string)
|
||||
_Arguments_
|
||||
* cartocss: cartocss string that contains the point style. Torque does not support the full cartocss spec, only a small subset.
|
||||
``value`` and ``zoom`` variables can be used. ``value`` is the value of aggregation (see ``countby`` constructor option). ``zoom`` is the current zoom being rendered
|
||||
```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,
|
||||
is_time : true,
|
||||
steps : 750,
|
||||
pixel_size : 3,
|
||||
blendmode : 'lighter'
|
||||
});
|
||||
```
|
||||
|
||||
```
|
||||
#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; }
|
||||
}
|
||||
```
|
||||
### 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 |
|
||||
|
||||
##### Dynamic/static options (Note for Santana: we can remove this option?)
|
||||
| Option | type | Default | Description |
|
||||
|-----------|:-----------|:----------|:---------------------------------------|
|
||||
| is_time | boolean | ```true``` | Determines if the drawing is static or dynamic/animated |
|
||||
|
||||
|
||||
##### Display options
|
||||
| Option | type | Default | Description |
|
||||
|-----------|:-----------|:----------|:---------------------------------------|
|
||||
| steps | integer | ```100``` | The number of steps to divide the data into for animated renderings |
|
||||
| resolution| numeric | ```2``` | The x and y dimensions of each pixel as returned by the data|
|
||||
| blendmode | boolean | ```null``` | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas |
|
||||
|
||||
### Play options
|
||||
|
||||
| Method | options | returns | Description |
|
||||
|-----------|:-----------|:----------|:---------------------------------------|
|
||||
| ```setKey(time)``` | ```time numeric``` | ```this``` | sets the animation to the step indicated by ```time```, must be between 0 and N where N equals the number of steps|
|
||||
|
||||
|
||||
### Style options
|
||||
|
||||
| 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; }
|
||||
}
|
||||
```
|
||||
|
||||
## L.TiledTorqueLayer(options)
|
||||
creates a static visualization
|
||||
_Arguments_:
|
||||
* options:
|
||||
- provider: 'url_template',
|
||||
- url: tile template url e.g 'http://host.com/{z}/{x}/{y}.json', (note to Andrew: link here to the json data format)
|
||||
- resolution: data resolution, e.g 4
|
||||
|
||||
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 |
|
||||
|
||||
|
||||
## L.TiledTorqueLayer.setKey(keys: number|array)
|
||||
set keys to show, if it's an array all the keys in that array are accumulated
|
||||
##### 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 | ```null``` | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas |
|
||||
|
||||
## L.TiledTorqueLayer.setCartoCSS(cartocss: string)
|
||||
### Filtering options
|
||||
|
||||
``value`` and ``zoom`` variables can be used. only ``polygon-fill`` property is supported currently
|
||||
| Method | options | returns | Description |
|
||||
|-----------|:-----------|:----------|:---------------------------------------|
|
||||
| ```setKey(keys)``` | ```keys numeric/array``` | ```this``` | which data categories to display on the map |
|
||||
|
||||
_Example_:
|
||||
```
|
||||
#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; }
|
||||
}
|
||||
```
|
||||
### 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`` property is 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; }
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
# gmaps layers (TODO)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user