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

Fix title md and remove cartojs references in torque support section

Browse Source
This commit is contained in:
csubira 2018-02-26 12:01:41 +01:00
parent 792a66ccf9
commit 4a049eedce
6 changed files with 54 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/examples/01-torque-interaction-methods.md
View File

@ -1,14 +1,14 @@
# Advanced Torque.js Interaction Methods ## Advanced Torque.js Interaction Methods
## Torque Layers ### Torque Layers
While you can add multiple layers with Torque.js, this is not recommended as it effects performance. While you can add multiple layers with Torque.js, this is not recommended as it effects performance.
### Torque Layer Source Object (_type: 'torque'_) #### Torque Layer Source Object (_type: 'torque'_)
This layer source object is used for Torque maps. Note that it does not allow sublayers. This layer source object is used for Torque maps. Note that it does not allow sublayers.
#### Example ##### Example
```javascript ```javascript
{ {
@ -24,7 +24,7 @@ This layer source object is used for Torque maps. Note that it does not allow su
``` ```
## Interaction Methods for a Torque Layer ### Interaction Methods for a Torque Layer
Used to create an animated torque layer with customized settings. Used to create an animated torque layer with customized settings.
@ -37,46 +37,46 @@ var torqueLayer = new L.TorqueLayer({
}); });
``` ```
### getValueForPos(_x, y[, step]_) #### getValueForPos(_x, y[, step]_)
#### Arguments ##### Arguments
Name | Description Name | Description
--- | --- --- | ---
`getValueForPos(_x, y[, step]_)` | Allows to get the value for the coordinate (in map reference system) for a concrete step. If a step is not specified, the animation step is used. Use caution, as this method increases CPU usage `getValueForPos(_x, y[, step]_)` | Allows to get the value for the coordinate (in map reference system) for a concrete step. If a step is not specified, the animation step is used. Use caution, as this method increases CPU usage
#### Returns ##### Returns
An object, such as a { bbox:[], value: VALUE } if there is value for the pos, otherwise, it is null. An object, such as a { bbox:[], value: VALUE } if there is value for the pos, otherwise, it is null.
It returns the value from the raster data, not the rendered data. It returns the value from the raster data, not the rendered data.
### getValueForBBox(_xstart, ystart, xend, yend_) #### getValueForBBox(_xstart, ystart, xend, yend_)
#### Arguments ##### Arguments
Name | Description Name | Description
--- | --- --- | ---
`getValueForBBox(_xstart, ystart, xend, yend_)` | An accumulated numerical value from all the torque areas, within the specified bounds `getValueForBBox(_xstart, ystart, xend, yend_)` | An accumulated numerical value from all the torque areas, within the specified bounds
#### Returns ##### Returns
Returns a number. Returns a number.
### getActivePointsBBox(_step_) #### getActivePointsBBox(_step_)
#### Arguments ##### Arguments
Name | Description Name | Description
--- | --- --- | ---
`getActivePointsBBox(_step_)` | The list of bounding boxes active for `step` `getActivePointsBBox(_step_)` | The list of bounding boxes active for `step`
#### Returns ##### Returns
Returns a list of values. Returns a list of values.
### invalidate() #### invalidate()
#### Arguments ##### Arguments
Name | Description Name | Description
--- | --- --- | ---
@ -84,7 +84,7 @@ Name | Description
**Tip:** All of these interaction methods are available for Google Map layers, with the exception of `invalidate`. **Tip:** All of these interaction methods are available for Google Map layers, with the exception of `invalidate`.
#### Example of Interaction Methods for a Torque Layer ##### Example of Interaction Methods for a Torque Layer
```javascript ```javascript
<script> <script>

10
docs/examples/02-torque-time-slider.md
View File

