12 KiB
CartoCSS Properties for Torque Style Maps
While you can use most of the CartoCSS properties to customize Torque maps, CARTO provides additional CartoCSS properties that are specific for Torque style maps. You can add these CartoCSS properties to Torque, Torque Heatmaps, and Torque Category maps.
Note: For a reference of the CartoCSS properties that are currently supported with Torque, see the torque-reference.json file.
CartoCSS - Torque Maps
The following CartoCSS properties can be applied to Torque style maps. Note that some values vary, depending on the type of Torque map you are creating.
-torque-frame-count | -torque-animation-duration | -torque-time-attribute -torque-aggregation-function | -torque-resolution | -torque-data-aggregation frame-offset |
Note: All Torque CartoCSS syntax is prefaced with a hypen.
-torque-frame-count number
Description | Specifies the number of animation steps/frames in your torque animation.
Sample CartoCSS Code | -torque-frame-count:128;
Default Value | 128, the data is broken into 128 time frames when parsing CartoCSS. If the data contains a fewer number of total frames, a lessor value is used.
Available Values | See numbers.
Tip: In the CARTO Builder, this is the STEPS value when the style is ANIMATED.
-torque-animation-duration number
Description | Specifies the length of time for your animation, in seconds.
Sample CartoCSS Code | -torque-animation-duration:30;
Default Value | undefined. Any positive number value is accepted.
Available Values | See numbers. This can also be a decimal - see float.
Tip: In the CARTO Builder, this is the DURATION value when the style is ANIMATED.
-torque-time-attribute string
Description | Defines the name of the date column in your dataset. This column can be an integer or a date.
Sample CartoCSS Code | -torque-time-attribute:"cartodb_id";
Default Value | undefined
Available Values | See string.
Tip: In the CARTO Builder, this is the COLUMN value when the style is ANIMATED.
-torque-aggregation-function keyword
Note: Please note the different available values that should be applied if you are using a Torque Category map.
Description | Since Torque maps renders data in clusters, this property defines how values are displayed in each cluster of the map. Column data must be numeric. For example, you can define: a maximum value, a count, or the total number of values in each cluster.
Note: When visualizing Torque style maps, it is required that you normalize your data to show a total count, or a range, of 0-255. For more details, see this description about statistical normalization.
Sample CartoCSS Code | -torque-aggregation-function: "count(cartodb_id)";
Default Value | "count(cartodb_id)"
Available Values | count(column_name), max(column_name), sum(column_name)
Related Example | Wiki page about how spatial aggregation works.
Note: Since the CARTO geospatial database is built on the PostgreSQL platform and supports advanced PostGIS capabilities, see PostgreSQL Aggregate Functions for additional supported values.
Tip: Functions can also be combinations of functions and operations. For example, log(1 + max(column_name)).
-torque-resolution float
Description | Since Torque maps create a grid from your data and aggregates data to each cell of that grid, this property defines the width and height of each cell, in pixels.
Sample CartoCSS Code | -torque-resolution:2;
Default Value | undefined
Available Values | Resolution values should be applied in powers of 2 (for example, 2 4 8 and so on). The maximum value is 256.
Note: Defining a larger number applies a larger grid to your data.
Tip: In the CARTO Builder, this is the RESOLUTION value when the style is ANIMATED.
-torque-data-aggregation keyword
Description | Defines how Torque maps display past data. By default, linear data aggregation is applied, where no traces of past data appears. Optionally, you can show past data markers cumulatively.
Sample CartoCSS Code | -torque-data-aggregation:linear;
Default Value | linear, does not leave any trace of past data.
Available Values | linear cumulative
Tip: In the CARTO Builder, this is the OVERLAP value when the style is ANIMATED.
frame-offset number
Description | Once your data is aggregated, you can further customize your Torque animation options by specifying how a pixel is rendered in the frames, after the initial rendering (the explosion effect on a Torque map).
Sample CartoCSS Code | [frame-offset=1] { ... }
Default Value | undefined, customize the marker options for each frame-offset property to add more styling.
Available Values | See numbers.
Tip: In the CARTO Builder, this is the TRAILS value when the style is ANIMATED.
The following example displays additional frame-offset values applied to a Torque map.
{% highlight scss %} #twitter_citymaps[frame-offset=1] { marker-width:12; marker-fill-opacity:0.45; } #twitter_citymaps[frame-offset=2] { marker-width:14; marker-fill-opacity:0.225; } #twitter_citymaps[value=1] { marker-fill:#A6CEE3; } {% endhighlight %}
Tip: You can also select each cluster value and apply custom marker styles, based on the data category. For example, suppose you want to apply a unique style only to the maximum value in your dataset, change the marker style for the maximum value in your animation. These values are located in your CartoCSS properties.
The following example displays CartoCSS properties with a Torque map.
{% highlight scss %} /** torque visualization */
Map { -torque-frame-count:512; -torque-animation-duration:30; -torque-time-attribute:"cartodb_id"; -torque-aggregation-function:"count(cartodb_id)"; -torque-resolution:2; -torque-data-aggregation:linear; }
#twitter_citymaps{ comp-op: lighter; marker-fill-opacity: 0.9; marker-line-color: #FFF; marker-line-width: 1.5; marker-line-opacity: 1; marker-type: ellipse; marker-width: 6; marker-fill: #ff9900; } #twitter_citymaps[frame-offset=1] { marker-width:8; marker-fill-opacity:0.45; } #twitter_citymaps[frame-offset=2] { marker-width:10; marker-fill-opacity:0.225; } {% endhighlight %}
CartoCSS - Torque Heatmaps
While any of the Torque CartoCSS properties can be applied to a Torque Heatmap, the following CartoCSS properties can also be applied to Torque Heatmaps.
-
image-filters
functions, enables you to define the color stop for your heatmap -
marker-file
uri, when creating a Torque Heatmap with Carto, marker files are automatically provided. You cannot change these options
Note: It is a known issue that certain marker properties are not supported when applied to Torque and Torque Category maps. Specifically, when the marker-file and marker-fill CartoCSS properties are applied, you cannot color a sprite using the marker-fill value. You must create a sprite per color when applying these properties to Torque map. Optionally, change the map type to a Torque Heatmap as a workaround.
The following example displays CartoCSS properties with a Torque Heatmap.
{% highlight scss %} /** torque_heat visualization */
Map { -torque-frame-count:1; -torque-animation-duration:10; -torque-time-attribute:"cartodb_id"; -torque-aggregation-function:"count(cartodb_id)"; -torque-resolution:2; -torque-data-aggregation:linear; }
#twitter_citymaps{ image-filters: colorize-alpha(blue, cyan, #008000, yellow , orange, red); marker-file: url(http://s3.amazonaws.com/com.cartodb.assets.static/alphamarker.png); marker-fill-opacity: 0.4*[value]; marker-width: 35; } #twitter_citymaps[frame-offset=1] { marker-width:37; marker-fill-opacity:0.2; } #twitter_citymaps[frame-offset=2] { marker-width:39; marker-fill-opacity:0.1; } {% endhighlight %}
CartoCSS - Torque Category Maps
While any of the Torque CartoCSS properties can be applied to a Torque Category map, the -torque-aggregration-function contains different available values that are specific for Torque Category maps.
-torque-aggregation-function keyword (Torque Category only)
Description | Torque Category applies a PostgreSQL command to find the values that appear most often in your data (in order to cluster your data accordingly).
Note: When visualizing Torque style maps, it is required that you normalize your data to show a total count, or a range, of 0-255. For more details, see this description about statistical normalization.
Sample CartoCSS Code | -torque-aggregation-function:"CDB_Math_Mode (torque_category)";
Default Value | "CDB_Math_Mode(torque_category)"
Available Values | count(column_name), max(column_name), sum(column_name)
Tip: For a Torque category layer that is created dynamically with carto.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 example.
Note: column_name is a column that contains an integer or number for each category in the map. If you are applying CartoCSS with the CARTO Editor, you can select a text column. When applied as the CDB_Math_Mode value, the statistical mode, or category, of the most occurrences over time appear as a Torque pixel. If a pixel returns multiple values, the colors may overlap and render incorrectly.
Tip: An advanced math trick to properly blend colors is to apply the sum(distinct(column_name)); value. This enables you to render pixels in categories and apply colors to each value. For example, when all pixel values=1, the sum of distinct is 1. When all pixels values=2, the sum of distinct is 2. When the values are mixed with either 1 or 2, the sum of distinct is 3. You can then apply marker-fill colors to each value category (value=1, value=2, value=3). If you have more than two values in your column, use these guidelines to figure out your own math trick to render the data.
Additionally, you can use the column_name value to diverge values (i.e. when there is only one record of category 1 and 99 records of category 2).
Tip: Since Torque does not return negative values, set this value high, i.e. 100. For example, "100+sum(floor(category_name*1.5)-2)"; converts values to negative and positive values and sums them up. The greater the negative value, the greater the preference to category 1 in the pixel. The greater the positive value, the greater the preference to category 2.
Related Examples | Wiki page about how spatial aggregation works.
The following example displays CartoCSS properties with a Torque Category map.
{% highlight scss %} /** torque_cat visualization */
Map { -torque-frame-count:1024; -torque-animation-duration:30; -torque-time-attribute:"dates"; -torque-aggregation-function:"CDB_Math_Mode(torque_category"; -torque-resolution:2; -torque-data-aggregation:linear; } {% endhighlight %}