Merge ab7cf33 into 000eab9

visgl · Mar 15, 2020 · b4122ff · b4122ff
2 parents 000eab9 + ab7cf33
commit b4122ff
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 87 deletions.
diff --git a/README.md b/README.md
@@ -20,78 +20,59 @@
 [![docs](http://i.imgur.com/mvfvgf0.jpg)](https://uber.github.io/deck.gl)
 
 
-## Installation
+deck.gl is designed to make visualization of large data sets simple. It enables users to quickly get impressive visual results with limited effort through composition of existing layers, while offering a complete architecture for packaging advanced WebGL based visualizations as reusable JavaScript layers.
 
+The basic idea of using deck.gl is to map **data** (usually an array of JSON objects) into a stack of visual **layers** - e.g. icons, polygons, texts; and look at them with **views**: map, first-person, orthographic, etc.
+
+deck.gl handles a number of challenges out of the box:
+
+* Rendering of large data sets and performant updates
+* Interactive event handling such as picking, highlighting and filtering
+* Cartographic projections and integration with major basemap providers
+* A catalog of proven, well-tested layers
+
+One of deck.gl's philosophies is to be highly customizable. All layers come with flexible APIs to allow programmatic control of every aspect of the rendering. All core classes such as Layer, View, Controller, Effect and Transition are designed to be easily extendable by the users to address custom use cases.
+
+## Flavors
+
+### Script Tag
+
+```html
+<script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script>
 ```
+
+- [Get started](/docs/get-started/using-standalone.md#using-the-scripting-api)
+- [Full examples](https://github.com/uber/deck.gl/tree/master/examples/get-started/scripting)
+
+### NPM Module
+
+```bash
 npm install deck.gl
 ```
 
-## Using deck.gl
-
-deck.gl offers an extensive catalog of pre-packaged visualization "layers", including [ScatterplotLayer](http://deck.gl/#/documentation/deckgl-api-reference/layers/scatterplot-layer), [ArcLayer](http://deck.gl/#/documentation/deckgl-api-reference/layers/arc-layer), [TextLayer](http://deck.gl/#/documentation/deckgl-api-reference/layers/text-layer), [GeoJsonLayer](http://deck.gl/#/documentation/deckgl-api-reference/layers/geojson-layer), etc. The input to a layer is usually an array of JSON objects. Each layer offers a highly-flexible API to customize how the data should be rendered.
-
-Example constructing a deck.gl ScatterplotLayer:
-
-```js
-import {ScatterplotLayer} from '@deck.gl/layers';
-
-/**
- * data is an array of object in the shape of:
- * {
- *   "name":"Montgomery St. (MONT)",
- *   "address":"598 Market Street, San Francisco CA 94104",
- *   "entries":"43430",
- *   "exits":"45128",
- *   "coordinates":[-122.401407,37.789256]
- * }
- */
-const scatterplotLayer = new ScatterplotLayer({
-  id: 'bart-stations',
-  data: 'https://github.com/uber-common/deck.gl-data/blob/master/website/bart-stations.json',
-  getRadius: d => Math.sqrt(d.entries) / 100,
-  getPosition: d => d.coordinates,
-  getFillColor: [255, 228, 0],
-});
-```
+#### Pure JS
 
-## Using deck.gl with React
+- [Get started](/docs/get-started/using-standalone.md)
+- [Full examples](https://github.com/uber/deck.gl/tree/master/examples/get-started/pure-js)
 
-```js
-import DeckGL from 'deck.gl';
+#### React
 
-<DeckGL
-  width="100%"
-  height="100%"
-  initialViewState={{longitude: -122.4, latitude: 37.78, zoom: 8}}
-  controller={true}
-  layers={[scatterplotLayer]} />
-```
+- [Get started](/docs/get-started/using-with-react.md)
+- [Full examples](https://github.com/uber/deck.gl/tree/master/examples/get-started/react)
 
-## Using deck.gl with Pure JS
-
-```js
-import {Deck} from '@deck.gl/core';
-
-const deck = new Deck({
-  width: '100vw',
-  height: '100vh',
-  initialViewState: {
-    longitude: -122.4,
-    latitude: 37.78,
-    zoom: 8
-  },
-  controller: true,
-  layers: [scatterplotLayer]
-});
+### Python
+
+```bash
+pip install pydeck
 ```
 
-Minimum setups of end-to-end deck.gl usage is also showcased in the [hello-world examples](./examples/get-started), using both [webpack](https://webpack.js.org/) and [browserify](http://browserify.org/), so you can choose which bundler you prefer or are more familiar with.
+- [Get started](https://github.com/uber/deck.gl/blob/master/bindings/pydeck/README.md)
 
-To learn how to use deck.gl through the many examples that come with the deck.gl repo, please clone the latest **release** branch:
+### Third-Party Bindings
 
-```
-git clone -b 7.3-release --single-branch https://github.com/uber/deck.gl.git
-```
+- [deckgl-typings](https://github.com/danmarshall/deckgl-typings) (Typescript)
+- [mapdeck](https://symbolixau.github.io/mapdeck/articles/mapdeck.html) (R)
+- [vega-deck.gl](https://github.com/microsoft/SandDance/tree/master/packages/vega-deck.gl) ([Vega](https://vega.github.io/))
 
 For the most up-to-date information, see our [API documentations](http://deck.gl/#/documentation)
 

diff --git a/docs/README.md b/docs/README.md
@@ -2,49 +2,83 @@
 
 <p align="center">
   These docs are for
-  <a href="https://github.com/uber/deck.gl/blob/7.2-release/docs/README.md">
-    <img src="https://img.shields.io/badge/deck.gl-v7.2-brightgreen.svg?style=flat-square" />
+  <a href="https://github.com/uber/deck.gl/blob/8.1-release/docs/README.md">
+    <img src="https://img.shields.io/badge/deck.gl-v8.1-brightgreen.svg?style=flat-square" />
   </a>
   Looking for an old version?
-  <a href="https://github.com/uber/deck.gl/blob/7.1-release/docs/README.md">
-    <img src="https://img.shields.io/badge/deck.gl-v7.1-green.svg?style=flat-square" />
-  <a href="https://github.com/uber/deck.gl/blob/7.0-release/docs/README.md">
-    <img src="https://img.shields.io/badge/deck.gl-v7.0-green.svg?style=flat-square" />
-  <a href="https://github.com/uber/deck.gl/blob/6.0-release/docs/README.md">
-    <img src="https://img.shields.io/badge/deck.gl-v6.0-green.svg?style=flat-square" />
+  <a href="https://github.com/uber/deck.gl/blob/8.0-release/docs/README.md">
+    <img src="https://img.shields.io/badge/deck.gl-v8.0-green.svg?style=flat-square" />
   </a>
-  <a href="https://github.com/uber/deck.gl/blob/5.0-release/docs/README.md">
-    <img src="https://img.shields.io/badge/v-5.0-green.svg?style=flat-square" />
+  <a href="https://github.com/uber/deck.gl/blob/7.3-release/docs/README.md">
+    <img src="https://img.shields.io/badge/deck.gl-v7.3-green.svg?style=flat-square" />
   </a>
-  <a href="https://github.com/uber/deck.gl/blob/4.0-release/docs/README.md">
-    <img src="https://img.shields.io/badge/v-4.0-green.svg?style=flat-square" />
-  </a>
-  <a href="https://github.com/uber/deck.gl/tree/3.0-release/docs/README.md">
-    <img src="https://img.shields.io/badge/v-3.0-green.svg?style=flat-square" />
+  <a href="https://github.com/uber/deck.gl/blob/6.4-release/docs/README.md">
+    <img src="https://img.shields.io/badge/deck.gl-v6.4-green.svg?style=flat-square" />
   </a>
 </p>
 
 deck.gl is designed to make visualization of large data sets simple. It enables users to quickly get impressive visual results with limited effort through composition of existing layers, while offering a complete architecture for packaging advanced WebGL based visualizations as reusable JavaScript layers.
 
-## Brief Overview
-
-The basic idea of using deck.gl is to render a stack of visual overlays, usually (but not always) over maps.
+The basic idea of using deck.gl is to map **data** (usually an array of JSON objects) into a stack of visual **layers** - e.g. icons, polygons, texts; and look at them with **views**: map, first-person, orthographic, etc.
 
-To make this simple concept work, deck.gl handles a number of challenges:
+deck.gl handles a number of challenges out of the box:
 
-* Handling of large data sets and performant updates
-* Interactive event handling such as picking
-* Cartographic projections and integration with underlying map
+* Rendering of large data sets and performant updates
+* Interactive event handling such as picking, highlighting and filtering
+* Cartographic projections and integration with major basemap providers
 * A catalog of proven, well-tested layers
-* Easy to create new layers or customize existing layers
+
+One of deck.gl's philosophies is to be highly customizable. All layers come with flexible APIs to allow programmatic control of every aspect of the rendering. All core classes such as Layer, View, Controller, Effect and Transition are designed to be easily extendable by the users to address custom use cases.
+
+## Flavors
+
+### Script Tag
+
+```html
+<script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script>
+```
+
+- [Get started](/docs/get-started/using-standalone.md#using-the-scripting-api)
+- [Full examples](https://github.com/uber/deck.gl/tree/master/examples/get-started/scripting)
+
+### NPM Module
+
+```bash
+npm install deck.gl
+```
+
+#### Pure JS
+
+- [Get started](/docs/get-started/using-standalone.md)
+- [Full examples](https://github.com/uber/deck.gl/tree/master/examples/get-started/pure-js)
+
+#### React
+
+- [Get started](/docs/get-started/using-with-react.md)
+- [Full examples](https://github.com/uber/deck.gl/tree/master/examples/get-started/react)
+
+### Python
+
+```bash
+pip install pydeck
+```
+
+- [Get started](https://github.com/uber/deck.gl/blob/master/bindings/pydeck/README.md)
+
+### Third-Party Bindings
+
+- [deckgl-typings](https://github.com/danmarshall/deckgl-typings) (Typescript)
+- [mapdeck](https://symbolixau.github.io/mapdeck/articles/mapdeck.html) (R)
+- [vega-deck.gl](https://github.com/microsoft/SandDance/tree/master/packages/vega-deck.gl) ([Vega](https://vega.github.io/))
 
 ## Ecosystem
 
 deck.gl is one of the main frameworks in the [vis.gl](http://vis.gl) framework suite.
 
-deck.gl has been developed in parallel with a number of companion modules, e.g.:
+deck.gl has been developed in parallel with a number of companion modules, including:
 
 * [luma.gl](https://luma.gl/) - A general purpose WebGL library designed to be interoperable both with the raw WebGL API and (as far as possible) with other WebGL libraries. In particular, luma.gl does not claim ownership of the WebGL context, and can work with any supplied context, including contexts created by the application or other WebGL libraries.
+* [loaders.gl](https://loaders.gl) - a suite of framework-independent loaders for file formats focused on visualization of big data, including point clouds, 3D geometries, images, geospatial formats as well as tabular data.
 * [react-map-gl](https://uber.github.io/react-map-gl/) - A React wrapper around Mapbox GL which works seamlessly with deck.gl.
 * [nebula.gl](https://nebula.gl/) - A high-performance feature editing framework for deck.gl.
 

diff --git a/docs/get-started/learning-resources.md b/docs/get-started/learning-resources.md
@@ -1,13 +1,23 @@
 # Learning Resources
 
-## Vis Academy
+## Technical Deep Dive
 
-In-depth tutorials for how to develop deck.gl applications are available on the [Vis Academy](http://vis.academy/#/) website. Focused on React applications.
+An in-depth view into the technical details and architectural decisions behind deck.gl. [Google Slides](https://docs.google.com/presentation/d/1qtXUQzMuIa8NYIKUa1RKfSwvgpeccY-wrPrYqsb_8rE/edit#slide=id.g7db7fb98fb_0_45)
 
 ## Prototyping & Sharing
 
-PureJS examples in prototyping environments. Great templates for feature testing and bug reporting:
+PureJS examples in prototyping environments. These are great templates for feature testing and bug reporting:
 
 * deck.gl's [Codepen demos](https://codepen.io/vis-gl/)
 * deck.gl's [Observable demos](https://beta.observablehq.com/@pessimistress)
-* [Scripting Gallery](http://deck.gl/showcases/gallery/)
+* [One-page scripting examples](http://deck.gl/showcases/gallery/)
+
+## Vis Academy
+
+In-depth tutorials for how to develop deck.gl React applications are available on the [Vis Academy](http://vis.academy/#/) website.
+
+## Community
+
+[vis.gl's Medium blog](https://medium.com/vis-gl) 
+
+Join our [Slack channel](deckgl.slack.com) for learning and discussions.