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

package/dist/gltf/lib/api/gltf-iterator.js

@@ -0,0 +1,940 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { getTypedArrayForAccessor as getAccessorTypedArray, getTypedArrayForBufferView as getBufferViewTypedArray, getTypedArrayForImageData as getImageTypedArray } from "../gltf-utils/get-typed-array.js";
+import { getAccessorTypeFromSize } from "../gltf-utils/gltf-utils.js";
+/** Base class for a lightweight view of one raw glTF object. */
+class GLTFObjectIterator {
+    /** Original glTF container. */
+    gltf;
+    /** Stable tag identifying the wrapped object type. */
+    type;
+    /** Index in the object's top-level or parent-local collection. */
+    index;
+    /** Exact unmodified object from the source glTF JSON. */
+    data;
+    /** Human-readable path to the raw object. */
+    path;
+    /** Root iterator used to resolve linked indices. */
+    iterator;
+    /** Create a lightweight wrapper for a raw glTF object. */
+    constructor(iterator, type, index, data, path) {
+        this.iterator = iterator;
+        this.gltf = iterator.gltf;
+        this.type = type;
+        this.index = index;
+        this.data = data;
+        this.path = path;
+    }
+}
+/** Base class for an object stored in a parent-local array or property. */
+class GLTFNestedObjectIterator extends GLTFObjectIterator {
+    /** Wrapper containing this nested object. */
+    parent;
+    /** Create a wrapper for a parent-local raw glTF object. */
+    constructor(iterator, type, index, data, path, parent) {
+        super(iterator, type, index, data, path);
+        this.parent = parent;
+    }
+}
+/** Lightweight accessor wrapper. */
+class GLTFAccessorIterator extends GLTFObjectIterator {
+    /** Resolve the accessor's buffer view. */
+    get bufferView() {
+        return this.data.bufferView === undefined
+            ? undefined
+            : this.iterator.resolveBufferView(this.data.bufferView, `${this.path}.bufferView`);
+    }
+}
+/** Lightweight animation wrapper. */
+class GLTFAnimationIterator extends GLTFObjectIterator {
+    /** Iterate animation channels in source order. */
+    get channels() {
+        return iterateValues(this.data.channels, (channel, channelIndex) => this.iterator.getOrCreateNested(channel, () => new GLTFAnimationChannelIterator(this.iterator, 'animationChannel', channelIndex, channel, `${this.path}.channels[${channelIndex}]`, this)));
+    }
+    /** Iterate animation samplers in source order. */
+    get samplers() {
+        return iterateValues(this.data.samplers, (sampler, samplerIndex) => this.iterator.getOrCreateNested(sampler, () => new GLTFAnimationSamplerIterator(this.iterator, 'animationSampler', samplerIndex, sampler, `${this.path}.samplers[${samplerIndex}]`, this)));
+    }
+}
+/** Lightweight animation channel wrapper. */
+class GLTFAnimationChannelIterator extends GLTFNestedObjectIterator {
+    /** Resolve the animation-local sampler. */
+    get sampler() {
+        const samplers = this.parent.data.samplers;
+        const sampler = samplers[this.data.sampler];
+        if (!sampler) {
+            throw new Error(`Invalid glTF reference at ${this.path}.sampler: animation sampler index ${this.data.sampler} is out of range`);
+        }
+        return this.iterator.getOrCreateNested(sampler, () => new GLTFAnimationSamplerIterator(this.iterator, 'animationSampler', this.data.sampler, sampler, `${this.parent.path}.samplers[${this.data.sampler}]`, this.parent));
+    }
+    /** Return the channel target wrapper. */
+    get target() {
+        return this.iterator.getOrCreateNested(this.data.target, () => new GLTFAnimationChannelTargetIterator(this.iterator, 'animationChannelTarget', 0, this.data.target, `${this.path}.target`, this));
+    }
+}
+/** Lightweight animation channel target wrapper. */
+class GLTFAnimationChannelTargetIterator extends GLTFNestedObjectIterator {
+    /** Resolve the target node when one is specified. */
+    get node() {
+        return this.data.node === undefined
+            ? undefined
+            : this.iterator.resolveNode(this.data.node, `${this.path}.node`);
+    }
+}
+/** Lightweight animation sampler wrapper. */
+class GLTFAnimationSamplerIterator extends GLTFNestedObjectIterator {
+    /** Resolve the sampler input accessor. */
+    get input() {
+        return this.iterator.resolveAccessor(this.data.input, `${this.path}.input`);
+    }
+    /** Resolve the sampler output accessor. */
+    get output() {
+        return this.iterator.resolveAccessor(this.data.output, `${this.path}.output`);
+    }
+}
+/** Lightweight buffer wrapper. */
+class GLTFBufferIterator extends GLTFObjectIterator {
+    /** Return the loaded byte range parallel to this JSON buffer, when available. */
+    get loadedBuffer() {
+        return this.gltf.buffers[this.index];
+    }
+}
+/** Lightweight buffer-view wrapper. */
+class GLTFBufferViewIterator extends GLTFObjectIterator {
+    /** Resolve the backing JSON buffer. */
+    get buffer() {
+        return this.iterator.resolveBuffer(this.data.buffer, `${this.path}.buffer`);
+    }
+    /** Return a byte view over the loaded buffer-view range. */
+    get loadedBufferView() {
+        const loadedBuffer = this.buffer.loadedBuffer;
+        if (!loadedBuffer) {
+            return undefined;
+        }
+        const byteOffset = loadedBuffer.byteOffset + (this.data.byteOffset || 0);
+        return new Uint8Array(loadedBuffer.arrayBuffer, byteOffset, this.data.byteLength);
+    }
+}
+/** Lightweight camera wrapper. */
+class GLTFCameraIterator extends GLTFObjectIterator {
+}
+/** Lightweight external-asset wrapper for draft glTF 2.1. */
+class GLTFExternalAssetIterator extends GLTFObjectIterator {
+    /** Resolve the file containing the external glTF asset. */
+    get file() {
+        return this.iterator.resolveFile(this.data.file, `${this.path}.file`);
+    }
+    /** Return the parsed external glTF loaded parallel to this definition. */
+    get loadedAsset() {
+        return this.gltf.externalAssets?.[this.index];
+    }
+}
+/** Lightweight file wrapper for draft glTF 2.1. */
+class GLTFFileIterator extends GLTFObjectIterator {
+    /** Resolve the optional buffer view containing this file. */
+    get bufferView() {
+        return this.data.bufferView === undefined
+            ? undefined
+            : this.iterator.resolveBufferView(this.data.bufferView, `${this.path}.bufferView`);
+    }
+    /** Return the resolved file loaded parallel to this definition. */
+    get loadedFile() {
+        return this.gltf.files?.[this.index];
+    }
+}
+/** Lightweight image wrapper. */
+class GLTFImageIterator extends GLTFObjectIterator {
+    /** Resolve the optional buffer view containing this image. */
+    get bufferView() {
+        return this.data.bufferView === undefined
+            ? undefined
+            : this.iterator.resolveBufferView(this.data.bufferView, `${this.path}.bufferView`);
+    }
+    /** Return the decoded image loaded parallel to this definition. */
+    get loadedImage() {
+        return this.gltf.images?.[this.index];
+    }
+}
+/** Lightweight material wrapper. */
+class GLTFMaterialIterator extends GLTFObjectIterator {
+    /** Resolve the base-color texture info. */
+    get baseColorTexture() {
+        return this.getTextureInfo(this.data.pbrMetallicRoughness?.baseColorTexture, 0, 'pbrMetallicRoughness.baseColorTexture');
+    }
+    /** Resolve the metallic-roughness texture info. */
+    get metallicRoughnessTexture() {
+        return this.getTextureInfo(this.data.pbrMetallicRoughness?.metallicRoughnessTexture, 1, 'pbrMetallicRoughness.metallicRoughnessTexture');
+    }
+    /** Resolve the normal texture info. */
+    get normalTexture() {
+        return this.getTextureInfo(this.data.normalTexture, 2, 'normalTexture');
+    }
+    /** Resolve the occlusion texture info. */
+    get occlusionTexture() {
+        return this.getTextureInfo(this.data.occlusionTexture, 3, 'occlusionTexture');
+    }
+    /** Resolve the emissive texture info. */
+    get emissiveTexture() {
+        return this.getTextureInfo(this.data.emissiveTexture, 4, 'emissiveTexture');
+    }
+    /** Resolve standard texture-info properties in their schema order. */
+    get textures() {
+        const textureInfos = [
+            this.baseColorTexture,
+            this.metallicRoughnessTexture,
+            this.normalTexture,
+            this.occlusionTexture,
+            this.emissiveTexture
+        ].filter((textureInfo) => Boolean(textureInfo));
+        return textureInfos.values();
+    }
+    /** Wrap one optional standard material texture-info property. */
+    getTextureInfo(textureInfo, index, propertyPath) {
+        return textureInfo
+            ? this.iterator.getOrCreateNested(textureInfo, () => new GLTFTextureInfoIterator(this.iterator, 'textureInfo', index, textureInfo, `${this.path}.${propertyPath}`, this))
+            : undefined;
+    }
+}
+/** Lightweight texture-info wrapper nested in a material. */
+class GLTFTextureInfoIterator extends GLTFNestedObjectIterator {
+    /** Resolve the texture referenced by the raw texture-info `index` field. */
+    get texture() {
+        return this.iterator.resolveTexture(this.data.index, `${this.path}.index`);
+    }
+}
+/** Lightweight mesh wrapper. */
+class GLTFMeshIterator extends GLTFObjectIterator {
+    /** Iterate mesh primitives in source order. */
+    get primitives() {
+        return iterateValues(this.data.primitives, (primitive, primitiveIndex) => this.iterator.getOrCreateNested(primitive, () => new GLTFMeshPrimitiveIterator(this.iterator, 'primitive', primitiveIndex, primitive, `${this.path}.primitives[${primitiveIndex}]`, this)));
+    }
+}
+/** Lightweight mesh primitive wrapper. */
+class GLTFMeshPrimitiveIterator extends GLTFNestedObjectIterator {
+    /** Resolve every vertex attribute accessor by semantic name. */
+    get attributes() {
+        return new Map(Object.entries(this.data.attributes).map(([attributeName, accessorIndex]) => [
+            attributeName,
+            this.iterator.resolveAccessor(accessorIndex, `${this.path}.attributes.${attributeName}`)
+        ]));
+    }
+    /** Resolve the optional index accessor. */
+    get indices() {
+        return this.data.indices === undefined
+            ? undefined
+            : this.iterator.resolveAccessor(this.data.indices, `${this.path}.indices`);
+    }
+    /** Resolve the optional material. */
+    get material() {
+        return this.data.material === undefined
+            ? undefined
+            : this.iterator.resolveMaterial(this.data.material, `${this.path}.material`);
+    }
+    /** Resolve morph-target attribute accessors without rewriting target dictionaries. */
+    get targets() {
+        return (this.data.targets || []).map((target, targetIndex) => new Map(Object.entries(target).map(([attributeName, accessorIndex]) => [
+            attributeName,
+            this.iterator.resolveAccessor(accessorIndex, `${this.path}.targets[${targetIndex}].${attributeName}`)
+        ])));
+    }
+}
+/** Lightweight node wrapper. */
+class GLTFNodeIterator extends GLTFObjectIterator {
+    /** Resolve the optional camera. */
+    get camera() {
+        return this.data.camera === undefined
+            ? undefined
+            : this.iterator.resolveCamera(this.data.camera, `${this.path}.camera`);
+    }
+    /** Iterate resolved child nodes in source order. */
+    get children() {
+        return iterateValues(this.data.children || [], (childNodeIndex, childIndex) => this.iterator.resolveNode(childNodeIndex, `${this.path}.children[${childIndex}]`));
+    }
+    /** Resolve the optional skin. */
+    get skin() {
+        return this.data.skin === undefined
+            ? undefined
+            : this.iterator.resolveSkin(this.data.skin, `${this.path}.skin`);
+    }
+    /** Resolve the optional mesh definition. */
+    get mesh() {
+        return this.data.mesh === undefined
+            ? undefined
+            : this.iterator.resolveMesh(this.data.mesh, `${this.path}.mesh`);
+    }
+    /** Resolve the optional draft glTF 2.1 external asset. */
+    get externalAsset() {
+        return this.data.externalAsset === undefined
+            ? undefined
+            : this.iterator.resolveExternalAsset(this.data.externalAsset, `${this.path}.externalAsset`);
+    }
+}
+/** Lightweight texture sampler wrapper. */
+class GLTFSamplerIterator extends GLTFObjectIterator {
+}
+/** Lightweight scene wrapper. */
+class GLTFSceneIterator extends GLTFObjectIterator {
+    /** Iterate resolved scene root nodes in source order. */
+    get nodes() {
+        return iterateValues(this.data.nodes || [], (nodeIndex, sceneNodeIndex) => this.iterator.resolveNode(nodeIndex, `${this.path}.nodes[${sceneNodeIndex}]`));
+    }
+}
+/** Lightweight skin wrapper. */
+class GLTFSkinIterator extends GLTFObjectIterator {
+    /** Resolve the optional inverse-bind-matrix accessor. */
+    get inverseBindMatrices() {
+        return this.data.inverseBindMatrices === undefined
+            ? undefined
+            : this.iterator.resolveAccessor(this.data.inverseBindMatrices, `${this.path}.inverseBindMatrices`);
+    }
+    /** Resolve the optional skeleton root node. */
+    get skeleton() {
+        return this.data.skeleton === undefined
+            ? undefined
+            : this.iterator.resolveNode(this.data.skeleton, `${this.path}.skeleton`);
+    }
+    /** Iterate resolved joint nodes in source order. */
+    get joints() {
+        return iterateValues(this.data.joints, (jointNodeIndex, jointIndex) => this.iterator.resolveNode(jointNodeIndex, `${this.path}.joints[${jointIndex}]`));
+    }
+}
+/** Lightweight texture wrapper. */
+class GLTFTextureIterator extends GLTFObjectIterator {
+    /** Resolve the optional sampler. */
+    get sampler() {
+        return this.data.sampler === undefined
+            ? undefined
+            : this.iterator.resolveSampler(this.data.sampler, `${this.path}.sampler`);
+    }
+    /** Resolve the optional source image. */
+    get source() {
+        return this.data.source === undefined
+            ? undefined
+            : this.iterator.resolveImage(this.data.source, `${this.path}.source`);
+    }
+}
+/**
+ * Traverse and transform raw glTF data through lazy, identity-preserving object wrappers.
+ *
+ * The iterator never clones, links, normalizes, or otherwise postprocesses its input. Wrapper
+ * `data` fields are the original mutable JSON objects so extension handlers can transform them in
+ * place while using typed reference getters for navigation.
+ */
+export class GLTFIterator {
+    /** Original glTF container traversed by this iterator. */
+    gltf;
+    /** Cached wrapper for each raw source object. */
+    objectCache = new WeakMap();
+    /** Cached lazy reference facades keyed by their source wrapper. */
+    referencesCache = new WeakMap();
+    /** Create an iterator over an existing parsed glTF container. */
+    constructor(gltf) {
+        this.gltf = gltf;
+    }
+    /** Exact unmodified glTF JSON root. */
+    get data() {
+        return this.gltf.json;
+    }
+    /** Return the loaded bytes addressed by a raw bufferView index. */
+    getTypedArrayForBufferView(bufferViewIndex) {
+        return getBufferViewTypedArray(this.data, this.gltf.buffers, bufferViewIndex);
+    }
+    /** Return the loaded typed values addressed by a raw accessor index or decoded accessor. */
+    getTypedArrayForAccessor(accessor) {
+        return getAccessorTypedArray(this.data, this.gltf.buffers, accessor);
+    }
+    /** Return the loaded bytes addressed by a raw image index. */
+    getTypedArrayForImageData(imageIndex) {
+        return getImageTypedArray(this.data, this.gltf.buffers, imageIndex);
+    }
+    /** Return the loaded buffer companion for a raw buffer definition. */
+    getLoadedBuffer(buffer) {
+        const metadata = this.getMetadata(buffer);
+        return this.gltf.buffers[metadata.index];
+    }
+    /** Return the loaded byte range for a raw buffer-view definition. */
+    getLoadedBufferView(bufferView) {
+        const buffer = this.getReferences(bufferView).buffer;
+        const loadedBuffer = this.getLoadedBuffer(buffer);
+        if (!loadedBuffer) {
+            return undefined;
+        }
+        const byteOffset = loadedBuffer.byteOffset + (bufferView.byteOffset || 0);
+        return new Uint8Array(loadedBuffer.arrayBuffer, byteOffset, bufferView.byteLength);
+    }
+    /** Return the loaded image companion for a raw image definition. */
+    getLoadedImage(image) {
+        return this.gltf.images?.[this.getMetadata(image).index];
+    }
+    /** Return the loaded file companion for a raw file definition. */
+    getLoadedFile(file) {
+        return this.gltf.files?.[this.getMetadata(file).index];
+    }
+    /** Return the loaded asset companion for a raw external-asset definition. */
+    getLoadedExternalAsset(externalAsset) {
+        return this.gltf.externalAssets?.[this.getMetadata(externalAsset).index];
+    }
+    /** Append loaded bytes and a raw buffer definition, returning the new buffer index. */
+    addBuffer(array) {
+        const arrayBuffer = array.buffer.slice(array.byteOffset, array.byteOffset + array.byteLength);
+        this.gltf.buffers.push({ arrayBuffer, byteOffset: 0, byteLength: array.byteLength });
+        this.data.buffers ||= [];
+        this.data.buffers.push({ byteLength: array.byteLength });
+        return this.data.buffers.length - 1;
+    }
+    /** Append a raw bufferView definition and return its index. */
+    addBufferView(bufferIndex, byteLength, byteOffset = 0) {
+        this.data.bufferViews ||= [];
+        this.data.bufferViews.push({ buffer: bufferIndex, byteOffset, byteLength });
+        return this.data.bufferViews.length - 1;
+    }
+    /** Append a raw accessor definition and return its index. */
+    addAccessor(bufferViewIndex, accessor) {
+        this.data.accessors ||= [];
+        this.data.accessors.push({
+            bufferView: bufferViewIndex,
+            type: getAccessorTypeFromSize(accessor.size),
+            componentType: accessor.componentType,
+            count: accessor.count,
+            min: accessor.min,
+            max: accessor.max
+        });
+        return this.data.accessors.length - 1;
+    }
+    getReferences(object) {
+        const cachedReferences = this.referencesCache.get(object);
+        if (cachedReferences) {
+            return cachedReferences;
+        }
+        const objectIterator = this.getObjectIterator(object);
+        const references = createReferences(objectIterator);
+        this.referencesCache.set(object, references);
+        return references;
+    }
+    /** Return iterator-owned metadata for a raw glTF object. */
+    getMetadata(object) {
+        const objectIterator = this.getObjectIterator(object);
+        const parent = objectIterator instanceof GLTFNestedObjectIterator ? objectIterator.parent.data : undefined;
+        return {
+            gltf: this.gltf,
+            type: objectIterator.type,
+            index: objectIterator.index,
+            parent,
+            path: objectIterator.path
+        };
+    }
+    /** Resolve the default scene. */
+    get scene() {
+        return this.data.scene === undefined
+            ? undefined
+            : this.resolveScene(this.data.scene, 'scene').data;
+    }
+    /** Resolve the optional draft glTF 2.1 thumbnail image. */
+    get thumbnail() {
+        return this.data.asset.thumbnail === undefined
+            ? undefined
+            : this.resolveImage(this.data.asset.thumbnail, 'asset.thumbnail').data;
+    }
+    /** Iterate raw accessors in source order. */
+    get accessors() {
+        return this.iterateCollectionData('accessor');
+    }
+    /** Iterate raw animations in source order. */
+    get animations() {
+        return this.iterateCollectionData('animation');
+    }
+    /** Iterate raw buffers in source order. */
+    get buffers() {
+        return this.iterateCollectionData('buffer');
+    }
+    /** Iterate raw buffer views in source order. */
+    get bufferViews() {
+        return this.iterateCollectionData('bufferView');
+    }
+    /** Iterate raw cameras in source order. */
+    get cameras() {
+        return this.iterateCollectionData('camera');
+    }
+    /** Iterate raw draft glTF 2.1 external assets in source order. */
+    get externalAssets() {
+        return this.iterateCollectionData('externalAsset');
+    }
+    /** Iterate raw draft glTF 2.1 files in source order. */
+    get files() {
+        return this.iterateCollectionData('file');
+    }
+    /** Iterate raw images in source order. */
+    get images() {
+        return this.iterateCollectionData('image');
+    }
+    /** Iterate raw materials in source order. */
+    get materials() {
+        return this.iterateCollectionData('material');
+    }
+    /** Iterate raw mesh definitions in source order. */
+    get meshes() {
+        return this.iterateCollectionData('mesh');
+    }
+    /** Iterate raw nodes in source order. */
+    get nodes() {
+        return this.iterateCollectionData('node');
+    }
+    /** Iterate raw texture samplers in source order. */
+    get samplers() {
+        return this.iterateCollectionData('sampler');
+    }
+    /** Iterate raw scenes in source order. */
+    get scenes() {
+        return this.iterateCollectionData('scene');
+    }
+    /** Iterate raw skins in source order. */
+    get skins() {
+        return this.iterateCollectionData('skin');
+    }
+    /** Iterate raw textures in source order. */
+    get textures() {
+        return this.iterateCollectionData('texture');
+    }
+    /** Return whether an extension is declared used or required. */
+    hasExtension(extensionName) {
+        return (Boolean(this.data.extensionsUsed?.includes(extensionName)) ||
+            Boolean(this.data.extensionsRequired?.includes(extensionName)));
+    }
+    /** Return whether an extension is declared required. */
+    isExtensionRequired(extensionName) {
+        return Boolean(this.data.extensionsRequired?.includes(extensionName));
+    }
+    getExtension(objectOrExtensionName, objectExtensionName) {
+        const data = typeof objectOrExtensionName === 'string' ? this.data : objectOrExtensionName;
+        const extensionName = typeof objectOrExtensionName === 'string' ? objectOrExtensionName : objectExtensionName;
+        return data.extensions?.[extensionName];
+    }
+    setExtension(objectOrExtensionName, extensionNameOrExtension, extensionOrRequired) {
+        const isRootExtension = typeof objectOrExtensionName === 'string';
+        const data = isRootExtension ? this.data : objectOrExtensionName;
+        const extensionName = isRootExtension
+            ? objectOrExtensionName
+            : extensionNameOrExtension;
+        const extension = isRootExtension
+            ? extensionNameOrExtension
+            : extensionOrRequired;
+        const required = isRootExtension ? Boolean(extensionOrRequired) : false;
+        data.extensions ||= {};
+        data.extensions[extensionName] = extension;
+        this.registerUsedExtension(extensionName);
+        if (required) {
+            this.registerRequiredExtension(extensionName);
+        }
+    }
+    /** Register an extension in `extensionsUsed`. */
+    registerUsedExtension(extensionName) {
+        this.data.extensionsUsed ||= [];
+        if (!this.data.extensionsUsed.includes(extensionName)) {
+            this.data.extensionsUsed.push(extensionName);
+        }
+    }
+    /** Register an extension in both `extensionsUsed` and `extensionsRequired`. */
+    registerRequiredExtension(extensionName) {
+        this.registerUsedExtension(extensionName);
+        this.data.extensionsRequired ||= [];
+        if (!this.data.extensionsRequired.includes(extensionName)) {
+            this.data.extensionsRequired.push(extensionName);
+        }
+    }
+    removeExtension(objectOrExtensionName, objectExtensionName) {
+        const isRootExtension = typeof objectOrExtensionName === 'string';
+        const data = isRootExtension ? this.data : objectOrExtensionName;
+        const extensionName = isRootExtension ? objectOrExtensionName : objectExtensionName;
+        if (data.extensions?.[extensionName] !== undefined) {
+            this.recordRemovedExtension(extensionName);
+            delete data.extensions[extensionName];
+        }
+        if (isRootExtension) {
+            removeString(this.data.extensionsUsed, extensionName);
+            removeString(this.data.extensionsRequired, extensionName);
+        }
+    }
+    /** Record that an extension payload was consumed by a transformation. */
+    recordRemovedExtension(extensionName) {
+        const json = this.data;
+        json.extensionsRemoved ||= [];
+        if (!json.extensionsRemoved.includes(extensionName)) {
+            json.extensionsRemoved.push(extensionName);
+        }
+    }
+    /** Resolve an accessor reference. */
+    resolveAccessor(index, sourcePath) {
+        return this.resolveCollectionObject('accessor', index, sourcePath);
+    }
+    /** Resolve a buffer reference. */
+    resolveBuffer(index, sourcePath) {
+        return this.resolveCollectionObject('buffer', index, sourcePath);
+    }
+    /** Resolve a buffer-view reference. */
+    resolveBufferView(index, sourcePath) {
+        return this.resolveCollectionObject('bufferView', index, sourcePath);
+    }
+    /** Resolve a camera reference. */
+    resolveCamera(index, sourcePath) {
+        return this.resolveCollectionObject('camera', index, sourcePath);
+    }
+    /** Resolve a draft external-asset reference. */
+    resolveExternalAsset(index, sourcePath) {
+        return this.resolveCollectionObject('externalAsset', index, sourcePath);
+    }
+    /** Resolve a draft file reference. */
+    resolveFile(index, sourcePath) {
+        return this.resolveCollectionObject('file', index, sourcePath);
+    }
+    /** Resolve an image reference. */
+    resolveImage(index, sourcePath) {
+        return this.resolveCollectionObject('image', index, sourcePath);
+    }
+    /** Resolve a material reference. */
+    resolveMaterial(index, sourcePath) {
+        return this.resolveCollectionObject('material', index, sourcePath);
+    }
+    /** Resolve a mesh reference. */
+    resolveMesh(index, sourcePath) {
+        return this.resolveCollectionObject('mesh', index, sourcePath);
+    }
+    /** Resolve a node reference. */
+    resolveNode(index, sourcePath) {
+        return this.resolveCollectionObject('node', index, sourcePath);
+    }
+    /** Resolve a sampler reference. */
+    resolveSampler(index, sourcePath) {
+        return this.resolveCollectionObject('sampler', index, sourcePath);
+    }
+    /** Resolve a scene reference. */
+    resolveScene(index, sourcePath) {
+        return this.resolveCollectionObject('scene', index, sourcePath);
+    }
+    /** Resolve a skin reference. */
+    resolveSkin(index, sourcePath) {
+        return this.resolveCollectionObject('skin', index, sourcePath);
+    }
+    /** Resolve a texture reference. */
+    resolveTexture(index, sourcePath) {
+        return this.resolveCollectionObject('texture', index, sourcePath);
+    }
+    /** Return a cached nested wrapper or create it once. */
+    getOrCreateNested(data, createIterator) {
+        return this.getOrCreate(data, createIterator);
+    }
+    /** Iterate one top-level glTF collection lazily. */
+    iterateCollection(type) {
+        const values = this.getCollection(type);
+        return iterateValues(values, (_, index) => this.resolveCollectionObject(type, index, type));
+    }
+    /** Iterate exact raw objects from one top-level glTF collection. */
+    iterateCollectionData(type) {
+        return (function* iterateRawObjects(iterator) {
+            for (const objectIterator of iterator.iterateCollection(type)) {
+                yield objectIterator.data;
+            }
+        })(this);
+    }
+    /** Return the registered internal context for a raw glTF object. */
+    getObjectIterator(object) {
+        const objectIterator = this.objectCache.get(object);
+        if (!objectIterator) {
+            throw new Error('glTF object is not registered with this iterator');
+        }
+        return objectIterator;
+    }
+    /** Resolve and cache one top-level collection object. */
+    resolveCollectionObject(type, index, sourcePath) {
+        const values = this.getCollection(type);
+        const data = values[index];
+        if (!data) {
+            throw new Error(`Invalid glTF reference at ${sourcePath}: ${type} index ${index} is out of range`);
+        }
+        return this.getOrCreate(data, () => this.createCollectionObject(type, index, data));
+    }
+    /** Return the raw array corresponding to a top-level wrapper type. */
+    getCollection(type) {
+        switch (type) {
+            case 'accessor':
+                return this.data.accessors || [];
+            case 'animation':
+                return this.data.animations || [];
+            case 'buffer':
+                return this.data.buffers || [];
+            case 'bufferView':
+                return this.data.bufferViews || [];
+            case 'camera':
+                return this.data.cameras || [];
+            case 'externalAsset':
+                return this.data.externalAssets || [];
+            case 'file':
+                return this.data.files || [];
+            case 'image':
+                return this.data.images || [];
+            case 'material':
+                return this.data.materials || [];
+            case 'mesh':
+                return this.data.meshes || [];
+            case 'node':
+                return this.data.nodes || [];
+            case 'sampler':
+                return this.data.samplers || [];
+            case 'scene':
+                return this.data.scenes || [];
+            case 'skin':
+                return this.data.skins || [];
+            case 'texture':
+                return this.data.textures || [];
+        }
+    }
+    /** Create one correctly typed top-level wrapper. */
+    createCollectionObject(type, index, data) {
+        const path = `${getCollectionName(type)}[${index}]`;
+        switch (type) {
+            case 'accessor':
+                return new GLTFAccessorIterator(this, type, index, data, path);
+            case 'animation':
+                return new GLTFAnimationIterator(this, type, index, data, path);
+            case 'buffer':
+                return new GLTFBufferIterator(this, type, index, data, path);
+            case 'bufferView':
+                return new GLTFBufferViewIterator(this, type, index, data, path);
+            case 'camera':
+                return new GLTFCameraIterator(this, type, index, data, path);
+            case 'externalAsset':
+                return new GLTFExternalAssetIterator(this, type, index, data, path);
+            case 'file':
+                return new GLTFFileIterator(this, type, index, data, path);
+            case 'image':
+                return new GLTFImageIterator(this, type, index, data, path);
+            case 'material':
+                return new GLTFMaterialIterator(this, type, index, data, path);
+            case 'mesh':
+                return new GLTFMeshIterator(this, type, index, data, path);
+            case 'node':
+                return new GLTFNodeIterator(this, type, index, data, path);
+            case 'sampler':
+                return new GLTFSamplerIterator(this, type, index, data, path);
+            case 'scene':
+                return new GLTFSceneIterator(this, type, index, data, path);
+            case 'skin':
+                return new GLTFSkinIterator(this, type, index, data, path);
+            case 'texture':
+                return new GLTFTextureIterator(this, type, index, data, path);
+        }
+    }
+    /** Reuse a wrapper for the same raw source object. */
+    getOrCreate(data, createIterator) {
+        const cachedIterator = this.objectCache.get(data);
+        if (cachedIterator) {
+            return cachedIterator;
+        }
+        const iterator = createIterator();
+        this.objectCache.set(data, iterator);
+        return iterator;
+    }
+}
+/** Build a lazy relationship facade without resolving any links during construction. */
+function createReferences(object) {
+    switch (object.type) {
+        case 'accessor':
+            return {
+                get bufferView() {
+                    return object.bufferView?.data;
+                }
+            };
+        case 'animation':
+            return {
+                get channels() {
+                    return iterateObjectData(object.channels);
+                },
+                get samplers() {
+                    return iterateObjectData(object.samplers);
+                }
+            };
+        case 'animationChannel':
+            return {
+                get sampler() {
+                    return object.sampler.data;
+                },
+                get target() {
+                    return object.target.data;
+                }
+            };
+        case 'animationChannelTarget':
+            return {
+                get node() {
+                    return object.node?.data;
+                }
+            };
+        case 'animationSampler':
+            return {
+                get input() {
+                    return object.input.data;
+                },
+                get output() {
+                    return object.output.data;
+                }
+            };
+        case 'bufferView':
+            return {
+                get buffer() {
+                    return object.buffer.data;
+                }
+            };
+        case 'externalAsset':
+            return {
+                get file() {
+                    return object.file.data;
+                }
+            };
+        case 'file':
+        case 'image':
+            return {
+                get bufferView() {
+                    return object.bufferView?.data;
+                }
+            };
+        case 'material':
+            return {
+                get baseColorTexture() {
+                    return object.baseColorTexture?.data;
+                },
+                get metallicRoughnessTexture() {
+                    return object.metallicRoughnessTexture?.data;
+                },
+                get normalTexture() {
+                    return object.normalTexture?.data;
+                },
+                get occlusionTexture() {
+                    return object.occlusionTexture?.data;
+                },
+                get emissiveTexture() {
+                    return object.emissiveTexture?.data;
+                },
+                get textures() {
+                    return iterateObjectData(object.textures);
+                }
+            };
+        case 'textureInfo':
+            return {
+                get texture() {
+                    return object.texture.data;
+                }
+            };
+        case 'mesh':
+            return {
+                get primitives() {
+                    return iterateObjectData(object.primitives);
+                }
+            };
+        case 'primitive':
+            return {
+                get attributes() {
+                    return mapObjectData(object.attributes);
+                },
+                get indices() {
+                    return object.indices?.data;
+                },
+                get material() {
+                    return object.material?.data;
+                },
+                get targets() {
+                    return object.targets.map(mapObjectData);
+                }
+            };
+        case 'node':
+            return {
+                get camera() {
+                    return object.camera?.data;
+                },
+                get children() {
+                    return iterateObjectData(object.children);
+                },
+                get skin() {
+                    return object.skin?.data;
+                },
+                get mesh() {
+                    return object.mesh?.data;
+                },
+                get externalAsset() {
+                    return object.externalAsset?.data;
+                }
+            };
+        case 'scene':
+            return {
+                get nodes() {
+                    return iterateObjectData(object.nodes);
+                }
+            };
+        case 'skin':
+            return {
+                get inverseBindMatrices() {
+                    return object.inverseBindMatrices?.data;
+                },
+                get skeleton() {
+                    return object.skeleton?.data;
+                },
+                get joints() {
+                    return iterateObjectData(object.joints);
+                }
+            };
+        case 'texture':
+            return {
+                get sampler() {
+                    return object.sampler?.data;
+                },
+                get source() {
+                    return object.source?.data;
+                }
+            };
+        default:
+            return {};
+    }
+}
+/** Iterate raw array values without creating wrapper arrays. */
+function iterateValues(values, getIterator) {
+    return (function* iterate() {
+        for (let index = 0; index < values.length; index++) {
+            yield getIterator(values[index], index);
+        }
+    })();
+}
+/** Yield the exact raw object carried by each internal iterator context. */
+function iterateObjectData(objects) {
+    return (function* iterateRawData() {
+        for (const object of objects) {
+            yield object.data;
+        }
+    })();
+}
+/** Replace internal iterator contexts in a reference map with their exact raw objects. */
+function mapObjectData(objects) {
+    return new Map(Array.from(objects, ([name, object]) => [name, object.data]));
+}
+/** Return the JSON collection name for a wrapper type. */
+function getCollectionName(type) {
+    switch (type) {
+        case 'bufferView':
+            return 'bufferViews';
+        case 'externalAsset':
+            return 'externalAssets';
+        case 'mesh':
+            return 'meshes';
+        default:
+            return `${type}s`;
+    }
+}
+/** Remove every occurrence of a string from an optional array. */
+function removeString(values, value) {
+    if (!values) {
+        return;
+    }
+    for (let index = values.length - 1; index >= 0; index--) {
+        if (values[index] === value) {
+            values.splice(index, 1);
+        }
+    }
+}
+//# sourceMappingURL=gltf-iterator.js.map