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 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``
|
- 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.
|
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)
|
## L.TorqueLayer(options)
|
||||||
|
|
||||||
_Arguments_:
|
One of two core classes for the Torque library - it is used to create an animated torque layer with custom settings.
|
||||||
* 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'
|
|
||||||
|
|
||||||
## L.TorqueLayer.setKey(time: number)
|
### Usage example
|
||||||
|
|
||||||
_Arguments_
|
```js
|
||||||
* time: set time to be displayed. Should be a number between [0, steps)
|
// initialize a torque layer that uses the CartoDB account details and SQL API to pull in data
|
||||||
## L.TorqueLayer.setCartoCSS(cartocss: string)
|
var torqueLayer = new L.TorqueLayer({
|
||||||
_Arguments_
|
user : 'viz2',
|
||||||
* cartocss: cartocss string that contains the point style. Torque does not support the full cartocss spec, only a small subset.
|
table : 'ow',
|
||||||
``value`` and ``zoom`` variables can be used. ``value`` is the value of aggregation (see ``countby`` constructor option). ``zoom`` is the current zoom being rendered
|
column : 'date',
|
||||||
|
countby : 'count(cartodb_id)',
|
||||||
|
resolution : 1,
|
||||||
|
is_time : true,
|
||||||
|
steps : 750,
|
||||||
|
pixel_size : 3,
|
||||||
|
blendmode : 'lighter'
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
```
|
### Options
|
||||||
#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; }
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
|
##### 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)
|
## L.TiledTorqueLayer(options)
|
||||||
creates a static visualization
|
|
||||||
_Arguments_:
|
One of two core classes for the Torque library - it is used to create a static torque layer with client side filtering.
|
||||||
* options:
|
|
||||||
- provider: 'url_template',
|
##### Provider options
|
||||||
- url: tile template url e.g 'http://host.com/{z}/{x}/{y}.json', (note to Andrew: link here to the json data format)
|
| Option | type | Default | Description |
|
||||||
- resolution: data resolution, e.g 4
|
|-----------|:-----------|:----------|:---------------------------------------|
|
||||||
|
| 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)
|
##### Display options (Note to Santana: is blendmode here? or above even?)
|
||||||
set keys to show, if it's an array all the keys in that array are accumulated
|
| 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_:
|
### Style options
|
||||||
```
|
|
||||||
#layer {
|
| Method | options | returns | Description |
|
||||||
polygon-fill: #FFFF00;
|
|-----------|:-----------|:----------|:---------------------------------------|
|
||||||
[value >= 10] { polygon-fill: #FFCC00; }
|
| ```setCartoCSS(cartocss)``` | ```cartocss string``` | ```this``` | style the map rendering using client-side cartocss |
|
||||||
[value >= 100] { polygon-fill: #FF9900; }
|
|
||||||
[value >= 1000] { polygon-fill: #FF6600; }
|
``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).
|
||||||
[value >= 10000] { polygon-fill: #FF3300; }
|
|
||||||
[value > 100000] { polygon-fill: #C00; }
|
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)
|
# gmaps layers (TODO)
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user