Add carto module to integrate with CARTO backend

Co-authored-by: Víctor Velarde <victor.velarde@gmail.com> Co-authored-by: Javier Aragón <jaragon@cartodb.com>
visgl · Sep 24, 2020 · ce74dcf · ce74dcf
1 parent e0cd727
commit ce74dcf
Show file tree

Hide file tree

Showing 25 changed files with 1,095 additions and 1 deletion.
diff --git a/docs/api-reference/carto/carto-bqtiler-layer.md b/docs/api-reference/carto/carto-bqtiler-layer.md
@@ -0,0 +1,80 @@
+
+
+# CartoBQTilerLayer
+
+`CartoBQTilerLayer` is a layer to visualize large datasets (millions or billions of rows) directly from [Google BigQuery](https://cloud.google.com/bigquery) without having to move data outside of BigQuery.
+
+First you need first to generate a tileset of your dataset in your BigQuery account using CARTO BigQuery Tiler. For more info click [here](https://carto.com/bigquery/beta/).
+
+```js
+import DeckGL from '@deck.gl/react';
+import {CartoBQTilerLayer} from '@deck.gl/carto';
+
+
+function App({viewState}) {
+  const layer = new CartoBQTilerLayer({
+          data: 'cartobq.maps.nyc_taxi_points_demo_id',
+          getLineColor: [255, 255, 255],
+          getFillColor: [238, 77, 90],
+          pointRadiusMinPixels: 2,
+          lineWidthMinPixels: 1
+        });
+
+  return <DeckGL viewState={viewState} layers={[layer]} />;
+}
+```
+
+## Installation
+
+To install the dependencies from NPM:
+
+```bash
+npm install deck.gl
+# or
+npm install @deck.gl/core @deck.gl/layers @deck.gl/carto
+```
+
+```js
+import {CartoBQTilerLayer} from '@deck.gl/carto';
+new CartoBQTilerLayer({});
+```
+
+To use pre-bundled scripts:
+
+```html
+<script src="https://unpkg.com/deck.gl@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+
+<!-- or -->
+<script src="https://unpkg.com/@deck.gl/core@^8.0.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/layers@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/geo-layers@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+```
+
+```js
+new deck.carto.CartoBQTilerLayer({});
+```
+
+
+## Properties
+
+Inherits all properties from [`MVTLayer`](/docs/api-reference/geo-layers/mvt-layer.md).
+
+
+##### `data` (String)
+
+Required. Tileset id
+
+##### `uniqueIdProperty` (String)
+
+* Default: `id`
+
+Optional. Needed for highlighting a feature split across two or more tiles if no [feature id](https://github.com/mapbox/vector-tile-spec/tree/master/2.1#42-features) is provided.
+
+A string pointing to a tile attribute containing a unique identifier for features across tiles.
+
+
+## Source
+
+[modules/carto/src/layers/carto-bqtiler-layer.js](https://github.com/visgl/deck.gl/tree/master/modules/carto/src/layers/carto-bqtiler-layer.js)
diff --git a/docs/api-reference/carto/carto-sql-layer.md b/docs/api-reference/carto/carto-sql-layer.md
@@ -0,0 +1,114 @@
+
+
+# CartoSQLLayer
+
+`CartoSQLLayer` is a layer to visualize data hosted in your CARTO account and to apply custom SQL.
+
+```js
+import DeckGL from '@deck.gl/react';
+import {CartoSQLLayer, setDefaultCredentials} from '@deck.gl/carto';
+
+setDefaultCredentials({
+  username: 'public',
+  apiKey: 'default_public'
+});
+
+function App({viewState}) {
+  const layer = new CartoSQLLayer({
+    data: 'SELECT * FROM world_population_2015',
+    pointRadiusMinPixels: 2,
+    getLineColor: [0, 0, 0, 0.75],
+    getFillColor: [238, 77, 90],
+    lineWidthMinPixels: 1
+  })
+
+  return <DeckGL viewState={viewState} layers={[layer]} />;
+}
+```
+
+## Installation
+
+To install the dependencies from NPM:
+
+```bash
+npm install deck.gl
+# or
+npm install @deck.gl/core @deck.gl/layers @deck.gl/carto
+```
+
+```js
+import {CartoSQLLayer} from '@deck.gl/carto';
+new CartoSQLLayer({});
+```
+
+To use pre-bundled scripts:
+
+```html
+<script src="https://unpkg.com/deck.gl@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+
+<!-- or -->
+<script src="https://unpkg.com/@deck.gl/core@^8.0.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/layers@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/geo-layers@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+```
+
+```js
+new deck.carto.CartoSQLLayer({});
+```
+
+
+## Properties
+
+Inherits all properties from [`MVTLayer`](/docs/api-reference/geo-layers/mvt-layer.md).
+
+
+##### `data` (String)
+
+Required. Either a sql query or a name of dataset
+
+##### `uniqueIdProperty` (String)
+
+* Default: `cartodb_id`
+
+Optional. A string pointing to a unique attribute at the result of the query. A unique attribute is needed for highlighting a feature split across two or more tiles.
+
+
+##### `credentials` (Object)
+
+Optional. Object with the credentials to connect with CARTO.
+
+* Default:
+
+```js
+{
+  username: 'public',
+  apiKey: 'default_public',
+  serverUrlTemplate: 'https://{user}.carto.com'
+}
+```
+
+##### `bufferSize` (Number)
+
+Optional. MVT BufferSize in pixels
+
+* Default: `1`
+
+##### `version` (String)
+
+Optional. MapConfig version
+
+* Default: `1.3.1`
+
+
+##### `tileExtent` (String)
+
+Optional. Tile extent in tile coordinate space as defined by MVT specification.
+
+* Default: `4096`
+
+
+## Source
+
+[modules/carto/src/layers/carto-sql-layer.js](https://github.com/visgl/deck.gl/tree/master/modules/carto/src/layers/carto-sql-layer.js)
diff --git a/docs/api-reference/carto/overview.md b/docs/api-reference/carto/overview.md
@@ -0,0 +1,56 @@
+# @deck.gl/carto
+
+Deck.gl is the preferred and official solution for creating modern Webapps using the [CARTO Location Intelligence platform](https://carto.com/)
+
+<img src="https://raw.githubusercontent.com/CartoDB/viz-doc/master/deck.gl/img/osm_buildings.jpg" />
+
+
+It integrates with the [CARTO Maps API](https://carto.com/developers/maps-api/reference/) to:
+
+* Provide a geospatial backend storage for your geospatial data.
+* Visualize large datasets which do not fit within browser memory.
+* Provide an SQL spatial interface to work with your data.
+
+
+## Install package
+
+```bash
+npm install deck.gl
+# or
+npm install @deck.gl/core @deck.gl/layers @deck.gl/geo-layers @deck.gl/carto
+```
+
+## Usage
+
+```js
+import DeckGL from '@deck.gl/react';
+import {CartoSQLLayer, setDefaultCredentials} from '@deck.gl/carto';
+
+setDefaultCredentials({
+  username: 'public',
+  apiKey: 'default_public'
+});
+
+function App({viewState}) {
+  const layer = new CartoSQLLayer({
+    data: 'SELECT * FROM world_population_2015',
+    pointRadiusMinPixels: 2,
+    getLineColor: [0, 0, 0, 0.75],
+    getFillColor: [238, 77, 90],
+    lineWidthMinPixels: 1
+  })
+
+  return <DeckGL viewState={viewState} layers={[layer]} />;
+}
+```
+
+### Examples
+
+You can see real examples for the following:
+
+* [Scripting](https://carto.com/developers/deck-gl/examples/): Quick scripting examples to play with the module without NPM or Webpack. If you're not a web developer, this is probably what you're looking for.
+
+* [React](https://github.com/CartoDB/viz-doc/tree/master/deck.gl/examples/react): integrate in a React application.
+
+* [Pure JS](https://github.com/CartoDB/viz-doc/tree/master/deck.gl/examples/pure-js): integrate in a pure js application, using webpack.
+
diff --git a/docs/table-of-contents.json b/docs/table-of-contents.json
@@ -182,6 +182,14 @@
             {"entry": "docs/api-reference/arcgis/load-arcgis-modules"}
           ]
         },
+        {
+          "title": "@deck.gl/carto",
+          "entries": [
+            {"entry": "docs/api-reference/carto/overview"},
+            {"entry": "docs/api-reference/carto/carto-sql-layer"},
+            {"entry": "docs/api-reference/carto/carto-bqtiler-layer"}
+          ]
+        },
         {
           "title": "@deck.gl/google-maps",
           "entries": [

diff --git a/examples/get-started/pure-js/carto/README.md b/examples/get-started/pure-js/carto/README.md
@@ -0,0 +1,8 @@
+Pure js demo for CARTO layers
+
+### Usage
+Copy the content of this folder to your project. Run
+```js
+yarn
+yarn start
+```
diff --git a/examples/get-started/pure-js/carto/app.js b/examples/get-started/pure-js/carto/app.js
@@ -0,0 +1,110 @@
+import mapboxgl from 'mapbox-gl';
+import {Deck} from '@deck.gl/core';
+import {CartoSQLLayer, CartoBQTilerLayer, setDefaultCredentials} from '@deck.gl/carto';
+
+const INITIAL_VIEW_STATE = {
+  latitude: 0,
+  longitude: 0,
+  zoom: 1
+};
+
+setDefaultCredentials({
+  username: 'public',
+  apiKey: 'default_public'
+});
+
+// Add Mapbox GL for the basemap. It's not a requirement if you don't need a basemap.
+const map = new mapboxgl.Map({
+  container: 'map',
+  style: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
+  interactive: false,
+  center: [INITIAL_VIEW_STATE.longitude, INITIAL_VIEW_STATE.latitude],
+  zoom: INITIAL_VIEW_STATE.zoom
+});
+
+// Define color breaks for CartoBQTilerLayer
+const BUILDINGS_COLORS = {
+  ONE_MILLION: [207, 89, 126],
+  HUNDRED_THOUSAND: [232, 133, 113],
+  TEN_THOUSAND: [238, 180, 121],
+  THOUSAND: [233, 226, 156],
+  HUNDRED: [156, 203, 134],
+  TEN: [57, 177, 133],
+  OTHER: [0, 147, 146]
+};
+
+// Set the default visible layer
+let visibleLayer = 'airports';
+
+// Create Deck.GL map
+export const deck = new Deck({
+  canvas: 'deck-canvas',
+  width: '100%',
+  height: '100%',
+  initialViewState: INITIAL_VIEW_STATE,
+  controller: true,
+  onViewStateChange: ({viewState}) => {
+    // Synchronize Deck.gl view with Mapbox
+    map.jumpTo({
+      center: [viewState.longitude, viewState.latitude],
+      zoom: viewState.zoom,
+      bearing: viewState.bearing,
+      pitch: viewState.pitch
+    });
+  }
+});
+
+// Add event listener to radio buttons
+document.getElementsByName('layer-visibility').forEach(e => {
+  e.addEventListener('click', () => {
+    visibleLayer = e.value;
+    render();
+  });
+});
+
+render();
+
+// Function to render the layers. Will be invoked any time visibility changes.
+function render() {
+  const layers = [
+    new CartoSQLLayer({
+      id: 'airports',
+      data: 'SELECT * FROM ne_10m_airports',
+      visible: visibleLayer === 'airports',
+      filled: true,
+      pointRadiusMinPixels: 2,
+      pointRadiusScale: 2000,
+      getRadius: f => 11 - f.properties.scalerank,
+      getFillColor: [200, 0, 80, 180],
+      autoHighlight: true,
+      highlightColor: [0, 0, 128, 128],
+      pickable: true
+    }),
+    new CartoBQTilerLayer({
+      id: 'osm_buildings',
+      data: 'cartobq.maps.osm_buildings',
+      visible: visibleLayer === 'building',
+      getFillColor: object => {
+        // Apply color based on an attribute
+        if (object.properties.aggregated_total > 1000000) {
+          return BUILDINGS_COLORS.ONE_MILLION;
+        } else if (object.properties.aggregated_total > 100000) {
+          return BUILDINGS_COLORS.HUNDRED_THOUSAND;
+        } else if (object.properties.aggregated_total > 10000) {
+          return BUILDINGS_COLORS.TEN_THOUSAND;
+        } else if (object.properties.aggregated_total > 1000) {
+          return BUILDINGS_COLORS.THOUSAND;
+        } else if (object.properties.aggregated_total > 100) {
+          return BUILDINGS_COLORS.HUNDRED;
+        } else if (object.properties.aggregated_total > 10) {
+          return BUILDINGS_COLORS.TEN;
+        }
+        return BUILDINGS_COLORS.OTHER;
+      },
+      pointRadiusMinPixels: 2,
+      stroked: false
+    })
+  ];
+  // update layers in deck.gl.
+  deck.setProps({layers});
+}