cartodb/torque
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

split files

Browse Source
This commit is contained in:
Carlos Matallín 2015-12-14 20:16:52 +01:00
parent 6f35d6399a
commit 31920d0d73
2 changed files with 315 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
doc/getting_started.md Normal file
View File

@ -0,0 +1,155 @@
# Getting Started with Torque.js
Torque.js is a JavaScript library that enables you to animate time series data. Torque.js uses tile cubes, which are JSON representations of multidimensional data with geospatial coordinates. [Tile cube specifications](http://wiki.osgeo.org/wiki/Tile_Map_Service_Specification
) render data on the client, to optimize the transfer of temporal and categorical data for maps.
**Tip:** Torque is both a spatial and temporal aggregator. It does not plot your exact lat/lon points, it lays an invisible grid over your map, and draws one marker for each grid cell that contains points (representing an aggregation of all of the points in the grid cell). You can control the size of this grid with the CartoCSS [`-torque-resolution`](/cartodb-platform/cartocss/properties-for-torque/#torque-resolution-float) property. You are also able to control the type of aggregation with the CartoCSS [`-torque-aggregation-function`](/cartodb-platform/cartocss/properties-for-torque/#torque-aggregation-function-keyword). For more details, see the wiki page about how [Torque aggregates data](https://github.com/CartoDB/torque/wiki/How-spatial-aggregation-works).
## Implementing Torque.js
The following workflow describes how to implement Torque.js:
Workflow | Details
--- | ---
Preparing your Torque Data | When visualizing Torque style maps, it is required that you normalize your data to show a total count, or a range, of `0`-`255`. For more details, see this description about [statistical normalization](https://books.google.com/books?id=FrUQHIzXK6EC&pg=PT347&lpg=PT347&dq=choropleth+normalization&source=bl&ots=muDZhsb2jT&sig=DbomJnKedQjaKvcQgm_sVqHBt-8&hl=en&sa=X&ved=0CCYQ6AEwAjgKahUKEwje0ee8qaTHAhUCZj4KHRF5CjM#v=onepage&q=choropleth%20normalization&f=false).<br /><br />Currently, you can only animate Torque point data. Line, polygon, and multipoint data are not supported for Torque animation.<br /><br />**Note:** When importing Torque data, CartoDB uploads and assumes timezones are in UTC format by default. To specify a different timezone format, you must use the SQL API to import data into CartoDB.
Initialize the Torque.js Layer | Specify your username, tablename and date column to add a Torque layer to your map<br /><br /><span class="wrap-border"><img src="/img/layout/torque/initialize_torquejs.jpg" alt="Intialize Torque.js" /></span>
Install the required CartoDB Torque Libraries | The Torque.js library interacts with CartoDB to generate the Torque tile format. If you are hosting your data on an external connector, you can modify the input parameters to redirect to any "Torque tiles service".<br /><br />- For [basic Torque.js](#torque-library), you can export Torque tiles from your CartoDB account or use a local Postgres installation<br /><br />- For [advanced interaction methods](#advanced-torquejs-libraries), you must download the latest Torque.js source code
Include all Torque Tiles Specifications | [Torque tile specifications](#torque-tiles-specifications) define the TorqueMap Metadata and tileset information.<br /><br />**Note:** All Torque tile fields in the specification are required.
Customize your Animation | Style and customize your animations with [CartoCSS Properties for Torque Style Maps](/cartodb-platform/cartocss/properties-for-torque/)
## Torque Library
Torque lets you render bigdata&trade;, time series or categorical data interactively. This is useful when you need to go beyond a static map, and create visualizations from temporal datasets. You can customize how your animated data appears in order to map such things as human movement, Twitter activity, biodiversity data, and other large-scale datasets.
- Export Torque tiles from your CartoDB account, or use a local Postgres installation [https://github.com/CartoDB/torque-gen](https://github.com/CartoDB/torque-gen)
- Install [https://github.com/CartoDB/torque/blob/master/dist/torque.js](https://github.com/CartoDB/torque/blob/master/dist/torque.js)
## Advanced Torque.js Libraries
If you are interested in using advanced interaction methods, it is a prerequisite to load the Torque.js library before using the advanced interaction methods.
- Download the [latest release](https://github.com/CartoDB/torque/releases) of the Torque.js source code
## Torque Tiles Specifications
Torque tiles are JSON representations of multidimensional data, with geospatial coordinates, that utilizes client-side resolution for rendering data. This optimizes the transfer of data for your Torque maps. Torque tile specifications are defined by two document types, Metadata and Tiles. The Metadata document describes the shared information across the Torque tile dataset. For each tile requested, there is a Tile document returned, which describes the data for that tile.
### Metadata
The TorqueMap Metadata document describes key tileset information, and includes the following fields:
Metadata Field | Description
--- | ---
`start`| start time, in steps or unix timestamp
`end`| end time, in steps or unix timestamp
`resolution`| the pixel resolution,by the power of two (1/4, 1/2,... 2, 4, 16), for a scale of 256 x 256 pixels<br /><br />**Note:** TileCubes are typically rendered on tiles of 256 x 256 pixels. It is recommended that you choose a scale that renders perfectly along the borders of the 256 x 256 tile, otherwise there may be issues rendering artifacts. The available pixel resolutions are: `1, 2, 4, 8, 16, 32, 64, 128, 256`
`data_steps`| number of steps (in integer format)
`column_type`| "integer" or "date", default "integer"
`minzoom`| minimum zoom level, optional
`maxzoom`| max zoom level, optional
`tiles`| tile array for this set, **required**
`bounds`| [bounding box](http://wiki.openstreetmap.org/wiki/Bounding_Box) for tileset, optional
#### Example of Metadata Document
{% highlight js %}
{
start: 0,
end: 100,
resolution: 2
# scale: 1/resolution,
data_steps: 365,
column_type: "number"
"minzoom": 0,
"maxzoom": 11,
"tiles": [
'http://a.host.com/{z}/{x}/{y}.torque.json',
'http://b.host.com/{z}/{x}/{y}.torque.json',
'http://c.host.com/{z}/{x}/{y}.torque.json',
'http://d.host.com/{z}/{x}/{y}.torque.json'
],
"bounds": [ -180, -85.05112877980659, 180, 85.0511287798066 ]
}
{% endhighlight %}
### Tiles
The TorqueMap Tiles document contains the required, core set of information to be rendered. This includes the number of pixels for the data, and the x and y values for each pixel.
#### The URL Schema
`http://host.com/{z}/{x}/{y}.torque.[json|bin]`
#### Tile Format
Each Torque tile is a JSON document containing an array, each of whose elements represents a point within the tile. The tile format is notated using the following format:
Tile Format | Type | Description
--- | --- |
`x`| ` integer` | x pixel coordinate in tile system reference
`y`| `integer` | y pixel coordinate in tile system reference
`steps` | | time slots when this pixel is **active**, there is data at that time
`values` | | values for each time slot<br /><br />**Tip:** You can use the values column to store encoding categories for your data
#### Extracting Tile Results for Calculations
You can extract the pixel position, and the current time, with the Tile document results.
##### Extract the Pixel Position
To extract the pixel position for the tile, use the following calculation:
`pixel_x = x * resolution`
`pixel_y = y * resolution`
Where:
`x` and `y` are in range [0, 256/resolution] to render the final pixel position (based on 256 x2 56 tiles).
The coordinate origin for Torque tiles is the bottom left corner of the grid.
##### Extract the Current Time
To extract the current time from the Tile document, use the following calculation:
`current_time = translate.start + step * (translate.end - translate.start)/data_steps;`
Where:
The `current_time`, `translate.start, translate.end`, and `data_steps` values are used to extract the time.
##### Tile Format Example
{% highlight js %}
[
{
x: 25,
y: 77,
values: [ 1, 10 ],
steps: [214, 215]
},
...
]
{% endhighlight %}
### Errors
All Torque tile fields in the specification are required. If a tile returns with no data or no value, _Uncaught TypeErrors_ may appear. For example, suppose you have `x, y, values` and `steps` defined, but `data_steps` are not defined in integer format, you will receive an error.
## Additional Torque Resources
The following links contain examples, and other public information, about using Torque maps.
- Torque [CartoCSS Reference page](https://github.com/cartodb/torque-reference), useful for building parsers, tests, compilers, and syntax highlighting/checking
- CartoDB repository of [examples](https://github.com/CartoDB/torque/tree/master/examples)
- A CartoDB [time example](http://cartodb.github.com/torque/) of a Torque map and data
- CartoDB wiki page describing [how spatial aggregration works](https://github.com/CartoDB/torque/wiki/How-spatial-aggregation-works)
- The [Guardian's Data Blog](http://www.guardian.co.uk/news/datablog/interactive/2012/oct/01/first-world-war-royal-navy-ships-mapped) about Royal Navy ships in WWI using a Torque map
- An example of how to create a [simple Torque visualization](https://github.com/CartoDB/torque#getting-started) and the [source code](https://github.com/CartoDB/torque/blob/master/examples/navy_leaflet.html) used to create the example
- An example of how to use CartoDB.js to [add a Torque layer from a named map with auth_tokens enabled](https://gist.github.com/chriswhong/a4d1e6305ecaf2ad507a)

160
doc/torque_api.md Normal file
View File

@ -0,0 +1,160 @@
# Torque API Methods
Torque API methods can be applied when creating a visualization using the [CartoDB.js API methods](/cartodb-platform/cartodb-js/api-methods/).
### L.TorqueLayer(options)
One of two core classes for the Torque library - it is used to create an animated torque layer with custom settings.
#### Arguments
##### Provider options
Name | Description
--- | ---
provider | A string object, where is the data coming from. Default value is `sql_api`
options |
--- | ---
&#124;_ sql_api |
&#124;_ url_template |
&#124;_ windshaft |
{% comment %}writer note_csobier: for consistency, describe options above and add ### Returns section.{% endcomment %}
#### 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',
cartocss: CARTOCSS
});
```
##### CartoDB Data Options (SQL API Provider)
Name | Description
--- | ---
user_name | A string object, your CartoDB [account name](/cartodb-editor/your-account/#account). Default value is ```null```
table_name | A string object, the CartoDB table name where data is found (also known as a dataset.) Default value is ```null```
query | A string object, the SQL query to be performed to fetch the data. Default value is ```null```.<br/><br/>You must use this param or table, but not at the same time
cartocss | A string object, the CartoCSS style for the map. Default value is ```null```
loop | A boolean object that defines the animation loop. Default value is ```true```. If ```false```, the animation is paused when it reaches the last frame
**Tip:** For a Torque category layer that is created dynamically with `cartodb.createLayer`, the SQL query must explicitly include how to build the torque_category column. You must include both the `sql` and `table_name` parameters. See this [createLayer with torque category layer](https://gist.github.com/danicarrion/dcaf6f00a71aa55134b4) example.
{% comment %}writer note_csobier: for consistency, add ### Returns section and ### Example. Note that the following table show some returns that do not make much sense to me, I did not edit the tables below, except to remove blank options columns.{% endcomment %}
### Time Methods
Method | Options | Returns | Description |
---|---|---|---|
`setStep(step)` | `time numeric` | `this` | the value must be between 0 and the total number of `steps` in the animation
`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)
`toggle()` | | `this` | toggles (pause/play) the animation
`getStep()` | | current animation step (integer) | gets the current animation step. A step is considered an animation frame
`getTime()` | | current animation time (Date) | gets the real animation time
`isRunning()` | | `true`/`false` | describes whether the Torque layer is playing or is stopped
**Note:** Torque.js interprets the beginning and ending date/time from your "Time Column" as one block, then divides that up into Steps, depending on the number you set. It does not necessarily draw one frame for each row.
### Layer Control Methods
Method | Options | Returns | Description
---|---|---|---
`hide()` | none | `this` | hides the Torque layer
`show()` | none| `this` | shows the Torque layer
### Style Methods
Method | Options | Returns | Description
---|---|---|---|
`setCartoCSS(cartocss)` | `cartocss string` | `this` | style the map rendering using client-side cartocss (not available with named maps)
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](/cartodb-platform/cartocss/properties-for-torque/). `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.
#### Example
This CartoCSS example should be `string` encoded in Javascript.
```scss
#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 previous frame
[frame-offset = 2] { marker-fill: red; marker-width: 30; marker-fill-opacity: 0.02;}' // renders two frames ago from the current being rendered
}
```
### Data Methods
Method | Options | Returns | Description
---|---|---|---
`setSQL(sql statement)` | `SQL string` | `this` | Change the SQL on the data table (not available with named maps)
`error(callback)` | `callback function with a list of errors as argument` | `this` | specifies a callback function to run if there are query errors
#### Example
SQL Example to limit the data used in the Torque map.
```js
torqueLayer.setSQL("SELECT * FROM table LIMIT 100");
```
### Events
_**Note:** You can only run events after the [required libraries](/cartodb-platform/torque/torquejs-getting-started/#advanced-torquejs-libraries) are loaded. Otherwise, the [interaction methods](/cartodb-platform/torque/torque-interaction-methods/) will not work._
Events in Torque follow the format:
```js
torqueLayer.on('event-type', function([callback_obj]) {
// do something
});
```
Events | Callback Object | Description
---|---|---
`change:steps` | current step | When a map changes steps, this event is triggered
`change:time` | current time, step number | When a map changes time, this event is triggered
`play` | none | Triggered when the Torque layer is played
`pause` | none | Triggered when the Torque layer is paused
`stop` | none | Triggered when the Torque layer is stopped
`load` | none | Triggered when the Torque layer is loaded
#### Example
An event example to print the current step to the console log.
```js
torqueLayer.on('change:steps', function(step) {
// do something with step
console.log('Current step is ' + step);
});
```
## Google Maps Layers
### GMapsTorqueLayer(_options_)
This class does exactly the same as ``L.TorqueLayer`` but using Google Maps instead. The main difference is that this class
is not a layer but is an overlay, so in order to add it to the a map use, ``layer.setMap`` instead of ``overlayMapTypes``. See the [Overlay View](https://developers.google.com/maps/documentation/javascript/reference#OverlayView) reference in Google Maps API doc.
#### Options
Name | Description
--- | ---
map | A google.maps.Map instance