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

package/src/gltf/lib/encoders/encode-glb.ts

@@ -0,0 +1,198 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/* eslint-disable camelcase, max-statements */
+import {
+  copyPaddedStringToDataView,
+  copyPaddedArrayBufferToDataView
+} from '@loaders.gl/core/loader-utils';
+import type {GLB, GLBChunk} from '../types/glb-types';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+
+const MAGIC_glTF = 0x46546c67; // glTF in ASCII
+const MAGIC_JSON = 0x4e4f534a; // JSON in ASCII
+const MAGIC_BIN = 0x004e4942; // BIN\0 in ASCII
+
+const LE = true; // Binary GLTF is little endian.
+
+export type GLBEncodeOptions = {
+  /** GLB version to encode. Defaults to the input version or v2. */
+  version?: number;
+  [key: string]: unknown;
+};
+
+/**
+ * Encode the full GLB buffer with header etc
+ *
+ * @param glb
+ * @param dataView - if `null`, does not encode but just calculates length
+ * @param byteOffset
+ * @param options
+ * @returns
+ *
+ * @see https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#glb-file-format-specification
+ * @todo type GLB argument
+ */
+export function encodeGLBSync(
+  glb: GLB | GLTFWithBuffers,
+  dataView: DataView | null,
+  byteOffset = 0,
+  options: GLBEncodeOptions = {}
+) {
+  const magic = MAGIC_glTF;
+  const version = options.version ?? ('version' in glb ? glb.version : 2);
+  const json = glb.json ?? {};
+
+  if (version === 3) return encodeGLBV3(glb, dataView, byteOffset, magic, json);
+  if (version !== 2) throw new Error(`Unsupported GLB writer version ${version}.`);
+  const binary =
+    'binChunks' in glb
+      ? glb.binary
+        ? new Uint8Array(glb.binary)
+        : glb.binChunks?.[0] && getChunkBytes(glb.binChunks[0])
+      : glb.buffers?.[0] && getChunkBytes(glb.buffers[0]);
+
+  const byteOffsetStart = byteOffset;
+
+  // Write GLB Header
+  if (dataView) {
+    dataView.setUint32(byteOffset + 0, magic, LE); // Magic number (the ASCII string 'glTF').
+    dataView.setUint32(byteOffset + 4, version, LE); // Version 2 of binary glTF container format uint32
+    dataView.setUint32(byteOffset + 8, 0, LE); // Total byte length of generated file (uint32), will be set last
+  }
+  const byteOffsetFileLength = byteOffset + 8;
+  byteOffset += 12; // GLB_FILE_HEADER_SIZE
+
+  // Write the JSON chunk header
+  const byteOffsetJsonHeader = byteOffset;
+  if (dataView) {
+    dataView.setUint32(byteOffset + 0, 0, LE); // Byte length of json chunk (will be written later)
+    dataView.setUint32(byteOffset + 4, MAGIC_JSON, LE); // Chunk type
+  }
+  byteOffset += 8; // GLB_CHUNK_HEADER_SIZE
+
+  // Write the JSON chunk
+  const jsonString = JSON.stringify(json);
+  byteOffset = copyPaddedStringToDataView(dataView, byteOffset, jsonString, 4);
+
+  // Now we know the JSON chunk length so we can write it.
+  if (dataView) {
+    const jsonByteLength = byteOffset - byteOffsetJsonHeader - 8; // GLB_CHUNK_HEADER_SIZE
+    dataView.setUint32(byteOffsetJsonHeader + 0, jsonByteLength, LE); // Byte length of json chunk (uint32)
+  }
+
+  // Write the BIN chunk if present. The BIN chunk is optional.
+  if (binary) {
+    const byteOffsetBinHeader = byteOffset;
+
+    // Write the BIN chunk header
+    if (dataView) {
+      dataView.setUint32(byteOffset + 0, 0, LE); // Byte length BIN (uint32)
+      dataView.setUint32(byteOffset + 4, MAGIC_BIN, LE); // Chunk type
+    }
+    byteOffset += 8; // GLB_CHUNK_HEADER_SIZE
+
+    byteOffset = copyPaddedArrayBufferToDataView(dataView, byteOffset, binary, 4);
+
+    // Now we know the BIN chunk length so we can write it.
+    if (dataView) {
+      const binByteLength = byteOffset - byteOffsetBinHeader - 8; // GLB_CHUNK_HEADER_SIZE
+      dataView.setUint32(byteOffsetBinHeader + 0, binByteLength, LE); // Byte length BIN (uint32)
+    }
+  }
+
+  // Now we know the glb file length so we can write it.
+  if (dataView) {
+    const fileByteLength = byteOffset - byteOffsetStart;
+    dataView.setUint32(byteOffsetFileLength, fileByteLength, LE); // Total byte length of generated file (uint32)
+  }
+
+  return byteOffset;
+}
+
+/** Encode a draft GLB v3 container with 64-bit file and chunk lengths. */
+function encodeGLBV3(
+  glb: GLB | GLTFWithBuffers,
+  dataView: DataView | null,
+  byteOffset: number,
+  magic: number,
+  json: Record<string, unknown>
+): number {
+  const byteOffsetStart = byteOffset;
+  const chunks: GLBChunk[] = [
+    {type: MAGIC_JSON, arrayBuffer: encodeJSON(json)},
+    ...(('chunks' in glb ? glb.chunks : []) ?? []),
+    ...('binChunks' in glb
+      ? (glb.binChunks ?? []).map(chunk => ({
+          type: MAGIC_BIN,
+          arrayBuffer: getChunkBytes(chunk).slice().buffer
+        }))
+      : (glb.buffers ?? []).map(buffer => ({
+          type: MAGIC_BIN,
+          arrayBuffer: getChunkBytes(buffer).slice().buffer
+        })))
+  ];
+
+  if (dataView) {
+    dataView.setUint32(byteOffset, magic, LE);
+    dataView.setUint32(byteOffset + 4, 3, LE);
+    setUint64(dataView, byteOffset + 8, 0, 'GLB file length');
+  }
+  byteOffset += 16;
+
+  for (const chunk of chunks) {
+    const encoding = chunk.encoding ?? 0;
+    if (encoding !== 0) throw new Error(`Unsupported GLB chunk encoding ${encoding}.`);
+    const byteOffsetChunkHeader = byteOffset;
+    if (dataView) {
+      dataView.setUint32(byteOffset, chunk.type, LE);
+      dataView.setUint32(byteOffset + 4, encoding, LE);
+      setUint64(dataView, byteOffset + 8, 0, 'GLB chunk length');
+    }
+    byteOffset += 16;
+    byteOffset = copyPaddedArrayBufferToDataView(
+      dataView,
+      byteOffset,
+      new Uint8Array(chunk.arrayBuffer),
+      4
+    );
+    if (dataView) {
+      setUint64(
+        dataView,
+        byteOffsetChunkHeader + 8,
+        byteOffset - byteOffsetChunkHeader - 16,
+        'GLB chunk length'
+      );
+    }
+  }
+
+  if (dataView) {
+    setUint64(dataView, byteOffsetStart + 8, byteOffset - byteOffsetStart, 'GLB file length');
+  }
+  return byteOffset;
+}
+
+function getChunkBytes(chunk: {
+  arrayBuffer: ArrayBuffer;
+  byteOffset: number;
+  byteLength: number;
+}): Uint8Array {
+  return new Uint8Array(chunk.arrayBuffer, chunk.byteOffset, chunk.byteLength);
+}
+
+function encodeJSON(json: Record<string, unknown>): ArrayBuffer {
+  const jsonString = JSON.stringify(json);
+  const byteLength = new TextEncoder().encode(jsonString).byteLength;
+  const paddedByteLength = Math.ceil(byteLength / 4) * 4;
+  const arrayBuffer = new ArrayBuffer(paddedByteLength);
+  const dataView = new DataView(arrayBuffer);
+  copyPaddedStringToDataView(dataView, 0, jsonString, 4);
+  return arrayBuffer;
+}
+
+function setUint64(dataView: DataView, byteOffset: number, value: number, label: string): void {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error(`${label} is outside the safe integer range.`);
+  dataView.setBigUint64(byteOffset, BigInt(value), LE);
+}

