Merge pull request #251 from CartoDB/newdocs
docs: add timeslider and interaction methods
This commit is contained in:
Carlos Matallín
commit
2677f80814
141
doc/torque_interaction_methods.md
Normal file
141
doc/torque_interaction_methods.md
Normal file
@ -0,0 +1,141 @@
|
|||||||
|
# Advanced Torque.js Interaction Methods
|
||||||
|
|
||||||
|
_**Note:** Before applying Torque.js interaction methods, you must first load the [required libraries](http://docs.cartodb.com/cartodb-platform/torque/torquejs-getting-started/#advanced-torquejs-libraries)_.
|
||||||
|
|
||||||
|
|
||||||
|
## 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 CartoDB 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: 'CartoDB'
|
||||||
|
}).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);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
60
doc/torque_time_slider.md
Normal file
60
doc/torque_time_slider.md
Normal file
@ -0,0 +1,60 @@
|
|||||||
|
# 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](http://docs.cartodb.com/cartodb-platform/cartodb-js/api-methods/#cartodbcreatevis) and [createLayer](http://docs.cartodb.com/cartodb-platform/cartodb-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](http://docs.cartodb.com/cartodb-platform/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 CartoDB.js options are also supported for Torque.js. For the complete list of arguments, options, and returns, see [CartoDB.js API Methods](http://docs.cartodb.com/cartodb-platform/cartodb-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 [CartoDB.js](http://docs.cartodb.com/cartodb-platform/cartodb-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`](http://docs.cartodb.com/cartodb-platform/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:** This is the _Steps_ option from the [Torque wizard](/cartodb-editor/maps/#torque) of the CartDB Editor.
|
||||||
|
|
||||||
|
- [`-torque-animation-duration`](http://docs.cartodb.com/cartodb-platform/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:** This is the _Duration (secs)_ option from the [Torque wizard](/cartodb-editor/maps/#torque) of the CartoDB Editor.
|
||||||
|
|
||||||
|
### 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](http://docs.cartodb.com/cartodb-platform/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 the CartoDB Editor, the date format of the Torque time slider is automatically calculated by CartoDB and cannot be edited. See [Calculating the Time Slider in the CartoDB Editor](#calculating-the-time-slider-in-the-cartodb-editor) 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](http://docs.cartodb.com/cartodb-platform/cartocss/properties-for-torque/#torque-animation-duration-number) of the animation, and adjust the time slider timestamp with the number of [Steps](http://docs.cartodb.com/cartodb-platform/cartocss/properties-for-torque/#torque-frame-count-number).
|
||||||
|
|
||||||
|
#### Calculating the Time Slider in the CartoDB Editor
|
||||||
|
|
||||||
|
When creating Torque maps with the CartoDB Editor, the date format of the Torque time slider is automatically calculated by CartoDB, 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