@loaders.gl/scene 5.0.0-beta.1 → 5.0.0-beta.2

package/src/draco/draco-library-options.ts

@@ -0,0 +1,76 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoadLibraryOptions} from '@loaders.gl/core/worker-utils';
+import type {DracoDecoderProfile} from './lib/draco-module-loader';
+
+/** Bundled Draco runtime selection and optional application overrides. */
+export type DracoLibraryOptions = LoadLibraryOptions & {
+  /** Selects the full decoder or the smaller glTF-compatible subset. Defaults to full. */
+  decoderProfile?: DracoDecoderProfile;
+};
+
+/**
+ * Creates browser-bundler URL overrides for vendored Draco encoder and decoder runtimes.
+ * Classic and generated ESM assets live in the scene package’s dist/libs directory.
+ * Explicit application modules override the bundled defaults.
+ */
+export function getDracoLibraryOptions(
+  options: DracoLibraryOptions = {}
+): DracoLibraryOptions & {decoderProfile: DracoDecoderProfile} {
+  const decoderProfile = options.decoderProfile ?? 'full';
+  const decoderModules =
+    decoderProfile === 'gltf'
+      ? {
+          'draco_wasm_wrapper_gltf.js': new URL(
+            '../../dist/libs/draco_wasm_wrapper_gltf.js',
+            import.meta.url
+          ).href,
+          'draco_decoder_gltf.wasm': new URL(
+            '../../dist/libs/draco_decoder_gltf.wasm',
+            import.meta.url
+          ).href
+        }
+      : {
+          'draco_wasm_wrapper.js': new URL('../../dist/libs/draco_wasm_wrapper.js', import.meta.url)
+            .href,
+          'draco_decoder.wasm': new URL('../../dist/libs/draco_decoder.wasm', import.meta.url).href
+        };
+  const moduleLibraries: Record<string, string> = {
+    'draco_encoder.mjs': new URL('../../dist/libs/draco_encoder.mjs', import.meta.url).href,
+    'draco_decoder.mjs': new URL('../../dist/libs/draco_decoder.mjs', import.meta.url).href,
+    ...(decoderProfile === 'gltf'
+      ? {
+          'draco_wasm_wrapper_gltf.mjs': new URL(
+            '../../dist/libs/draco_wasm_wrapper_gltf.mjs',
+            import.meta.url
+          ).href
+        }
+      : {
+          'draco_wasm_wrapper.mjs': new URL(
+            '../../dist/libs/draco_wasm_wrapper.mjs',
+            import.meta.url
+          ).href
+        })
+  };
+  // Do not substitute bundled ESM assets for an application's classic-name override.
+  for (const libraryName of Object.keys(moduleLibraries)) {
+    const classicName = libraryName.replace(/\.mjs$/, '.js');
+    if (options.modules?.[classicName] !== undefined) {
+      delete moduleLibraries[libraryName];
+    }
+  }
+  return {
+    ...options,
+    decoderProfile,
+    modules: {
+      'draco_encoder.js': new URL('../../dist/libs/draco_encoder.js', import.meta.url).href,
+      'draco_encoder.wasm': new URL('../../dist/libs/draco_encoder.wasm', import.meta.url).href,
+      'draco_decoder.js': new URL('../../dist/libs/draco_decoder.js', import.meta.url).href,
+      ...decoderModules,
+      ...moduleLibraries,
+      ...options.modules
+    }
+  };
+}

package/src/draco/draco-loader-options.ts

@@ -0,0 +1,33 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {StrictLoaderOptions} from '@loaders.gl/core/loader-utils';
+import type {DracoParseOptions} from './lib/draco-parser';
+import type {DracoDecoderProfile} from './lib/draco-module-loader';
+
+/** Draco decoder backend selected by the metadata loader. */
+export type DracoDecoderBackend = 'wasm' | 'javascript' | 'draco3d';
+
+/** Options for the Draco loader. */
+export type DracoLoaderOptions = StrictLoaderOptions & {
+  draco?: DracoParseOptions & {
+    /** Decoder backend. Defaults to WASM when available and JavaScript otherwise. */
+    backend?: DracoDecoderBackend | 'js';
+    /** Selects mesh output or Apache Arrow output. */
+    shape?: 'mesh' | 'arrow-table';
+    /** Selects the full decoder or the smaller glTF-compatible decoder build. */
+    decoderProfile?: DracoDecoderProfile;
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+    workerUrl?: string;
+  };
+};
+
+/** Default option bag for the Draco loader. */
+export const DRACO_LOADER_DEFAULT_OPTIONS = {
+  backend: typeof WebAssembly === 'object' ? 'wasm' : 'javascript',
+  extraAttributes: {},
+  attributeNameEntry: undefined,
+  shape: 'arrow-table',
+  decoderProfile: 'full'
+} as const;