package/src/gltf/lib/encoders/encode-gltf-draco.ts

@@ -0,0 +1,239 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {DracoBuildOptions, DracoBuilderMesh, DracoEncodingResult} from '@loaders.gl/draco';
+import {encodeDraco} from '@loaders.gl/draco';
+import type {TypedArray} from '@loaders.gl/core/schema';
+import type {GLTFWriterOptions} from '../../gltf-writer';
+import type {GLTFMeshPrimitive} from '../types/gltf-json-schema';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+import {getTypedArrayForAccessor} from '../gltf-utils/get-typed-array';
+
+const KHR_DRACO_MESH_COMPRESSION = 'KHR_draco_mesh_compression';
+
+/** Draco options accepted by the glTF writer. */
+export type GLTFDracoWriterOptions = DracoBuildOptions & {
+  /** Enable generation of `KHR_draco_mesh_compression` buffer views. */
+  enabled?: boolean;
+  /** Leave unsupported primitive modes unchanged instead of throwing. */
+  skipUnsupportedPrimitives?: boolean;
+};
+
+/**
+ * Creates a Draco-compressed glTF copy.
+ *
+ * The input JSON and loaded buffers are never modified. Compressed payloads
+ * are appended to buffer 0 and referenced by `KHR_draco_mesh_compression`;
+ * the original accessors remain available for consumers that do not decode the
+ * extension.
+ */
+export async function compressGLTFWithDraco(
+  gltf: GLTFWithBuffers,
+  options: GLTFWriterOptions = {}
+): Promise<GLTFWithBuffers> {
+  const dracoOptions = options.gltf?.draco;
+  if (!dracoOptions?.enabled) {
+    return gltf;
+  }
+  if ((gltf.buffers?.length || 0) > 1) {
+    throw new Error('GLTF Draco writer requires a single buffer');
+  }
+
+  const json = cloneGLTFJson(gltf.json);
+  const buffers = cloneBuffers(gltf.buffers || []);
+  const output: GLTFWithBuffers = {...gltf, json, buffers};
+  const primitives: Array<{
+    primitive: GLTFMeshPrimitive;
+    result: DracoEncodingResult;
+  }> = [];
+
+  for (const mesh of json.meshes || []) {
+    for (const primitive of mesh.primitives || []) {
+      const mode = primitive.mode ?? 4;
+      if (mode !== 4) {
+        if (dracoOptions.skipUnsupportedPrimitives ?? true) {
+          continue;
+        }
+        throw new Error(
+          `GLTF Draco writer cannot compress primitive mode ${mode}; only TRIANGLES (4) is supported`
+        );
+      }
+      if (primitive.extensions?.[KHR_DRACO_MESH_COMPRESSION]) {
+        throw new Error('GLTF Draco writer refuses to replace an existing Draco extension');
+      }
+      const meshData = getPrimitiveMesh(gltf, primitive);
+      const result = await encodeDraco(meshData, {
+        core: options.core,
+        modules: options.modules,
+        draco: dracoOptions
+      });
+      primitives.push({primitive, result});
+    }
+  }
+
+  if (primitives.length === 0) {
+    return output;
+  }
+
+  const originalBytes = getBufferBytes(buffers);
+  let byteLength = originalBytes.byteLength;
+  for (const {result} of primitives) {
+    byteLength = alignTo4(byteLength) + result.data.byteLength;
+  }
+  const combinedBytes = new Uint8Array(byteLength);
+  combinedBytes.set(originalBytes);
+
+  json.bufferViews = json.bufferViews || [];
+  json.buffers = json.buffers || [{byteLength: 0}];
+  let byteOffset = alignTo4(originalBytes.byteLength);
+  for (const {primitive, result} of primitives) {
+    new Uint8Array(combinedBytes.buffer, byteOffset, result.data.byteLength).set(
+      new Uint8Array(result.data)
+    );
+    const bufferView = json.bufferViews.length;
+    json.bufferViews.push({buffer: 0, byteOffset, byteLength: result.data.byteLength});
+    primitive.extensions = {
+      ...(primitive.extensions || {}),
+      [KHR_DRACO_MESH_COMPRESSION]: {
+        bufferView,
+        attributes: Object.fromEntries(
+          Object.entries(result.report.attributes).map(([attributeName, attribute]) => [
+            attributeName,
+            attribute.id
+          ])
+        )
+      }
+    };
+    byteOffset = alignTo4(byteOffset + result.data.byteLength);
+  }
+
+  const finalBytes = combinedBytes;
+  output.buffers[0] = {
+    ...(output.buffers[0] || {byteOffset: 0}),
+    arrayBuffer: finalBytes.buffer,
+    byteOffset: 0,
+    byteLength: finalBytes.byteLength
+  };
+  json.buffers[0] = {...(json.buffers[0] || {}), byteLength: finalBytes.byteLength};
+  json.extensionsUsed = addExtension(json.extensionsUsed, KHR_DRACO_MESH_COMPRESSION);
+  return output;
+}
+
+/** Builds Draco input from one raw glTF primitive. */
+function getPrimitiveMesh(gltf: GLTFWithBuffers, primitive: GLTFMeshPrimitive): DracoBuilderMesh {
+  if (!primitive.attributes || primitive.attributes.POSITION === undefined) {
+    throw new Error('GLTF Draco writer requires a POSITION attribute');
+  }
+  const attributes: Record<
+    string,
+    TypedArray | {value: TypedArray; size: number; normalized?: boolean}
+  > = {};
+  for (const [attributeName, accessorIndex] of Object.entries(primitive.attributes)) {
+    const accessor = gltf.json.accessors?.[accessorIndex];
+    if (!accessor) {
+      throw new Error(`GLTF Draco writer could not resolve accessor ${accessorIndex}`);
+    }
+    if (accessor.sparse) {
+      throw new Error(`GLTF Draco writer does not support sparse accessor ${accessorIndex}`);
+    }
+    const value = getStandardTypedArray(gltf, accessorIndex, accessor.componentType);
+    attributes[attributeName] = {
+      value,
+      size: getComponentCount(accessor.type),
+      ...(accessor.normalized === undefined ? {} : {normalized: accessor.normalized})
+    };
+  }
+
+  let indices: TypedArray;
+  if (primitive.indices !== undefined) {
+    const accessor = gltf.json.accessors?.[primitive.indices];
+    if (!accessor) {
+      throw new Error(`GLTF Draco writer could not resolve index accessor ${primitive.indices}`);
+    }
+    if (accessor.sparse) {
+      throw new Error(`GLTF Draco writer does not support sparse accessor ${primitive.indices}`);
+    }
+    indices = getStandardTypedArray(gltf, primitive.indices, accessor.componentType);
+  } else {
+    const positionAccessor = gltf.json.accessors?.[primitive.attributes.POSITION];
+    if (!positionAccessor || positionAccessor.count % 3 !== 0) {
+      throw new Error('GLTF Draco writer requires triangle-aligned POSITION data without indices');
+    }
+    indices = new Uint32Array(positionAccessor.count);
+    for (let index = 0; index < indices.length; index++) {
+      indices[index] = index;
+    }
+  }
+  return {attributes, indices};
+}
+
+/** Returns an accessor array type accepted by the official Draco JS binding. */
+function getStandardTypedArray(
+  gltf: GLTFWithBuffers,
+  accessorIndex: number,
+  componentType: number
+): TypedArray {
+  const value = getTypedArrayForAccessor(gltf.json, gltf.buffers, accessorIndex);
+  if (
+    value instanceof BigInt64Array ||
+    value instanceof BigUint64Array ||
+    value instanceof Float64Array
+  ) {
+    throw new Error(
+      `GLTF Draco writer does not support 64-bit accessor ${accessorIndex} (componentType ${componentType}); the official 1.5.7 encoder binding has no 64-bit attribute API`
+    );
+  }
+  return value;
+}
+
+/** Clones the plain JSON portion without retaining caller-owned object identity. */
+function cloneGLTFJson<T>(json: T): T {
+  return JSON.parse(JSON.stringify(json)) as T;
+}
+
+/** Copies loaded buffer storage so appending compressed data cannot mutate input. */
+function cloneBuffers(buffers: GLTFWithBuffers['buffers']): GLTFWithBuffers['buffers'] {
+  return buffers.map(buffer => ({
+    ...buffer,
+    arrayBuffer: buffer.arrayBuffer.slice(0)
+  }));
+}
+
+/** Returns the active bytes of the first loaded glTF buffer. */
+function getBufferBytes(buffers: GLTFWithBuffers['buffers']): Uint8Array {
+  const buffer = buffers[0] || {arrayBuffer: new ArrayBuffer(0), byteOffset: 0, byteLength: 0};
+  return new Uint8Array(buffer.arrayBuffer, buffer.byteOffset || 0, buffer.byteLength);
+}
+
+/** Aligns a byte offset to the glTF-required four-byte boundary. */
+function alignTo4(value: number): number {
+  return Math.ceil(value / 4) * 4;
+}
+
+/** Adds an extension name once while preserving the existing declaration order. */
+function addExtension(extensions: string[] | undefined, extension: string): string[] {
+  return extensions?.includes(extension) ? extensions : [...(extensions || []), extension];
+}
+
+/** Returns the number of scalar components represented by a glTF accessor type. */
+function getComponentCount(type: string): number {
+  switch (type) {
+    case 'SCALAR':
+      return 1;
+    case 'VEC2':
+      return 2;
+    case 'VEC3':
+      return 3;
+    case 'VEC4':
+      return 4;
+    case 'MAT2':
+      return 4;
+    case 'MAT3':
+      return 9;
+    case 'MAT4':
+      return 16;
+    default:
+      throw new Error(`GLTF Draco writer does not recognize accessor type ${type}`);
+  }
+}

