From 5e933ed8fc7e6c8911cbafca227f790e305f4a5d Mon Sep 17 00:00:00 2001 From: Xiaoji Chen Date: Fri, 12 Apr 2019 17:05:03 -0700 Subject: [PATCH] Update what's new and get-started docs (#2969) --- docs/api-reference/react/deckgl.md | 5 +- docs/get-started/getting-started.md | 2 +- docs/get-started/using-standalone.md | 2 +- docs/get-started/using-with-map.md | 62 ++++++++++++++++++++++++ docs/get-started/using-with-mapbox-gl.md | 43 ---------------- docs/get-started/using-with-react.md | 6 ++- docs/whats-new.md | 49 +++++++++++-------- website/contents/pages.js | 4 +- 8 files changed, 102 insertions(+), 71 deletions(-) create mode 100644 docs/get-started/using-with-map.md delete mode 100644 docs/get-started/using-with-mapbox-gl.md diff --git a/docs/api-reference/react/deckgl.md b/docs/api-reference/react/deckgl.md index e934495965f..679f39ae7ef 100644 --- a/docs/api-reference/react/deckgl.md +++ b/docs/api-reference/react/deckgl.md @@ -11,7 +11,8 @@ The `DeckGL` class is a React wrapper of the `Deck` JavaScript class which expos ```js // Basic usage -import DeckGL, {ScatterplotLayer} from 'deck.gl'; +import DeckGL from '@deck.gl/react'; +import {ScatterplotLayer} from '@deck.gl/layers'; const App = (data) => ( ( Like any React component, `DeckGL` can accept child components. Child components are often maps (e.g. the `StaticMap` component from react-map-gl), but can be any React components. ```js -import DeckGL from 'deck.gl'; +import DeckGL from '@deck.gl/react'; import {StaticMap} from 'react-map-gl'; const App = (data) => ( diff --git a/docs/get-started/getting-started.md b/docs/get-started/getting-started.md index 1c591486ac9..563e61eeea0 100644 --- a/docs/get-started/getting-started.md +++ b/docs/get-started/getting-started.md @@ -55,7 +55,7 @@ and then running using: npm start ``` -If the example uses a mapbox base map you need a [Mapbox access token](/docs/get-started/using-with-mapbox-gl.md) +If the example uses a mapbox base map you need a [Mapbox access token](/docs/get-started/using-with-map.md) ```bash export MapboxAccessToken={Your Token Here} && npm start diff --git a/docs/get-started/using-standalone.md b/docs/get-started/using-standalone.md index 986a14df143..6f096cf86d5 100644 --- a/docs/get-started/using-standalone.md +++ b/docs/get-started/using-standalone.md @@ -2,7 +2,7 @@ The deck.gl core library and layers have no dependencies on React or Mapbox GL and can be used by any JavaScript application. -Our [examples](https://github.com/uber/deck.gl/tree/master/examples/get-started) contains a few "pure JS" templates that serve as a starting point for your application. +Our [get-started examples](https://github.com/uber/deck.gl/tree/master/examples/get-started) contains non-React templates that serve as a starting point for your application. ## Using @deck.gl/core diff --git a/docs/get-started/using-with-map.md b/docs/get-started/using-with-map.md new file mode 100644 index 00000000000..e9b8cf4564e --- /dev/null +++ b/docs/get-started/using-with-map.md @@ -0,0 +1,62 @@ +# Using deck.gl with a Base Map + +While deck.gl works independently without any map component, when visualizing geographic datasets, a base map could offer the invaluable context for understanding the overlay layers. + +deck.gl has been designed to work in tandem with popular JavaScript base map providers, especially Mapbox. Depending on your tech stack, deck.gl's support for a particular base map solution may come with different level of compatibility and limitations. + +## Using deck.gl with Mapbox GL JS + +[mapbox-gl](https://github.com/mapbox/mapbox-gl-js) is a powerful open-source map renderer from [Mapbox](https://mapbox.com). deck.gl's `MapView` is designed to sync perfectly with the camera of Mapbox, at every zoom level and rotation angle. + +When using deck.gl and Mapbox, there are two options you can choose from: + +- Using the Deck canvas as a overlay on top of the Mapbox map, in [pure JS](https://github.com/uber/deck.gl/tree/master/examples/get-started/pure-js/mapbox) or [React](https://github.com/uber/deck.gl/tree/master/examples/get-started/react/mapbox). This is the most tested and robust use case. +- Using deck.gl layers as custom Mapbox layers, using the [@deck.gl/mapbox](/docs/api-reference/mapbox/overview.md) module. This allows you to interleave deck.gl layers with base map layers, e.g. below text labels or occlude each other correctly in 3D. Be cautious that this feature is experimental: we are working closely with Mapbox to evolve the API. + + + + +### react-map-gl + +[react-map-gl](https://github.com/uber/react-map-gl) is a React wrapper around mapbox-gl. If you'd like to use deck.gl with React, this component is the recommended companion. + +All the [examples on this website](https://github.com/uber/deck.gl/tree/master/examples/website) are implemented using the React integration. The `DeckGL` React component works especially well as the parent of a react-map-gl [StaticMap](https://uber.github.io/react-map-gl/#/Documentation/api-reference/static-map), which automatically interprets the deck.gl view state (i.e. latitude, longitude, zoom etc). In this configuration your deck.gl layers will render as a perfectly synchronized geospatial overlay over the underlying map. + +### About Mapbox Tokens + +The mapbox-gl library is open source and free to use. However, to load the map styles and tiles from Mapbox's data service, you will need to register on their website in order to retrieve an [access token](https://docs.mapbox.com/help/how-mapbox-works/access-tokens/) required by the map component, which will be used to identify you and start serving up map tiles. The service will be free until a certain level of traffic is exceeded. + +If you are using mapbox-gl without React, check out [Mapbox GL JS API](https://docs.mapbox.com/mapbox-gl-js/api/#accesstoken) for how to apply the token. + +If you are using react-map-gl, there are several ways to provide a token to your app: + +* Set the `MapboxAccessToken` environment variable. You may need to add additional set up to the bundler ([example](https://webpack.js.org/plugins/environment-plugin/)) so that `process.env.MapboxAccessToekn` is accessible at runtime. +* Provide it in the URL, e.g `?access_token=TOKEN` +* Pass it as a prop to the ReactMapGL instance `` + + +### Display Maps Without A Mapbox Token + +It is possible to use the map component without the Mapbox service, if you use another tile source (for example, if you host your own map tiles). You will need a custom Mapbox GL style that points to your own [vector tile source](https://www.mapbox.com/mapbox-gl-js/style-spec/), and pass it to `ReactMapGL` using the `mapStyle` prop. This custom style must match the schema of your tile source. + +Open source tile schemas include: + +- [TileZen schema](https://tilezen.readthedocs.io/en/latest/layers/) +- [OpenMapTiles schema ](https://openmaptiles.org/schema/) + +Some useful resources for creating your own map service: + +- [Mapbox Vector Tile Spec](https://www.mapbox.com/developers/vector-tiles/) +- [Open source tools](https://github.com/mapbox/awesome-vector-tiles) + + +## Using deck.gl with Google Maps + +Starting v7.0, deck.gl has experimental support for Google Maps with the [@deck.gl/google-maps](/docs/api-reference/google-maps/overview.md) module. It allows you to construct a Deck instance as a custom Google Maps [OverlayView](https://developers.google.com/maps/documentation/javascript/reference/#OverlayView). + + + +The Deck canvas can only be used as a overlay on top of Google Maps, see [pure JS example](https://github.com/uber/deck.gl/tree/master/examples/get-started/pure-js/google-maps). Tilting is not supported due to Google Maps API restrictions. See module documentation page for a full list of features. + +Note that to run the examples, you need a [Google Maps API key](https://developers.google.com/maps/documentation/javascript/get-api-key). + diff --git a/docs/get-started/using-with-mapbox-gl.md b/docs/get-started/using-with-mapbox-gl.md deleted file mode 100644 index a2e4a9f306a..00000000000 --- a/docs/get-started/using-with-mapbox-gl.md +++ /dev/null @@ -1,43 +0,0 @@ -# Using deck.gl with Mapbox GL - -While a deck.gl application could choose to render on top of any JavaScript Map component (or even render without an underlying map), deck.gl has been developed in parallel with the [react-map-gl](https://github.com/uber/react-map-gl) component, which is a React wrapper around mapbox-gl, and is the recommended companion to use deck.gl for most applications. - -## About react-map-gl - -As shown in the [examples](https://github.com/uber/deck.gl/tree/master/examples/), the `DeckGL` React component works especially well as the child of a React component such as react-map-gl that displays a map using parameters similar to the deck.gl Viewport (i.e. latitude, longitude, zoom etc). In this configuration your deck.gl layers will render as a perfectly synchronized geospatial overlay over the underlying map. - -## About Mapbox Tokens - -react-map-gl and the underlying Mapbox GL JS libraries are open source and free to use. However, to load the map styles and tiles from Mapbox's data service, you will need to register on their website in order to retrieve an [access token](https://docs.mapbox.com/help/how-mapbox-works/access-tokens/) required by the map component, which will be used to identify you and start serving up map tiles. The service will be free until a certain level of traffic is exceeded. - -If you are using mapbox-gl without React, check out [Mapbox GL JS API](https://docs.mapbox.com/mapbox-gl-js/api/#accesstoken) for how to apply the token. - -If you are using react-map-gl, there are several ways to provide a token to your app: - -* Set the `MapboxAccessToken` environment variable. You may need to add additional set up to the bundler ([example](https://webpack.js.org/plugins/environment-plugin/)) so that `process.env.MapboxAccessToekn` is accessible at runtime. -* Provide it in the URL, e.g `?access_token=TOKEN` -* Pass it as a prop to the ReactMapGL instance `` - - -### Display Maps Without A Mapbox Token - -It is possible to use the map component without the Mapbox service, if you use another tile source (for example, if you host your own map tiles). You will need a custom Mapbox GL style that points to your own [vector tile source](https://www.mapbox.com/mapbox-gl-js/style-spec/), and pass it to `ReactMapGL` using the `mapStyle` prop. This custom style must match the schema of your tile source. - -Open source tile schemas include: - -- [TileZen schema](https://tilezen.readthedocs.io/en/latest/layers/) -- [OpenMapTiles schema ](https://openmaptiles.org/schema/) - -Some useful resources for creating your own map service: - -- [Mapbox Vector Tile Spec](https://www.mapbox.com/developers/vector-tiles/) -- [Open source tools](https://github.com/mapbox/awesome-vector-tiles) - - -## Mixing deck.gl and mapbox Layers - -An experimental module ` @deck.gl/mapbox` enables seamless interleaving of mapbox and deck.gl layers. - - - -See [module documentation](/docs/api-reference/mapbox/overview.md) for examples and limitations. diff --git a/docs/get-started/using-with-react.md b/docs/get-started/using-with-react.md index f927c6aa094..79f0138a982 100644 --- a/docs/get-started/using-with-react.md +++ b/docs/get-started/using-with-react.md @@ -10,7 +10,8 @@ To use deck.gl with React, simply import the `DeckGL` React component and render ```jsx /// app.js import React from 'react'; -import DeckGL, {LineLayer} from 'deck.gl'; +import DeckGL from '@deck.gl/react'; +import {LineLayer} from '@deck.gl/layers'; // Viewport settings const viewState = { @@ -46,7 +47,8 @@ An important companion to deck.gl is `react-map-gl`. It is a React wrapper for [ ```jsx /// app.js import React from 'react'; -import DeckGL, {LineLayer} from 'deck.gl'; +import DeckGL from '@deck.gl/react'; +import {LineLayer} from '@deck.gl/layers'; import {StaticMap} from 'react-map-gl'; // Set your mapbox access token here diff --git a/docs/whats-new.md b/docs/whats-new.md index 78037054196..0b48cdade72 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -6,6 +6,12 @@ This page contains highlights of each deck.gl release. Also check our [vis.gl bl Target Release Date: Mar, 2019 +### New Effects System + +A new effects system is written from the ground up for v7.0. This opens the possibilities for many exciting visual effect features down the road. As a start, we're introducing [LightingEffect](/docs/effects/lighting-effect.md) - an easier, more comprehensive way to control the lighting for your layers. + +### New Layer Catalog + @@ -15,7 +21,7 @@ Target Release Date: Mar, 2019
-

