@loaders.gl/images 3.4.0-alpha.1 → 3.4.0-alpha.3

package/dist/lib/category-api/parse-isobmff-binary.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Box is a container format that can contain a variety of media related files,
+ * so we want to return information about which type of file is actually contained inside
+ */
+export type BoxFileType = {
+    extension: string;
+    mimeType: string;
+};
+/**
+ * Tests if a buffer is in ISO base media file format (ISOBMFF) @see https://en.wikipedia.org/wiki/ISO_base_media_file_format
+ * (ISOBMFF is a media container standard based on the Apple QuickTime container format)
+ */
+export declare function getISOBMFFMediaType(buffer: Uint8Array): BoxFileType | null;
+/**
+ * brands explained @see https://github.com/strukturag/libheif/issues/83
+ * code adapted from @see https://github.com/sindresorhus/file-type/blob/main/core.js#L489-L492
+ */
+export declare function decodeMajorBrand(buffer: Uint8Array): BoxFileType | null;
+//# sourceMappingURL=parse-isobmff-binary.d.ts.map

package/dist/lib/category-api/parse-isobmff-binary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-isobmff-binary.d.ts","sourceRoot":"","sources":["../../../src/lib/category-api/parse-isobmff-binary.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAC;AAEhE;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAa1E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAmDvE"}

package/dist/lib/category-api/parse-isobmff-binary.js