package/src/draco/draco-loader-types.ts

@@ -0,0 +1,78 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader, LoaderWithParser} from '@loaders.gl/core/loader-utils';
+import type {ArrowTable} from '@loaders.gl/core/schema';
+import type {DracoMesh} from './lib/draco-types';
+import {
+  deserializeArrowWorkerResult,
+  serializeArrowWorkerResult
+} from '@loaders.gl/core/schema-utils/arrow-transport';
+import {VERSION} from './lib/utils/version';
+import {DracoFormat} from './draco-format';
+import {
+  DRACO_LOADER_DEFAULT_OPTIONS,
+  type DracoDecoderBackend,
+  type DracoLoaderOptions
+} from './draco-loader-options';
+
+export type {DracoLoaderOptions} from './draco-loader-options';
+
+/** Preloads the parser-bearing Draco loader implementation. */
+async function preload(
+  _url: string,
+  options?: Record<string, unknown>
+): Promise<LoaderWithParser<DracoMesh | ArrowTable, never, DracoLoaderOptions>> {
+  const dracoLoaderOptions = options as DracoLoaderOptions | undefined;
+  switch (getDracoBackend(dracoLoaderOptions)) {
+    case 'wasm': {
+      const {DracoWASMLoaderWithParser} = await import('@loaders.gl/scene/draco-wasm-loader');
+      return DracoWASMLoaderWithParser;
+    }
+
+    case 'javascript': {
+      const {DracoJavaScriptLoaderWithParser} = await import(
+        '@loaders.gl/scene/draco-javascript-loader'
+      );
+      return DracoJavaScriptLoaderWithParser;
+    }
+
+    case 'draco3d': {
+      const {Draco3DLoaderWithParser} = await import('@loaders.gl/scene/draco3d-loader');
+      return Draco3DLoaderWithParser;
+    }
+
+    default:
+      throw new Error(`DracoLoader: unsupported backend "${dracoLoaderOptions?.draco?.backend}"`);
+  }
+}
+
+/** Metadata-only worker loader for Draco3D compressed geometries. */
+export const DracoLoader = {
+  dataType: null as unknown as DracoMesh | ArrowTable,
+  batchType: null as never,
+  ...DracoFormat,
+  // shapes: ['mesh'],
+  version: VERSION,
+  worker: true,
+  /** Node test workers live with the Draco implementation. */
+  workerSourceNode: 'draco/workers/draco-worker-node.ts',
+  serializeWorkerResult: serializeArrowWorkerResult,
+  deserializeWorkerResult: deserializeArrowWorkerResult,
+  options: {
+    draco: DRACO_LOADER_DEFAULT_OPTIONS
+  },
+  preload
+} as const satisfies Loader<DracoMesh | ArrowTable, never, DracoLoaderOptions>;
+
+/** @deprecated Use DracoLoader. */
+export const DracoWorkerLoader = DracoLoader;
+
+/** Resolves the Draco decoder backend from loader options. */
+function getDracoBackend(options?: DracoLoaderOptions): DracoDecoderBackend {
+  if (options?.draco?.backend) {
+    return options.draco.backend === 'js' ? 'javascript' : options.draco.backend;
+  }
+  return DracoLoader.options.draco.backend;
+}

package/src/draco/draco-loader.ts