MeshLayer

+

ScenegraphLayer

 @@ -25,18 +31,12 @@ Target Release Date: Mar, 2019
-### New Effects System - -A new effects system is written from the ground up for v7.0. This opens the possibilities for many exciting visual effect features down the road. As a start, we're introducing [LightingEffect](/docs/effects/lighting-effect.md) - an easier, more comprehensive way to control the lighting for your layers. - -### New Layer Catalog - As the number of deck.gl layers grow, we are splitting existing and new layers into multiple submodules for better dependency management. These new layer modules are: * `@deck.gl/layers` - Primitive layers that are the building blocks of all visualizations - [ArcLayer](/docs/layers/arc-layer.md) - - [BitmapLayer](/docs/layers/bitmap-layer.md) **New** - - [ColumnLayer](/docs/layers/column-layer.md) **New** + - [BitmapLayer](/docs/layers/bitmap-layer.md) **New** + - [ColumnLayer](/docs/layers/column-layer.md) **New** - [GeoJsonLayer](/docs/layers/geojson-layer.md) - [GridCellLayer](/docs/layers/grid-cell-layer.md) - [IconLayer](/docs/layers/icon-layer.md) @@ -54,27 +54,36 @@ As the number of deck.gl layers grow, we are splitting existing and new layers i - [HexagonLayer](/docs/layers/hexagon-layer.md) - [ScreenGridLayer](/docs/layers/screen-grid-layer.md) * `@deck.gl/geo-layers` - Additional layers that handle geospatial use cases and GIS formats. - - [GreatCircleLayer](/docs/layers/great-circle-layer.md) **New** - - [H3ClusterLayer](/docs/layers/h3-cluster-layer.md) **New** - - [H3HexagonLayer](/docs/layers/h3-hexagon-layer.md) **New** - - [S2Layer](/docs/layers/s2-layer.md) **New** - - [TileLayer](/docs/layers/tile-layer.md) **New** - - [TripsLayer](/docs/layers/trips-layer.md) **New** + - [GreatCircleLayer](/docs/layers/great-circle-layer.md) **New** + - [H3ClusterLayer](/docs/layers/h3-cluster-layer.md) **New** + - [H3HexagonLayer](/docs/layers/h3-hexagon-layer.md) **New** + - [S2Layer](/docs/layers/s2-layer.md) **New** + - [TileLayer](/docs/layers/tile-layer.md) **New** + - [TripsLayer](/docs/layers/trips-layer.md) **New** * `@deck.gl/mesh-layers` - Additional layers that render 3D meshes and [scene graphs](https://en.wikipedia.org/wiki/Scene_graph). - - [SimpleMeshLayer](/docs/layers/simple-mesh-layer.md) **New** - - [ScenegraphLayer](/docs/layers/scenegraph-layer.md) **New** + - [SimpleMeshLayer](/docs/layers/simple-mesh-layer.md) **New** + - [ScenegraphLayer](/docs/layers/scenegraph-layer.md) **New** ### Layer API * **Binary data support**: In v7.0 we are making binary data a first-class citizen of deck.gl. Whereas the `data` prop of layers only accepted JavaScript arrays in the past, you may now provide a non-iterable object to `data`. See [example](/docs/developer-guide/performance.md#on-using-binary-data). -* **Alignment in core layer API**: In the past, some deck.gl layers use pixel sizes (e.g. `IconLayer`, `TextLayer`, `LineLayer` and `ArcLayer`) and some layers use meter sizes (e.g. `ScatterplotLayer`, `PathLayer`). In v7.0 we are introducing new props `sizeUnits` and `widthUnits` that allow users to tweak these behaviors. `*MinPixels` and `*MaxPixels` props are also added for layers that previously only support pixel sizes. +* **Size units**: In the past, some deck.gl layers use pixel sizes (e.g. `IconLayer`, `TextLayer`, `LineLayer` and `ArcLayer`) and some layers use meter sizes (e.g. `ScatterplotLayer`, `PathLayer`). In v7.0 we are introducing new props `sizeUnits` and `widthUnits` that allow users to tweak these behaviors. `*MinPixels` and `*MaxPixels` props are also added for layers that previously only support pixel sizes. +* **Billboard**: Prior this v7.0, `IconLayer` and `TextLayer` are rendered as billboards (i.e. always facing the camera). A prop `billboard` is added to these layers so that you can place icons and texts relative to the world. + +### Google Maps Integration + +Starting v7.0, deck.gl has experimental support for Google Maps with the [@deck.gl/google-maps](/docs/api-reference/google-maps/overview.md) module. It allows you to construct a Deck instance as a custom Google Maps [OverlayView](https://developers.google.com/maps/documentation/javascript/reference/#OverlayView). See module documentation page for a full list of supported features. + + +

