Add docs for GPUGridLayer and ContourLayer (visgl#2002)

mpearson · Jul 6, 2018 · c6e8ac1 · c6e8ac1
1 parent cb0e08f
commit c6e8ac1
Show file tree

Hide file tree

Showing 6 changed files with 199 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -47,7 +47,7 @@ const flights = new ArcLayer({
 <DeckGL width={1920} height={1080} layers={[flights]} />
 ```
 
-Simple usage of deck.gl is also showcased in the [hello-world examples](./examples/get-started), using both [webpack2](./examples/get-started/hello-world-webpack2) and [browserify](./examples/get-started/hello-world-browserify), so you can choose which bundler you prefer or are more familiar with.
+Simple usage of deck.gl is also showcased in the [hello-world examples](./examples/get-started), using both [webpack2](./examples/get-started/react-webpack-2) and [browserify](./examples/get-started/react-browserify), so you can choose which bundler you prefer or are more familiar with.
 
 To learn how to use deck.gl through the many examples that coming with the deck.gl repo, please clone the latest **release** branch. `git clone -b 5.3-release --single-branch https://github.com/uber/deck.gl.git`
 

diff --git a/examples/layer-browser/src/examples/experimental-layers.js b/examples/layer-browser/src/examples/experimental-layers.js
@@ -172,7 +172,7 @@ const GPUGridLayerExample = {
   layer: GPUGridLayer,
   getData: () => dataSamples.points,
   props: {
-    id: 'gpuGridLayer',
+    id: 'gpu-grid-layer',
     cellSize: 200,
     opacity: 1,
     extruded: true,

diff --git a/modules/experimental-layers/src/contour-layer/contour-layer.js b/modules/experimental-layers/src/contour-layer/contour-layer.js
@@ -25,7 +25,7 @@ import {LineLayer} from '@deck.gl/layers';
 import {pointToDensityGridData} from '../gpu-grid-layer/gpu-grid-utils';
 import {generateContours} from './contour-utils';
 
-const DEFAULT_COLOR = [255, 0, 255];
+const DEFAULT_COLOR = [255, 255, 255];
 const DEFAULT_THRESHOLD = 1;
 
 const defaultProps = {

diff --git a/modules/experimental-layers/src/contour-layer/contour-layer.md b/modules/experimental-layers/src/contour-layer/contour-layer.md
@@ -0,0 +1,87 @@
+# ContourLayer
+
+## About
+
+`ContourLayer` renders contour lines for a given threshold and cell size. Internally it implements [Marching Squares](https://en.wikipedia.org/wiki/Marching_squares) algorithm to generate contour line segments and feeds them into `LineLayer` to render lines.
+
+```js
+import DeckGL, {GridLayer} from 'deck.gl';
+
+const App = ({data, viewport}) => {
+
+  /**
+   * Data format:
+   * [
+   *   {COORDINATES: [-122.42177834, 37.78346622]},
+   *   ...
+   * ]
+   */
+  const layer = new ContourLayer({
+    id: 'contourLayer',
+    // Three contours are rendered.
+    contours: [
+      {threshold: 1, color: [255, 0, 0]},
+      {threshold: 5, color: [0, 255, 0]},
+      {threshold: 10, color: [0, 0, 255]},
+    ],
+    cellSize: 200,
+    getStrokeWidth: 3
+    getPosition: d => d.COORDINATES,
+  });
+
+  return (<DeckGL {...viewport} layers={[layer]} />);
+};
+```
+
+## Properties
+
+Inherits from all [Base Layer](/docs/api-reference/layer.md) properties.
+
+### Render Options
+
+##### `cellSize` (Number, optional)
+
+* Default: `1000`
+
+Size of each cell in meters
+
+##### `gpuAggregation` (bool, optional)
+
+* Default: true
+
+When set to true and browser supports GPU aggregation, aggregation is performed on GPU. GPU aggregation can be 2 to 3 times faster depending upon number of points and number of cells.
+
+NOTE: GPU Aggregation requires WebGL2 support by the browser. When `gpuAggregation` is set to true and browser doesn't support WebGL2, aggregation falls back to CPU.
+
+##### `contours` (Array, optional)
+
+* Default: `[{threshold: 1}, color: [255, 255, 255]]`
+
+Array of objects with following keys
+* `threshold` (Number) : Threshold value to be used in contour generation.
+* `color` (Array) : RGB color array to be used to render contour lines.
+
+#### `getStrokeWidth` (Number, optional)
+
+* Default: `1`
+
+Width of the contour line in pixels. All contours are rendered with same width, but can have different colors using `contours` prop.
+
+##### `fp64` (Boolean, optional)
+
+* Default: `false`
+
+Whether the layer should be rendered in high-precision 64-bit mode
+
+### Data Accessors
+
+##### `getPosition` (Function, optional)
+
+* Default: `object => object.position`
+
+Method called to retrieve the position of each point.
+
+
+## Source
+
+[modules/experimental-layers/src/contour-layer](https://github.com/uber/deck.gl/tree/master/modules/experimental-layers/src/contour-layer)
diff --git a/modules/experimental-layers/src/gpu-grid-layer/gpu-grid-layer.js b/modules/experimental-layers/src/gpu-grid-layer/gpu-grid-layer.js
@@ -25,8 +25,7 @@ import GPUGridCellLayer from './gpu-grid-cell-layer';
 import {pointToDensityGridData} from './gpu-grid-utils';
 
 const MINCOLOR = [0, 0, 0, 255];
-const CPU_MAXCOLOR = [255, 0, 0, 255];
-const GPU_MAXCOLOR = [0, 255, 0, 255];
+const MAXCOLOR = [0, 255, 0, 255];
 
 const defaultProps = {
   // elevation
@@ -98,7 +97,7 @@ export default class GPUGridLayer extends CompositeLayer {
 
     const {countsBuffer, maxCountBuffer, gridSize, gridOrigin, gridOffset} = this.state;
     const minColor = MINCOLOR;
-    const maxColor = this.props.gpuAggregation ? GPU_MAXCOLOR : CPU_MAXCOLOR;
+    const maxColor = MAXCOLOR;
 
     // return props to the sublayer constructor
     return super.getSubLayerProps({

diff --git a/modules/experimental-layers/src/gpu-grid-layer/gpu-grid-layer.md b/modules/experimental-layers/src/gpu-grid-layer/gpu-grid-layer.md
@@ -0,0 +1,107 @@
+# GPUGridLayer
+
+## About
+
+The GPUGridLayer renders a grid heatmap based on an array of points.
+It takes the constant cell size, aggregates input points in world space (lng/lat space).The color
+and height of the cell is a linear function of number of points it contains.
+
+GPUGridLayer is a `CompositeLayer`
+
+```js
+import DeckGL, {GridLayer} from 'deck.gl';
+
+const App = ({data, viewport}) => {
+
+  /**
+   * Data format:
+   * [
+   *   {COORDINATES: [-122.42177834, 37.78346622]},
+   *   ...
+   * ]
+   */
+  const layer = new GPUGridLayer({
+    id: 'gpu-grid-layer',
+    data,
+    extruded: true,
+    cellSize: 200,
+    elevationScale: 4,
+    getPosition: d => d.COORDINATES,
+  });
+
+  return (<DeckGL {...viewport} layers={[layer]} />);
+};
+```
+
+**Note:** This layer is similar to [GridLayer](/docs/layers/grid-layer.md) but supports aggregation on GPU using new prop `gpuAggregation`. Also several features of [GridLayer](/docs/layers/grid-layer.md) are not yet implemented and currently being worked on.
+
+## Properties
+
+Inherits from all [Base Layer](/docs/api-reference/layer.md) properties.
+
+### Render Options
+
+##### `cellSize` (Number, optional)
+
+* Default: `1000`
+
+Size of each cell in meters
+
+##### `gpuAggregation` (bool, optional)
+
+* Default: true
+
+When set to true and browser supports GPU aggregation, aggregation is performed on GPU. GPU aggregation can be 2 to 3 times faster depending upon number of points and number of cells.
+
+NOTE: GPU Aggregation requires WebGL2 support by the browser. When `gpuAggregation` is set to true and browser doesn't support WebGL2, aggregation falls back to CPU.
+
+##### `coverage` (Number, optional)
+
+* Default: `1`
+
+Cell size multiplier, clamped between 0 - 1. The final size of cell
+is calculated by `coverage * cellSize`. Note: coverage does not affect how points
+are binned. Coverage are linear based.
+
+##### `elevationScale` (Number, optional)
+
+* Default: `1`
+
+Cell elevation multiplier. The elevation of cell is calculated by
+`elevationScale * count`. `count` is number of points that fall into the cell.
+`elevationScale` is a handy property to scale all cells without updating the data.
+
+##### `extruded` (Boolean, optional)
+
+* Default: `true`
+
+Whether to enable cell elevation. Cell elevation scale by count of points in each cell. If set to false, all cell will be flat.
+
+##### `fp64` (Boolean, optional)
+
+* Default: `false`
+
+Whether the layer should be rendered in high-precision 64-bit mode
+
+##### `lightSettings` (Object, optional) **EXPERIMENTAL**
+
+This is an object that contains light settings for extruded polygons.
+Be aware that this prop will likely be changed in a future version of deck.gl.
+
+### Data Accessors
+
+##### `getPosition` (Function, optional)
+
+* Default: `object => object.position`
+
+Method called to retrieve the position of each point.
+
+
+## Following props of GridLyer are not supported yet.
+
+`colorDomain`, `colorRange`, `elevationDomain`,`elevationRange`, `upperPercentile` `lowerPercentile` `elevationUpperPercentile`, `elevationLowerPercentile`
+
+
+## Source
+
+[modules/experimental-layers/src/gpu-grid-layer](https://github.com/uber/deck.gl/tree/master/modules/experimental-layers/src/gpu-grid-layer)