@loaders.gl/scene 5.0.0-alpha.9 → 5.0.0-beta.2

package/src/obj/mtl-loader.ts

@@ -0,0 +1,37 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+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 {MTLLoader as MTLWorkerLoaderMetadata} from './mtl-loader-types';
+import {MTLLoader as MTLLoaderMetadata} from './mtl-loader-types';
+
+const {preload: _MTLWorkerLoaderPreload, ...MTLWorkerLoaderMetadataWithoutPreload} =
+  MTLWorkerLoaderMetadata;
+const {preload: _MTLLoaderPreload, ...MTLLoaderMetadataWithoutPreload} = MTLLoaderMetadata;
+
+export type MTLLoaderOptions = LoaderOptions & {
+  mtl?: ParseMTLOptions;
+};
+
+/**
+ * Loader for the MTL material format
+ * Parses a Wavefront .mtl file specifying materials
+ */
+export const MTLWorkerLoaderWithParser = {
+  ...MTLWorkerLoaderMetadataWithoutPreload
+} as const satisfies Loader<MTLMaterial[], never, LoaderOptions>;
+
+// MTLLoaderWithParser
+
+/**
+ * Loader for the MTL material format
+ */
+export const MTLLoaderWithParser = {
+  ...MTLLoaderMetadataWithoutPreload,
+  parse: async (arrayBuffer: ArrayBuffer, options?: MTLLoaderOptions) =>
+    parseMTL(new TextDecoder().decode(arrayBuffer), options?.mtl),
+  parseTextSync: (text: string, options?: MTLLoaderOptions) => parseMTL(text, options?.mtl)
+} as const satisfies LoaderWithParser<MTLMaterial[], never, MTLLoaderOptions>;

package/src/obj/obj-format.ts

@@ -0,0 +1,18 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Format} from '@loaders.gl/core/loader-utils';
+
+/**
+ * The OBJ geometry format
+ */
+export const OBJFormat = {
+  name: 'OBJ',
+  id: 'obj',
+  module: 'scene',
+  encoding: 'text',
+  format: 'obj',
+  extensions: ['obj'],
+  mimeTypes: ['text/plain']
+} as const satisfies Format;

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

@@ -0,0 +1,75 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader, LoaderOptions} from '@loaders.gl/core/loader-utils';
+import type {Mesh, MeshArrowTable, ArrowTableBatch} from '@loaders.gl/core/schema';
+import {OBJFormat} from './obj-format';
+import {serializeArrowWorkerTable} from '@loaders.gl/core/schema-utils/arrow-transport';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+export type OBJLoaderOptions = LoaderOptions & {
+  obj?: {
+    /** Output shape. Defaults to a Mesh Arrow table. */
+    shape?: 'mesh' | 'arrow-table';
+    /** Treat OBJ vertex records as a point cloud and stream `v` rows in batches. */
+    pointCloud?: boolean;
+    /** Override the URL to the worker bundle (by default loads from unpkg.com) */
+    workerUrl?: string;
+  };
+};
+
+/** Legacy OBJ mesh batch returned after caller-side conversion. */
+export type OBJMeshBatch = {
+  /** Legacy mesh batch shape. */
+  shape: 'mesh';
+  /** Parsed data batch discriminator. */
+  batchType: 'data';
+  /** Decoded mesh. */
+  data: Mesh;
+  /** Number of vertices. */
+  length: number;
+};
+
+/** Public OBJ batch output shapes. */
+export type OBJParsedBatch = OBJMeshBatch | ArrowTableBatch;
+
+/**
+ * Preloads the parser-bearing OBJ loader implementation.
+ */
+async function preload() {
+  const {OBJLoaderWithParser} = await import('@loaders.gl/scene/obj-loader');
+  return OBJLoaderWithParser;
+}
+
+/**
+ * Metadata-only worker loader for the OBJ geometry format
+ */
+export const OBJLoader = {
+  ...OBJFormat,
+
+  dataType: null as unknown as Mesh | MeshArrowTable,
+  batchType: null as unknown as OBJParsedBatch,
+  version: VERSION,
+  worker: true,
+  /** Enables the stateful input/output batch protocol on the built-in worker. */
+  workerInBatches: true,
+  serializeWorkerResult: serializeArrowWorkerTable,
+  text: true,
+  testText: testOBJFile,
+  options: {
+    obj: {shape: 'arrow-table'}
+  },
+  preload
+} as const satisfies Loader<Mesh | MeshArrowTable, OBJParsedBatch, OBJLoaderOptions>;
+
+function testOBJFile(text: string): boolean {
+  // TODO - There could be comment line first
+  return text[0] === 'v';
+}
+
+/** @deprecated Use OBJLoader. */
+export const OBJWorkerLoader = OBJLoader;