GoogleMapsOverlay

### Improved Test Utilities The `@deck.gl/test-utils` module is revamped with two new exports: -* [`generateLayerTests`](/docs/api-reference/test-utils/generate-layer-tests.md) - automatically create test cases for use with [`testLayer`](/docs/api-reference/test-utils/test-layer.md) to test layer conformance. -* [`SnapshotTestRunner`](/docs/api-reference/test-utils/snapshot-test-runner.md) - automated integration test for WebGL. Renders deck.gl layers, takes screenshot and compare with golden images in headless Chromium. +* `generateLayerTests` - automatically create test cases for use with [`testLayer`](/docs/api-reference/test-utils/test-layer.md) to test layer conformance. +* `SnapshotTestRunner` - automated integration test for WebGL. Renders deck.gl layers, takes screenshot and compare with golden images in headless Chromium. +Read more in [Developer Guide: Testing](/docs/developer-guide/testing.md). ## deck.gl v6.4 diff --git a/website/contents/pages.js b/website/contents/pages.js index 4755ac53554..8d576a4f011 100644 --- a/website/contents/pages.js +++ b/website/contents/pages.js @@ -233,8 +233,8 @@ export const docPages = generatePath([ content: getDocUrl('get-started/using-with-react.md') }, { - name: 'Using With Mapbox GL', - content: getDocUrl('get-started/using-with-mapbox-gl.md') + name: 'Using With A Base Map', + content: getDocUrl('get-started/using-with-map.md') }, { name: 'Learning Resources',