@ -1,4 +1,4 @@
# Torque Time Slider ## Torque Time Slider
You can use the `time_slider` option to show an animated time slider with Torque layers. This option is enabled by default when creating visualizations with [cartodb.createVis](https://carto.com/docs/carto-engine/carto-js/api-methods/#cartodbcreatevis) and [createLayer](https://carto.com/docs/carto-engine/carto-js/api-methods/#cartodbcreatelayermap-layersource--options--callback). Both require a map_id DOM object. You can use the `time_slider` option to show an animated time slider with Torque layers. This option is enabled by default when creating visualizations with [cartodb.createVis](https://carto.com/docs/carto-engine/carto-js/api-methods/#cartodbcreatevis) and [createLayer](https://carto.com/docs/carto-engine/carto-js/api-methods/#cartodbcreatelayermap-layersource--options--callback). Both require a map_id DOM object.
@ -13,7 +13,7 @@ Related Examples | To disable the time slider option, use `time_slider: false`.
**Note:** The `time_slider` option is specific for Torque.js only. All the other CARTO.js options are also supported for Torque.js. For the complete list of arguments, options, and returns, see [CARTO.js API Methods](https://carto.com/docs/carto-engine/carto-js/api-methods/#api-methods). **Note:** The `time_slider` option is specific for Torque.js only. All the other CARTO.js options are also supported for Torque.js. For the complete list of arguments, options, and returns, see [CARTO.js API Methods](https://carto.com/docs/carto-engine/carto-js/api-methods/#api-methods).
## Customize Animation for your Time Slider ### Customize Animation for your Time Slider
You can customize the animation of your Torque time slider by editing the `-torque-frame-count` and `-torque-animation-duration` CartoCSS properties. (Optionally, you can create a [CARTO.js](https://carto.com/docs/carto-engine/carto-js/api-methods/#api-methods) map to create a custom time slider). This section also describes how time interval data is aggregated, and describes the formula used to calculate time buckets. You can customize the animation of your Torque time slider by editing the `-torque-frame-count` and `-torque-animation-duration` CartoCSS properties. (Optionally, you can create a [CARTO.js](https://carto.com/docs/carto-engine/carto-js/api-methods/#api-methods) map to create a custom time slider). This section also describes how time interval data is aggregated, and describes the formula used to calculate time buckets.
@ -21,7 +21,7 @@ You can customize the animation of your Torque time slider by editing the `-torq
- [`-torque-animation-duration`](https://carto.com/docs/carto-engine/cartocss/properties-for-torque/#torque-animation-duration-number) specifies the length of time for your animation, in seconds. You can adjust the duration of the animation as needed.<br /><br />**Tip:** In CARTO Builder, this is the DURATION value when the style is ANIMATED. - [`-torque-animation-duration`](https://carto.com/docs/carto-engine/cartocss/properties-for-torque/#torque-animation-duration-number) specifies the length of time for your animation, in seconds. You can adjust the duration of the animation as needed.<br /><br />**Tip:** In CARTO Builder, this is the DURATION value when the style is ANIMATED.
### Aggregating Time Interval Data #### Aggregating Time Interval Data
Before customizing the time slider, you should understand how Torque time interval data is calculated. Torque aggregates time (rather than use an exact start time and end from your column fields). Torque calculates the time interval as follows: Before customizing the time slider, you should understand how Torque time interval data is calculated. Torque aggregates time (rather than use an exact start time and end from your column fields). Torque calculates the time interval as follows:
@ -36,7 +36,7 @@ Thus, the start and end time for each bucket depends on the number of divided st
**Note:** If you are creating Torque maps with CARTO Builder, the date format of the Torque time slider is automatically calculated by CARTO and cannot be edited. See [Calculating the Time Slider in CARTO Builder](#calculating-the-time-slider-in-carto-builder) for more details. **Note:** If you are creating Torque maps with CARTO Builder, the date format of the Torque time slider is automatically calculated by CARTO and cannot be edited. See [Calculating the Time Slider in CARTO Builder](#calculating-the-time-slider-in-carto-builder) for more details.
### Formula for Calculating Time Buckets #### Formula for Calculating Time Buckets
The following formula can help you calculate the number of steps for your Torque data. The following formula can help you calculate the number of steps for your Torque data.
@ -50,7 +50,7 @@ Where:
The Torque time slider displays these buckets of time, animating the entire sequence of your dataset, and divides the time according to the number of specified steps. You can alter the [duration](https://carto.com/docs/carto-engine/cartocss/properties-for-torque/#torque-animation-duration-number) of the animation, and adjust the time slider timestamp with the number of [Steps](https://carto.com/docs/carto-engine/cartocss/properties-for-torque/#torque-frame-count-number). The Torque time slider displays these buckets of time, animating the entire sequence of your dataset, and divides the time according to the number of specified steps. You can alter the [duration](https://carto.com/docs/carto-engine/cartocss/properties-for-torque/#torque-animation-duration-number) of the animation, and adjust the time slider timestamp with the number of [Steps](https://carto.com/docs/carto-engine/cartocss/properties-for-torque/#torque-frame-count-number).
#### Calculating the Time Slider in CARTO Builder ##### Calculating the Time Slider in CARTO Builder
When creating Torque maps with CARTO Builder, the date format of the Torque time slider is automatically calculated by CARTO, depending on the range of time in your dataset. It cannot be edited. If your data contains the following range of time, the time slider displays as described: When creating Torque maps with CARTO Builder, the date format of the Torque time slider is automatically calculated by CARTO, depending on the range of time in your dataset. It cannot be edited. If your data contains the following range of time, the time slider displays as described:

6
docs/guides/01-getting-started.md
View File

@ -1,4 +1,4 @@
# Getting Started ## Getting Started
Although the most straightforward way to use Torque is through either CARTO Builder, or by passing the layer's viz.json to [CARTO.js](https://carto.com/docs/carto-engine/carto-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: Although the most straightforward way to use Torque is through either CARTO Builder, or by passing the layer's viz.json to [CARTO.js](https://carto.com/docs/carto-engine/carto-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:
@ -73,14 +73,14 @@ 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](https://carto.com/docs/carto-engine/torque/torqueapi/). 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](https://carto.com/docs/carto-engine/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: 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)) * 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)) * 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)) * 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 ### Additional Torque Resources
The following links contain examples, and other public information, about using Torque maps. The following links contain examples, and other public information, about using Torque maps.

17
docs/guides/02-CartoCSS.md
View File

@ -1,23 +1,22 @@
## Torque CartoCSS
# Torque CartoCSS ### -torque-clear-color
## -torque-clear-color
Color used to clear canvas on each frame. Color used to clear canvas on each frame.
## -torque-frame-count ### -torque-frame-count
Number of animation steps/frames used in the animation. If the data contains a fewer number of total frames, the lesser value will be used. Number of animation steps/frames used in the animation. If the data contains a fewer number of total frames, the lesser value will be used.
## -torque-resolution ### -torque-resolution
Spatial resolution in pixels. A resolution of 1 means no spatial aggregation of the data. Any other resolution of N results in spatial aggregation into cells of NxN pixels. The value N must be power of 2. Spatial resolution in pixels. A resolution of 1 means no spatial aggregation of the data. Any other resolution of N results in spatial aggregation into cells of NxN pixels. The value N must be power of 2.
## -torque-animation-duration ### -torque-animation-duration
Animation duration in seconds. Animation duration in seconds.
## -torque-aggregation-function ### -torque-aggregation-function
A function used to calculate a value from the aggregate data for each cell. See [-torque-resolution](#-torque-resolution). A function used to calculate a value from the aggregate data for each cell. See [-torque-resolution](#-torque-resolution).
## -torque-time-attribute ### -torque-time-attribute
The table column that contains the time information used create the animation. The table column that contains the time information used create the animation.
## -torque-data-aggregation ### -torque-data-aggregation
A linear animation will discard previous values while a cumulative animation will accumulate them until it restarts. A linear animation will discard previous values while a cumulative animation will accumulate them until it restarts.

34
docs/reference/01-torque-api.md
View File

@ -1,6 +1,6 @@
# Torque API ## Torque API
### L.TorqueLayer(options) #### L.TorqueLayer(options)
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 `<img>` elements, it's composed of a single [`<canvas>`](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) where all markers are drawn. 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 `<img>` elements, it's composed of a single [`<canvas>`](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) where all markers are drawn.
@ -14,7 +14,7 @@ var torqueLayer = new L.TorqueLayer({
map.addLayer(torqueLayer); map.addLayer(torqueLayer);
``` ```
#### Options ##### Options
Name | Description Name | Description
--- | --- --- | ---
@ -28,14 +28,14 @@ attribution | Attribution to be added in the bottom right of the map
maxZoom | Maximum zoom for the layer. maxZoom | Maximum zoom for the layer.
tileSize | Size, in pixels of the tiles tileSize | Size, in pixels of the tiles
##### Using a CARTO table directly ###### Using a CARTO table directly
Name | Description Name | Description
--- | --- --- | ---
user | A string object, your CARTO [account name](https://carto.com/docs/carto-editor/your-account/#account). Default value is ```null``` user | A string object, your CARTO [account name](https://carto.com/docs/carto-editor/your-account/#account). Default value is ```null```
table | A string object, the CARTO table name where data is found (also known as a dataset.) Default value is ```null``` table | A string object, the CARTO table name where data is found (also known as a dataset.) Default value is ```null```
##### Using a custom SQL query ###### Using a custom SQL query
Name | Description Name | Description
--- | --- --- | ---
@ -43,13 +43,13 @@ query | A string object, the SQL query to be performed to fetch the data. Defaul
**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. **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.
##### Providing a TileJSON file ###### Providing a TileJSON file
Name | Description 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 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 | 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](https://carto.com/docs/carto-engine/cartocss/properties-for-torque/#torque-frame-count-number), 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](https://carto.com/docs/carto-engine/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 Method | Options | Returns | Description
---|---|---|--- ---|---|---|---
`hide()` | none | `this` | hides the Torque layer `hide()` | none | `this` | hides the Torque layer
`show()` | none| `this` | shows the Torque layer `show()` | none| `this` | shows the Torque layer
#### Style Methods ##### Style Methods
Method | Options | Returns | Description Method | Options | Returns | Description
---|---|---|---| ---|---|---|---|
@ -81,7 +81,7 @@ Torque supports a limited subset of CartoCSS rules defined in the [torque-refere
TorqueLayer currently expects `marker` styling. TorqueLayer currently expects `marker` styling.
#### Example ##### Example
This is how a minimal example of a stylesheet for a Torque visualisation would look like. This is how a minimal example of a stylesheet for a Torque visualisation would look like.
@ -106,14 +106,14 @@ Map {
} }
``` ```
### Data Methods #### Data Methods
Method | Options | Returns | Description Method | Options | Returns | Description
---|---|---|--- ---|---|---|---
`setSQL(sql statement)` | `SQL string` | `this` | Change the SQL on the data table (not available with named maps) `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 `error(callback)` | `callback function with a list of errors as argument` | `this` | specifies a callback function to run if there are query errors
#### Example ##### Example
SQL Example to limit the data used in the Torque map. SQL Example to limit the data used in the Torque map.
@ -121,7 +121,7 @@ SQL Example to limit the data used in the Torque map.
torqueLayer.setSQL("SELECT * FROM table LIMIT 100"); torqueLayer.setSQL("SELECT * FROM table LIMIT 100");
``` ```
### Events #### Events
Events in Torque follow the format: Events in Torque follow the format:
@ -140,7 +140,7 @@ Events | Callback Object | Description
`stop` | none | Triggered when the Torque layer is stopped `stop` | none | Triggered when the Torque layer is stopped
`load` | none | Triggered when the Torque layer is loaded `load` | none | Triggered when the Torque layer is loaded
#### Example ##### Example
An event example to print the current step to the console log. An event example to print the current step to the console log.
@ -151,14 +151,14 @@ torqueLayer.on('change:steps', function(step) {
}); });
``` ```
## Google Maps Layers ### Google Maps Layers
### GMapsTorqueLayer(_options_) #### GMapsTorqueLayer(_options_)
This class does exactly the same as ``L.TorqueLayer`` but using Google Maps instead. The main difference is that this class 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. 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
Name | Description Name | Description
--- | --- --- | ---

13
docs/support/01-support-options.md
View File

@ -3,27 +3,22 @@
Feeling stuck? There are many ways to find help. Feeling stuck? There are many ways to find help.
* Ask a question on [GIS StackExchange](https://gis.stackexchange.com/questions/tagged/carto) using the `CARTO` tag. * Ask a question on [GIS StackExchange](https://gis.stackexchange.com/questions/tagged/carto) using the `CARTO` tag.
* [Report an issue](https://github.com/CartoDB/cartodb.js/issues) in Github. * [Report an issue](https://github.com/CartoDB/torque/issues/new) in Github.
* Engine Plan customers have additional access to enterprise-level support through CARTO's support representatives. * Engine Plan customers have additional access to enterprise-level support through CARTO's support representatives.
If you just want to describe an issue or share an idea, just <a class="typeform-share" href="https://cartohq.typeform.com/to/mH6RRl" data-mode="popup" target="_blank"> send your feedback</a><script>(function() { var qs,js,q,s,d=document, gi=d.getElementById, ce=d.createElement, gt=d.getElementsByTagName, id="typef_orm_share", b="https://embed.typeform.com/"; if(!gi.call(d,id)){ js=ce.call(d,"script"); js.id=id; js.src=b+"embed.js"; q=gt.call(d,"script")[0]; q.parentNode.insertBefore(js,q) } })() </script>. If you just want to describe an issue or share an idea, just <a class="typeform-share" href="https://cartohq.typeform.com/to/mH6RRl" data-mode="popup" target="_blank"> send your feedback</a>
### Issues on Github ### Issues on Github
<img class="left-content" src="/documentation/img/github-icon.png"> If you think you may have found a bug, or if you have a feature request that you would like to share with the Torque team, please [open an issue](https://github.com/CartoDB/torque/issues/new).
If you think you may have found a bug, or if you have a feature request that you would like to share with the CARTO.js team, please [open an issue](https://github.com/cartodb/cartodb.js/issues/new). Before opening an issue, review the [contributing guidelines](https://github.com/CartoDB/torque/blob/master/CONTRIBUTING.md).
Before opening an issue, review the [contributing guidelines](https://github.com/CartoDB/cartodb.js/blob/develop/CONTRIBUTING.md#filling-a-ticket).
### Community support on GIS Stack Exchange ### Community support on GIS Stack Exchange
<img class="right-content" src="/documentation/img/gis-stackexchange-icon.png">
GIS Stack Exchange is the most popular community in the geospatial industry. This is a collaboratively-edited question and answer site for geospatial programmers and technicians. It is a fantastic resource for asking technical questions about developing and maintaining your application. GIS Stack Exchange is the most popular community in the geospatial industry. This is a collaboratively-edited question and answer site for geospatial programmers and technicians. It is a fantastic resource for asking technical questions about developing and maintaining your application.
Members of the CARTO.js team regularly monitor the `carto` tag. You can look for CARTO topics by adding `carto` or `cartodb.js` to your search query. You can also add additional tags to your question in order to attract the attention of experts in related technologies.
When posting a new question, please consider the following: When posting a new question, please consider the following: