From 31920d0d737185e417b65e35be2a36588ac11b40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Matall=C3=ADn?= Date: Mon, 14 Dec 2015 20:16:52 +0100 Subject: [PATCH 01/23] split files --- doc/getting_started.md | 155 +++++++++++++++++++++++++++++++++++++++ doc/torque_api.md | 160 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 315 insertions(+) create mode 100644 doc/getting_started.md create mode 100644 doc/torque_api.md diff --git a/doc/getting_started.md b/doc/getting_started.md new file mode 100644 index 0000000..9f86c9c --- /dev/null +++ b/doc/getting_started.md @@ -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).

Currently, you can only animate Torque point data. Line, polygon, and multipoint data are not supported for Torque animation.

**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

Intialize Torque.js +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".

- For [basic Torque.js](#torque-library), you can export Torque tiles from your CartoDB account or use a local Postgres installation

- 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.

**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™, 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

**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

**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) diff --git a/doc/torque_api.md b/doc/torque_api.md new file mode 100644 index 0000000..58c0167 --- /dev/null +++ b/doc/torque_api.md @@ -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 | +--- | --- +|_ sql_api | +|_ url_template | +|_ 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```.

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 From 985c0b0eb55fda0ed28c12e3cf5ee51ae3928e2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Matall=C3=ADn?= Date: Mon, 14 Dec 2015 20:19:38 +0100 Subject: [PATCH 02/23] split files --- doc/API.md | 161 ++--------------------------------------------------- 1 file changed, 4 insertions(+), 157 deletions(-) diff --git a/doc/API.md b/doc/API.md index 53e73b3..86f0c53 100644 --- a/doc/API.md +++ b/doc/API.md @@ -1,161 +1,8 @@ - # Torque API +Torque.js is an efficient and stylish rendering method to animate your data. Torque.js uses TileCubes, which are JSON representations of multidimensional data with geospatial coordinates, to render data on the client. -## 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', - cartocss: CARTOCSS - }); -``` - -### Options - -##### Provider options - -| Option | type | Default | Description | Options | -|-----------|:-----------|:----------|:---------------------------------------|---------| -| provider | string | ```sql_api``` | Where is the data coming from | `sql_api`, `url_template`, or `windshaft` | - -##### CartoDB data options (SQL API provider) - -| Option | type | Default | Description | -|-----------|:-----------|:----------|:---------------------------------------| -| user_name | string | ```null``` | CartoDB account name. Found from: http://accountname.cartodb.com| -| table_name | string | ```null``` | CartoDB table name where data is found | -| query | string | ```null``` | SQL query to be performed to fetch the data. You must use this param or table, not at the same time | -| cartocss | string | ```null``` | CartoCSS style for this map | -| loop | boolean | ```true``` | If ```false```, the animation is paused when it reaches the last frame | - - -### 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) -| ```toggle()```| | ```this```| toggles (pause/play) the animation -| ```getStep()``` | | current animation step (integer) | gets the current animation step -| ```getTime()``` | | current animation time (Date) | gets the real animation time -| ```isRunning()``` | | `true`/`false` | describes whether the Torque layer is playing or is stopped - -### 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](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 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 | - -##### SQL Example - -Limit the data used in the Torque map. -```js -torqueLayer.setSQL("SELECT * FROM table LIMIT 100"); -``` - -### Interaction methods (only available for Leaflet) -| Method | options | returns | Description | -|-----------|:-----------|:----------|:---------------------------------------| -| ```getValueForPos(x, y[, step])```| | an object like { bbox:[], value: VALUE } if there is value for the pos, null otherwise | allows to get the value for the coordinate (in map reference system) for a concrete step. If step is not specified the animation one is used. This method is expensive in terms of CPU so be careful. It returns the value from the raster data not the rendered data | -| ```getValueForBBox(xstart, ystart, xend, yend)```| | a number | returns an accumulated numerical value from all the torque areas within the specified bounds | -| ```getActivePointsBBox(step)```| | list of bbox | returns the list of bounding boxes active for ``step`` -| ```getValues(step)```| | list of values| returns the list of values for the pixels active in ``step`` -| ```invalidate()```| | | forces a reload of the layer data. - -### Interaction methods (only available for Leaflet) -| Method | options | returns | Description | -|-----------|:-----------|:----------|:---------------------------------------| -| ```getActivePointsBBox(step)```| | list of bbox | returns the list of bounding boxes active for ``step`` -| ```invalidate()```| | | forces a reload of the layer data. - - -### Events -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 | - -##### Event Example - -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 - -##### options -| Option | type | Default | Description | -|-----------|:-----------|:----------|:---------------------------------------| -| map | google.maps.Map | | google.maps.Map instance | - -see ``L.TorqueLayer`` for the rest of the options. - +## Documentation +* [Getting Started with Torque.js](getting_started.md) +* [Torque API Methods](torque_api.md) From 77d9ac810c3a81d58cd52b25d711bd8c2151f20b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Matall=C3=ADn?= Date: Mon, 14 Dec 2015 20:29:14 +0100 Subject: [PATCH 03/23] split files --- doc/torque_api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/torque_api.md b/doc/torque_api.md index 58c0167..ec10d3f 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -14,11 +14,11 @@ Name | Description --- | --- provider | A string object, where is the data coming from. Default value is `sql_api` -options | +options |   --- | --- -|_ sql_api | -|_ url_template | -|_ windshaft | +|_ sql_api |   +|_ url_template |   +|_ windshaft |   {% comment %}writer note_csobier: for consistency, describe options above and add ### Returns section.{% endcomment %} From 4fe5cd21507b9a8a6fc6bb85d0b090a7ac36cbd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Matall=C3=ADn?= Date: Wed, 16 Dec 2015 11:46:32 +0100 Subject: [PATCH 04/23] docs: torque functions --- doc/torque_api.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/torque_api.md b/doc/torque_api.md index ec10d3f..f6e5e99 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -158,3 +158,10 @@ is not a layer but is an overlay, so in order to add it to the a map use, ``laye Name | Description --- | --- map | A google.maps.Map instance + + +## Torque Functions + +Since Torque API methods can be applied when creating a visualization using the [CartoDB.js API methods](/cartodb-platform/cartodb-js/api-methods/), these [Torque Functions](https://github.com/CartoDB/cartodb.js/blob/be76b55caeeb0dfc147e3fa36628d9e215717ce5/src/vis/vis.js#L229) are available. + +_**Note:** We are currently in the process of enhancing this functions and returns. A future documentation update will include complete descriptions of these Torque functions._ From 56cfe309bd79c57f6faa3861bbfd06d870857a89 Mon Sep 17 00:00:00 2001 From: csobier Date: Wed, 30 Dec 2015 09:21:30 -0500 Subject: [PATCH 05/23] added Raul's edits --- doc/API.md | 2 +- doc/getting_started.md | 2 +- doc/torque_api.md | 7 ++++--- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/API.md b/doc/API.md index 86f0c53..ce3bde2 100644 --- a/doc/API.md +++ b/doc/API.md @@ -1,6 +1,6 @@ # Torque API -Torque.js is an efficient and stylish rendering method to animate your data. Torque.js uses TileCubes, which are JSON representations of multidimensional data with geospatial coordinates, to render data on the client. +Torque.js is an efficient and stylish rendering method to animate your data. Torque.js uses [TileCubes](http://wiki.osgeo.org/wiki/Tile_Map_Service_Specification), which are JSON representations of multidimensional data with geospatial coordinates, to render data on the client. ## Documentation diff --git a/doc/getting_started.md b/doc/getting_started.md index 9f86c9c..6216585 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -32,7 +32,7 @@ Torque lets you render bigdata™, time series or categorical data interacti 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 +- Download the [latest registry version](https://www.npmjs.com/package/torque.js) of the Torque.js source code ## Torque Tiles Specifications diff --git a/doc/torque_api.md b/doc/torque_api.md index f6e5e99..a862ede 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -60,7 +60,7 @@ Method | Options | Returns | Description | `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. +**Note:** Torque.js interprets the beginning and ending date/time from your "Time Column" as one block, then divides that up into [Steps](/cartodb-platform/cartocss/properties-for-torque/#torque-frame-count-number), depending on the number you set. It does not necessarily draw one frame for each row. ### Layer Control Methods @@ -73,9 +73,10 @@ Method | Options | Returns | Description | Method | Options | Returns | Description ---|---|---|---| -`setCartoCSS(cartocss)` | `cartocss string` | `this` | style the map rendering using client-side cartocss (not available with named maps) +`setCartoCSS(cartocss)` | `cartocss string` | `this` | style the map rendering using client-side CartoCSS (not available with [Named maps](/cartodb-platform/maps-api/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. +Torque supports a limited subset of CartoCSS parameters, as described in the [torque-reference](https://github.com/cartodb/torque-reference). Alternatively, Mapnik supports the following [mapnik-reference](https://github.com/cartodb/torque-reference) for 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. From 2ced306f23c21af6965691c43fd42ee8ad9d9df2 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Wed, 13 Jan 2016 19:15:17 +0100 Subject: [PATCH 06/23] doc changes --- doc/torque_api.md | 64 ++++++++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 31 deletions(-) diff --git a/doc/torque_api.md b/doc/torque_api.md index a862ede..394efb5 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -1,51 +1,53 @@ -# 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/). +# Torque API ### L.TorqueLayer(options) -One of two core classes for the Torque library - it is used to create an animated torque layer with custom settings. +A layer to be added to a Leaflet map. It works as a regular tiled layer within the Leaflet tile pane, but instead of containing `` elements, it's composed of a single [``](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) where all markers are drawn. -#### Arguments - -##### Provider options - -Name | Description ---- | --- -provider | A string object, where is the data coming from. Default value is `sql_api` - -options |   ---- | --- -|_ sql_api |   -|_ url_template |   -|_ 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 +```javascript var torqueLayer = new L.TorqueLayer({ user: 'viz2', table: 'ow', - cartocss: CARTOCSS + cartocss: '' }); + +map.addLayer(torqueLayer); ``` -##### CartoDB Data Options (SQL API Provider) +#### Options 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```.

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 +resolution | Spatial resolution in pixels. A resolution of 1 means no spatial aggregation of the data. Its value must be a power of 2 +steps | Number of steps that the animation is divided into +animationDuration | Duration, in seconds, of the animation +zIndex | Z-Index CSS property of the layer +attribution | Attribution to be added in the bottom right of the map +maxZoom | Maximum zoom for the layer. +tileSize | Size, in pixels of the tiles + +##### Using your CartoDB credentials + +Name | Description +--- | --- +user | A string object, your CartoDB [account name](/cartodb-editor/your-account/#account). Default value is ```null``` +table | A string object, the CartoDB table name where data is found (also known as a dataset.) Default value is ```null``` + +##### Using a custom SQL query + +Name | Description +--- | --- +query | A string object, the SQL query to be performed to fetch the data. Default value is ```null```.