package/src/obj/obj-loader.ts

@@ -0,0 +1,203 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {OBJLoaderOptions, OBJParsedBatch} from './obj-loader-types';
+
+import {
+  concatenateArrayBuffersAsync,
+  makeLineIterator,
+  makeTextDecoderIterator,
+  makeTableScanBatch,
+  type LoaderWithParser
+} from '@loaders.gl/core/loader-utils';
+import type {Mesh, MeshArrowTable} from '@loaders.gl/core/schema';
+import {
+  deserializeArrowWorkerTable,
+  serializeArrowWorkerTable
+} from '@loaders.gl/core/schema-utils/arrow-transport';
+import {
+  convertMeshToTable,
+  convertTableToMesh,
+  getMeshBoundingBox
+} from '@loaders.gl/core/schema-utils';
+import {getOBJSchema} from './lib/get-obj-schema';
+import {parseOBJ} from './lib/parse-obj';
+import {OBJLoader as OBJLoaderMetadata} from './obj-loader-types';
+
+const {preload: _OBJLoaderPreload, ...OBJLoaderMetadataWithoutPreload} = OBJLoaderMetadata;
+
+function convertOBJMesh(mesh: Mesh, options?: OBJLoaderOptions): Mesh | MeshArrowTable {
+  const table = convertMeshToTable(mesh, 'arrow-table');
+  return options?.obj?.shape === 'mesh' ? convertTableToMesh(table) : table;
+}
+
+// OBJLoaderWithParser
+
+/**
+ * Loader for the OBJ geometry format
+ */
+export const OBJLoaderWithParser = {
+  ...OBJLoaderMetadataWithoutPreload,
+  parse: async (arrayBuffer: ArrayBuffer, options?: OBJLoaderOptions) =>
+    convertOBJMesh(parseOBJ(new TextDecoder().decode(arrayBuffer), options), options),
+  parseTextSync: (text: string, options?: OBJLoaderOptions) =>
+    convertOBJMesh(parseOBJ(text, options), options),
+  parseInBatches: async function* (
+    arrayBuffer:
+      | AsyncIterable<ArrayBufferLike | ArrayBufferView>
+      | Iterable<ArrayBufferLike | ArrayBufferView>,
+    options
+  ): AsyncIterable<OBJParsedBatch> {
+    const batchSize = getNumericBatchSize(options);
+    if (options?.obj?.pointCloud) {
+      const textIterator = makeTextDecoderIterator(arrayBuffer as AsyncIterable<ArrayBuffer>);
+      const lineIterator = makeLineIterator(textIterator);
+      yield* parseOBJPointCloudLinesInBatches(lineIterator, options, batchSize);
+      return;
+    }
+
+    const data = await concatenateArrayBuffersAsync(arrayBuffer);
+    const text = new TextDecoder().decode(data);
+    if (hasOBJGeometryRecords(text)) {
+      yield makeOBJBatch(parseOBJ(text, options), options);
+      return;
+    }
+
+    yield* parseOBJPointCloudInBatches(text, options, batchSize);
+  },
+  serializeWorkerResult: serializeArrowWorkerTable,
+  deserializeWorkerResult: deserializeOBJWorkerResult,
+  serializeWorkerBatch: serializeArrowWorkerTable,
+  deserializeWorkerBatch: deserializeOBJWorkerBatch
+} as const satisfies LoaderWithParser<Mesh | MeshArrowTable, OBJParsedBatch, OBJLoaderOptions>;
+
+/** Returns a numeric batch size when batching has an explicit row count. */
+function getNumericBatchSize(options?: OBJLoaderOptions): number | undefined {
+  const batchSize = options?.batchSize ?? options?.core?.batchSize;
+  return typeof batchSize === 'number' ? batchSize : undefined;
+}
+
+function hasOBJGeometryRecords(text: string): boolean {
+  return text.split(/\r?\n/).some(line => {
+    const trimmedLine = line.trimStart();
+    return trimmedLine.startsWith('f ') || trimmedLine.startsWith('l ');
+  });
+}
+
+function* parseOBJPointCloudInBatches(
+  text: string,
+  options?: OBJLoaderOptions,
+  batchSize?: number
+): Iterable<OBJParsedBatch> {
+  const vertexLines = text.split(/\r?\n/).filter(line => line.trimStart().startsWith('v '));
+  yield* makeOBJPointCloudBatches(vertexLines, options, batchSize);
+}
+
+async function* parseOBJPointCloudLinesInBatches(
+  lines: AsyncIterable<string>,
+  options?: OBJLoaderOptions,
+  batchSize?: number
+): AsyncIterable<OBJParsedBatch> {
+  const normalizedBatchSize = batchSize || 1000;
+  let vertexLines: string[] = [];
+
+  for await (const line of lines) {
+    if (!line.trimStart().startsWith('v ')) {
+      continue;
+    }
+    vertexLines.push(line);
+    if (vertexLines.length >= normalizedBatchSize) {
+      yield makeOBJBatch(parseOBJPointCloudMesh(vertexLines), options);
+      vertexLines = [];
+    }
+  }
+
+  if (vertexLines.length > 0) {
+    yield makeOBJBatch(parseOBJPointCloudMesh(vertexLines), options);
+  }
+}
+
+function* makeOBJPointCloudBatches(
+  vertexLines: string[],
+  options?: OBJLoaderOptions,
+  batchSize?: number
+): Iterable<OBJParsedBatch> {
+  const normalizedBatchSize = batchSize || vertexLines.length || 1;
+
+  for (let rowIndex = 0; rowIndex < vertexLines.length; rowIndex += normalizedBatchSize) {
+    const mesh = parseOBJPointCloudMesh(
+      vertexLines.slice(rowIndex, rowIndex + normalizedBatchSize)
+    );
+    yield makeOBJBatch(mesh, options);
+  }
+}
+
+/** Builds a point-list mesh directly from OBJ `v` records. */
+function parseOBJPointCloudMesh(vertexLines: string[]): Mesh {
+  const positions = new Float32Array(vertexLines.length * 3);
+
+  for (let vertexIndex = 0; vertexIndex < vertexLines.length; vertexIndex++) {
+    const values = vertexLines[vertexIndex].trim().split(/\s+/);
+    positions[vertexIndex * 3 + 0] = Number(values[1]);
+    positions[vertexIndex * 3 + 1] = Number(values[2]);
+    positions[vertexIndex * 3 + 2] = Number(values[3]);
+  }
+
+  const attributes = {
+    POSITION: {
+      value: positions,
+      size: 3
+    }
+  };
+  const boundingBox = getMeshBoundingBox(attributes);
+
+  return {
+    loaderData: {
+      header: {}
+    },
+    schema: getOBJSchema(attributes, {
+      mode: 0,
+      boundingBox: boundingBox ?? undefined
+    }),
+    header: {
+      vertexCount: vertexLines.length,
+      boundingBox: boundingBox ?? undefined
+    },
+    mode: 0,
+    topology: 'point-list',
+    attributes
+  };
+}
+
+function makeOBJBatch(mesh: Mesh, options?: OBJLoaderOptions): OBJParsedBatch {
+  const table = convertMeshToTable(mesh, 'arrow-table');
+  if (options?.obj?.shape === 'mesh') {
+    const convertedMesh = convertTableToMesh(table);
+    return {
+      shape: 'mesh',
+      batchType: 'data',
+      data: convertedMesh,
+      length: convertedMesh.header?.vertexCount || 0
+    };
+  }
+
+  return makeTableScanBatch(table);
+}
+
+/** Hydrates worker columns before applying the requested legacy mesh shape on the caller. */
+function deserializeOBJWorkerResult(
+  result: unknown,
+  options?: OBJLoaderOptions
+): Mesh | MeshArrowTable {
+  const table = deserializeArrowWorkerTable(result);
+  return options?.obj?.shape === 'mesh' ? convertTableToMesh(table) : table;
+}
+
+/** Restores the OBJ mesh batch envelope after caller-side conversion. */
+function deserializeOBJWorkerBatch(result: unknown, options?: OBJLoaderOptions): OBJParsedBatch {
+  const table = deserializeArrowWorkerTable(result);
+  if (options?.obj?.shape !== 'mesh') return table;
+  const mesh = convertTableToMesh(table);
+  return {shape: 'mesh', batchType: 'data', data: mesh, length: table.length};
+}

