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

package/src/gltf/lib/extensions/MSFT_texture_dds.ts

@@ -0,0 +1,52 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTFLoaderOptions} from '../../gltf-loader-types';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+import type {GLTF_MSFT_texture_dds} from '../types/gltf-json-schema';
+import type {Loader, LoaderContext} from '@loaders.gl/core/loader-utils';
+import {GLTFIterator} from '../api/gltf-iterator';
+
+/** Name of the Microsoft DDS texture extension. */
+export const name = 'MSFT_texture_dds';
+
+/** Finds a DDS-capable loader supplied through the parent loader context. */
+export function getDDSLoader(context?: LoaderContext): Loader | undefined {
+  return context?.loaders?.find(
+    loader => loader.extensions?.includes('dds') || loader.mimeTypes?.includes('image/vnd-ms.dds')
+  );
+}
+
+/** Select DDS sources only when an application supplies a compatible loader. */
+export function preprocess(
+  gltf: GLTFWithBuffers,
+  _options: GLTFLoaderOptions,
+  context?: LoaderContext
+): void {
+  const iterator = new GLTFIterator(gltf);
+  if (!iterator.hasExtension(name)) return;
+  if (!getDDSLoader(context)) {
+    if (iterator.isExtensionRequired(name)) {
+      throw new Error('gltf: Required extension MSFT_texture_dds needs a DDS parser');
+    }
+    return;
+  }
+  for (const texture of iterator.textures) {
+    const extension = iterator.getExtension<GLTF_MSFT_texture_dds>(texture, name);
+    if (extension) texture.source = extension.source;
+  }
+}
+
+/** Remove DDS declarations only after image loading can identify the selected sources. */
+export async function decode(
+  gltf: GLTFWithBuffers,
+  options: GLTFLoaderOptions,
+  context?: LoaderContext
+): Promise<void> {
+  if (!getDDSLoader(context) || options.gltf?.loadImages === false) return;
+  const iterator = new GLTFIterator(gltf);
+  if (!iterator.hasExtension(name)) return;
+  for (const texture of iterator.textures) iterator.removeExtension(texture, name);
+  iterator.removeExtension(name);
+}

package/src/gltf/lib/extensions/utils/3d-tiles-utils.ts