@@ -0,0 +1,45 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoaderWithParser, LoaderContext} from '@loaders.gl/core/loader-utils';
+import {extractLoadLibraryOptions} from '@loaders.gl/core/worker-utils';
+import type {ArrowTable} from '@loaders.gl/core/schema';
+import type {DracoMesh} from './lib/draco-types';
+import {parseDraco} from './lib/parse-draco';
+import {loadDracoDecoderModule} from './lib/draco-module-loader';
+import {DracoLoader as DracoLoaderMetadata} from './draco-loader-types';
+import type {DracoLoaderOptions} from './draco-loader-options';
+
+const {preload: _DracoLoaderPreload, ...DracoLoaderMetadataWithoutPreload} = DracoLoaderMetadata;
+
+export type {DracoLoaderOptions} from './draco-loader-options';
+
+/**
+ * Loader for Draco3D compressed geometries
+ */
+export const DracoLoaderWithParser = {
+  ...DracoLoaderMetadataWithoutPreload,
+  parse
+} as const satisfies LoaderWithParser<DracoMesh | ArrowTable, never, DracoLoaderOptions>;
+
+/** Decodes compressed geometry through the selected Draco runtime. */
+async function parse(
+  arrayBuffer: ArrayBuffer,
+  options?: DracoLoaderOptions,
+  context?: LoaderContext
+): Promise<DracoMesh | ArrowTable> {
+  return await parseDraco(
+    arrayBuffer,
+    options,
+    async () =>
+      await loadDracoDecoderModule(
+        extractLoadLibraryOptions(options),
+        options?.draco?.backend === 'javascript' || options?.draco?.backend === 'js'
+          ? 'js'
+          : 'wasm',
+        options?.draco?.decoderProfile
+      ),
+    context
+  );
+}

package/src/draco/draco-wasm-loader-with-parser.ts

@@ -0,0 +1,31 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoaderWithParser, LoaderContext} from '@loaders.gl/core/loader-utils';
+import {extractLoadLibraryOptions} from '@loaders.gl/core/worker-utils';
+import type {ArrowTable} from '@loaders.gl/core/schema';
+import type {DracoMesh} from './lib/draco-types';
+import {loadDracoDecoderModule} from './lib/draco-module-loader';
+import {parseDraco} from './lib/parse-draco';
+import {DracoLoader as DracoLoaderMetadata} from './draco-loader-types';
+import type {DracoLoaderOptions} from './draco-loader-options';
+
+const {preload: _DracoLoaderPreload, ...DracoLoaderMetadataWithoutPreload} = DracoLoaderMetadata;
+
+/** Parser-bearing Draco loader backed by the WASM decoder. */
+export const DracoWASMLoaderWithParser = {
+  ...DracoLoaderMetadataWithoutPreload,
+  parse: async (arrayBuffer: ArrayBuffer, options?: DracoLoaderOptions, context?: LoaderContext) =>
+    await parseDraco(
+      arrayBuffer,
+      options,
+      async () =>
+        await loadDracoDecoderModule(
+          extractLoadLibraryOptions(options),
+          'wasm',
+          options?.draco?.decoderProfile
+        ),
+      context
+    )
+} as const satisfies LoaderWithParser<DracoMesh | ArrowTable, never, DracoLoaderOptions>;

package/src/draco/draco-writer.ts

