Remove older doc folder
This commit is contained in:
parent
ebd978fe7d
commit
05fb3cfc18
10
doc/API.md
10
doc/API.md
@ -1,10 +0,0 @@
|
|||||||
# Torque API
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
* [Getting Started with Torque.js](getting_started.md)
|
|
||||||
* [Torque API Methods](torque_api.md)
|
|
||||||
* [Advanced Interaction Methods](torque_interaction_methods.md)
|
|
||||||
* [Torque Time Slider](torque_time_slider.md)
|
|
@ -1,23 +0,0 @@
|
|||||||
|
|
||||||
# Torque CartoCSS
|
|
||||||
|
|
||||||
## -torque-clear-color
|
|
||||||
Color used to clear canvas on each frame.
|
|
||||||
|
|
||||||
## -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.
|
|
||||||
|
|
||||||
## -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.
|
|
||||||
|
|
||||||
## -torque-animation-duration
|
|
||||||
Animation duration in seconds.
|
|
||||||
|
|
||||||
## -torque-aggregation-function
|
|
||||||
A function used to calculate a value from the aggregate data for each cell. See [-torque-resolution](#-torque-resolution).
|
|
||||||
|
|
||||||
## -torque-time-attribute
|
|
||||||
The table column that contains the time information used create the animation.
|
|
||||||
|
|
||||||
## -torque-data-aggregation
|
|
||||||
A linear animation will discard previous values while a cumulative animation will accumulate them until it restarts.
|
|
@ -1,93 +0,0 @@
|
|||||||
# 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:
|
|
||||||
|
|
||||||
```html
|
|
||||||
<link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet/v0.7.7/leaflet.css" />
|
|
||||||
<body>
|
|
||||||
<div id="map"></div>
|
|
||||||
<script src="http://cdn.leafletjs.com/leaflet/v0.7.7/leaflet.js"></script>
|
|
||||||
<script>
|
|
||||||
var map = new L.Map('map', {
|
|
||||||
zoomControl: true,
|
|
||||||
center: [40, 0],
|
|
||||||
zoom: 3
|
|
||||||
});
|
|
||||||
|
|
||||||
L.tileLayer('http://{s}.api.cartocdn.com/base-dark/{z}/{x}/{y}.png', {
|
|
||||||
attribution: 'CARTO'
|
|
||||||
}).addTo(map);
|
|
||||||
</script>
|
|
||||||
</body>
|
|
||||||
```
|
|
||||||
|
|
||||||
This HTML file automatically generates the Torque.js library, which includes any Torque dependencies. 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
|
|
||||||
<script>
|
|
||||||
var CARTOCSS = [
|
|
||||||
'Map {',
|
|
||||||
'-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;',
|
|
||||||
' marker-fill-opacity: 0.8;',
|
|
||||||
' marker-fill: #FEE391; ',
|
|
||||||
' comp-op: "lighten";',
|
|
||||||
'}'
|
|
||||||
].join('\n');
|
|
||||||
|
|
||||||
var torqueLayer = new L.TorqueLayer({
|
|
||||||
user : 'your_username',
|
|
||||||
table : 'your_table_name',
|
|
||||||
cartocss: CARTOCSS
|
|
||||||
});
|
|
||||||
torqueLayer.addTo(map);
|
|
||||||
torqueLayer.play()
|
|
||||||
</script>
|
|
||||||
```
|
|
||||||
|
|
||||||
You can use any kind of tile source outside CARTO, 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](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
|
|
||||||
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))
|
|
||||||
|
|
||||||
## 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
|
|
||||||
- CARTO repository of [examples](https://github.com/CartoDB/torque/tree/master/examples)
|
|
||||||
- A CARTO [time example](http://cartodb.github.com/torque/) of a Torque map and data
|
|
||||||
- CARTO 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 CARTO.js to [add a Torque layer from a named map with auth_tokens enabled](https://gist.github.com/chriswhong/a4d1e6305ecaf2ad507a)
|
|
@ -1,165 +0,0 @@
|
|||||||
# Torque API
|
|
||||||
|
|
||||||
### 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.
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
var torqueLayer = new L.TorqueLayer({
|
|
||||||
user: 'viz2',
|
|
||||||
table: 'ow',
|
|
||||||
cartocss: '<cartocss here>'
|
|
||||||
});
|
|
||||||
|
|
||||||
map.addLayer(torqueLayer);
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Options
|
|
||||||
|
|
||||||
Name | Description
|
|
||||||
--- | ---
|
|
||||||
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 a CARTO table directly
|
|
||||||
|
|
||||||
Name | Description
|
|
||||||
--- | ---
|
|
||||||
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```
|
|
||||||
|
|
||||||
##### 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```.<br/><br/>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.
|
|
||||||
|
|
||||||
##### 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
|
|
||||||
|
|
||||||
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](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
|
|
||||||
|
|
||||||
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](https://carto.com/docs/carto-engine/maps-api/named-maps/))
|
|
||||||
|
|
||||||
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](https://carto.com/docs/carto-engine/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.
|
|
||||||
|
|
||||||
#### Example
|
|
||||||
|
|
||||||
This is how a minimal example of a stylesheet for a Torque visualisation would look like.
|
|
||||||
|
|
||||||
```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-width: 3;
|
|
||||||
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
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
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
|
|
@ -1,138 +0,0 @@
|
|||||||
# Advanced Torque.js Interaction Methods
|
|
||||||
|
|
||||||
## Torque Layers
|
|
||||||
|
|
||||||
While you can add multiple layers with Torque.js, this is not recommended as it effects performance.
|
|
||||||
|
|
||||||
### Torque Layer Source Object (_type: 'torque'_)
|
|
||||||
|
|
||||||
This layer source object is used for Torque maps. Note that it does not allow sublayers.
|
|
||||||
|
|
||||||
#### Example
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
{
|
|
||||||
type: 'torque', // Required
|
|
||||||
order: 1, // Optional
|
|
||||||
options: {
|
|
||||||
query: "SQL statement", // Required if table_name is not given
|
|
||||||
table_name: "table_name", // Required if query is not given
|
|
||||||
user_name: "your_user_name", // Required
|
|
||||||
cartocss: "CartoCSS styles" // Required
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
## Interaction Methods for a Torque Layer
|
|
||||||
|
|
||||||
Used to create an animated torque layer with customized settings.
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
// initialize a torque layer that uses the CARTO account details and SQL API to pull in data
|
|
||||||
var torqueLayer = new L.TorqueLayer({
|
|
||||||
user : 'viz2',
|
|
||||||
table : 'ow',
|
|
||||||
cartocss: CARTOCSS
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### getValueForPos(_x, y[, step]_)
|
|
||||||
|
|
||||||
#### Arguments
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
#### Returns
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
### getValueForBBox(_xstart, ystart, xend, yend_)
|
|
||||||
|
|
||||||
#### Arguments
|
|
||||||
|
|
||||||
Name | Description
|
|
||||||
--- | ---
|
|
||||||
`getValueForBBox(_xstart, ystart, xend, yend_)` | An accumulated numerical value from all the torque areas, within the specified bounds
|
|
||||||
|
|
||||||
#### Returns
|
|
||||||
|
|
||||||
Returns a number.
|
|
||||||
|
|
||||||
### getActivePointsBBox(_step_)
|
|
||||||
|
|
||||||
#### Arguments
|
|
||||||
|
|
||||||
Name | Description
|
|
||||||
--- | ---
|
|
||||||
`getActivePointsBBox(_step_)` | The list of bounding boxes active for `step`
|
|
||||||
|
|
||||||
#### Returns
|
|
||||||
|
|
||||||
Returns a list of values.
|
|
||||||
|
|
||||||
### invalidate()
|
|
||||||
|
|
||||||
#### Arguments
|
|
||||||
|
|
||||||
Name | Description
|
|
||||||
--- | ---
|
|
||||||
`invalidate()` | Forces a reload of the layer data
|
|
||||||
|
|
||||||
**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
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
<script>
|
|
||||||
// define the torque layer style using cartocss
|
|
||||||
// this creates a kind of density map
|
|
||||||
// color scale from http://colorbrewer2.org/
|
|
||||||
var CARTOCSS = [
|
|
||||||
'Map {',
|
|
||||||
'-torque-time-attribute: "date";',
|
|
||||||
'-torque-aggregation-function: "avg(temp::float)";',
|
|
||||||
'-torque-frame-count: 1;',
|
|
||||||
'-torque-animation-duration: 15;',
|
|
||||||
'-torque-resolution: 16',
|
|
||||||
'}',
|
|
||||||
'#layer {',
|
|
||||||
' marker-width: 8;',
|
|
||||||
' marker-fill-opacity: 1.0;',
|
|
||||||
' marker-fill: #fff5eb; ',
|
|
||||||
' marker-type: rectangle;',
|
|
||||||
' [value > 1] { marker-fill: #fee6ce; }',
|
|
||||||
' [value > 2] { marker-fill: #fdd0a2; }',
|
|
||||||
' [value > 4] { marker-fill: #fdae6b; }',
|
|
||||||
' [value > 10] { marker-fill: #fd8d3c; }',
|
|
||||||
' [value > 15] { marker-fill: #f16913; }',
|
|
||||||
' [value > 20] { marker-fill: #d94801; }',
|
|
||||||
' [value > 25] { marker-fill: #8c2d04; }',
|
|
||||||
'}'
|
|
||||||
].join('\n');
|
|
||||||
|
|
||||||
var map = new L.Map('map', {
|
|
||||||
zoomControl: true,
|
|
||||||
center: [40, 0],
|
|
||||||
zoom: 3
|
|
||||||
});
|
|
||||||
L.tileLayer('http://{s}.api.cartocdn.com/base-dark/{z}/{x}/{y}.png', {
|
|
||||||
attribution: 'CARTO'
|
|
||||||
}).addTo(map);
|
|
||||||
var torqueLayer = new L.TorqueLayer({
|
|
||||||
user : 'viz2',
|
|
||||||
table : 'ow',
|
|
||||||
cartocss: CARTOCSS
|
|
||||||
});
|
|
||||||
torqueLayer.addTo(map);
|
|
||||||
map.on('click', function(e) {
|
|
||||||
var p = e.containerPoint
|
|
||||||
var value = torqueLayer.getValueForPos(p.x, p.y);
|
|
||||||
if (value !== null) {
|
|
||||||
map.openPopup('average temperature: ' + value.value + "C", e.latlng);
|
|
||||||
}
|
|
||||||
});
|
|
||||||
```
|
|
@ -1,60 +0,0 @@
|
|||||||
# 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.
|
|
||||||
|
|
||||||
**Enable / Disable the Torque Time Slider**
|
|
||||||
|
|
||||||
Description | The Torque time slider is enabled by default, for your visualization or layer.
|
|
||||||
Sample Torque.js Code | `{ time_slider: true });`
|
|
||||||
Default Value | `true`, enabled by default.
|
|
||||||
Available Values | See [boolean](https://carto.com/docs/carto-engine/cartocss/properties/#boolean).
|
|
||||||
Related Examples | To disable the time slider option, use `time_slider: false`. See [No Torque Time Slider - Example Code](http://bl.ocks.org/michellechandra/081ca7160a8c782266d2).<br/><br/>For a code example about how to use the `time_slider` option to modify a Torque map, see [Torque with a Custom Time Slider](http://bl.ocks.org/csobier/cebdd47242d7ca98ec5e).
|
|
||||||
|
|
||||||
**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
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
- [`-torque-frame-count`](https://carto.com/docs/carto-engine/cartocss/properties-for-torque/#torque-frame-count-number) specifies the number of animation steps/frames in your torque animation. You can change the time slider timestamp by adjusting the number of steps.<br /><br />**Tip:** In CARTO Builder, this is the STEPS 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
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
- Reads the first date/time stamp from your dataset
|
|
||||||
- Reads the last date/time stamp to from your dataset
|
|
||||||
- Aggregates the time period based on the first and last date/time stamp (including seconds)
|
|
||||||
- Once the time interval is defined, it breaks the time period up in smaller "buckets"
|
|
||||||
- The number of buckets is based on the number of [Steps](https://carto.com/docs/carto-engine/cartocss/properties-for-torque/#torque-frame-count-number) you select for your Torque map
|
|
||||||
- Each bucket, or step, is one animation frame
|
|
||||||
|
|
||||||
Thus, the start and end time for each bucket depends on the number of divided steps (not a specific start time or end time that you entered).
|
|
||||||
|
|
||||||
**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
|
|
||||||
|
|
||||||
The following formula can help you calculate the number of steps for your Torque data.
|
|
||||||
|
|
||||||
`time = times.start + (times.end - times.start)*(step/total_steps);`
|
|
||||||
|
|
||||||
Where:
|
|
||||||
|
|
||||||
- `time` = time at each hop
|
|
||||||
- `times.start` = the earliest time in your date/time column
|
|
||||||
- `times.end` = the latest time in your date/time column
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
- Time range is _less than one day_, the time slider displays the _time_
|
|
||||||
- Time range is _less than three days_, the time slider displays the _day and time_
|
|
||||||
- Time range is _more than three days, but less than a year_, the time slider displays the _month/day/year_
|
|
||||||
- Time range is _more than a year_, the time slider displays the _month/year_
|
|
Loading…
Reference in New Issue
Block a user