MVTLayer and TerrainLayer switch to use worker-only loaders (visgl#5946)

Author: Pessimistress

docs/api-reference/geo-layers/mvt-layer.md

@@ -117,6 +117,8 @@ On top of the [default options](/docs/api-reference/core/layer.md#loadoptions),
 
 - [MVTLoader](https://loaders.gl/modules/mvt/docs/api-reference/mvt-loader)
 
+Note that by default, the `MVTLoader` parses data using web workers, with code loaded from a [CDN](https://unpkg.com). To change this behavior, see [loaders and workers](/docs/developer-guide/loading-data.md#loaders-and-web-workers).
+
 ##### `binary` (Boolean, optional)
 
 * Default: true

docs/api-reference/geo-layers/terrain-layer.md

@@ -145,21 +145,15 @@ Must be supplied when using non-tiled elevation data.
 - Default: `null`
 
 
-##### `workerUrl` (String, optional)
-
-**Advanced** Supply url to local terrain worker bundle. By default, it points to the latest published `@loaders.gl/terrain` NPM module on [unpkg.com](unpkg.com). Custom `workerUrl` may be desirable if the application wishes to serve the worker code itself without relying on the CDN. The worker bundle can be located locally in `"node_modules/@loaders.gl/terrain/dist/terrain-loader.worker.js"`.
-
-Set `workerUrl` to an empty string to disable worker during debugging (improves error messages).
-
-- Default: `null`
-
-
 ##### `loadOptions` (Object, optional)
 
 On top of the [default options](/docs/api-reference/core/layer.md#loadoptions), also accepts options for the following loaders:
 
+- [TerrainLoader](https://loaders.gl/modules/terrain/docs/api-reference/terrain-loader)
 - [ImageLoader](https://loaders.gl/modules/images/docs/api-reference/image-loader) if the `texture` prop is supplied
 
+Note that by default, the `TerrainLoader` parses data using web workers, with code loaded from a [CDN](https://unpkg.com). To change this behavior, see [loaders and workers](/docs/developer-guide/loading-data.md#loaders-and-web-workers).
+
 
 ### Render Options
 

docs/developer-guide/loading-data.md

@@ -136,6 +136,36 @@ setInterval(() => {
 }, 5 * 60 * 1000);
 ```
 
+
+## Loaders and Web Workers
+
+For the best performance, some specialized loaders parse data using web workers, for example `TerrainLoader` in the [TerrainLayer](/docs/api-reference/geo-layers/terrain-layer.md) and `MVTLoader` in the [MVTLayer](/docs/api-reference/geo-layers/mvt-layer.md). By default, the worker code is loaded from from the latest published NPM module on [unpkg.com](https://unpkg.com).
+
+It might be desirable for some applications to serve the worker code itself without relying on the CDN. To do this, locate the worker bundle locally in `node_modules/@loaders.gl/<module>/dist/<name>-loader.worker.js` and serve it as a static asset with your server. Point the loader to use this alternative URL using `loadOptions.<name>.workerUrl`:
+
+```js
+new MVTLayer({
+  loadOptions: {
+    mvt: {
+      workerUrl: <my_worker_url>
+    }
+  }
+}
+```
+
+If the layer is used in an environment that does not support web workers, or you need to debug the loader code on the main thread, you may import the full loader like this:
+
+```js
+import {MVTLoader} from '@loaders.gl/mvt';
+new MVTLayer({
+  loaders: [MVTLoader],
+  loadOptions: {worker: false}
+});
+```
+
+Refer to each specific layer's documentation to see which loaders are used.
+
+
 ## Load Resource Without an URL
 
 In some use cases, resources do not exist at a static URL. For example, some applications construct images dynamically based on user input. Some applications receive arbitrary binary blobs from a server via a WebSocket connection.

docs/upgrade-guide.md

@@ -25,6 +25,25 @@ The module entry point is now only lightly transpiled for the most commonly used
 - `CartoSQLLayer` will be deprecated in 8.6. Use `CartoLayer` instead with `type` set to `MAP_TYPES.QUERY`.
 - `GeoJsonLayer`'s `getRadius` props is deprecated, replaced by `getPointRadius`.
 - It is recommended to use `zoomOffset` in the `TileLayer` when trying to affect the `zoom` resolution at which tiles are fetched.
+- `MVTLayer` and `TerrainLayer`'s default loaders no longer support parsing on the main thread. This is the same behavior as before, just dropping unused code from the bundle. Should you need to use the layers in an environment where web worker is not available, or debug the loaders, you can supply the full loader as such:
+
+  ```js
+  import {MVTLoader} from '@loaders.gl/mvt';
+  new MVTLayer({
+    loaders: [MVTLoader],
+    loadOptions: {worker: false}
+  });
+  ```
+
+  ```js
+  import {TerrainLoader} from '@loaders.gl/terrain';
+  new TerrainLayer({
+    loaders: [TerrainLoader],
+    loadOptions: {worker: false}
+  });
+  ```
+- `TerrainLayer`'s `workerUrl` prop is removed, use `loadOptions.terrain.workerUrl` instead.
+
 
 ### onError Callback
 

modules/geo-layers/src/mvt-layer/mvt-layer.js

@@ -1,6 +1,6 @@
 import {log} from '@deck.gl/core';
 import {Matrix4} from 'math.gl';
-import {MVTLoader} from '@loaders.gl/mvt';
+import {MVTWorkerLoader} from '@loaders.gl/mvt';
 import {binaryToGeoJson} from '@loaders.gl/gis';
 import {COORDINATE_SYSTEM} from '@deck.gl/core';
 import {_binaryToFeature, _findIndexBinary} from '@deck.gl/layers';
@@ -17,7 +17,7 @@ const WORLD_SIZE = 512;
 const defaultProps = {
   uniqueIdProperty: {type: 'string', value: ''},
   highlightedFeatureId: null,
-  loaders: [MVTLoader],
+  loaders: [MVTWorkerLoader],
   binary: true
 };
 

modules/geo-layers/src/terrain-layer/terrain-layer.js

@@ -18,10 +18,10 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
-import {CompositeLayer} from '@deck.gl/core';
+import {CompositeLayer, log} from '@deck.gl/core';
 import {SimpleMeshLayer} from '@deck.gl/mesh-layers';
 import {WebMercatorViewport, COORDINATE_SYSTEM} from '@deck.gl/core';
-import {TerrainLoader} from '@loaders.gl/terrain';
+import {TerrainWorkerLoader} from '@loaders.gl/terrain';
 import TileLayer from '../tile-layer/tile-layer';
 import {urlType, getURLFromTemplate} from '../tile-layer/utils';
 
@@ -55,7 +55,7 @@ const defaultProps = {
   wireframe: false,
   material: true,
 
-  loaders: [TerrainLoader]
+  loaders: [TerrainWorkerLoader]
 };
 
 // Turns array of templates into a single string to work around shallow change
@@ -95,29 +95,33 @@ export default class TerrainLayer extends CompositeLayer {
       const terrain = this.loadTerrain(props);
       this.setState({terrain});
     }
+
+    // TODO - remove in v9
+    if (props.workerUrl) {
+      log.removed('workerUrl', 'loadOptions.terrain.workerUrl')();
+    }
   }
 
-  loadTerrain({elevationData, bounds, elevationDecoder, meshMaxError, signal, workerUrl}) {
+  loadTerrain({elevationData, bounds, elevationDecoder, meshMaxError, signal}) {
     if (!elevationData) {
       return null;
     }
-    const loadOptions = {
-      ...this.getLoadOptions(),
+    let loadOptions = this.getLoadOptions();
+    loadOptions = {
+      ...loadOptions,
       terrain: {
+        ...loadOptions?.terrain,
         bounds,
         meshMaxError,
         elevationDecoder
       }
     };
-    if (workerUrl !== null) {
-      loadOptions.terrain.workerUrl = workerUrl;
-    }
     const {fetch} = this.props;
     return fetch(elevationData, {propName: 'elevationData', layer: this, loadOptions, signal});
   }
 
   getTiledTerrainData(tile) {
-    const {elevationData, fetch, texture, elevationDecoder, meshMaxError, workerUrl} = this.props;
+    const {elevationData, fetch, texture, elevationDecoder, meshMaxError} = this.props;
     const dataUrl = getURLFromTemplate(elevationData, tile);
     const textureUrl = getURLFromTemplate(texture, tile);
 
@@ -136,8 +140,7 @@ export default class TerrainLayer extends CompositeLayer {
       bounds,
       elevationDecoder,
       meshMaxError,
-      signal,
-      workerUrl
+      signal
     });
     const surface = textureUrl
       ? // If surface image fails to load, the tile should still be displayed

test/modules/geo-layers/mvt-layer.spec.js

@@ -5,6 +5,7 @@ import {ClipExtension} from '@deck.gl/extensions';
 import {transform} from '@deck.gl/geo-layers/mvt-layer/coordinate-transform';
 import {GeoJsonLayer} from '@deck.gl/layers';
 import {geojsonToBinary} from '@loaders.gl/gis';
+import {MVTLoader} from '@loaders.gl/mvt';
 
 import {ScatterplotLayer} from '@deck.gl/layers';
 import {WebMercatorViewport} from '@deck.gl/core';
@@ -442,11 +443,7 @@ test('MVTLayer#triangulation', async t => {
         throw error;
       }
     },
-    loadOptions: {
-      mvt: {
-        workerUrl: null
-      }
-    }
+    loaders: [MVTLoader]
   };
   const testCases = [{props, onAfterUpdate}];
 
@@ -499,11 +496,7 @@ for (const tileset of ['mvt-tiles', 'mvt-with-hole']) {
           throw error;
         }
       },
-      loadOptions: {
-        mvt: {
-          workerUrl: null
-        }
-      }
+      loaders: [MVTLoader]
     };
     const testCases = [
       {props: {binary: false, data: url1, ...props}, onAfterUpdate},

test/modules/geo-layers/terrain-layer.spec.js

@@ -22,13 +22,15 @@ import test from 'tape-catch';
 import {generateLayerTests, testLayerAsync} from '@deck.gl/test-utils';
 import {TerrainLayer, TileLayer} from '@deck.gl/geo-layers';
 import {SimpleMeshLayer} from '@deck.gl/mesh-layers';
+import {TerrainLoader} from '@loaders.gl/terrain';
 
 test('TerrainLayer', async t => {
   const testCases = generateLayerTests({
     Layer: TerrainLayer,
     sampleProps: {
       elevationData: 'https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png',
-      texture: 'https://wms.chartbundle.com/tms/1.0.0/sec/{z}/{x}/{y}.png?origin=nw'
+      texture: 'https://wms.chartbundle.com/tms/1.0.0/sec/{z}/{x}/{y}.png?origin=nw',
+      loaders: [TerrainLoader]
     },
     assert: t.ok,
     onBeforeUpdate: ({testCase}) => t.comment(testCase.title),
@@ -44,7 +46,8 @@ test('TerrainLayer', async t => {
     Layer: TerrainLayer,
     sampleProps: {
       elevationData: 'https://s3.amazonaws.com/elevation-tiles-prod/terrarium/1/0/0.png',
-      bounds: [-180, 85, 0, 0]
+      bounds: [-180, 85, 0, 0],
+      loaders: [TerrainLoader]
     },
     assert: t.ok,
     onBeforeUpdate: ({testCase}) => t.comment(testCase.title),