package/src/gltf/lib/encoders/encode-gltf.ts

@@ -0,0 +1,45 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {encodeGLBSync} from './encode-glb';
+import {GLTFWriterOptions} from '../../gltf-writer';
+import {GLTFWithBuffers} from '@loaders.gl/scene/gltf';
+
+export type GLTFEncodeOptions = Record<string, any>;
+
+/**
+ * Encode the full glTF file as a binary GLB file
+ * Returns an ArrayBuffer that represents the complete GLB image that can be saved to file
+ *
+ * @todo - Does not support encoding to non-GLB versions of glTF format. Other formats
+ * - Encode as a textual JSON file with binary data in base64 data URLs.
+ * - Encode as a JSON with all images (and buffers?) in separate binary files
+ *
+ * glb-file-format-specification
+ * @see https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#
+ *
+ * @param gltf
+ * @param arrayBuffer
+ * @param byteOffset
+ * @param options
+ * @returns
+ */
+export function encodeGLTFSync(
+  gltf: GLTFWithBuffers,
+  arrayBuffer: DataView | null,
+  byteOffset: number,
+  options: GLTFWriterOptions
+) {
+  validateGltf(gltf);
+
+  // TODO: Copy buffers to binary
+
+  return encodeGLBSync(gltf, arrayBuffer, byteOffset, options);
+}
+
+function validateGltf(gltf) {
+  if (gltf.buffers && gltf.buffers.length > 1) {
+    throw new Error('encodeGLTF: multiple buffers not yet implemented');
+  }
+}