diff --git a/docs/examples/01-torque-interaction-methods.md b/docs/examples/01-torque-interaction-methods.md new file mode 100644 index 0000000..3a9be2a --- /dev/null +++ b/docs/examples/01-torque-interaction-methods.md @@ -0,0 +1,138 @@ +# 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 + + + +``` + +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 + +``` + +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) diff --git a/docs/guides/02-CartoCSS.md b/docs/guides/02-CartoCSS.md new file mode 100644 index 0000000..00ab400 --- /dev/null +++ b/docs/guides/02-CartoCSS.md @@ -0,0 +1,23 @@ + +# 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. diff --git a/docs/reference/01-torque-api.md b/docs/reference/01-torque-api.md new file mode 100644 index 0000000..1ea5a85 --- /dev/null +++ b/docs/reference/01-torque-api.md @@ -0,0 +1,165 @@ +# 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 `` elements, it's composed of a single [``](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: '' +}); + +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```.

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 diff --git a/docs/support/01-support-options.md b/docs/support/01-support-options.md new file mode 100644 index 0000000..05ea88c --- /dev/null +++ b/docs/support/01-support-options.md @@ -0,0 +1,41 @@ +## Support Options + +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. +* [Report an issue](https://github.com/CartoDB/cartodb.js/issues) in Github. +* 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 . + +### Issues on Github + + + +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/cartodb.js/blob/develop/CONTRIBUTING.md#filling-a-ticket). + + +### Community support on GIS Stack Exchange + + +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: + +* Read the GIS Stack Exchange [help](https://gis.stackexchange.com/help) and [how to ask](https://gis.stackexchange.com/help/how-to-ask) pages for guidelines and tips about posting questions. +* Be very clear about your question in the subject. A clear explanation helps those trying to answer your question, as well as those who may be looking for information in the future. +* Be informative in your post. Details, code snippets, logs, screenshots, etc. help others to understand your problem. +* Use code that demonstrates the problem. It is very hard to debug errors without sample code to reproduce the problem. + +### Engine Plan Customers + +Engine Plan customers have additional support options beyond general community support. As per your account Terms of Service, you have access to enterprise-level support through CARTO's support representatives available at [enterprise-support@carto.com](mailto:enterprise-support@carto.com) + +In order to speed up the resolution of your issue, provide as much information as possible (even if it is a link from community support). This allows our engineers to investigate your problem as soon as possible. + +If you are not yet CARTO customer, browse our [plans & pricing](https://carto.com/pricing/) and find the right plan for you. \ No newline at end of file