doc: updates for v2 (#593)

docs/specifications/category-image.md

@@ -1,10 +1,14 @@
 # Category: Image
 
-> The Image Category is being defined for loaders.gl v2.0 and is currently experimental and unstable.
-
 The image category documents a common data format, options, conventions and utilities for loader and writers for images that follow loaders.gl conventions.
 
-Image category loaders includes: `JPEGLoader`, `PNGLoader`, `GIFLoader`, `BMPLoader`, `SVGLoader` and of course all the loaders in the `ImageLoaders` composite loader.
+Participating Loaders
+
+| Loader                | Notes |
+| --------------------- | ----- |
+| ImageLoader           |       |
+| CompressedImageLoader |       |
+| BasisLoader           |       |
 
 ## Features and Capabilities
 
@@ -16,29 +20,31 @@ Apart from providing a set of image loaders that integrate with loaders.gl, ther
 - Handles SVG images
 - Image type detection (without loading images)
 
-## Installation and Usage
+## Installation
 
-Image category support is bundled in the `@loaders.gl/images` module:
+Core image category support is provided by the `@loaders.gl/images` module:
 
 ```bash
 npm install @loaders.gl/core @loaders.gl/images
 ```
 
+## Usage
+
 Individual loaders for specific image formats can be imported for `@loaders.gl/images`:
 
 ```js
-import {JEPGLoader, PNGLoader} from '@loaders.gl/images';
+import {ImageLoader} from '@loaders.gl/images';
 import {registerLoaders, load} from '@loaders.gl/core';
-registerLoaders([JEPGLoader, PNGLoader]);
+registerLoaders(ImageLoader);
 const image = await load('image.jpeg');
 ```
 
 However since each image loader is quite small (in terms of code size and bundle size impact), most applications will just install all image loaders in one go:
 
 ```js
 import {ImageLoaders} from '@loaders.gl/images';
-import {registerLoaders, load} from '@loaders.gl/core';
-registerLoaders(ImageLoaders);
+import {registerLoader, load} from '@loaders.gl/core';
+registerLoaders(ImageLoader);
 const image = await load('image.jpeg');
 ```
 
@@ -56,25 +62,22 @@ The loaded image representation can vary somewhat based on your environment. For
 
 The image category support some generic options (specified using `options.image.<option-name>`), that are applicable to all (or most) image loaders.
 
-| Option                           | Default       | Type    | Availability    | Description                                          |
-| -------------------------------- | ------------- | ------- | --------------- | ---------------------------------------------------- |
-| `options.image.format`           | `'auto'`      | string  | See table       | One of `auto`, `imagebitmap`, `html`, `ndarray`      |
-| `options.image.decodeHTML`       | `true`        | boolean | No: Edge, IE11  | Wait for HTMLImages to be fully decoded.             |
-| `options.image.crossOrigin`      | `'anonymous'` | boolean | All Browsers    | Sets `crossOrigin` field for HTMLImage loads         |
-| `options.image.useWorkers` (TBA) | `true`        | boolean | Chrome, Firefox | If true, uses worker loaders on supported platforms. |
+| Option                      | Default       | Type    | Availability   | Description                                     |
+| --------------------------- | ------------- | ------- | -------------- | ----------------------------------------------- |
+| `options.image.type`        | `'auto'`      | string  | See table      | One of `auto`, `imagebitmap`, `html`, `ndarray` |
+| `options.image.decodeHTML`  | `true`        | boolean | No: Edge, IE11 | Wait for HTMLImages to be fully decoded.        |
+| `options.image.crossOrigin` | `'anonymous'` | boolean | All Browsers   | Sets `crossOrigin` field for HTMLImage loads    |
 
 ## Notes
 
-### About worker support
+### About worker loading
 
 - Worker loading is only supported for the `imagebitmap` format (on Chrome and Firefox).
-- `ImageBitmap` is **transferrable** and can be moved back to main thread without copying.ß
-- There should be no technical limitations to loading images on workers in node, however node workers are not supported yet.
+- `ImageBitmap` is **transferrable** and can be moved back to main thread without copying.
 
-In contrast to other modules, where worker loaders have to be separately installed, since image workers are small and worker loading is only available on some browsers, the image loaders dynamically determines if worker loading is available.
-Use `options.image.useWorkers: false` to disable worker loading of images on all platforms.
+Since image worker loading is only available on some browsers, the `ImageLoader` dynamically determines if worker loading is available. Use `options.worker: false` to disable worker loading of images.
 
-## Utilities
+## Image API
 
 The image category also provides a few utilities:
 

docs/upgrade-guide.md

@@ -4,6 +4,11 @@
 
 Version 2.0 is a major release that consolidates functionality and APIs, and a number of deprecated functions have been removed.
 
+Some general changes:
+
+- All exported loader and writer objects now expose a `mimeType` field. This field is not yet used by `@loaders.gl/core` but is available for applications (e.g. see `selectLoader`).
+- All (non-worker) loaders are now required to expose a `parse` function (in addition to any more specialized `parseSync/parseText/parseInBatches` functions). This simplifies using loaders without `@loaders.gl/core`, which can reduce footprint in small applications.
+
 ### `@loaders.gl/core`
 
 | Removal            | Replacement                                                            |

docs/whats-new.md

@@ -2,61 +2,62 @@
 
 ## v2.1 (In Development)
 
-Release Date: Target Feb-Mar, 2019.
+Target Release Date: mid-Feb, 2019. `alpha` releases will be made available.
 
-## v2.0
-
-Release Date: Target Dec, 2019, currently available as `2.0.0-beta` releases
+**@loaders.gl/core**
 
-The 2.0 release brings stronger loader composition, image loading improvements, significant overhauls to several loaders and removes deprecated functions across the board.
+- The `load` and `parse` functions can now read directly from `Stream` instances (works for both node and browser streams). However, note that simply reading from a stream does not automatically trigger "streaming" parsing, applications will still want to use `loadInBatches` and `streamInBatches` when processing larger files.
 
-- `@loaders.gl/images`: Redefined as a new Image Category, see below
-- `@loaders.gl/core`: `loader.loadAndParse` removed.
+**@loaders.gl/images**
 
-### @loaders.gl/core
+- Data Texture Loading: `ImageLoader` now accepts a `data: true` parameter that returns image data instead of an actual image, intended for use of images as data textures.
+- `ImageBitmap` Loading: now works correctly: `load(..., ImageLoader, {image: {type 'imagebitmap'}}) => ImageBitmap`
 
-- **Loader Specification Updates**
+**@loaders.gl/wkt** (new loader module)
 
-  - All (non-worker) loaders are now required to expose a `parse` function (in addition to any more specialized `parseSync/parseText/parseInBatches` functions). This simplifies using loaders without `@loaders.gl/core`, which can reduce footprint in small applications.
-  - All exported loader and writer objects now expose a `mimeType` field. This field is not yet used by `@loaders.gl/core` but is available for applications (e.g. see `selectLoader`).
-
-- **Composite Loaders**
+- New loader module for the Well-Known Text geometry format.
 
-  - Loaders can call other loaders
-
-### @loaders.gl/images
+## v2.0
 
-- **Image Category** now defined
+Release Date: Dec 20, 2019
 
-  - Category ensures interchangability
+The 2.0 release brings potentially dramatic bundle size savings through dynamic loading of loaders and workers, significant overhauls to several loaders including , image loading improvements and the glTF loader, and a powerful loader composition system.
 
-- **New ImageLoader options**
-- `options.image` contain common options that apply across the category
+- **Loader-Specific Options** Each loader now defines its own sub object in the options object. This makes it possible to cleanly specify options for multiple loaders at the same time. This is helpful when loaders.gl auto-selects a pre-registered loader or when passing options to a sub-loader when using a composite loader.
 
-  - `options.image.type`, Ability to control loaded image type, default `auto`
-  - TBA `options.image.useWorkers: true` - Worker Image Loaders on Chrome and Firefox
-  - TBA `options.image.decodeHTML: true` - Support for `Image.decode()` to ensure HTML images are ready to be used when loader promise resolves.
+- **Smaller Loaders** Big loaders such as `DracoLoader` and `BasisLoader` that use large libraries (e.g. WASM/WebAssembly or emscripten/C++ transpiled to JavaScript) now load those libraries dynamically from `unpkg.com` CDN resulting in dramatic bundle size savings. E.g the bundle size impact of the `DracoLoader` was reduced from > 1MB to just over 10KB.
 
-- **Parsed Image API** To help working with loaded images across platform
+- **Worker Loaders**
 
-  - `isImage`, `getImageType`, `getImageSize`, `getImageData`, ...
+  - Ease-of-use: Worker loading is provided by the main loader objects. It is not necessary to import the `...WorkerLoader` objects to enable worker loading (but see below about bundle size)
+  - Performance: Loading on worker threads is now the default: All worker enabled loaders now run on worker threads by default (set `options.worker: false` to disable worker-thread loading and run the loader on the main thread).
+  - Debugging: Development builds of workers are now available on `unpkg.com` CDN, eabling debugging of worker loaders.
+  - Bundle size: Workers are no longer bundled, but loaded from from the `unpkg.com` CDN.
+  - Bundle size: Note that the old `...WorkerLoader` classes are still available. Using these can save even more bundle space since during tree-shaking since they do not depend on the non-worker parser.
 
-- **Binary Image API** Separate API to work with unparsed images in binary data form
+- **Composite Loaders**
+  - The new _composite loader_ architecture enables complex loaders like `Tile3DLoader` and `GLTFLoader` to be composed from more primitive loaders without losing the ability to run some parts on worker, pass arguments to sub-loaders etc.
 
-  - `isBinaryImage`, `getBinaryImageType`, `getBinaryImageSize`, ...
+### New Loader Modules
 
-- **Separate Loaders** (Experimental) Now exports a separate micro loader for each format: `_JPEGLoader`, `_PNGLoader`, `_GIFLoader`, `_BMPLoader`, `_SVGLoader`
+- **@loaders.gl/basis** (Experimental) A new module for the basis format that enables. This module also provides a `CompressedImageLoader` for more traditional compressed images.
+- **@loaders.gl/json** (Experimental) A new streaming `JSONLoader` that supports batched (i.e. streaming) parsing from standard JSON files, e.g. geojson. No need to reformat your files as line delimited JSON.
 
-- **Separate Loaders**
+### Update Loader Modules
 
-  - Composite loader (Array) `ImageLoaders` for easy registration.
+- `@loaders.gl/gltf` the `GLTFLoader` is now a "composite loader". The perhaps most important change is that `load(url, GLTFLoader)` also loads all sub-assets, including images, Draco compressed meshes, etc making the loaded data easier for applications to use.
+- `@loaders.gl/images` see below for a list of changes
 
-- **Improved Node.js image support**
-  - More test cases are now run in both browser and Node.js and a few important issues were uncovered and fixed.
+### @loaders.gl/images Updates
 
-### @loaders.gl/json
+- **New ImageLoader options** `options: {image: {}}` contain common options that apply across the category
+  - `options.image.type`, Ability to control loaded image type enabling faster `ImageBitmap` instances to be loaded via `type: 'imagebitmap`. Default `auto` setting returns traditional HTML image objects.
+- Image Decoding. `options.image.decodeHTML: true` - `ImageLoader` now ensures HTML images are completely decoded and ready to be used when the image is returned (by calling `Image.decode()`).
 
-A new streaming `JSONLoader`(Experimental) that supports batched (i.e. streaming) parsing from standard JSON files, e.g. geojson. No need to reformat your files as line delimited JSON.
+- **Parsed Image API** Since the type of images returned by the `ImageLoader` depends on the `{image: {type: ...}}` option, a set of functions are provided to work portably with loaded images: `isImage()`, `getImageType()`, `getImageSize()`, `getImageData()`, ...
+- **Binary Image API** Separate API to work with unparsed images in binary data form: `isBinaryImage()`, `getBinaryImageType()`, `getBinaryImageSize()`, ...
+- **"Texture" Loading API** New methods `loadImages` and `loadImageCube` can signficantly simplify loading of arrays of arrays of (mipmapped) images that are often used in 3D applications. These methods allow an entire complex of images (e.g. 6 cube faces with 10 mip images each) to be loaded using a single async call.
+- **Improved Node.js support** More image test cases are now run in both browser and Node.js and a couple of important Node.js issues were uncovered and fixed.
 
 ## v1.3
 

modules/3d-tiles/docs/api-reference/tile-3d-loader.md

@@ -11,8 +11,9 @@ Parses a [3D tile](https://github.com/AnalyticalGraphicsInc/3d-tiles).
 | Decoder Type          | Synchronous (limited), Asynchronous                                                                            |
 | Worker Thread Support | No                                                                                                             |
 | Streaming Support     | No \*                                                                                                          |
+| Subloaders            | `DracoLoader` (`.pnts`), `GLTFLoader` (`.b3dm`, `.i3dm`)                                                       |
 
-\* Streaming is not supported for invididual tiles, however tilesets are streamed by loading only the tiles needed for the current view.
+\* Streaming is not supported for invididual tiles, however tilesets are streamed by loading only the tiles needed for the
 
 ## Usage
 
@@ -33,7 +34,7 @@ const gltf = await load(url, Tile3DLoader, {DracoLoader, decompress: true});
 
 ## Options
 
-To enable parsing of DRACO compressed point clouds and glTF tiles, make sure to first register a [DracoLoader](/docs/api-reference/draco/draco-loader). The `DracoWorkerLoader` will usually give best loading performance and interactivity.
+To enable parsing of DRACO compressed point clouds and glTF tiles, make sure to first register the [DracoLoader](/docs/api-reference/draco/draco-loader).
 
 Point cloud tie options
 

modules/arrow/docs/api-reference/arrow-loader.md

@@ -17,13 +17,10 @@ The `ArrowLoader` parses the Apache Arrow columnar table format.
 ## Usage
 
 ```js
-import {ArrowLoader, ArrowWorkerLoader} from '@loaders.gl/arrow';
+import {ArrowLoader} from '@loaders.gl/arrow';
 import {load} from '@loaders.gl/core';
 
-// Decode on main thread
 const data = await load(url, ArrowLoader, options);
-// Decode on worker thread
-const data = await load(url, ArrowWorkerLoader, options);
 ```
 
 ## Options

modules/gltf/docs/api-reference/gltf-loader.md

@@ -11,6 +11,7 @@ A glTF file contains a hierarchical scenegraph description that can be used to i
 | File Format     | [glTF](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0) |
 | Data Format     | [Scenegraph](/docs/specifications/category-scenegraph)                     |
 | Supported APIs  | `load`, `parse`, `parseSync`                                               |
+| Subloaders      | `DracoLoader`, `ImageLoader`                                               |  |
 
 ## Usage
 

modules/images/docs/api-reference/image-loader.md

@@ -22,12 +22,15 @@ const image = await load(url, ImageLoader, options);
 
 ## Options
 
-| Option         | Type    | Default  | Description                                                                  |
-| -------------- | ------- | -------- | ---------------------------------------------------------------------------- |
-| `image.type`   | String  | `'auto'` | Set to `imagebitmap`, `html` or `ndarray` to control type of returned image. |
-| `image.decode` | boolean | `true`   | Ensures `html` type images are fully decoded before promise resolves.        |
+| Option         | Type    | Default  | Description                                                                                                                 |
+| -------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `image.type`   | String  | `'auto'` | Set to `imagebitmap`, `html` or `ndarray` to control type of returned image.                                                |
+| `image.data`   | boolean | `false`  | If true, extracts image data instead of returning an actual image, as an `ImageData`-shaped object `{widht, height, data}`. |
+| `image.decode` | boolean | `true`   | Applies to `html` type images only, ensures image is fully decoded before loading promise resolves.                         |
 
-In addition, for `imagebitmap` type images, it is possible to pass through options to [`createImageBitmap`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/createImageBitmap) to control image extraction, via the separate `options.imagebitmap` object.
+### ImageBitmap Options
+
+In addition, for `imagebitmap` type images, it is possible to pass through options to [`createImageBitmap`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/createImageBitmap) to control image extraction, via the separate `options.imagebitmap` object. However, for portability it may be best to avoid relying on these options for now, since some browsers do not support `ImageBitmap` options (and some browsers do not support `ImageBitmap`s at all).
 
 | Option                             | Type   | Default     | Description                                                                                                                   |
 | ---------------------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |

modules/las/docs/api-reference/las-loader.md

@@ -15,13 +15,10 @@ The `LASLoader` parses a point cloud in the LASER file format.
 ## Usage
 
 ```js
-import {LASLoader, LASWorkerLoader} from '@loaders.gl/las';
+import {LASLoader} from '@loaders.gl/las';
 import {load} from '@loaders.gl/core';
 
-// Decode on main thread
 const data = await load(url, LASLoader, options);
-// Decode on worker thread
-const data = await load(url, LASWorkerLoader, options);
 ```
 
 ## Options

modules/obj/docs/api-reference/obj-loader.md

@@ -15,13 +15,10 @@ The `OBJLoader` parses the OBJ half of the classic Wavefront OBJ/MTL format.
 ## Usage
 
 ```js
-import {OBJLoader, OBJWorkerLoader} from '@loaders.gl/obj';
+import {OBJLoader} from '@loaders.gl/obj';
 import {load} from '@loaders.gl/core';
 
-// Decode on main thread
 const data = await load(url, OBJLoader, options);
-// Decode on worker thread
-const data = await load(url, OBJWorkerLoader, options);
 ```
 
 ## Options

modules/pcd/docs/api-reference/pcd-loader.md

@@ -17,13 +17,10 @@ Note: Currently only `ascii` and `binary` subformats are supported. Compressed b
 ## Usage
 
 ```js
-import {PCDLoader, PCDWorkerLoader} from '@loaders.gl/pcd';
+import {PCDLoader} from '@loaders.gl/pcd';
 import {load} from '@loaders.gl/core';
 
-// Decode on main thread
 const data = await load(url, PCSLoader, options);
-// Decode on worker thread
-const data = await load(url, PCDWorkerLoader, options);
 ```
 
 ## Options

modules/ply/docs/api-reference/ply-loader.md

@@ -15,13 +15,10 @@ The `PLYLoader` parses simple meshes in the Polygon File Format or the Stanford
 ## Usage
 
 ```js
-import {PLYLoader, PLYWorkerLoader} from '@loaders.gl/ply';
+import {PLYLoader} from '@loaders.gl/ply';
 import {load} from '@loaders.gl/core';
 
-// Decode on main thread
 const data = await load(url, PLYLoader, options);
-// Decode on worker thread
-const data = await load(url, PLYWorkerLoader, options);
 ```
 
 ## Options