From bd80d4a6ec099e075a8f37a5c97a2a9cd03eeb55 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 14:03:15 -0400 Subject: [PATCH 01/14] bulltes not displayed right --- doc/API.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/API.md b/doc/API.md index ca8643f..508d559 100644 --- a/doc/API.md +++ b/doc/API.md @@ -12,6 +12,7 @@ depending on the map provider you are using you need to use different layer type ## L.TorqueLayer(options) _Arguments_: + * options: object that contains the following attributes: - user: cartodb username - table: table name From ab38c9127f4c296e4a65b3bbf24467b65cd16104 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 14:16:12 -0400 Subject: [PATCH 02/14] trying leaflet api doc style parameters table --- doc/API.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/API.md b/doc/API.md index 508d559..e884a72 100644 --- a/doc/API.md +++ b/doc/API.md @@ -11,6 +11,35 @@ depending on the map provider you are using you need to use different layer type ## L.TorqueLayer(options) +The core class of the Torque library - it is used to create a 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', + column : 'date', + countby : 'count(cartodb_id)', + resolution : 1, + is_time : true, + steps : 750, + pixel_size : 3, + blendmode : 'lighter' + }); +``` + +#### Options + +##### Provider options +| Option | type | Default | Description | +|-----------|:----------|:----------|:---------------------------------------| +| provider | string | sql_api | Where is the data coming from? Alternative is 'url_template'| + + + provider: 'sql_api', + _Arguments_: * options: object that contains the following attributes: From 7f0259f2fcba20f6c25f03955d56ac8bcc25e36f Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 14:20:53 -0400 Subject: [PATCH 03/14] continuing leaflet api doc style parameters table --- doc/API.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/API.md b/doc/API.md index e884a72..265fec1 100644 --- a/doc/API.md +++ b/doc/API.md @@ -1,10 +1,10 @@ # Torque API -Torque provides two kinds of visulizations. +Torque provides two kinds of visualizations. - static: provides a way to create heatmap like visualizations (note for Andrew: fon). see ``TorqueLayer`` - - dinamyc: animate points over a map (note for Andrew: Navy) see ``TiledTorqueLayer`` + - dynamic: animate points over a map (note for Andrew: Navy) see ``TiledTorqueLayer`` depending on the map provider you are using you need to use different layer type. Currently we provide layers for Google Maps and Leaflet. @@ -37,6 +37,15 @@ The core class of the Torque library - it is used to create a torque layer with |-----------|:----------|:----------|:---------------------------------------| | provider | string | sql_api | Where is the data coming from? Alternative is 'url_template'| +##### CartoDB data options +| Option | type | Default | Description | +|-----------|:----------|:----------|:---------------------------------------| +| user | string | null | CartoDB account name. Found as, accountname.cartodb.com| +| table | string | null | CartoDB table name where data is found | +| column | string | null | CartoDB table's column name where date information is found (for dynamic type torque layer only)| +| countby | string | null | The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function | + + provider: 'sql_api', From 604302eca5019d1538691a82bda2f97fa4f6ba68 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 14:39:07 -0400 Subject: [PATCH 04/14] continuing leaflet api doc style parameters table --- doc/API.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/doc/API.md b/doc/API.md index 265fec1..bcb9b85 100644 --- a/doc/API.md +++ b/doc/API.md @@ -35,16 +35,20 @@ The core class of the Torque library - it is used to create a torque layer with ##### Provider options | Option | type | Default | Description | |-----------|:----------|:----------|:---------------------------------------| -| provider | string | sql_api | Where is the data coming from? Alternative is 'url_template'| +| provider | string | ```sql_api``` | Where is the data coming from? Alternative is 'url_template'| ##### CartoDB data options | Option | type | Default | Description | |-----------|:----------|:----------|:---------------------------------------| -| user | string | null | CartoDB account name. Found as, accountname.cartodb.com| -| table | string | null | CartoDB table name where data is found | -| column | string | null | CartoDB table's column name where date information is found (for dynamic type torque layer only)| -| countby | string | null | The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function | +| user | string | ```null``` | CartoDB account name. Found as, accountname.cartodb.com| +| table | string | ```null``` | CartoDB table name where data is found | +| column | string | ```null``` | CartoDB table's column name where date information is found (for dynamic type torque layer only)| +| countby | string | ```null``` | The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function | +##### Visualization options +| Option | type | Default | Description | +|-----------|:----------|:----------|:---------------------------------------| +| is_time | boolean | ```true``` | Where is the data coming from? Alternative is 'url_template'| provider: 'sql_api', From 649be2fbcfc74cdd1c1fb10ba7f7bc2f651d57a4 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 14:47:56 -0400 Subject: [PATCH 05/14] finished torquelayer options documentation --- doc/API.md | 43 +++++++++++++++++-------------------------- 1 file changed, 17 insertions(+), 26 deletions(-) diff --git a/doc/API.md b/doc/API.md index bcb9b85..9b81a87 100644 --- a/doc/API.md +++ b/doc/API.md @@ -33,37 +33,28 @@ The core class of the Torque library - it is used to create a torque layer with #### Options ##### Provider options -| Option | type | Default | Description | -|-----------|:----------|:----------|:---------------------------------------| -| provider | string | ```sql_api``` | Where is the data coming from? Alternative is 'url_template'| +| Option | type | Default | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| provider | string | ```sql_api``` | Where is the data coming from? Alternative is 'url_template'| ##### CartoDB data options -| Option | type | Default | Description | -|-----------|:----------|:----------|:---------------------------------------| -| user | string | ```null``` | CartoDB account name. Found as, accountname.cartodb.com| -| table | string | ```null``` | CartoDB table name where data is found | -| column | string | ```null``` | CartoDB table's column name where date information is found (for dynamic type torque layer only)| -| countby | string | ```null``` | The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function | +| Option | type | Default | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| user | string | ```null``` | CartoDB account name. Found as, accountname.cartodb.com| +| table | string | ```null``` | CartoDB table name where data is found | +| column | string | ```null``` | CartoDB table's column name where date information is found (for dynamic type torque layer only)| +| countby | string | ```null``` | The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function | -##### Visualization options -| Option | type | Default | Description | -|-----------|:----------|:----------|:---------------------------------------| -| is_time | boolean | ```true``` | Where is the data coming from? Alternative is 'url_template'| +##### Dynamic/static options +| Option | type | Default | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| is_time | boolean | ```true``` | Determines if the drawing is static or dynamic/animated | +| steps | integer | ```100``` | The number of steps to divide the data into for animated renderings | - provider: 'sql_api', - -_Arguments_: - - * options: object that contains the following attributes: - - user: cartodb username - - table: table name - - column: time column - - countby: aggregation per pixel, e.g: 'count(cartodb_id)', - - resolution: pixel resolution, - - is_time: true or false, - - steps: animation steps, e.g: 750, - - blendmode: canvas blend mode 'lighter' +##### Display options +| resolution| numeric | ```2``` | The x and y dimensions of each pixel when rendered on the map. Must match the format of the data| +| blendmode | boolean | ```null``` | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas | ## L.TorqueLayer.setKey(time: number) From b2e503ed0812800b1345bfcda5d2409e82a31625 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 14:54:12 -0400 Subject: [PATCH 06/14] added header to last table --- doc/API.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/API.md b/doc/API.md index 9b81a87..755e907 100644 --- a/doc/API.md +++ b/doc/API.md @@ -53,6 +53,8 @@ The core class of the Torque library - it is used to create a torque layer with ##### Display options +| Option | type | Default | Description | +|-----------|:-----------|:----------|:---------------------------------------| | resolution| numeric | ```2``` | The x and y dimensions of each pixel when rendered on the map. Must match the format of the data| | blendmode | boolean | ```null``` | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas | From 655be362e66bdad0bf220933058b1d25bf7ad8d6 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 17:16:37 -0400 Subject: [PATCH 07/14] moving setKey under play options in the torquelayer --- doc/API.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/doc/API.md b/doc/API.md index 755e907..901d6de 100644 --- a/doc/API.md +++ b/doc/API.md @@ -13,7 +13,7 @@ depending on the map provider you are using you need to use different layer type The core class of the Torque library - it is used to create a torque layer with custom settings. -#### Usage example +### Usage example ```js // initialize a torque layer that uses the CartoDB account details and SQL API to pull in data @@ -30,7 +30,7 @@ The core class of the Torque library - it is used to create a torque layer with }); ``` -#### Options +### Options ##### Provider options | Option | type | Default | Description | @@ -55,9 +55,17 @@ The core class of the Torque library - it is used to create a torque layer with ##### Display options | Option | type | Default | Description | |-----------|:-----------|:----------|:---------------------------------------| -| resolution| numeric | ```2``` | The x and y dimensions of each pixel when rendered on the map. Must match the format of the data| +| resolution| numeric | ```2``` | The x and y dimensions of each pixel as returned by the data| | blendmode | boolean | ```null``` | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas | +## Play options + +| Method | options | returns | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| ```setTime(numeric)``` | ```time``` | ```this``` | sets the animation to the step indicated by ```time```, must be between 0 and N where N equals the number of steps| + + + ## L.TorqueLayer.setKey(time: number) _Arguments_ From d30cf732a6338ce3402abf1ce89ff5100264842f Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 17:18:06 -0400 Subject: [PATCH 08/14] moving setKey under play options in the torquelayer --- doc/API.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/API.md b/doc/API.md index 901d6de..2d1fe51 100644 --- a/doc/API.md +++ b/doc/API.md @@ -58,11 +58,13 @@ The core class of the Torque library - it is used to create a torque layer with | resolution| numeric | ```2``` | The x and y dimensions of each pixel as returned by the data| | blendmode | boolean | ```null``` | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas | -## Play options +### Play options | Method | options | returns | Description | |-----------|:-----------|:----------|:---------------------------------------| -| ```setTime(numeric)``` | ```time``` | ```this``` | sets the animation to the step indicated by ```time```, must be between 0 and N where N equals the number of steps| +| ```js +setTime(numeric) +``` | ```time``` | ```this``` | sets the animation to the step indicated by ```time```, must be between 0 and N where N equals the number of steps| From 765c3f25a7c4db675b785b4b49664a9a691b8deb Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 17:18:45 -0400 Subject: [PATCH 09/14] moving setKey under play options in the torquelayer --- doc/API.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/API.md b/doc/API.md index 2d1fe51..c97cdce 100644 --- a/doc/API.md +++ b/doc/API.md @@ -62,9 +62,7 @@ The core class of the Torque library - it is used to create a torque layer with | Method | options | returns | Description | |-----------|:-----------|:----------|:---------------------------------------| -| ```js -setTime(numeric) -``` | ```time``` | ```this``` | sets the animation to the step indicated by ```time```, must be between 0 and N where N equals the number of steps| +| ```js setTime(numeric)``` | ```time``` | ```this``` | sets the animation to the step indicated by ```time```, must be between 0 and N where N equals the number of steps| From ba47e01767cc40a6fa9a47e9bcf10e162950a000 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 17:33:15 -0400 Subject: [PATCH 10/14] ironed over tiledtorquelayer --- doc/API.md | 71 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 49 insertions(+), 22 deletions(-) diff --git a/doc/API.md b/doc/API.md index c97cdce..7b985d4 100644 --- a/doc/API.md +++ b/doc/API.md @@ -11,7 +11,7 @@ depending on the map provider you are using you need to use different layer type ## L.TorqueLayer(options) -The core class of the Torque library - it is used to create a torque layer with custom settings. +One of two core classes for the Torque library - it is used to create an animated torque layer with custom settings. ### Usage example @@ -45,16 +45,16 @@ The core class of the Torque library - it is used to create a torque layer with | column | string | ```null``` | CartoDB table's column name where date information is found (for dynamic type torque layer only)| | countby | string | ```null``` | The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function | -##### Dynamic/static options +##### Dynamic/static options (Note for Santana: we can remove this option?) | Option | type | Default | Description | |-----------|:-----------|:----------|:---------------------------------------| | is_time | boolean | ```true``` | Determines if the drawing is static or dynamic/animated | -| steps | integer | ```100``` | The number of steps to divide the data into for animated renderings | ##### Display options | Option | type | Default | Description | |-----------|:-----------|:----------|:---------------------------------------| +| steps | integer | ```100``` | The number of steps to divide the data into for animated renderings | | resolution| numeric | ```2``` | The x and y dimensions of each pixel as returned by the data| | blendmode | boolean | ```null``` | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas | @@ -62,18 +62,20 @@ The core class of the Torque library - it is used to create a torque layer with | Method | options | returns | Description | |-----------|:-----------|:----------|:---------------------------------------| -| ```js setTime(numeric)``` | ```time``` | ```this``` | sets the animation to the step indicated by ```time```, must be between 0 and N where N equals the number of steps| +| ```setKey(time)``` | ```time numeric``` | ```this``` | sets the animation to the step indicated by ```time```, must be between 0 and N where N equals the number of steps| +### Style options -## L.TorqueLayer.setKey(time: number) +| Method | options | returns | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| ```setCartoCSS(cartocss)``` | ```cartocss string``` | ```this``` | style the map rendering using client-side cartocss | -_Arguments_ - * time: set time to be displayed. Should be a number between [0, steps) -## L.TorqueLayer.setCartoCSS(cartocss: string) -_Arguments_ - * cartocss: cartocss string that contains the point style. Torque does not support the full cartocss spec, only a small subset. - ``value`` and ``zoom`` variables can be used. ``value`` is the value of aggregation (see ``countby`` constructor option). ``zoom`` is the current zoom being rendered +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 here](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 ``` #layer {, @@ -89,24 +91,49 @@ _Arguments_ } ``` - ## L.TiledTorqueLayer(options) -creates a static visualization -_Arguments_: - * options: - - provider: 'url_template', - - url: tile template url e.g 'http://host.com/{z}/{x}/{y}.json', (note to Andrew: link here to the json data format) - - resolution: data resolution, e.g 4 + +One of two core classes for the Torque library - it is used to create a static torque layer with client side filtering. + +##### Provider options +| Option | type | Default | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| provider | string | ```sql_api``` | Where is the data coming from? Alternative is 'url_template'| +| url | string | ```null``` | Tile template URL for fetching data e.g 'http://host.com/{z}/{x}/{y}.json'| + +##### CartoDB data options (Note to Santana: are these really here?) +| Option | type | Default | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| user | string | ```null``` | CartoDB account name. Found as, accountname.cartodb.com| +| table | string | ```null``` | CartoDB table name where data is found | +| column | string | ```null``` | CartoDB table's column name where date information is found (for dynamic type torque layer only)| +| countby | string | ```null``` | The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function | -## L.TiledTorqueLayer.setKey(keys: number|array) -set keys to show, if it's an array all the keys in that array are accumulated +##### Display options (Note to Santana: is blendmode here? or above even?) +| Option | type | Default | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| resolution| numeric | ```2``` | The x and y dimensions of each pixel as returned by the data| +| blendmode | boolean | ```null``` | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas | -## L.TiledTorqueLayer.setCartoCSS(cartocss: string) +### Filtering options + +| Method | options | returns | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| ```setKey(keys)``` | ```keys numeric|array``` | ```this``` | which data categories to display on the map | + +### Style options + +| Method | options | returns | Description | +|-----------|:-----------|:----------|:---------------------------------------| +| ```setCartoCSS(cartocss)``` | ```cartocss string``` | ```this``` | style the map rendering using client-side cartocss | ``value`` and ``zoom`` variables can be used. only ``polygon-fill`` property is supported currently -_Example_: +TorqueLayer currently expects ```polygon``` styling + +##### CartoCSS Example + ``` #layer { polygon-fill: #FFFF00; From da87152e9fb5951d12bcb7dc159af067d7b4163f Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 17:34:05 -0400 Subject: [PATCH 11/14] added css styling in markdown --- doc/API.md | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/doc/API.md b/doc/API.md index 7b985d4..dfabeb0 100644 --- a/doc/API.md +++ b/doc/API.md @@ -77,19 +77,19 @@ TorqueLayer currently expects ```marker``` styling ##### CartoCSS Example - ``` - #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; } - } - ``` +```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; } +} +``` ## L.TiledTorqueLayer(options) @@ -134,16 +134,16 @@ TorqueLayer currently expects ```polygon``` styling ##### CartoCSS Example - ``` - #layer { - polygon-fill: #FFFF00; - [value >= 10] { polygon-fill: #FFCC00; } - [value >= 100] { polygon-fill: #FF9900; } - [value >= 1000] { polygon-fill: #FF6600; } - [value >= 10000] { polygon-fill: #FF3300; } - [value > 100000] { polygon-fill: #C00; } - } - ``` +```css +#layer { + polygon-fill: #FFFF00; + [value >= 10] { polygon-fill: #FFCC00; } + [value >= 100] { polygon-fill: #FF9900; } + [value >= 1000] { polygon-fill: #FF6600; } + [value >= 10000] { polygon-fill: #FF3300; } + [value > 100000] { polygon-fill: #C00; } +} +``` # gmaps layers (TODO) From 83b16218fb00cf26f1cd29ea6eb40f18b18005e5 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 17:34:53 -0400 Subject: [PATCH 12/14] added css styling in markdown --- doc/API.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/API.md b/doc/API.md index dfabeb0..a949813 100644 --- a/doc/API.md +++ b/doc/API.md @@ -77,6 +77,8 @@ TorqueLayer currently expects ```marker``` styling ##### CartoCSS Example +This should be ```string``` encoded in Javascript + ```css #layer {, marker-fill: #662506; @@ -134,6 +136,8 @@ TorqueLayer currently expects ```polygon``` styling ##### CartoCSS Example +This should be ```string``` encoded in Javascript + ```css #layer { polygon-fill: #FFFF00; From 7cbafd7a8e7a0ae96e2ed50e907d6d7705a79c05 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 17:35:53 -0400 Subject: [PATCH 13/14] added second link to cartocss.md --- doc/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/API.md b/doc/API.md index a949813..536d779 100644 --- a/doc/API.md +++ b/doc/API.md @@ -130,7 +130,7 @@ One of two core classes for the Torque library - it is used to create a static t |-----------|:-----------|:----------|:---------------------------------------| | ```setCartoCSS(cartocss)``` | ```cartocss string``` | ```this``` | style the map rendering using client-side cartocss | -``value`` and ``zoom`` variables can be used. only ``polygon-fill`` property is supported currently +``value`` and ``zoom`` variables can be used. only ``polygon-fill`` property is supported currently. To see the full list of supported parameters, read the [Torque CartoCSS documentation here](CartoCSS.md). TorqueLayer currently expects ```polygon``` styling From b6c0ade69f0b07ec9cb90beb163fb414508b9489 Mon Sep 17 00:00:00 2001 From: Andrew Hill Date: Tue, 20 Aug 2013 17:36:39 -0400 Subject: [PATCH 14/14] table fix --- doc/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/API.md b/doc/API.md index 536d779..5b0f0c4 100644 --- a/doc/API.md +++ b/doc/API.md @@ -122,7 +122,7 @@ One of two core classes for the Torque library - it is used to create a static t | Method | options | returns | Description | |-----------|:-----------|:----------|:---------------------------------------| -| ```setKey(keys)``` | ```keys numeric|array``` | ```this``` | which data categories to display on the map | +| ```setKey(keys)``` | ```keys numeric/array``` | ```this``` | which data categories to display on the map | ### Style options