Merge 8da73fe into 781ba27

docs/table-of-contents.json

@@ -186,8 +186,7 @@
             {"entry": "modules/images/docs/api-reference/load-image"},
             {"entry": "modules/images/docs/api-reference/load-image-array"},
             {"entry": "modules/images/docs/api-reference/load-image-cube"},
-            {"entry": "modules/images/docs/api-reference/parsed-image-api"},
-            {"entry": "modules/images/docs/api-reference/binary-image-api"}
+            {"entry": "modules/images/docs/api-reference/parsed-image-api"}
           ]
         },
         {

docs/upgrade-guide.md

@@ -2,13 +2,19 @@
 
 ## Upgrading to v2.3
 
-`@loaders.gl/core`:
+**@loaders.gl/core**
 
 - `selectLoader()` is now async and returns a `Promise` that resolves to a loader.
 - `selectLoaderSync()` is available for situations when calling an async function is inconvenient.
 - Passing `fetch` options to `load()` and `parse()` etc. should now be done via the `options.fetch` sub-options object. fetch options on the root object are now deprecated.
 
-`@loaders.gl/kml`:
+**@loaders.gl/images**
+
+- (BREAKING) Parsed image APIs have moved to `@loaders.gl/image-api`: `isImage`, `getImageType`, `getImageData`, `getImageSize`.
+- (BREAKING) Texture loading APIs have moved to `@loaders.gl/image-api`: `loadImage`, `loadImageArray`, `loadImageCube`.
+- `isBinaryImage`, `getBinaryImageMIMEType`, `getBinaryImageSize` are deprecated, use `getBinaryImageMetadata` instead.
+
+**@loaders.gl/kml**
 
 - The `KMLAsGeoJsonLoader` has been removed, use `KMLLoader`, with `options.gis.format: 'geojson'`.
 

docs/whats-new.md

@@ -18,6 +18,10 @@ This release brings a new Shapefile loader, compression codecs (Zlib, LZ4, Zstan
 
 - A new module with "transforms" for calculating cryptographic hashes (MD5, SHA256 etc) incrementally, e.g. on incoming binary chunks while streaming data into `parseInBatches`.
 
+**@loaders.gl/image-api** (NEW)
+
+- A new module with utility functions for image processing, complementing the existing `@loaders.gl/images` module.
+
 **@loaders.gl/core**
 
 - (BREAKING) `selectLoader()` is now async and returns a `Promise` that resolves to a loader, and can now identify loaders through content sniffing `Blob` and `File` objects.
@@ -30,6 +34,12 @@ This release brings a new Shapefile loader, compression codecs (Zlib, LZ4, Zstan
 - `fetch` polyfill: Files with `.gz` extension are automatically decompressed with gzip. The extension reported in the `fetch` response has the `.gz` extension removed.
 - `fetch` polyfill: Improved robustness and error handling in Node.js when opening unreadable or non-existent files. Underlying errors (`ENOEXIST`, `EISDIR` etc) are now caught and reported in `Response.statusText`.
 
+**@loaders.gl/images**
+
+- `ImageWriter`: new improved browser implementation.
+- (BREAKING) Parsed image APIs have moved to `@loaders.gl/image-api`.
+- (BREAKING) Texture loading APIs have moved to `@loaders.gl/image-api`.
+
 **@loaders.gl/json**
 
 - Binary output is now available for the `GeoJsonLoader`, via `options.gis.format: 'binary'`.

examples/benchmarks/app.js

@@ -3,6 +3,7 @@ import {render} from 'react-dom';
 
 import {BenchResults} from '@probe.gl/react-bench';
 import {Bench} from '@probe.gl/bench';
+import {isBrowser} from '@loaders.gl/loader-utils';
 
 import {addModuleBenchmarksToSuite} from '../../test/bench/modules';
 
@@ -39,7 +40,10 @@ export default class App extends PureComponent {
     const suite = new Bench({
       log: this._logResult.bind(this)
     });
-    await addModuleBenchmarksToSuite(suite, addReferenceBenchmarks);
+    // Avoid server side rendering in gatsby
+    if (isBrowser) {
+      await addModuleBenchmarksToSuite(suite, addReferenceBenchmarks);
+    }
     suite
       // Calibrate performance
       .calibrate()

examples/benchmarks/package.json

@@ -10,10 +10,10 @@
     "react": "^16.3.0",
     "react-dom": "^16.3.0",
     "@probe.gl/bench": "^3.3.0",
-    "@probe.gl/react-bench": "^3.3.0"
+    "@probe.gl/react-bench": "^3.3.0",
+    "@loaders.gl/loader-utils": "2.2.0"
   },
   "devDependencies": {
-    "@loaders.gl/core": "2.2.0",
     "@babel/cli": "^7.0.0",
     "@babel/core": "^7.4.0",
     "@babel/preset-react": "^7.0.0",

modules/core/src/javascript-utils/is-type.d.ts

@@ -11,7 +11,6 @@ export function isFile(value: any): boolean;
 export function isBlob(value: any): boolean;
 
 export function isWritableDOMStream(value: any): boolean;
-
 export function isReadableDOMStream(value: any): boolean;
 
 /**
@@ -20,9 +19,6 @@ export function isReadableDOMStream(value: any): boolean;
 export function isBuffer(value: any): boolean;
 
 export function isWritableNodeStream(value: any): boolean;
-
 export function isReadableNodeStream(value: any): boolean;
-
 export function isReadableStream(value: any): boolean;
-
 export function isWritableStream(value: any): boolean;

modules/gltf/package.json

@@ -41,6 +41,7 @@
     "@loaders.gl/core": "2.3.0-alpha.7",
     "@loaders.gl/draco": "2.3.0-alpha.7",
     "@loaders.gl/images": "2.3.0-alpha.7",
+    "@loaders.gl/image-api": "2.3.0-alpha.7",
     "@loaders.gl/loader-utils": "2.3.0-alpha.7"
   }
 }

modules/gltf/src/lib/deprecated/glb-builder.js

@@ -1,6 +1,6 @@
 /* eslint-disable camelcase, max-statements */
 import {padTo4Bytes, copyToArray} from '@loaders.gl/loader-utils';
-import {isImage} from '@loaders.gl/images';
+import {isImage} from '@loaders.gl/image-api';
 import {getAccessorTypeFromSize, getComponentTypeFromArray} from '../gltf-utils/gltf-utils';
 import encodeGLBSync from '../encode-glb';
 

modules/gltf/src/lib/deprecated/gltf-builder.js

@@ -1,4 +1,4 @@
-import {getBinaryImageMIMEType, getBinaryImageSize} from '@loaders.gl/images';
+import {getBinaryImageMetadata} from '@loaders.gl/images';
 import assert from '../utils/assert';
 import {UBER_POINT_CLOUD_EXTENSION} from '../gltf-constants';
 import GLBBuilder from './glb-builder';
@@ -147,9 +147,8 @@ export default class GLTFBuilder extends GLBBuilder {
     const bufferViewIndex = this.addBufferView(imageData);
 
     // Get the properties of the image to add as metadata.
-    const mimeType = getBinaryImageMIMEType(imageData) || {};
+    const {mimeType, width, height} = getBinaryImageMetadata(imageData) || {};
     if (mimeType) {
-      const {width, height} = getBinaryImageSize(imageData, mimeType) || {};
       this.json.images.push({
         bufferView: bufferViewIndex,
         mimeType,

modules/gltf/src/lib/gltf-scenegraph.js

@@ -1,4 +1,4 @@
-import {getBinaryImageMIMEType} from '@loaders.gl/images';
+import {getBinaryImageMetadata} from '@loaders.gl/images';
 import {padTo4Bytes, copyToArray} from '@loaders.gl/loader-utils';
 import assert from './utils/assert';
 import {
@@ -300,8 +300,9 @@ export default class GLTFScenegraph {
     // If image is referencing a bufferView instead of URI, mimeType must be defined:
     //   https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#images
     //   "a reference to a bufferView; in that case mimeType must be defined."
-    mimeType = mimeType || getBinaryImageMIMEType(imageData);
+    const metadata = getBinaryImageMetadata(imageData) || {};
 
+    mimeType = mimeType || metadata.mimeType;
     const bufferViewIndex = this.addBufferView(imageData);
 
     const glTFImage = {

modules/gltf/test/lib/gltf-scenegraph-modifiers.spec.js

@@ -23,7 +23,6 @@ test('GLTFScenegraph#addImage', t => {
   const gltfScenegraph = new GLTFScenegraph();
 
   // t.throws(() => gltfScenegraph.addImage(PNG1x1), 'addImage() throws if no MIMEType');
-
   const imageIndex = gltfScenegraph.addImage(PNG1x1);
   t.equal(imageIndex, 0, 'Image index should be 0');
 

modules/i3s/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loaders.gl/i3s",
   "version": "2.3.0-alpha.7",
-  "description": "i3s .",
+  "description": "i3s loaders for indexed scenegraph layers",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

modules/image-api/README.md

@@ -0,0 +1,7 @@
+# @loaders.gl/image-api
+
+[loaders.gl](https://loaders.gl/docs) is a collection of framework independent 3D and geospatial parsers and encoders.
+
+This module contains category APIs for images that follow loaders.gl conventions and work under both node and browser.
+
+For documentation please visit the [website](https://loaders.gl).

modules/image-api/docs/README.md

@@ -0,0 +1,51 @@
+# Overview
+
+The `@loaders.gl/image-api` module contains loader and writers for images that follow loaders.gl conventions and work under both node and browser.
+
+## Installation
+
+```bash
+npm install @loaders.gl/image-api
+```
+
+## API
+
+### Parsed Image API
+
+A set of functions to work with parsed images returned by the `ImageLoader`.
+
+| Function                                        | Description                                                                                               |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `isImageTypeSupported(type : string) : boolean` | Check if type is supported by current run-time environment                                                |
+| `getDefaultImageType() : string`                | Returns the image type selected by default ( `options.image.type: 'auto'` in current run-time environment |
+| `isImage(image : any) : boolean`                | Checks any JavaScript value to see if it is an image of a type that loaders.gl can work with              |
+| `getImageType(image : any) : string`            | Returns the type name for this image.                                                                     |
+| `getImageData(image : any) : object`            | Returns an image data object with a `data` array representing the pixels of an image                      |
+
+### Binary Image API
+
+Note that `@loaders.gl/images` also exports a binary image API.
+
+### Image Loading API for WebGL Textures
+
+The images API also offers functions to load "composite" images for WebGL textures, cube textures and image mip levels.
+
+These functions take a `getUrl` parameter that enables the app to supply the url for each "sub-image", and return a single promise enabling applications to for instance load all the faces of a cube texture, with one image for each mip level for each face in a single async operation.
+
+| Function                                                               | Description                                                                                                           |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| [`loadImage`](modules/images/docs/api-reference/load-image)            | Load a single image                                                                                                   |
+| [`loadImageArray`](modules/images/docs/api-reference/load-image-array) | Load an array of images, e.g. for a `Texture2DArray` or `Texture3D`                                                   |
+| [`loadImageCube`](modules/images/docs/api-reference/load-image-cube)   | Load a map of 6 images for the faces of a cube map, or a map of 6 arrays of images for the mip levels of the 6 faces. |
+
+As with all loaders.gl functions, while these functions are intended for use in WebGL applications, they do not call any WebGL functions, and do not actually create any WebGL textures..
+
+## Image Types
+
+To support image loading on older browsers and Node.js, the `ImageLoader` can return different types, i.e. different representations of the parsed image.
+
+- `ImageBitmap` - An `ImageBitmap` object represents a bitmap image that can be performantly painted to a canvas ("without undue latency"). Due to the signficant performance advantages, and the fact that `ImageBitmap` instances can be transferred efficiently between threads, `ImageBitmap` is the preferred parsed image representation in browsers, when available. Currently only available in Chrome and Firefox.
+- `Image` (aka `HTMLImageElement`) - The traditional HTML image class. Available in all browsers.
+- `data` - Raw binary memory representing the image pixels, typically in RGBA `Uint8Array` format. JavaScript computations can be done on this data. Also, Node.js texture creation functions in headless gl accept `data` images. and browser `ImageData` objects can be initialized with this data.
+
+See [`ImageLoader`](modules/images/docs/api-reference/image-loader) for more details on options etc.

modules/image-api/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@loaders.gl/image-api",
+  "version": "2.3.0-alpha.7",
+  "description": "Framework-independent API for images (PNG, JPG, ...)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/visgl/loaders.gl"
+  },
+  "keywords": [
+    "webgl",
+    "loader",
+    "image",
+    "PNG",
+    "JPEG",
+    "JPG"
+  ],
+  "types": "src/index.d.ts",
+  "main": "dist/es5/index.js",
+  "module": "dist/esm/index.js",
+  "esnext": "dist/es6/index.js",
+  "sideEffects": false,
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "pre-build": "npm run build-bundle && npm run build-bundle -- --env.dev",
+    "build-bundle": "webpack  --display=minimal --config ../../scripts/bundle.config.js"
+  },
+  "dependencies": {
+    "@loaders.gl/loader-utils": "2.3.0-alpha.7",
+    "@loaders.gl/images": "2.3.0-alpha.7"
+  }
+}

modules/image-api/src/bundle.js

@@ -0,0 +1,7 @@
+/* global window, global */
+const moduleExports = require('./index');
+const _global = typeof window === 'undefined' ? global : window;
+// @ts-ignore
+_global.loaders = _global.loaders || {};
+// @ts-ignore
+module.exports = Object.assign(_global.loaders, moduleExports);

modules/image-api/src/index.d.ts

@@ -0,0 +1,19 @@
+// TYPES
+export {ImageDataType, ImageType, ImageTypeEnum} from './types';
+
+// IMAGE CATEGORY API
+
+// Parsed Image API
+export {isImageTypeSupported, getDefaultImageType} from './lib/category-api/image-type';
+
+export {
+  isImage,
+  getImageType,
+  getImageSize,
+  getImageData
+} from './lib/category-api/parsed-image-api';
+
+// Texture Loading API
+export {loadImage} from './lib/texture-api/load-image';
+export {loadImageArray} from './lib/texture-api/load-image-array';
+export {loadImageCube} from './lib/texture-api/load-image-cube';

modules/image-api/src/index.js

@@ -0,0 +1,22 @@
+// IMAGE CATEGORY API
+
+// Binary Image API
+export {getBinaryImageMetadata} from '@loaders.gl/images';
+
+// Parsed Image API
+export {isImageTypeSupported} from './lib/category-api/image-type';
+
+export {
+  isImage,
+  getImageType,
+  getImageSize,
+  getImageData
+} from './lib/category-api/parsed-image-api';
+
+// Texture Loading API
+export {loadImage} from './lib/texture-api/load-image';
+export {loadImageArray} from './lib/texture-api/load-image-array';
+export {loadImageCube} from './lib/texture-api/load-image-cube';
+
+// DEPRECATED in v2.3
+export {getDefaultImageType} from './lib/category-api/image-type';

modules/images/src/lib/category-api/image-type.js → modules/image-api/src/lib/category-api/image-type.js

@@ -1,5 +1,5 @@
 /* global ImageBitmap, Image */
-import {global, isBrowser} from '../utils/globals';
+import {global, isBrowser} from '@loaders.gl/loader-utils';
 
 // @ts-ignore TS2339: Property does not exist on type
 const {_parseImageNode} = global;
@@ -23,14 +23,8 @@ export function isImageTypeSupported(type) {
     case 'data':
       return DATA_SUPPORTED;
 
-    // DEPRECATED types
-    case 'html':
-      return IMAGE_SUPPORTED;
-    case 'ndarray':
-      return DATA_SUPPORTED;
-
     default:
-      throw new Error(`@loaders.gl/images: image ${type} not supported in this environment`);
+      throw new Error(`@loaders.gl/images: ${type} not supported`);
   }
 }
 

modules/images/src/lib/category-api/parsed-image-api.js → modules/image-api/src/lib/category-api/parsed-image-api.js

@@ -1,5 +1,5 @@
 /* global Image, ImageBitmap */
-import assert from '../utils/assert';
+import {assert} from '@loaders.gl/loader-utils';
 
 export function isImage(image) {
   return Boolean(getImageTypeOrNull(image));

modules/images/src/lib/texture-api/generate-url.js → modules/image-api/src/lib/texture-api/generate-url.js

@@ -1,5 +1,5 @@
 import {resolvePath} from '@loaders.gl/loader-utils';
-import assert from '../utils/assert';
+import {assert} from '@loaders.gl/loader-utils';
 
 // Generate a url by calling getUrl with mix of options, applying options.baseUrl
 export function generateUrl(getUrl, options, urlOptions) {

modules/images/src/lib/texture-api/load-image-array.js → modules/image-api/src/lib/texture-api/load-image-array.js

@@ -1,4 +1,4 @@
-import parseImage from '../parsers/parse-image';
+import {_parseImage as parseImage} from '@loaders.gl/images';
 import {getImageUrls} from './load-image';
 import {deepLoad} from './deep-load';
 

modules/images/src/lib/texture-api/load-image-cube.js → modules/image-api/src/lib/texture-api/load-image-cube.js

@@ -1,4 +1,4 @@
-import parseImage from '../parsers/parse-image';
+import {_parseImage as parseImage} from '@loaders.gl/images';
 import {getImageUrls} from './load-image';
 import {deepLoad} from './deep-load';
 

modules/images/src/lib/texture-api/load-image.js → modules/image-api/src/lib/texture-api/load-image.js

@@ -1,12 +1,12 @@
-import assert from '../utils/assert';
-import parseImage from '../parsers/parse-image';
+import {assert} from '@loaders.gl/loader-utils';
+import {_parseImage} from '@loaders.gl/images'; // TODO use ImageLoader instead, remove this export
 import {getImageSize} from '../category-api/parsed-image-api';
 import {generateUrl} from './generate-url';
 import {deepLoad, shallowLoad} from './deep-load';
 
 export async function loadImage(getUrl, options = {}) {
   const imageUrls = await getImageUrls(getUrl, options);
-  return await deepLoad(imageUrls, parseImage, options);
+  return await deepLoad(imageUrls, _parseImage, options);
 }
 
 export async function getImageUrls(getUrl, options, urlOptions = {}) {
@@ -22,7 +22,7 @@ async function getMipmappedImageUrls(getUrl, mipLevels, options, urlOptions) {
   // If no mip levels supplied, we need to load the level 0 image and calculate based on size
   if (mipLevels === 'auto') {
     const url = generateUrl(getUrl, options, {...urlOptions, lod: 0});
-    const image = await shallowLoad(url, parseImage, options);
+    const image = await shallowLoad(url, _parseImage, options);
 
     const {width, height} = getImageSize(image);
     mipLevels = getMipLevels({width, height});