@@ -0,0 +1,252 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  canEncodeWithWorker,
+  type WriterWithEncoder,
+  type WriterOptions
+} from '@loaders.gl/core/loader-utils';
+import type {Mesh, MeshArrowTable, TypedArray} from '@loaders.gl/core/schema';
+import {convertTableToMesh} from '@loaders.gl/core/schema-utils';
+import {extractLoadLibraryOptions, processOnWorkerInBatches} from '@loaders.gl/core/worker-utils';
+import type {DracoMesh} from './lib/draco-types';
+import type {DracoBuilderMesh, DracoBuildOptions, DracoEncodingResult} from './lib/draco-builder';
+import DRACOBuilder from './lib/draco-builder';
+import {loadDracoEncoderModule} from './lib/draco-module-loader';
+import {VERSION} from './lib/utils/version';
+import {DracoFormat} from './draco-format';
+
+/** Legacy flat attribute map accepted by `DracoWriter`. */
+export type DracoWriterAttributes = Record<string, TypedArray>;
+
+/** Inputs accepted by `DracoWriter`. */
+export type DracoWriterInput =
+  | DracoMesh
+  | Mesh
+  | MeshArrowTable
+  | DracoBuilderMesh
+  | DracoWriterAttributes;
+
+/** Options for `DracoWriter`. */
+export type DracoWriterOptions = WriterOptions & {
+  /** Draco-specific writer options. */
+  draco?: DracoBuildOptions;
+};
+
+/** Progress notification emitted after each geometry in a batch. */
+export type DracoBatchProgress = {
+  /** Number of geometries completed. */
+  completed: number;
+  /** Total number of geometries in the batch. */
+  total: number;
+};
+
+/** Options for cancellable, progress-reporting batch encoding. */
+export type DracoBatchOptions = DracoWriterOptions & {
+  /** Abort signal checked between native encoding operations. */
+  signal?: AbortSignal;
+  /** Called after each geometry is encoded. */
+  onProgress?: (progress: DracoBatchProgress) => void;
+};
+
+/** A batch of Draco-writable geometries. */
+export type DracoWriterInputBatch = DracoWriterInput[];
+
+const DEFAULT_DRACO_WRITER_OPTIONS = {
+  pointcloud: false, // Set to true if pointcloud (mode: 0, no indices)
+  attributeNameEntry: 'name'
+  // Draco Compression Parameters
+  // method: 'MESH_EDGEBREAKER_ENCODING', // Use draco defaults
+  // speed: [5, 5], // Use draco defaults
+  // quantization: { // Use draco defaults
+  //   POSITION: 10
+  // }
+};
+
+/** Worker-enabled exporter for Draco3D compressed geometries. */
+export const DracoWriterWorker = {
+  ...DracoFormat,
+  id: 'draco-writer',
+  name: 'Draco compressed geometry writer',
+  module: 'scene',
+  version: VERSION,
+  worker: true,
+  workerNode: 'draco-writer-worker-node.cjs',
+  /** Node test workers live with the Draco implementation. */
+  workerSourceNode: 'draco/workers/draco-writer-worker-node.ts',
+  options: {
+    draco: {}
+  }
+};
+
+/**
+ * Exporter for Draco3D compressed geometries
+ */
+export const DracoWriter = {
+  ...DracoFormat,
+  name: 'DRACO',
+  version: VERSION,
+  options: {
+    draco: DEFAULT_DRACO_WRITER_OPTIONS
+  },
+  encode,
+  encodeInBatches
+} as const satisfies WriterWithEncoder<DracoWriterInput, unknown, DracoWriterOptions>;
+
+/** Encode Draco mesh category data. */
+async function encode(
+  data: DracoWriterInput,
+  options: DracoWriterOptions = {}
+): Promise<ArrayBuffer> {
+  return (await encodeDraco(data, options)).data;
+}
+
+/** Encodes Draco geometry and returns bytes together with native encoding diagnostics. */
+export async function encodeDraco(
+  data: DracoWriterInput,
+  options: DracoWriterOptions = {}
+): Promise<DracoEncodingResult> {
+  // Dynamically load draco
+  const {draco} = await loadDracoEncoderModule(extractLoadLibraryOptions(options));
+  const dracoBuilder = new DRACOBuilder(draco);
+
+  try {
+    return dracoBuilder.encodeSyncWithReport(normalizeDracoMesh(data), options.draco);
+  } finally {
+    dracoBuilder.destroy();
+  }
+}
+
+/**
+ * Encodes multiple geometries while loading and initializing the Draco runtime once.
+ *
+ * The input geometries are processed sequentially to keep peak native memory bounded.
+ * Each result is independent and uses the same writer options.
+ */
+export async function encodeDracoBatch(
+  data: DracoWriterInput[],
+  options: DracoBatchOptions = {}
+): Promise<DracoEncodingResult[]> {
+  throwIfAborted(options.signal);
+  const results: DracoEncodingResult[] = [];
+  let completed = 0;
+  for await (const result of encodeDracoInBatches([data], options)) {
+    results.push(result);
+    completed++;
+    options.onProgress?.({completed, total: data.length});
+  }
+  return results;
+}
+
+/**
+ * Encodes geometry batches while retaining one encoder runtime and one worker
+ * lease for the complete input iterator.
+ *
+ * Worker mode is selected with `worker: true` and the normal Draco writer
+ * worker options. Set `worker: false` to keep the operation local.
+ */
+export function encodeDracoInBatches(
+  data: AsyncIterable<DracoWriterInputBatch> | Iterable<DracoWriterInputBatch>,
+  options: DracoBatchOptions = {}
+): AsyncIterable<DracoEncodingResult> {
+  const normalizedData = normalizeDracoInputBatches(data);
+  if (canEncodeWithWorker(DracoWriterWorker, options)) {
+    const {onProgress: _onProgress, ...workerOptions} = options;
+    return processOnWorkerInBatches<DracoBuilderMesh[], DracoEncodingResult>(
+      DracoWriterWorker,
+      normalizedData,
+      workerOptions
+    );
+  }
+  return encodeDracoInBatchesLocally(normalizedData, options);
+}
+
+/** Encodes batches through the public writer's ArrayBuffer-only batch API. */
+async function* encodeInBatches(
+  data: AsyncIterable<DracoWriterInput> | Iterable<DracoWriterInput>,
+  options: DracoBatchOptions = {}
+): AsyncIterable<ArrayBuffer> {
+  const geometryBatches = (async function* () {
+    for await (const geometry of data) {
+      yield [geometry];
+    }
+  })();
+  for await (const result of encodeDracoInBatches(geometryBatches, options)) {
+    yield result.data;
+  }
+}
+
+/** Worker-safe local implementation that initializes Draco exactly once. */
+export async function* encodeDracoInBatchesLocally(
+  data: AsyncIterable<DracoBuilderMesh[]> | Iterable<DracoBuilderMesh[]>,
+  options: DracoBatchOptions = {}
+): AsyncIterable<DracoEncodingResult> {
+  const {draco} = await loadDracoEncoderModule(extractLoadLibraryOptions(options));
+  const dracoBuilder = new DRACOBuilder(draco);
+  try {
+    for await (const batch of data) {
+      for (const geometry of batch) {
+        throwIfAborted(options.signal);
+        yield dracoBuilder.encodeSyncWithReport(geometry, options.draco);
+      }
+    }
+  } finally {
+    dracoBuilder.destroy();
+  }
+}
+
+/** Converts any accepted input batch into structured-clone-safe builder meshes. */
+async function* normalizeDracoInputBatches(
+  data: AsyncIterable<DracoWriterInputBatch> | Iterable<DracoWriterInputBatch>
+): AsyncIterable<DracoBuilderMesh[]> {
+  for await (const batch of data) {
+    yield batch.map(normalizeDracoMesh);
+  }
+}
+
+/** Throws the signal's reason before starting or between native encodes. */
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) {
+    return;
+  }
+  if (signal.reason !== undefined) {
+    throw signal.reason;
+  }
+  const error = new Error('Draco batch encoding aborted');
+  error.name = 'AbortError';
+  throw error;
+}
+
+/** Returns Draco-writable mesh data without copying ordinary Mesh attributes. */
+function normalizeDracoMesh(data: DracoWriterInput): DracoBuilderMesh {
+  if (isMeshArrowTable(data)) {
+    return convertTableToMesh(data);
+  }
+
+  if (isDracoBuilderMesh(data)) {
+    return data;
+  }
+
+  const {indices, ...attributes} = data;
+  return {attributes, ...(indices ? {indices} : {})};
+}
+
+/** Return true when the input is MeshArrowTable category data. */
+function isMeshArrowTable(data: unknown): data is MeshArrowTable {
+  return (
+    typeof data === 'object' && data !== null && 'shape' in data && data.shape === 'arrow-table'
+  );
+}
+
+/** Returns true when input uses the nested Mesh attribute representation. */
+function isDracoBuilderMesh(data: DracoWriterInput): data is DracoBuilderMesh | Mesh | DracoMesh {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'attributes' in data &&
+    typeof data.attributes === 'object' &&
+    data.attributes !== null &&
+    !ArrayBuffer.isView(data.attributes)
+  );
+}