@@ -0,0 +1,94 @@
+"use strict";
+// loaders.gl, MIT license
+// code adapted from https://github.com/sindresorhus/file-type under MIT license
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeMajorBrand = exports.getISOBMFFMediaType = void 0;
+/**
+ * Tests if a buffer is in ISO base media file format (ISOBMFF) @see https://en.wikipedia.org/wiki/ISO_base_media_file_format
+ * (ISOBMFF is a media container standard based on the Apple QuickTime container format)
+ */
+function getISOBMFFMediaType(buffer) {
+    // Almost all ISO base media files start with `ftyp` box. (It's not required to be first, but it's recommended to be.)
+    if (!checkString(buffer, 'ftyp', 4)) {
+        return null;
+    }
+    // Extra check: test for 8859-1 printable characters (for simplicity, it's a mask which also catches one non-printable character).
+    if ((buffer[8] & 0x60) === 0x00) {
+        return null;
+    }
+    // `ftyp` box must contain a brand major identifier, which must consist of ISO 8859-1 printable characters.
+    return decodeMajorBrand(buffer);
+}
+exports.getISOBMFFMediaType = getISOBMFFMediaType;
+/**
+ * brands explained @see https://github.com/strukturag/libheif/issues/83
+ * code adapted from @see https://github.com/sindresorhus/file-type/blob/main/core.js#L489-L492
+ */
+function decodeMajorBrand(buffer) {
+    const brandMajor = getUTF8String(buffer, 8, 12).replace('\0', ' ').trim();
+    switch (brandMajor) {
+        case 'avif':
+        case 'avis':
+            return { extension: 'avif', mimeType: 'image/avif' };
+        default:
+            return null;
+    }
+    // We don't need these now, but they are easy to add
+    // case 'mif1':
+    //   return {extension: 'heic', mimeType: 'image/heif'};
+    // case 'msf1':
+    //   return {extension: 'heic', mimeType: 'image/heif-sequence'};
+    // case 'heic':
+    // case 'heix':
+    //   return {extension: 'heic', mimeType: 'image/heic'};
+    // case 'hevc':
+    // case 'hevx':
+    //   return {extension: 'heic', mimeType: 'image/heic-sequence'};
+    // case 'qt':
+    //   return {ext: 'mov', mime: 'video/quicktime'};
+    // case 'M4V':
+    // case 'M4VH':
+    // case 'M4VP':
+    //   return {ext: 'm4v', mime: 'video/x-m4v'};
+    // case 'M4P':
+    //   return {ext: 'm4p', mime: 'video/mp4'};
+    // case 'M4B':
+    //   return {ext: 'm4b', mime: 'audio/mp4'};
+    // case 'M4A':
+    //   return {ext: 'm4a', mime: 'audio/x-m4a'};
+    // case 'F4V':
+    //   return {ext: 'f4v', mime: 'video/mp4'};
+    // case 'F4P':
+    //   return {ext: 'f4p', mime: 'video/mp4'};
+    // case 'F4A':
+    //   return {ext: 'f4a', mime: 'audio/mp4'};
+    // case 'F4B':
+    //   return {ext: 'f4b', mime: 'audio/mp4'};
+    // case 'crx':
+    //   return {ext: 'cr3', mime: 'image/x-canon-cr3'};
+    // default:
+    // if (brandMajor.startsWith('3g')) {
+    //   if (brandMajor.startsWith('3g2')) {
+    //     return {ext: '3g2', mime: 'video/3gpp2'};
+    //   }
+    //   return {ext: '3gp', mime: 'video/3gpp'};
+    // }
+    // return {ext: 'mp4', mime: 'video/mp4'};
+}
+exports.decodeMajorBrand = decodeMajorBrand;
+/** Interpret a chunk of bytes as a UTF8 string */
+function getUTF8String(array, start, end) {
+    return String.fromCharCode(...array.slice(start, end));
+}
+function stringToBytes(string) {
+    return [...string].map((character) => character.charCodeAt(0));
+}
+function checkString(buffer, header, offset = 0) {
+    const headerBytes = stringToBytes(header);
+    for (let i = 0; i < headerBytes.length; ++i) {
+        if (headerBytes[i] !== buffer[i + offset]) {
+            return false;
+        }
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loaders.gl/images",
-  "version": "3.4.0-alpha.1",
+  "version": "3.4.0-alpha.3",
   "description": "Framework-independent loaders and writers for images (PNG, JPG, ...)",
   "license": "MIT",
   "publishConfig": {
@@ -32,7 +32,10 @@
     "build-bundle": "esbuild src/bundle.ts --outfile=dist/dist.min.js --bundle --minify --sourcemap"
   },
   "dependencies": {
-    "@loaders.gl/loader-utils": "3.4.0-alpha.1"
+    "@loaders.gl/loader-utils": "3.4.0-alpha.3"
   },
-  "gitHead": "4085b0323050e4361614471319a1fb4729547bbf"
+  "gitHead": "a954528dd1d78a1f128d8f6b07e4baeb7a296924",
+  "devDependencies": {
+    "@types/get-pixels": "^3.3.2"
+  }
 }

package/src/image-loader.ts

@@ -3,12 +3,13 @@ import {VERSION} from './lib/utils/version';
 import parseImage from './lib/parsers/parse-image';
 import {getBinaryImageMetadata} from './lib/category-api/binary-image-api';
 
-const EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'ico', 'svg'];
+const EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'ico', 'svg', 'avif'];
 const MIME_TYPES = [
   'image/png',
   'image/jpeg',
   'image/gif',
   'image/webp',
+  'image/avif',
   'image/bmp',
   'image/vnd.microsoft.icon',
   'image/svg+xml'

package/src/index.ts

@@ -22,7 +22,8 @@ export {
 } from './lib/category-api/parsed-image-api';
 
 // EXPERIMENTAL
-export {_isImageFormatSupported} from './lib/category-api/image-format';
+export {getSupportedImageFormats} from './lib/category-api/image-format';
+export {isImageFormatSupported} from './lib/category-api/image-format';
 
-// DEPRECATED - Remove in V3 (fix dependency in luma.gl)
+// DEPRECATED - Remove in V4 (fix dependency in luma.gl)
 export {loadImage} from './lib/texture-api/load-image';

package/src/lib/category-api/binary-image-api.ts

@@ -6,6 +6,8 @@
 // import {bufferToArrayBuffer} from '../node/buffer-to-array-buffer';
 // TODO - this should be handled in @loaders.gl/polyfills
 
+import {getISOBMFFMediaType} from './parse-isobmff-binary';
+
 /** MIME type, width and height extracted from binary compressed image data */
 export type BinaryImageMetadata = {
   mimeType: string;
@@ -19,7 +21,7 @@ const LITTLE_ENDIAN = true;
 /**
  * Extracts `{mimeType, width and height}` from a memory buffer containing a known image format
  * Currently supports `image/png`, `image/jpeg`, `image/bmp` and `image/gif`.
- * @param binaryData image file memory to parse
+ * @param binaryData: DataView | ArrayBuffer image file memory to parse
  * @returns metadata or null if memory is not a valid image file format layout.
  */
 export function getBinaryImageMetadata(
@@ -30,13 +32,30 @@ export function getBinaryImageMetadata(
     getPngMetadata(dataView) ||
     getJpegMetadata(dataView) ||
     getGifMetadata(dataView) ||
-    getBmpMetadata(dataView)
+    getBmpMetadata(dataView) ||
+    getISOBMFFMetadata(dataView)
   );
 }
 
+// ISOBMFF
+
+function getISOBMFFMetadata(binaryData: DataView | ArrayBuffer): BinaryImageMetadata | null {
+  const buffer = new Uint8Array(binaryData instanceof DataView ? binaryData.buffer : binaryData);
+  const mediaType = getISOBMFFMediaType(buffer);
+  if (!mediaType) {
+    return null;
+  }
+  return {
+    mimeType: mediaType.mimeType,
+    // TODO - decode width and height
+    width: 0,
+    height: 0
+  };
+}
+
 // PNG
 
-function getPngMetadata(binaryData) {
+function getPngMetadata(binaryData: DataView | ArrayBuffer): BinaryImageMetadata | null {
   const dataView = toDataView(binaryData);
   // Check file contains the first 4 bytes of the PNG signature.
   const isPng = dataView.byteLength >= 24 && dataView.getUint32(0, BIG_ENDIAN) === 0x89504e47;
@@ -56,7 +75,7 @@ function getPngMetadata(binaryData) {
 
 // Extract size from a binary GIF file
 // TODO: GIF is not this simple
-function getGifMetadata(binaryData) {
+function getGifMetadata(binaryData: DataView | ArrayBuffer): BinaryImageMetadata | null {
   const dataView = toDataView(binaryData);
   // Check first 4 bytes of the GIF signature ("GIF8").
   const isGif = dataView.byteLength >= 10 && dataView.getUint32(0, BIG_ENDIAN) === 0x47494638;
@@ -75,7 +94,7 @@ function getGifMetadata(binaryData) {
 // BMP
 
 // TODO: BMP is not this simple
-export function getBmpMetadata(binaryData) {
+export function getBmpMetadata(binaryData: DataView | ArrayBuffer): BinaryImageMetadata | null {
   const dataView = toDataView(binaryData);
   // Check magic number is valid (first 2 characters should be "BM").
   // The mandatory bitmap file header is 14 bytes long.
@@ -99,7 +118,7 @@ export function getBmpMetadata(binaryData) {
 // JPEG
 
 // Extract width and height from a binary JPEG file
-function getJpegMetadata(binaryData) {
+function getJpegMetadata(binaryData: DataView | ArrayBuffer): BinaryImageMetadata | null {
   const dataView = toDataView(binaryData);
   // Check file contains the JPEG "start of image" (SOI) marker
   // followed by another marker.

package/src/lib/category-api/image-format.ts

@@ -1,66 +1,119 @@
+// loaders.gl, MIT license
+
 import {isBrowser} from '@loaders.gl/loader-utils';
 
-// The following formats are supported by loaders.gl polyfills
-const NODE_FORMAT_SUPPORT = ['image/png', 'image/jpeg', 'image/gif'];
+const MIME_TYPES = [
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/avif',
+  'image/tiff',
+  // TODO - what is the correct type for SVG
+  'image/svg',
+  'image/svg+xml',
+  'image/bmp',
+  'image/vnd.microsoft.icon'
+];
+
+/** Only one round of tests is performed */
+const mimeTypeSupportedPromise: Promise<Set<string>> | null = null;
+
+/** Run-time browser detection of file formats requires async tests for most precise results */
+export async function getSupportedImageFormats(): Promise<Set<string>> {
+  if (mimeTypeSupportedPromise) {
+    return await mimeTypeSupportedPromise;
+  }
 
-/** Cache values for speed */
-const mimeTypeSupported: {[mimeType: string]: boolean} = {};
+  const supportedMimeTypes = new Set<string>();
+  for (const mimeType of MIME_TYPES) {
+    const supported = isBrowser
+      ? await checkBrowserImageFormatSupportAsync(mimeType)
+      : checkNodeImageFormatSupport(mimeType);
+    if (supported) {
+      supportedMimeTypes.add(mimeType);
+    }
+  }
+
+  return supportedMimeTypes;
+}
+
+/** Cache sync values for speed */
+const mimeTypeSupportedSync: {[mimeType: string]: boolean} = {};
 
 /**
- * Check if image MIME type is supported. Result is cached.
+ * Check if image MIME type is supported. Result is cached to avoid repeated tests.
  */
-export function _isImageFormatSupported(mimeType: string): boolean {
-  if (mimeTypeSupported[mimeType] === undefined) {
-    mimeTypeSupported[mimeType] = checkFormatSupport(mimeType);
+export function isImageFormatSupported(mimeType: string): boolean {
+  if (mimeTypeSupportedSync[mimeType] === undefined) {
+    const supported = isBrowser
+      ? checkBrowserImageFormatSupport(mimeType)
+      : checkNodeImageFormatSupport(mimeType);
+    mimeTypeSupportedSync[mimeType] = supported;
   }
-  return mimeTypeSupported[mimeType];
+  return mimeTypeSupportedSync[mimeType];
 }
 
 /**
- * Check if image MIME type is supported.
+ * Checks that polyfills are installed and that mimeType is supported by polyfills
+ * @todo Ideally polyfills should declare what formats they support, instead of storing that data here.
+ */
+function checkNodeImageFormatSupport(mimeType: string): boolean {
+  /** @deprecated Remove these in 4.0 and rely on polyfills to inject them */
+  const NODE_FORMAT_SUPPORT = ['image/png', 'image/jpeg', 'image/gif'];
+  // @ts-ignore
+  const {_parseImageNode, _imageFormatsNode = NODE_FORMAT_SUPPORT} = globalThis;
+  return Boolean(_parseImageNode) && _imageFormatsNode.includes(mimeType);
+}
+
+/** Checks image format support synchronously.
+ * @note Unreliable, fails on AVIF
  */
-function checkFormatSupport(mimeType: string): boolean {
+function checkBrowserImageFormatSupport(mimeType: string): boolean {
   switch (mimeType) {
+    case 'image/avif': // Will fail
     case 'image/webp':
-      return checkWebPSupport();
-    case 'image/svg':
-      return isBrowser;
+      return testBrowserImageFormatSupport(mimeType);
     default:
-      if (!isBrowser) {
-        // @ts-ignore
-        const {_parseImageNode} = globalThis;
-        return Boolean(_parseImageNode) && NODE_FORMAT_SUPPORT.includes(mimeType);
-      }
       return true;
   }
 }
 
-/** Check WebPSupport synchronously */
-function checkWebPSupport() {
-  if (!isBrowser) {
-    return false;
-  }
+const TEST_IMAGE = {
+  'image/avif':
+    'data:image/avif;base64,AAAAIGZ0eXBhdmlmAAAAAGF2aWZtaWYxbWlhZk1BMUIAAADybWV0YQAAAAAAAAAoaGRscgAAAAAAAAAAcGljdAAAAAAAAAAAAAAAAGxpYmF2aWYAAAAADnBpdG0AAAAAAAEAAAAeaWxvYwAAAABEAAABAAEAAAABAAABGgAAAB0AAAAoaWluZgAAAAAAAQAAABppbmZlAgAAAAABAABhdjAxQ29sb3IAAAAAamlwcnAAAABLaXBjbwAAABRpc3BlAAAAAAAAAAIAAAACAAAAEHBpeGkAAAAAAwgICAAAAAxhdjFDgQ0MAAAAABNjb2xybmNseAACAAIAAYAAAAAXaXBtYQAAAAAAAAABAAEEAQKDBAAAACVtZGF0EgAKCBgANogQEAwgMg8f8D///8WfhwB8+ErK42A=',
+  // Lossy test image. Support for lossy images doesn't guarantee support for all WebP images.
+  'image/webp': 'data:image/webp;base64,UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoBAAEADsD+JaQAA3AAAAAA'
+};
+
+/** Checks WebP and AVIF support asynchronously */
+async function checkBrowserImageFormatSupportAsync(mimeType: string): Promise<boolean> {
+  const dataURL = TEST_IMAGE[mimeType];
+  return dataURL ? await testBrowserImageFormatSupportAsync(dataURL) : true;
+}
+
+/**
+ * Checks browser synchronously
+ * Checks if toDataURL supports the mimeType.
+ * @note Imperfect testOn Chrome this is true for WebP but not for AVIF
+ */
+function testBrowserImageFormatSupport(mimeType: string): boolean {
   try {
     const element = document.createElement('canvas');
-    return element.toDataURL('image/webp').indexOf('data:image/webp') === 0;
+    const dataURL = element.toDataURL(mimeType);
+    return dataURL.indexOf(`data:${mimeType}`) === 0;
   } catch {
     // Probably Safari...
     return false;
   }
 }
 
-// Note: better test but asynchronous
-
-// Lossy test image. Support for lossy images doesn't guarantee support for all WebP images.
-// https://stackoverflow.com/questions/5573096/detecting-webp-support
-// const WEBP_TEST_IMAGE = 'data:image/webp;base64,UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoBAAEADsD+JaQAA3AAAAAA';
-
 // Check WebPSupport asynchronously
-// async function isWebPSupported() {
-//   return new Promise( resolve => {
-//     const image = new Image();
-//     image.src = WEBP_TEST_IMAGE;
-//     image.onload = image.onerror = function () {
-//     resolve( image.height === 1 );
-//   }
-// }
+async function testBrowserImageFormatSupportAsync(testImageDataURL: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const image = new Image();
+    image.src = testImageDataURL;
+    image.onload = () => resolve(image.height > 0);
+    image.onerror = () => resolve(false);
+  });
+}

package/src/lib/category-api/parse-isobmff-binary.ts

@@ -0,0 +1,105 @@
+// loaders.gl, MIT license
+// code adapted from https://github.com/sindresorhus/file-type under MIT license
+
+/**
+ * Box is a container format that can contain a variety of media related files,
+ * so we want to return information about which type of file is actually contained inside
+ */
+export type BoxFileType = {extension: string; mimeType: string};
+
+/**
+ * Tests if a buffer is in ISO base media file format (ISOBMFF) @see https://en.wikipedia.org/wiki/ISO_base_media_file_format
+ * (ISOBMFF is a media container standard based on the Apple QuickTime container format)
+ */
+export function getISOBMFFMediaType(buffer: Uint8Array): BoxFileType | null {
+  // Almost all ISO base media files start with `ftyp` box. (It's not required to be first, but it's recommended to be.)
+  if (!checkString(buffer, 'ftyp', 4)) {
+    return null;
+  }
+
+  // Extra check: test for 8859-1 printable characters (for simplicity, it's a mask which also catches one non-printable character).
+  if ((buffer[8] & 0x60) === 0x00) {
+    return null;
+  }
+
+  // `ftyp` box must contain a brand major identifier, which must consist of ISO 8859-1 printable characters.
+  return decodeMajorBrand(buffer);
+}
+
+/**
+ * brands explained @see https://github.com/strukturag/libheif/issues/83
+ * code adapted from @see https://github.com/sindresorhus/file-type/blob/main/core.js#L489-L492
+ */
+export function decodeMajorBrand(buffer: Uint8Array): BoxFileType | null {
+  const brandMajor = getUTF8String(buffer, 8, 12).replace('\0', ' ').trim();
+
+  switch (brandMajor) {
+    case 'avif':
+    case 'avis':
+      return {extension: 'avif', mimeType: 'image/avif'};
+    default:
+      return null;
+  }
+  // We don't need these now, but they are easy to add
+  // case 'mif1':
+  //   return {extension: 'heic', mimeType: 'image/heif'};
+  // case 'msf1':
+  //   return {extension: 'heic', mimeType: 'image/heif-sequence'};
+  // case 'heic':
+  // case 'heix':
+  //   return {extension: 'heic', mimeType: 'image/heic'};
+  // case 'hevc':
+  // case 'hevx':
+  //   return {extension: 'heic', mimeType: 'image/heic-sequence'};
+  // case 'qt':
+  //   return {ext: 'mov', mime: 'video/quicktime'};
+  // case 'M4V':
+  // case 'M4VH':
+  // case 'M4VP':
+  //   return {ext: 'm4v', mime: 'video/x-m4v'};
+  // case 'M4P':
+  //   return {ext: 'm4p', mime: 'video/mp4'};
+  // case 'M4B':
+  //   return {ext: 'm4b', mime: 'audio/mp4'};
+  // case 'M4A':
+  //   return {ext: 'm4a', mime: 'audio/x-m4a'};
+  // case 'F4V':
+  //   return {ext: 'f4v', mime: 'video/mp4'};
+  // case 'F4P':
+  //   return {ext: 'f4p', mime: 'video/mp4'};
+  // case 'F4A':
+  //   return {ext: 'f4a', mime: 'audio/mp4'};
+  // case 'F4B':
+  //   return {ext: 'f4b', mime: 'audio/mp4'};
+  // case 'crx':
+  //   return {ext: 'cr3', mime: 'image/x-canon-cr3'};
+  // default:
+  // if (brandMajor.startsWith('3g')) {
+  //   if (brandMajor.startsWith('3g2')) {
+  //     return {ext: '3g2', mime: 'video/3gpp2'};
+  //   }
+  //   return {ext: '3gp', mime: 'video/3gpp'};
+  // }
+  // return {ext: 'mp4', mime: 'video/mp4'};
+}
+
+/** Interpret a chunk of bytes as a UTF8 string */
+function getUTF8String(array: Uint8Array, start: number, end: number): string {
+  return String.fromCharCode(...array.slice(start, end));
+}
+
+function stringToBytes(string: string): number[] {
+  return [...string].map((character) => character.charCodeAt(0));
+}
+
+function checkString(buffer: ArrayLike<number>, header: string, offset: number = 0): boolean {
+  const headerBytes = stringToBytes(header);
+
+  for (let i = 0; i < headerBytes.length; ++i) {
+    if (headerBytes[i] !== buffer[i + offset]) {
+      return false;
+    }
+  }
+
+  return true;
+}