@@ -197,7 +197,11 @@ export function getPrimitiveTextureData(
     const mimeType = json.images?.[imageIndex]?.mimeType;
     const parsedImage = scenegraph.gltf.images?.[imageIndex];
     // Checking for width is to prevent handling Un-processed images (e.g. [analyze] stage, where loadImages option is set to false)
-    if (parsedImage && typeof parsedImage.width !== 'undefined') {
+    if (
+      parsedImage &&
+      typeof parsedImage.width !== 'undefined' &&
+      !('compressed' in parsedImage && parsedImage.compressed)
+    ) {
       const textureData: number[] = [];
       for (let index = 0; index < textureCoordinates.length; index += 2) {
         const value = getImageValueByCoordinates(

package/src/gltf/lib/parsers/parse-gltf.ts

@@ -12,8 +12,8 @@ import type {ParseGLBOptions} from './parse-glb';
 
 import type {ImageType, TextureLevel} from '@loaders.gl/core/schema';
 import {parseJSON, sliceArrayBuffer, parseFromContext} from '@loaders.gl/core/loader-utils';
-import {ImageBitmapLoader} from '@loaders.gl/images';
-import {BasisLoader} from '@loaders.gl/textures';
+import {ImageLoader} from '@loaders.gl/images';
+import {BasisLoader} from '@loaders.gl/images';
 
 import {assert} from '../utils/assert';
 import {isGLB, parseGLBSync} from './parse-glb';
@@ -21,6 +21,7 @@ import {canonicalizeUrl, resolveUrl} from '../gltf-utils/resolve-url';
 import {findGLTFFileIndex, resolveGLTFFile} from '../gltf-utils/resolve-gltf-file';
 import {getTypedArrayForBufferView} from '../gltf-utils/get-typed-array';
 import {preprocessExtensions, decodeExtensions} from '../api/gltf-extensions';
+import {getDDSLoader} from '../extensions/MSFT_texture_dds';
 import {normalizeGLTFV1WithDeferredBuffers} from '../api/normalize-gltf-v1';
 
 /**  */
@@ -542,10 +543,38 @@ async function loadImage(
 
   const gltfOptions = getGLTFImageOptions(options, image.mimeType);
 
+  const ddsLoader = getDDSLoader(context);
+  const ddsSelected = Boolean(
+    ddsLoader &&
+      !options.gltf?.excludeExtensions?.includes('MSFT_texture_dds') &&
+      gltf.json.textures?.some(
+        texture =>
+          texture.source === index && texture.extensions?.MSFT_texture_dds?.source === index
+      )
+  );
+  if (ddsSelected) {
+    const levels = (await parseFromContext(
+      arrayBuffer,
+      ddsLoader!,
+      options,
+      context
+    )) as TextureLevel[];
+    assert(levels.length > 0, 'MSFT_texture_dds parser returned no texture levels');
+    gltf.images = gltf.images || [];
+    gltf.images[index] = {
+      compressed: true,
+      mipmaps: true,
+      width: levels[0].width,
+      height: levels[0].height,
+      data: levels
+    };
+    return;
+  }
+
   // Call `parse`
   let parsedImage = (await parseFromContext(
     arrayBuffer,
-    [ImageBitmapLoader, BasisLoader],
+    [ImageLoader, BasisLoader],
     gltfOptions,
     context
   )) as ImageType | TextureLevel[][];
@@ -560,8 +589,8 @@ async function loadImage(
       data: parsedImage[0]
     };
   }
-  // TODO making sure ImageBitmapLoader is overridable by using array of loaders
-  // const parsedImage = await parse(arrayBuffer, [ImageBitmapLoader]);
+  // TODO making sure ImageLoader is overridable by using array of loaders
+  // const parsedImage = await parse(arrayBuffer, [ImageLoader]);
 
   // Store the loaded image
   gltf.images = gltf.images || [];

package/src/gltf/lib/types/gltf-ext-gaussian-splatting-schema.ts

@@ -41,6 +41,6 @@ export type GLTFGaussianSplatPrimitive = {
   compressedBufferView?: number;
   /** Preserved compressed SPZ2 bytes for native or GPU decoders. */
   compressedBytes?: Uint8Array;
-  /** Result returned by an injected SPZ2 decoder, when one was supplied. */
+  /** Result returned by an injected SPZ loader or legacy decoder, when supplied. */
   decoded?: unknown;
 };

package/src/gltf/lib/types/gltf-texture-procedurals.ts

@@ -0,0 +1,67 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+/** Serialized value types in the experimental procedural graph proposal. */
+export type GLTFProceduralValueType =
+  | 'boolean'
+  | 'float'
+  | 'integer'
+  | 'color3'
+  | 'color4'
+  | 'vector2'
+  | 'vector3'
+  | 'vector4'
+  | 'integer2'
+  | 'integer3'
+  | 'integer4'
+  | 'matrix3x3'
+  | 'matrix4x4'
+  | 'string'
+  | 'filename';
+
+/** Named graph port, retaining serialized connections without evaluating them. */
+export interface GLTFProceduralPort {
+  /** Port category. */
+  nodetype: 'input' | 'output';
+  /** Declared value type. */
+  type: GLTFProceduralValueType;
+  /** Authored constant; scalar numeric arrays are retained as authored. */
+  value?: boolean | string | number | number[];
+  /** Upstream processing node index. */
+  node?: number;
+  /** Name of a graph interface input. */
+  input?: string;
+  /** Name of the selected upstream output. */
+  output?: string;
+}
+
+/** Processing node in a procedural graph. */
+export interface GLTFProceduralNode {
+  /** Optional display name. */
+  name?: string;
+  /** MaterialX or custom node category; unknown categories are retained. */
+  nodetype: string;
+  /** Single output type, or multiple named outputs. */
+  type: GLTFProceduralValueType | 'multioutput';
+  /** Named input ports. */
+  inputs?: Record<string, GLTFProceduralPort>;
+  /** Named output ports. */
+  outputs: Record<string, GLTFProceduralPort>;
+}
+
+/** Flat procedural graph using the draft's named-port representation. */
+export interface GLTFProceduralGraph extends GLTFProceduralNode {
+  /** Graph category. */
+  nodetype: 'nodegraph';
+  /** Processing nodes addressed by index. */
+  nodes: GLTFProceduralNode[];
+}
+
+/** Procedural output attached to a material texture-info object. */
+export interface GLTFProceduralBinding {
+  /** Index into the root extension's procedurals array. */
+  index: number;
+  /** Selected output name; required for graphs with multiple outputs. */
+  output?: string;
+}

package/src/gltf/lib/types/gltf-types.ts

@@ -5,6 +5,7 @@
 /* eslint-disable camelcase */
 
 import {ImageType} from '@loaders.gl/images';
+import type {TextureLevel} from '@loaders.gl/core/schema';
 import type {GLTF} from './gltf-json-schema';
 import type {GLTFGaussianSplatPrimitive} from './gltf-ext-gaussian-splatting-schema';
 import type {GLTFSpatialAudio} from './gltf-mpeg-audio-spatial-schema';
@@ -50,6 +51,13 @@ export type GLTFExternalFile = GLTFExternalBuffer & {
 
 type GLTFExternalImage =
   | ImageType
+  | {
+      compressed: true;
+      mipmaps: true;
+      width: number;
+      height: number;
+      data: TextureLevel[];
+    }
   | {
       compressed: true;
       mipmaps: false;

package/src/gltf/lib/types/gltf-zod-schema.ts

@@ -539,6 +539,11 @@ export const GLTFEXTTextureWebpSchema = z
   .object({source: GLTFIdSchema, extras: z.unknown().optional()})
   .catchall(z.unknown());
 
+/** Zod schema for the EXT_texture_avif texture source extension. */
+export const GLTFEXTTextureAvifSchema = z
+  .object({source: GLTFIdSchema, extras: z.unknown().optional()})
+  .catchall(z.unknown());
+
 /** Zod schema for the MSFT_texture_dds extension. */
 export const GLTFMSFTTextureDdsSchema = z
   .object({source: GLTFIdSchema, extras: z.unknown().optional()})

package/src/gltf/schema.ts

@@ -22,3 +22,4 @@ export {
 export * from './lib/types/gltf-additional-extension-schemas';
 export * from './lib/types/gltf-audio-extension-schemas';
 export * from './lib/types/gltf-extension-schemas';
+export {GLTFEXTTextureAvifSchema} from './lib/types/gltf-zod-schema';

package/src/gltf-loader-types.ts

@@ -0,0 +1 @@
+export * from './gltf/gltf-loader-types.js';

package/src/gltf-loader.ts

@@ -0,0 +1 @@
+export * from './gltf/gltf-loader.js';

package/src/gltf-source.ts

@@ -0,0 +1 @@
+export * from './gltf/gltf-source.js';

package/src/gltf-writer.ts

@@ -0,0 +1 @@
+export * from './gltf/gltf-writer.js';

package/src/index.ts

@@ -15,3 +15,11 @@ export {GLTFWriter} from './gltf/gltf-writer';
 export {GLBLoader} from './gltf/glb-loader-types';
 export {GLBWriter} from './gltf/glb-writer';
 export {GLTFFormat, GLBFormat} from './gltf/gltf-format';
+
+export {DracoLoader, DracoWorkerLoader} from './draco/draco-loader-types';
+export {DracoFormat} from './draco/draco-format';
+export type * from './draco/index';
+export {DRACO_EXTERNAL_LIBRARIES, DRACO_EXTERNAL_LIBRARY_URLS} from './draco/draco-libraries';
+
+export {MaterialXLoader} from './materialx-loader-types';
+export type {MaterialXDocument, MaterialXElement} from './materialx/parse-materialx';

package/src/materialx/README.md

@@ -0,0 +1,5 @@
+# MaterialX parser
+
+Native XML parsing implementation for browsers and Node.js. `parseMaterialX` returns an ordered element tree retaining string attributes, named connections, custom node categories and unresolved includes. It rejects malformed XML, document types, and missing or unsupported major versions.
+
+This implementation does not resolve libraries, validate MaterialX node signatures, evaluate graphs, or generate shaders. The scene package exports MaterialXLoader with a materialx-loader implementation subpath.

package/src/materialx/parse-materialx.ts

@@ -0,0 +1,70 @@
+import {parseXMLSync} from '@loaders.gl/documents/xml-parser';
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+/** Authored MaterialX element, including extension categories and connection attributes. */
+export interface MaterialXElement {
+  /** XML element category, for example nodegraph, input, or multiply. */
+  category: string;
+  /** Authored string attributes; values are not coerced or evaluated. */
+  attributes: Record<string, string>;
+  /** Child elements in document order. */
+  children: MaterialXElement[];
+}
+
+/** Parsed MaterialX document. External includes remain unresolved. */
+export interface MaterialXDocument {
+  /** Authored MaterialX version. */
+  version: string;
+  /** MaterialX root element. */
+  root: MaterialXElement;
+}
+
+/**
+ * Parses a MaterialX XML document using the native documents XML parser.
+ * Preserves unknown categories, connection references and value strings.
+ * Does not load includes, resolve node definitions, or evaluate shader graphs.
+ */
+export function parseMaterialX(text: string): MaterialXDocument {
+  if (/<!DOCTYPE|<!ENTITY/i.test(text)) {
+    throw new Error('MaterialX: document types and entity declarations are unsupported.');
+  }
+  let element: OrderedXMLElement;
+  try {
+    element = parseXMLSync(text, {
+      preserveOrder: true,
+      parseAttributeValue: false,
+      trimValues: false
+    });
+  } catch (error) {
+    throw new Error('MaterialX: malformed XML.', {cause: error});
+  }
+  if (element.name !== 'materialx') {
+    throw new Error('MaterialX: expected a materialx root element.');
+  }
+  const version = element.attributes.version;
+  if (!version || !/^1\.\d+$/.test(version)) {
+    throw new Error('MaterialX: expected a MaterialX 1.x version.');
+  }
+  return {version, root: parseElement(element, 0)};
+}
+
+/** Ordered element representation returned by the XML parser. */
+interface OrderedXMLElement {
+  /** XML element name. */
+  name: string;
+  /** Authored string attributes. */
+  attributes: Record<string, string>;
+  /** Ordered child elements. */
+  children: OrderedXMLElement[];
+}
+
+/** Converts the native XML tree to MaterialX categories. */
+function parseElement(element: OrderedXMLElement, depth: number): MaterialXElement {
+  return {
+    category: element.name,
+    attributes: element.attributes,
+    children: element.children.map(child => parseElement(child, depth + 1))
+  };
+}

package/src/materialx/procedural-graph.ts

@@ -0,0 +1,94 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+
+/** Typed connection to one node output. */
+export interface ProceduralConnection {
+  /** Stable identifier of the upstream node. */
+  node: string;
+  /** Name of its output port. */
+  output: string;
+}
+
+/** Input supplied by a constant or another node. */
+export interface ProceduralInput {
+  /** Declared value type. */
+  type: string;
+  /** Constant value, retained without implicit conversion. */
+  value?: unknown;
+  /** Optional upstream connection. */
+  connection?: ProceduralConnection;
+}
+
+/** Renderer-independent operation with explicitly declared ports. */
+export interface ProceduralNode {
+  /** Stable node identifier, unique within the graph. */
+  id: string;
+  /** Operation identifier for a downstream implementation registry. */
+  operation: string;
+  /** Named inputs. */
+  inputs: Record<string, ProceduralInput>;
+  /** Named output value types. */
+  outputs: Record<string, string>;
+}
+
+/** Graph contract independent of GPU resources or shader languages. */
+export interface ProceduralGraph {
+  /** Nodes in authored order. */
+  nodes: ProceduralNode[];
+  /** Named graph outputs and their upstream connections. */
+  outputs: Record<string, ProceduralConnection>;
+}
+
+/**
+ * Validates explicit references and exact port types, returning dependency-first nodes.
+ * Does not infer conversions, resolve MaterialX definitions, or evaluate operations.
+ */
+export function orderProceduralGraph(graph: ProceduralGraph): ProceduralNode[] {
+  const nodes = new Map<string, ProceduralNode>();
+  for (const node of graph.nodes) {
+    if (!node.id || nodes.has(node.id))
+      throw new Error('Procedural graph: duplicate or empty node ID.');
+    nodes.set(node.id, node);
+  }
+  const dependencies = new Map<string, Set<string>>();
+  const dependents = new Map<string, string[]>();
+  for (const node of graph.nodes) {
+    const upstream = new Set<string>();
+    for (const input of Object.values(node.inputs)) {
+      if (!input.connection) continue;
+      if (Object.hasOwn(input, 'value'))
+        throw new Error('Procedural graph: connected input also has a value.');
+      const source = resolveOutput(input.connection);
+      if (source.outputs[input.connection.output] !== input.type) {
+        throw new Error('Procedural graph: incompatible connection types.');
+      }
+      upstream.add(source.id);
+    }
+    dependencies.set(node.id, upstream);
+    for (const identifier of upstream) {
+      const downstream = dependents.get(identifier) || [];
+      downstream.push(node.id);
+      dependents.set(identifier, downstream);
+    }
+  }
+  for (const output of Object.values(graph.outputs)) resolveOutput(output);
+  const ordered = graph.nodes.filter(node => dependencies.get(node.id)!.size === 0);
+  for (let index = 0; index < ordered.length; index++) {
+    for (const identifier of dependents.get(ordered[index].id) || []) {
+      const upstream = dependencies.get(identifier)!;
+      upstream.delete(ordered[index].id);
+      if (!upstream.size) ordered.push(nodes.get(identifier)!);
+    }
+  }
+  if (ordered.length !== graph.nodes.length) throw new Error('Procedural graph: cycle detected.');
+  return ordered;
+
+  /** Resolves an explicitly named output without accepting inherited properties. */
+  function resolveOutput(connection: ProceduralConnection): ProceduralNode {
+    const node = nodes.get(connection.node);
+    if (!node || !Object.hasOwn(node.outputs, connection.output)) {
+      throw new Error('Procedural graph: missing node or output.');
+    }
+    return node;
+  }
+}

package/src/materialx-loader-types.ts

@@ -0,0 +1,24 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+import type {MaterialXDocument} from './materialx/parse-materialx';
+
+/** Loads the parser-bearing MaterialX implementation. */
+async function preload() {
+  const {MaterialXLoaderWithParser} = await import('@loaders.gl/scene/materialx-loader');
+  return MaterialXLoaderWithParser;
+}
+
+/** Metadata-only loader for MaterialX XML documents. */
+export const MaterialXLoader = {
+  name: 'MaterialX',
+  id: 'materialx',
+  module: 'scene',
+  version: 'latest',
+  extensions: ['mtlx'],
+  mimeTypes: ['application/xml'],
+  text: true,
+  dataType: null as unknown as MaterialXDocument,
+  batchType: null as never,
+  options: {},
+  preload
+} as const;

package/src/materialx-loader.ts

@@ -0,0 +1,15 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+import {MaterialXLoader} from './materialx-loader-types';
+import {parseMaterialX} from './materialx/parse-materialx';
+
+const {preload: _preload, ...metadata} = MaterialXLoader;
+
+/** Parser-bearing loader for MaterialX XML, using the native XML parser. */
+export const MaterialXLoaderWithParser = {
+  ...metadata,
+  parse: async (data: ArrayBuffer) => parseMaterialX(new TextDecoder().decode(data)),
+  parseSync: (data: ArrayBuffer) => parseMaterialX(new TextDecoder().decode(data)),
+  parseText: async (text: string) => parseMaterialX(text),
+  parseTextSync: parseMaterialX
+} as const;

package/src/mtl-loader-types.ts

@@ -0,0 +1 @@
+export * from './obj/mtl-loader-types.js';

package/src/mtl-loader.ts

@@ -0,0 +1 @@
+export * from './obj/mtl-loader.js';

package/src/obj/mtl-loader-types.ts

@@ -18,7 +18,7 @@ export type MTLLoaderOptions = LoaderOptions & {
  * Preloads the parser-bearing MTL loader implementation.
  */
 async function preload() {
-  const {MTLLoaderWithParser} = await import('@loaders.gl/scene/obj/mtl-loader');
+  const {MTLLoaderWithParser} = await import('@loaders.gl/scene/mtl-loader');
   return MTLLoaderWithParser;
 }
 

package/src/obj/mtl-loader.ts

@@ -5,7 +5,7 @@
 import type {Loader, LoaderWithParser, LoaderOptions} from '@loaders.gl/core/loader-utils';
 import type {MTLMaterial, ParseMTLOptions} from './lib/parse-mtl';
 import {parseMTL} from './lib/parse-mtl';
-import {MTLWorkerLoader as MTLWorkerLoaderMetadata} from './mtl-loader-types';
+import {MTLLoader as MTLWorkerLoaderMetadata} from './mtl-loader-types';
 import {MTLLoader as MTLLoaderMetadata} from './mtl-loader-types';
 
 const {preload: _MTLWorkerLoaderPreload, ...MTLWorkerLoaderMetadataWithoutPreload} =

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

@@ -41,7 +41,7 @@ export type OBJParsedBatch = OBJMeshBatch | ArrowTableBatch;
  * Preloads the parser-bearing OBJ loader implementation.
  */
 async function preload() {
-  const {OBJLoaderWithParser} = await import('@loaders.gl/scene/obj/obj-loader');
+  const {OBJLoaderWithParser} = await import('@loaders.gl/scene/obj-loader');
   return OBJLoaderWithParser;
 }
 

package/src/obj-loader-types.ts

@@ -0,0 +1 @@
+export * from './obj/obj-loader-types.js';

package/src/obj-loader.ts

@@ -0,0 +1 @@
+export * from './obj/obj-loader.js';

package/src/obj-writer.ts

@@ -0,0 +1 @@
+export * from './obj/obj-writer.js';

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

@@ -11,7 +11,7 @@ const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
 
 /** Loads the parser-bearing USD loader implementation. */
 async function preload() {
-  const {USDLoaderWithParser} = await import('@loaders.gl/scene/usd/usd-loader');
+  const {USDLoaderWithParser} = await import('@loaders.gl/scene/usd-loader');
   return USDLoaderWithParser;
 }
 

package/src/usd-loader-types.ts

@@ -0,0 +1 @@
+export * from './usd/usd-loader-types.js';

package/src/usd-loader.ts

@@ -0,0 +1 @@
+export * from './usd/usd-loader.js';