You must use this param or table, but not at the same time **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 %} +##### Providing a TileJSON file + +Name | Description +--- | --- +tileJSON | A URL pointing to a valid [TileJSON](https://github.com/mapbox/tilejson-spec) file from which to get the Torque tile templates ### Time Methods @@ -109,7 +111,7 @@ Method | Options | Returns | Description #### Example -SQL Example to limit the data used in the Torque map. +SQL Example to limit the data used in the Torque map.§ ```js torqueLayer.setSQL("SELECT * FROM table LIMIT 100"); From 5c0232fa5f91c37508591445288f78defdc7baf9 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 11:47:57 +0100 Subject: [PATCH 07/23] fixes hierarchy --- doc/torque_api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/torque_api.md b/doc/torque_api.md index 394efb5..739056c 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -49,7 +49,7 @@ Name | Description --- | --- tileJSON | A URL pointing to a valid [TileJSON](https://github.com/mapbox/tilejson-spec) file from which to get the Torque tile templates -### Time Methods +#### Time Methods Method | Options | Returns | Description | ---|---|---|---| @@ -64,14 +64,14 @@ Method | Options | Returns | Description | **Note:** Torque.js interprets the beginning and ending date/time from your "Time Column" as one block, then divides that up into [Steps](/cartodb-platform/cartocss/properties-for-torque/#torque-frame-count-number), depending on the number you set. It does not necessarily draw one frame for each row. -### Layer Control Methods +#### Layer Control Methods Method | Options | Returns | Description ---|---|---|--- `hide()` | none | `this` | hides the Torque layer `show()` | none| `this` | shows the Torque layer -### Style Methods +#### Style Methods Method | Options | Returns | Description ---|---|---|---| From 0749bdd0e1b95bf872e06d5e9c089943500f4d0a Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 11:48:17 +0100 Subject: [PATCH 08/23] changes provider title --- doc/torque_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/torque_api.md b/doc/torque_api.md index 739056c..a8883a3 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -28,7 +28,7 @@ attribution | Attribution to be added in the bottom right of the map maxZoom | Maximum zoom for the layer. tileSize | Size, in pixels of the tiles -##### Using your CartoDB credentials +##### Using a CartoDB table directly Name | Description --- | --- From 093fc94076e50c1b1cb52408814bed2ea1a4c327 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 11:48:29 +0100 Subject: [PATCH 09/23] adds a valid torque css example --- doc/torque_api.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/doc/torque_api.md b/doc/torque_api.md index a8883a3..a2cdad0 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -84,21 +84,20 @@ TorqueLayer currently expects `marker` styling. #### Example -This CartoCSS example should be `string` encoded in Javascript. +This is how a minimal example of a stylesheet for a Torque visualisation would look like. -```scss +```css +Map { +-torque-time-attribute: "date"; +-torque-aggregation-function: "count(cartodb_id)"; +-torque-frame-count: 760; +-torque-animation-duration: 15; +-torque-resolution: 2; +} #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 + marker-width: 3; + marker-fill-opacity: 0.8; + marker-fill: #FEE391; } ``` From 2675df3526b7753207672ee0e53672062d5dd1a4 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 11:50:06 +0100 Subject: [PATCH 10/23] indentation --- doc/torque_api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/torque_api.md b/doc/torque_api.md index a2cdad0..405ea8e 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -88,11 +88,11 @@ This is how a minimal example of a stylesheet for a Torque visualisation would l ```css Map { --torque-time-attribute: "date"; --torque-aggregation-function: "count(cartodb_id)"; --torque-frame-count: 760; --torque-animation-duration: 15; --torque-resolution: 2; + -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; From 990c52999af698082b48b101a815afef661d74f4 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 12:12:11 +0100 Subject: [PATCH 11/23] adjusts language of css description, removes duplicated information --- doc/torque_api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/torque_api.md b/doc/torque_api.md index 405ea8e..3556c98 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -77,8 +77,7 @@ Method | Options | Returns | Description ---|---|---|---| `setCartoCSS(cartocss)` | `cartocss string` | `this` | style the map rendering using client-side CartoCSS (not available with [Named maps](/cartodb-platform/maps-api/named-maps/)) -Torque supports a limited subset of CartoCSS parameters, as described in the [torque-reference](https://github.com/cartodb/torque-reference). Alternatively, Mapnik supports the following [mapnik-reference](https://github.com/cartodb/torque-reference) for 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. +Torque supports a limited subset of CartoCSS rules defined in the [torque-reference](https://github.com/cartodb/torque-reference). To see the full list of supported rules, read the [Torque CartoCSS documentation](/cartodb-platform/cartocss/properties-for-torque/). `value` and `zoom` variables can be used. `value` is the value of aggregation. `zoom` is the current zoom being rendered. TorqueLayer currently expects `marker` styling. From cd9e1a34579beff7d0bf7e57d574601f69dbbcf0 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 12:12:33 +0100 Subject: [PATCH 12/23] adds zoom and value to examples --- doc/torque_api.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/torque_api.md b/doc/torque_api.md index 3556c98..ed72496 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -98,6 +98,12 @@ Map { marker-fill-opacity: 0.8; marker-fill: #FEE391; } +#layer[value = 4] { // Use of the value variable, generated by the function specified in -torque-aggregation-function + marker-fill: #FABADA; +} +#layer[zoom = 12] { // Use of the zoom variable + marker-width: 10; +} ``` ### Data Methods From b0e04b7611843c912b4d60e6e327a59fad3b218b Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 12:14:05 +0100 Subject: [PATCH 13/23] typo --- doc/torque_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/torque_api.md b/doc/torque_api.md index ed72496..82c3ec5 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -115,7 +115,7 @@ Method | Options | Returns | Description #### Example -SQL Example to limit the data used in the Torque map.§ +SQL Example to limit the data used in the Torque map. ```js torqueLayer.setSQL("SELECT * FROM table LIMIT 100"); From 786af47be42ea518987ca4cff6afbc13762b5907 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 12:20:28 +0100 Subject: [PATCH 14/23] removes torque functions section --- doc/torque_api.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/doc/torque_api.md b/doc/torque_api.md index 82c3ec5..83c855a 100644 --- a/doc/torque_api.md +++ b/doc/torque_api.md @@ -165,10 +165,3 @@ is not a layer but is an overlay, so in order to add it to the a map use, ``laye Name | Description --- | --- map | A google.maps.Map instance - - -## Torque Functions - -Since Torque API methods can be applied when creating a visualization using the [CartoDB.js API methods](/cartodb-platform/cartodb-js/api-methods/), these [Torque Functions](https://github.com/CartoDB/cartodb.js/blob/be76b55caeeb0dfc147e3fa36628d9e215717ce5/src/vis/vis.js#L229) are available. - -_**Note:** We are currently in the process of enhancing this functions and returns. A future documentation update will include complete descriptions of these Torque functions._ From a04f1a7d5be64f33271020934e6c3fd3cce8d16f Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 12:49:10 +0100 Subject: [PATCH 15/23] corrected, culled content in abstract --- doc/getting_started.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index 6216585..3e20cb7 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -1,7 +1,6 @@ # 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. +Torque.js is a JavaScript library that enables you to display animated maps using time series data. Torque.js uses a [special tile specification](https://github.com/cartodb/torque-tiles), which consists of JSON representations of multidimensional data with geospatial coordinates. **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). From 3a0220194b8f55b31a605e8e5ade3bb84f1be1ff Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 17:15:29 +0100 Subject: [PATCH 16/23] adds browser rendering note --- doc/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index 3e20cb7..b140a1f 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -1,6 +1,6 @@ # Getting Started with Torque.js -Torque.js is a JavaScript library that enables you to display animated maps using time series data. Torque.js uses a [special tile specification](https://github.com/cartodb/torque-tiles), which consists of JSON representations of multidimensional data with geospatial coordinates. +Torque.js is a JavaScript library that enables you to display animated maps using time series data. Torque.js uses a [special tile specification](https://github.com/cartodb/torque-tiles), which consists of JSON representations of multidimensional data with geospatial coordinates. The Torque library parses these tiles and renders them in the browser. **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). From 4eb4bdbdc102b5e5726e6992638386a4cc61f0e9 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 17:15:45 +0100 Subject: [PATCH 17/23] fixes url template --- doc/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index b140a1f..8ab204c 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -82,7 +82,7 @@ The TorqueMap Tiles document contains the required, core set of information to b #### The URL Schema -`http://host.com/{z}/{x}/{y}.torque.[json|bin]` +`http://host.com/{z}/{x}/{y}.torque.json` #### Tile Format From fd828bb6b38d9dd9cd71ad8a0c8ab0da8ad5ed0a Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 17:16:00 +0100 Subject: [PATCH 18/23] puts the actual property names --- doc/getting_started.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index 8ab204c..880814d 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -90,10 +90,10 @@ Each Torque tile is a JSON document containing an array, each of whose elements 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