package/src/obj/obj-writer.ts

@@ -0,0 +1,190 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {WriterOptions, WriterWithEncoder} from '@loaders.gl/core/loader-utils';
+import type {Mesh, MeshArrowTable, MeshAttribute} from '@loaders.gl/core/schema';
+import {convertMeshToTable, convertTableToMesh} from '@loaders.gl/core/schema-utils';
+import {OBJFormat} from './obj-format';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Options for `OBJWriter`. */
+export type OBJWriterOptions = WriterOptions & {
+  /** Reserved for future OBJ writer options. */
+  obj?: Record<string, never>;
+};
+
+/**
+ * Writer for the OBJ geometry format.
+ */
+export const OBJWriter = {
+  ...OBJFormat,
+  dataType: null as unknown as Mesh | MeshArrowTable,
+  batchType: null as never,
+  version: VERSION,
+  options: {
+    obj: {}
+  },
+  text: true,
+  encode: async (data, options) => encodeOBJSync(data, options),
+  encodeSync: encodeOBJSync,
+  encodeTextSync: encodeOBJ
+} as const satisfies WriterWithEncoder<Mesh | MeshArrowTable, never, OBJWriterOptions>;
+
+/** Encode mesh category data as OBJ bytes. */
+function encodeOBJSync(data: Mesh | MeshArrowTable, options?: OBJWriterOptions): ArrayBuffer {
+  const text = encodeOBJ(data, options);
+  return new TextEncoder().encode(text).buffer;
+}
+
+/** Encode mesh category data as OBJ text. */
+function encodeOBJ(data: Mesh | MeshArrowTable, options?: OBJWriterOptions): string {
+  const mesh = convertTableToMesh(normalizeMeshArrowTable(data));
+  const positionAttribute = getRequiredAttribute(mesh, 'POSITION');
+  const normalAttribute = mesh.attributes.NORMAL;
+  const textureCoordinateAttribute = mesh.attributes.TEXCOORD_0;
+  const colorAttribute = mesh.attributes.COLOR_0;
+  const vertexCount = positionAttribute.value.length / positionAttribute.size;
+  const lines: string[] = ['# loaders.gl OBJ'];
+
+  for (let vertexIndex = 0; vertexIndex < vertexCount; vertexIndex++) {
+    const vertex = [
+      getComponent(positionAttribute, vertexIndex, 0),
+      getComponent(positionAttribute, vertexIndex, 1),
+      getComponent(positionAttribute, vertexIndex, 2)
+    ];
+
+    if (colorAttribute) {
+      vertex.push(
+        getColorComponent(colorAttribute, vertexIndex, 0),
+        getColorComponent(colorAttribute, vertexIndex, 1),
+        getColorComponent(colorAttribute, vertexIndex, 2)
+      );
+    }
+
+    lines.push(`v ${vertex.join(' ')}`);
+  }
+
+  if (textureCoordinateAttribute) {
+    for (let vertexIndex = 0; vertexIndex < vertexCount; vertexIndex++) {
+      lines.push(
+        `vt ${getComponent(textureCoordinateAttribute, vertexIndex, 0)} ${getComponent(
+          textureCoordinateAttribute,
+          vertexIndex,
+          1
+        )}`
+      );
+    }
+  }
+
+  if (normalAttribute) {
+    for (let vertexIndex = 0; vertexIndex < vertexCount; vertexIndex++) {
+      lines.push(
+        `vn ${getComponent(normalAttribute, vertexIndex, 0)} ${getComponent(
+          normalAttribute,
+          vertexIndex,
+          1
+        )} ${getComponent(normalAttribute, vertexIndex, 2)}`
+      );
+    }
+  }
+
+  const triangleIndices = getTriangleIndices(mesh, vertexCount);
+  for (let triangleIndex = 0; triangleIndex < triangleIndices.length; triangleIndex += 3) {
+    const face = [
+      getFaceVertex(
+        triangleIndices[triangleIndex],
+        Boolean(textureCoordinateAttribute),
+        Boolean(normalAttribute)
+      ),
+      getFaceVertex(
+        triangleIndices[triangleIndex + 1],
+        Boolean(textureCoordinateAttribute),
+        Boolean(normalAttribute)
+      ),
+      getFaceVertex(
+        triangleIndices[triangleIndex + 2],
+        Boolean(textureCoordinateAttribute),
+        Boolean(normalAttribute)
+      )
+    ];
+    lines.push(`f ${face.join(' ')}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/** Return mesh data as a MeshArrowTable, converting plain Mesh data first. */
+function normalizeMeshArrowTable(data: Mesh | MeshArrowTable): MeshArrowTable {
+  if ('shape' in data && data.shape === 'arrow-table') {
+    return data;
+  }
+  return convertMeshToTable(data as Mesh, 'arrow-table');
+}
+
+/** Return a required mesh attribute or throw a format-specific error. */
+function getRequiredAttribute(mesh: Mesh, attributeName: string): MeshAttribute {
+  const attribute = mesh.attributes[attributeName];
+  if (!attribute) {
+    throw new Error(`OBJWriter: ${attributeName} attribute is required`);
+  }
+  return attribute;
+}
+
+/** Return a single attribute component with 0 as the missing component fallback. */
+function getComponent(
+  attribute: MeshAttribute,
+  vertexIndex: number,
+  componentIndex: number
+): number {
+  return attribute.value[vertexIndex * attribute.size + componentIndex] || 0;
+}
+
+/** Return a color component normalized for OBJ vertex colors. */
+function getColorComponent(
+  attribute: MeshAttribute,
+  vertexIndex: number,
+  componentIndex: number
+): number {
+  const value = getComponent(attribute, vertexIndex, componentIndex);
+  return attribute.normalized || value > 1 ? value / 255 : value;
+}
+
+/** Return triangle indices for indexed or sequential triangle-list meshes. */
+function getTriangleIndices(mesh: Mesh, vertexCount: number): number[] {
+  if (mesh.indices?.value?.length) {
+    return Array.from(mesh.indices.value);
+  }
+
+  if (mesh.mode !== 4 && mesh.topology !== 'triangle-list') {
+    return [];
+  }
+
+  const triangleIndices: number[] = [];
+  for (let vertexIndex = 0; vertexIndex + 2 < vertexCount; vertexIndex += 3) {
+    triangleIndices.push(vertexIndex, vertexIndex + 1, vertexIndex + 2);
+  }
+  return triangleIndices;
+}
+
+/** Return an OBJ face vertex reference. */
+function getFaceVertex(
+  vertexIndex: number,
+  hasTextureCoordinates: boolean,
+  hasNormals: boolean
+): string {
+  const faceIndex = vertexIndex + 1;
+  if (hasTextureCoordinates && hasNormals) {
+    return `${faceIndex}/${faceIndex}/${faceIndex}`;
+  }
+  if (hasTextureCoordinates) {
+    return `${faceIndex}/${faceIndex}`;
+  }
+  if (hasNormals) {
+    return `${faceIndex}//${faceIndex}`;
+  }
+  return String(faceIndex);
+}

package/src/obj/unbundled.ts

@@ -0,0 +1,10 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+export {OBJFormat} from './obj-format';
+export type {OBJLoaderOptions} from './obj-loader-types';
+export {OBJWorkerLoader, OBJLoader} from './obj-loader-types';
+export {MTLFormat} from './mtl-format';
+export type {MTLLoaderOptions} from './mtl-loader-types';
+export {MTLWorkerLoader, MTLLoader} from './mtl-loader-types';

package/src/obj/workers/obj-worker.ts

@@ -0,0 +1,24 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {createLoaderWorker} from '@loaders.gl/core/loader-utils';
+import {OBJLoaderWithParser} from '../obj-loader';
+
+createLoaderWorker({
+  ...OBJLoaderWithParser,
+  /** Always returns columnar data; legacy mesh conversion runs on the caller. */
+  parse(input, options) {
+    return OBJLoaderWithParser.parse(input, {
+      ...options,
+      obj: {...options?.obj, shape: 'arrow-table'}
+    });
+  },
+  /** Keeps one columnar parser alive for the entire worker input stream. */
+  parseInBatches(input, options) {
+    return OBJLoaderWithParser.parseInBatches(input, {
+      ...options,
+      obj: {...options?.obj, shape: 'arrow-table'}
+    });
+  }
+});

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/index.ts

@@ -0,0 +1,15 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {USDLoader} from './usd-loader-types';
+export type {
+  USDAssetPath,
+  USDAttribute,
+  USDLoaderOptions,
+  USDPrim,
+  USDScenePath,
+  USDStage,
+  USDValue,
+  USDVariant
+} from './lib/usd-types';

package/src/{lib → usd/lib}/parse-usd.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {LoaderContext} from '@loaders.gl/loader-utils';
+import type {LoaderContext} from '@loaders.gl/core/loader-utils';
 import {parseUSDA} from './parse-usda';
 import {parseUSDZArchive} from './parse-usdz';
 import type {USDAssetPath, USDLoaderOptions, USDPrim, USDStage, USDValue} from './usd-types';

package/src/{lib → usd/lib}/usd-types.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {LoaderOptions} from '@loaders.gl/loader-utils';
+import type {LoaderOptions} from '@loaders.gl/core/loader-utils';
 
 /** Reference to an external OpenUSD layer and optional prim within that layer. */
 export type USDAssetPath = {

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

@@ -0,0 +1,40 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader} from '@loaders.gl/core/loader-utils';
+import type {USDLoaderOptions, USDStage} from './lib/usd-types';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+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-loader');
+  return USDLoaderWithParser;
+}
+
+/** Metadata-only loader for OpenUSD ASCII and uncompressed USDZ scenes. */
+export const USDLoader = {
+  dataType: null as unknown as USDStage,
+  batchType: null as never,
+  name: 'Universal Scene Description',
+  id: 'usd',
+  module: 'scene',
+  version: VERSION,
+  extensions: ['usd', 'usda', 'usdz'],
+  mimeTypes: ['model/vnd.usd', 'model/vnd.usda', 'model/vnd.usdz+zip'],
+  text: true,
+  binary: true,
+  tests: ['#usda', 'PK'],
+  options: {
+    usd: {
+      compose: true,
+      loadReferences: true,
+      maxReferenceDepth: 12,
+      variantSelections: {}
+    }
+  },
+  preload
+} as const satisfies Loader<USDStage, never, USDLoaderOptions>;

package/src/usd/usd-loader.ts

@@ -0,0 +1,26 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoaderWithParser} from '@loaders.gl/core/loader-utils';
+import {parseUSD} from './lib/parse-usd';
+import type {USDLoaderOptions, USDStage} from './lib/usd-types';
+import {USDLoader as USDLoaderMetadata} from './usd-loader-types';
+
+const {preload: _USDLoaderPreload, ...USDLoaderMetadataWithoutPreload} = USDLoaderMetadata;
+
+/** Parser-bearing loader for OpenUSD ASCII and uncompressed USDZ scenes. */
+export const USDLoaderWithParser = {
+  ...USDLoaderMetadataWithoutPreload,
+  parse: parseUSD,
+  parseText
+} as const satisfies LoaderWithParser<USDStage, never, USDLoaderOptions>;
+
+/** Encodes USDA source text before using the shared binary parser. */
+async function parseText(
+  text: string,
+  options?: USDLoaderOptions,
+  context?: Parameters<typeof parseUSD>[2]
+): Promise<USDStage> {
+  return parseUSD(new TextEncoder().encode(text).buffer, options, context);
+}