**Tip:** You can use the values column to store encoding categories for your data +`x__uint8`| ` integer` | x pixel coordinate in tile system reference +`y__unit8`| `integer` | y pixel coordinate in tile system reference +`dates__uint8` | | time slots when this pixel is **active**, there is data at that time +`vals__unit8` | | values for each time slot

**Tip:** You can use the values column to store encoding categories for your data #### Extracting Tile Results for Calculations @@ -127,10 +127,10 @@ The `current_time`, `translate.start, translate.end`, and `data_steps` values ar {% highlight js %} [ { - x: 25, - y: 77, - values: [ 1, 10 ], - steps: [214, 215] + x__uint8: 25, + y__uint8: 77, + vals__unit8: [ 1, 10 ], + dates__uint8: [214, 215] }, ... ] From b2b10868b0e703f773faec3e80bf0c3b3318c89e Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Thu, 14 Jan 2016 17:18:45 +0100 Subject: [PATCH 19/23] removes tm sign --- doc/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index 880814d..7ec024e 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -20,7 +20,7 @@ Customize your Animation | Style and customize your animations with [CartoCSS Pr ## Torque Library -Torque lets you render bigdata™, 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. +Torque lets you render large datasets containing 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) From 35150466140fbacb9ad51d4647c8c385c4a09a95 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Fri, 15 Jan 2016 16:49:31 +0100 Subject: [PATCH 20/23] starts rewrite --- doc/getting_started.md | 193 ++++++++++------------------------------- 1 file changed, 46 insertions(+), 147 deletions(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index 7ec024e..2226a98 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -1,154 +1,53 @@ -# Getting Started with Torque.js +#Getting started -Torque.js is a JavaScript library that enables you to display animated maps using time series data. Torque.js uses a [special tile specification](https://github.com/cartodb/torque-tiles), which consists of JSON representations of multidimensional data with geospatial coordinates. The Torque library parses these tiles and renders them in the browser. +Assuming you have a public dataset with a `date` column, it's really simple to create an animated map with the standalone Torque library. You need to have a Leaflet map prepared in an HTML page: -**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). +```html + + +
+ + + +``` -## Implementing Torque.js +For Torque to work with your table you only need a username, the name of the table, and a CartoCSS string to style the map. Leaflet's method `addTo` will add the torque layer to the map. `play` runs the animation with the options specified in the torque-specific CartoCSS properties -The following workflow describes how to implement Torque.js: +```html + +``` - -## Torque Library - -Torque lets you render large datasets containing 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 registry version](https://www.npmjs.com/package/torque.js) 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

**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` - -#### 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__uint8`| ` integer` | x pixel coordinate in tile system reference -`y__unit8`| `integer` | y pixel coordinate in tile system reference -`dates__uint8` | | time slots when this pixel is **active**, there is data at that time -`vals__unit8` | | values for each time slot

**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__uint8: 25, - y__uint8: 77, - vals__unit8: [ 1, 10 ], - dates__uint8: [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) From abe1dd457073b311e760896fec3f604146d85964 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Mon, 18 Jan 2016 11:46:59 +0100 Subject: [PATCH 21/23] getting started sguide --- doc/getting_started.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index 2226a98..89e36b3 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -1,6 +1,6 @@ #Getting started -Assuming you have a public dataset with a `date` column, it's really simple to create an animated map with the standalone Torque library. You need to have a Leaflet map prepared in an HTML page: +Although the most straightforward way to use Torque is through either the CartoDB editor, or by passing the layer's viz.json to [CartoDB.js](http://docs.cartodb.com/cartodb-platform/cartodb-js/getting-started/), many use cases work best with the standalone [Torque.js](https://github.com/CartoDB/torque/tree/master/dist). Assuming you have a public dataset with a `date` column, it's really simple to create an animated map with the library. First you need to have a Leaflet map prepared in an HTML page: ```html @@ -21,7 +21,7 @@ Assuming you have a public dataset with a `date` column, it's really simple to c ``` -For Torque to work with your table you only need a username, the name of the table, and a CartoCSS string to style the map. Leaflet's method `addTo` will add the torque layer to the map. `play` runs the animation with the options specified in the torque-specific CartoCSS properties +For Torque to work with your table you only need a username, the name of the table, and a CartoCSS string to style the map. Leaflet's method `addTo` will add the torque layer to the map. `play` runs the animation with the options specified in the CartoCSS properties ```html ``` +You can use any kind of tile source outside CartoDB, just by specifying the location of a [valid TileJSON](https://github.com/mapbox/tilejson-spec) file: + +```javascript + var torqueLayer = new L.TorqueLayer({ + tileJSON: 'http://url.to/tile.json' + cartocss: CARTOCSS + }); +``` + +Optionally, it is also possible to use a custom SQL query for your visualization: + +```javascript + var torqueLayer = new L.TorqueLayer({ + user : 'your_username', + table : 'your_table_name', + sql_query : 'SELECT * FROM your_table_name WHERE whatever' + cartocss: CARTOCSS + }); +``` + +Like in a video player, you can use animation control methods such as `play`, `stop` and `pause` at any point. Torque's animator fires a `change:time` event each time the animation "ticks" to the next frame, and there are a number of properties and methods that can be run during playback, which are detailed in the [API documentation](../torque_api.md). At any point, for example, the styling of the layer's markers can be changed using the `layer.setCartoCSS('##style##')`. + +#Usage examples +The best way to start learning about the library is by taking a look at some of the examples below: + +* A basic example using the WWI British Navy dataset - ([view live](http://cartodb.github.io/torque/examples/navy_leaflet.html) / [source code](https://github.com/CartoDB/torque/blob/master/examples/navy_leaflet.html)) +* Using tileJSON to fetch tiles - ([view live](http://cartodb.github.io/torque/examples/tilejson.html) / [source code](https://github.com/CartoDB/torque/blob/master/examples/tilejson.html)) +* A car's route at the Nürburgring track mapped in Torque - ([view live](http://cartodb.github.io/torque/examples/car.html) / [source code](https://github.com/CartoDB/torque/blob/master/examples/car.html)) \ No newline at end of file From 6638a13e1418b0bbc126dac8df51604bf345db65 Mon Sep 17 00:00:00 2001 From: Francisco Dans Date: Mon, 18 Jan 2016 11:55:09 +0100 Subject: [PATCH 22/23] adds resources --- doc/getting_started.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index 89e36b3..85191b5 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -1,4 +1,4 @@ -#Getting started +##Getting started Although the most straightforward way to use Torque is through either the CartoDB editor, or by passing the layer's viz.json to [CartoDB.js](http://docs.cartodb.com/cartodb-platform/cartodb-js/getting-started/), many use cases work best with the standalone [Torque.js](https://github.com/CartoDB/torque/tree/master/dist). Assuming you have a public dataset with a `date` column, it's really simple to create an animated map with the library. First you need to have a Leaflet map prepared in an HTML page: @@ -73,9 +73,21 @@ Optionally, it is also possible to use a custom SQL query for your visualization Like in a video player, you can use animation control methods such as `play`, `stop` and `pause` at any point. Torque's animator fires a `change:time` event each time the animation "ticks" to the next frame, and there are a number of properties and methods that can be run during playback, which are detailed in the [API documentation](../torque_api.md). At any point, for example, the styling of the layer's markers can be changed using the `layer.setCartoCSS('##style##')`. -#Usage examples +##Usage examples The best way to start learning about the library is by taking a look at some of the examples below: * A basic example using the WWI British Navy dataset - ([view live](http://cartodb.github.io/torque/examples/navy_leaflet.html) / [source code](https://github.com/CartoDB/torque/blob/master/examples/navy_leaflet.html)) * Using tileJSON to fetch tiles - ([view live](http://cartodb.github.io/torque/examples/tilejson.html) / [source code](https://github.com/CartoDB/torque/blob/master/examples/tilejson.html)) -* A car's route at the Nürburgring track mapped in Torque - ([view live](http://cartodb.github.io/torque/examples/car.html) / [source code](https://github.com/CartoDB/torque/blob/master/examples/car.html)) \ No newline at end of file +* A car's route at the Nürburgring track mapped in Torque - ([view live](http://cartodb.github.io/torque/examples/car.html) / [source code](https://github.com/CartoDB/torque/blob/master/examples/car.html)) + +## 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) \ No newline at end of file From 27e3480130da487ee8ed30b7fc3e508084c37edd Mon Sep 17 00:00:00 2001 From: csobier Date: Mon, 18 Jan 2016 12:46:23 -0500 Subject: [PATCH 23/23] applied minor edits to getting started section, based on our style guide --- doc/getting_started.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index 85191b5..38ecde0 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -1,6 +1,6 @@ -##Getting started +##Getting Started -Although the most straightforward way to use Torque is through either the CartoDB editor, or by passing the layer's viz.json to [CartoDB.js](http://docs.cartodb.com/cartodb-platform/cartodb-js/getting-started/), many use cases work best with the standalone [Torque.js](https://github.com/CartoDB/torque/tree/master/dist). Assuming you have a public dataset with a `date` column, it's really simple to create an animated map with the library. First you need to have a Leaflet map prepared in an HTML page: +Although the most straightforward way to use Torque is through either the CartoDB Editor, or by passing the layer's viz.json to [CartoDB.js](http://docs.cartodb.com/cartodb-platform/cartodb-js/getting-started/), many use cases work best with the standalone [Torque.js](https://github.com/CartoDB/torque/tree/master/dist). Assuming you have a public dataset with a `date` column, it is really simple to create an animated map with the library. First, you need to have a Leaflet map prepared in an HTML page: ```html @@ -21,7 +21,7 @@ Although the most straightforward way to use Torque is through either the CartoD ``` -For Torque to work with your table you only need a username, the name of the table, and a CartoCSS string to style the map. Leaflet's method `addTo` will add the torque layer to the map. `play` runs the animation with the options specified in the CartoCSS properties +For Torque to work with your table, you only need a username, the name of the table, and a CartoCSS string to style the map. Leaflet's method `addTo` adds the Torque layer to the map. `play` runs the animation with the options specified in the CartoCSS properties. ```html ``` -You can use any kind of tile source outside CartoDB, just by specifying the location of a [valid TileJSON](https://github.com/mapbox/tilejson-spec) file: +You can use any kind of tile source outside CartoDB, by specifying the location of a [valid TileJSON](https://github.com/mapbox/tilejson-spec) file: ```javascript var torqueLayer = new L.TorqueLayer({ @@ -71,9 +71,9 @@ Optionally, it is also possible to use a custom SQL query for your visualization }); ``` -Like in a video player, you can use animation control methods such as `play`, `stop` and `pause` at any point. Torque's animator fires a `change:time` event each time the animation "ticks" to the next frame, and there are a number of properties and methods that can be run during playback, which are detailed in the [API documentation](../torque_api.md). At any point, for example, the styling of the layer's markers can be changed using the `layer.setCartoCSS('##style##')`. +Like in a video player, you can use animation control methods such as `play`, `stop` and `pause` at any point. Torque's animator fires a `change:time` event each time the animation "ticks" to the next frame, and there are a number of properties and methods that can be run during playback, which are detailed in the [API documentation](/cartodb-platform/torque/torqueapi/). At any point, for example, the styling of the layer's markers can be changed using the `layer.setCartoCSS('##style##')`. -##Usage examples +##Usage Examples The best way to start learning about the library is by taking a look at some of the examples below: * A basic example using the WWI British Navy dataset - ([view live](http://cartodb.github.io/torque/examples/navy_leaflet.html) / [source code](https://github.com/CartoDB/torque/blob/master/examples/navy_leaflet.html))