@preference-sl/pref-viewer 2.11.0-beta.0 → 2.11.0-beta.1

package/src/gltf-resolver.js

@@ -0,0 +1,288 @@
+import { FileStorage } from "./file-storage.js";
+import { initDb, loadModel } from "./gltf-storage.js";
+
+/**
+ * GLTFResolver - Utility class for resolving, decoding, and preparing glTF/GLB assets from various sources.
+ *
+ * Responsibilities:
+ *  - Loads glTF/GLB assets from IndexedDB, direct URLs, or base64-encoded data.
+ *  - Decodes base64 data and determines file type (.gltf or .glb).
+ *  - Normalizes and replaces asset URIs with resolved URLs from FileStorage.
+ *  - Handles cache validation using asset size and timestamp to avoid unnecessary reloads.
+ *  - Provides methods for initializing storage, decoding assets, and preparing sources for viewer components.
+ *
+ * Usage:
+ *  - Instantiate: const resolver = new GLTFResolver();
+ *  - Prepare asset: await resolver.getSource(storage, currentSize, currentTimeStamp);
+ *
+ * Public Methods:
+ *  - getSource(storage, currentSize, currentTimeStamp): Resolves and prepares a glTF/GLB source for loading.
+ *
+ * Private Methods:
+ *  - #initializeStorage(db, table): Ensures IndexedDB store is initialized.
+ *  - #decodeBase64(base64): Decodes base64 data and determines file type.
+ *  - #isURLAbsolute(url): Checks if a URL is syntactically absolute.
+ *  - #saveAssetData(asset, index, parent, assetArray): Collects asset entries with external URIs.
+ *  - #replaceSceneURIAsync(assetContainerJSON, assetContainerURL): Replaces internal URIs in glTF JSON with resolved URLs.
+ *
+ * Notes:
+ *  - Designed for integration with PrefViewer and FileStorage.
+ *  - Follows the glTF 2.0 specification for asset structure and URI handling.
+ *  - All asset preparation is performed asynchronously to support large files and remote sources.
+ *  - See: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
+ */
+export default class GLTFResolver {
+    #fileStorage = null;
+
+    /**
+     * Creates a new GLTFResolver instance and initializes the FileStorage for asset management.
+     * @public
+     * @constructor
+     * @returns {GLTFResolver}
+     * @description
+     *   - Initializes an internal FileStorage instance with the database "PrefViewer" and object store "Files".
+     *   - Prepares the resolver for loading, decoding, and managing glTF/GLB assets from various sources.
+     */
+    constructor() {
+        this.#fileStorage = new FileStorage("PrefViewer", "Files");
+    }
+
+    /**
+     * Ensure the IndexedDB object store for GLTF/SVG storage is initialized.
+     * @private
+     * @param {string} db - Database name.
+     * @param {string} table - Object store name.
+     * @returns {Promise<void>}
+     * @description
+     * If a global PrefConfigurator.db already references the requested DB and table, no action is taken. Otherwise delegates to initDb to create/open the store.
+     */
+    async #initializeStorage(db, table) {
+        if (typeof window !== "undefined" && window.PrefConfigurator.db && window.PrefConfigurator.db.name === db && window.PrefConfigurator.db.objectStoreNames.contains(table)) {
+            return;
+        }
+        await initDb(db, table);
+    }
+
+    /**
+     * Decodes a base64-encoded glTF or GLB data URI or string into a Blob and determines its extension.
+     * If the decoded content is valid JSON, assumes it is a .gltf file; otherwise, treats it as .glb binary.
+     * @private
+     * @param {string} base64 - The base64-encoded data URI or string to decode.
+     * @returns {{blob: Blob|null, extension: string|null, size: number}}
+     *   - blob: The decoded Blob object, or null if decoding fails.
+     *   - extension: ".gltf" for JSON content, ".glb" for binary, or null if decoding fails.
+     *   - size: The length of the raw base64 payload.
+     * @description
+     *   - Attempts to decode the base64 payload and parse it as JSON.
+     *   - If parsing succeeds, returns a Blob with MIME type "model/gltf+json" and extension ".gltf".
+     *   - If parsing fails, returns a Blob with MIME type "model/gltf-binary" and extension ".glb".
+     *   - If decoding fails, returns nulls for blob and extension.
+     */
+    #decodeBase64(base64) {
+        const [, payload] = base64.split(",");
+        const raw = payload || base64;
+        let decoded = "";
+        let blob = null;
+        let extension = null;
+        let size = raw.length;
+        try {
+            decoded = atob(raw);
+        } catch {
+            return { blob, extension, size };
+        }
+        let isJson = false;
+        try {
+            JSON.parse(decoded);
+            isJson = true;
+        } catch {}
+        extension = isJson ? ".gltf" : ".glb";
+        const type = isJson ? "model/gltf+json" : "model/gltf-binary";
+        const array = Uint8Array.from(decoded, (c) => c.charCodeAt(0));
+        blob = new Blob([array], { type });
+        return { blob, extension, size };
+    }
+
+    /**
+     * Check whether a value is a syntactically absolute URL.
+     * @private
+     * @param {string} url - Value to test.
+     * @returns {boolean} True when `url` is a string that can be parsed by the global URL constructor (i.e. a syntactically absolute URL); false otherwise.
+     * @description
+     *  - Returns false for non-string inputs.
+     *  - Uses the browser's URL parser, so protocol-relative URLs ("//host/...") and relative paths are considered non-absolute.
+     *  - This is a syntactic check only — it does not perform network requests or validate reachability/CORS.
+     */
+    #isURLAbsolute(url) {
+        if (typeof url !== "string") {
+            return false;
+        }
+        try {
+            new URL(url);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Collects asset entries that have an external URI (non-data URI) and stores a normalized absolute or relative-resolved URI for later replacement.
+     * @private
+     * @param {Object} asset - glTF asset entry (an element of buffers[] or images[]).
+     * @param {number} index - Index of the asset within its parent array.
+     * @param {Array} parent - Reference to the parent array (buffers or images).
+     * @param {string} sceneURLBase - Base path used to resolve relative URIs.
+     * @param {Array} assetArray - Array to collect asset records for later URI replacement.
+     * @returns {void}
+     * @description
+     *   - Only assets with a non-data URI are collected.
+     *   - The pushed record has the shape: { parent: <array>, index: <number>, uri: <string> }.
+     *   - The URI is normalized (backslashes converted to forward slashes) and, if relative, is prefixed with sceneURLBase if available.
+     */
+    #saveAssetData(asset, index, parent, sceneURLBase, assetArray) {
+        if (asset.uri && !asset.uri.startsWith("data:")) {
+            const assetData = {
+                parent: parent,
+                index: index,
+                uri: `${!this.#isURLAbsolute(asset.uri) && sceneURLBase ? sceneURLBase : ""}${asset.uri}`.replace(/\\\\|\\|\/\\/g, "/"),
+            };
+            assetArray.push(assetData);
+        }
+    }
+
+    /**
+     * Replace internal URIs in a glTF AssetContainer JSON with URLs pointing to files stored in IndexedDB.
+     * @private
+     * @param {JSON} assetContainerJSON - AssetContainer in glTF (JSON) (modified in-place).
+     * @param {URL} [assetContainerURL] - Optional URL of the AssetContainer. Used as the base path to resolve relative URIs.
+     * @returns {Promise<void>} Resolves when all applicable URIs have been resolved/replaced.
+     * @description
+     * - When provided, assetContainerURL is used as the base path for other scene files (binary buffers and all images).
+     *   If not provided (null/undefined), it is because it is the assetContainer of the model or materials whose URIs are absolute.
+     * - According to the glTF 2.0 spec, only items inside the "buffers" and "images" arrays may have a "uri" property.
+     * - Data URIs (embedded base64) are ignored and left unchanged.
+     * - Matching asset URIs are normalized (backslashes converted to forward slashes) and passed to the FileStorage layer
+     *   to obtain a usable URL (object URL or cached URL).
+     * - The function performs replacements in parallel and waits for all lookups to complete.
+     * - The JSON is updated in-place with the resolved URLs.
+     * @see {@link https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#uris|glTF™ 2.0 Specification - URIs}
+     */
+    async #replaceSceneURIAsync(assetContainerJSON, assetContainerURL) {
+        if (!assetContainerJSON) {
+            return;
+        }
+
+        let sceneURLBase = assetContainerURL;
+
+        if (typeof assetContainerURL === "string") {
+            const lastIndexOfSlash = assetContainerURL.lastIndexOf("/");
+            if (lastIndexOfSlash !== -1) {
+                sceneURLBase = assetContainerURL.substring(0, lastIndexOfSlash + 1);
+            }
+        }
+
+        const arrayOfAssetsWithURI = [];
+        if (assetContainerJSON.buffers) {
+            assetContainerJSON.buffers.forEach((asset, index, array) => this.#saveAssetData(asset, index, array, sceneURLBase, arrayOfAssetsWithURI));
+        }
+        if (assetContainerJSON.images) {
+            assetContainerJSON.images.forEach((asset, index, array) => this.#saveAssetData(asset, index, array, sceneURLBase, arrayOfAssetsWithURI));
+        }
+
+        // Replace parallel URIs so that if files are not stored yet, they are downloaded in parallel
+        const promisesArray = arrayOfAssetsWithURI.map(async (asset) => {
+            const uri = await this.#fileStorage.getURL(asset.uri);
+            if (uri) {
+                asset.parent[asset.index].uri = uri;
+            }
+        });
+        await Promise.all(promisesArray);
+    }
+
+    /**
+     * Resolves and prepares a glTF/GLB source from various storage backends.
+     * Supports IndexedDB, direct URLs, and base64-encoded data.
+     * Handles cache validation using asset size and timestamp, and updates URIs for .gltf files as needed.
+     * @public
+     * @param {object} storage - Storage descriptor containing url, db, table, and id properties.
+     * @param {number|null} currentSize - The current cached size of the asset, or null if not cached.
+     * @param {string|null} currentTimeStamp - The current cached timestamp of the asset, or null if not cached.
+     * @returns {Promise<false|{source: File|string, size: number, timeStamp: string|null, extension: string}>}
+     *   - Resolves to false if no update is needed or on error.
+     *   - Resolves to an object containing the resolved source (File or data URI), size, timestamp, and extension if an update is required.
+     * @description
+     *   - If storage specifies IndexedDB (db, table, id), loads the asset from IndexedDB and checks for updates.
+     *   - If storage specifies a direct URL or base64 data, decodes and validates the asset.
+     *   - For .gltf files, replaces internal URIs with resolved URLs from FileStorage.
+     *   - Performs cache validation using size and timestamp to avoid unnecessary reloads.
+     *   - Returns the prepared source, size, timestamp, and extension for further processing.
+     */
+    async getSource(storage, currentSize, currentTimeStamp) {
+        let source = storage.url || null;
+        let newSize, newTimeStamp;
+        let pending = false;
+
+        if (storage.db && storage.table && storage.id) {
+            await this.#initializeStorage(storage.db, storage.table);
+            const object = await loadModel(storage.id, storage.table);
+            if (!object || !object.data || !object.timeStamp || !object.size) {
+                return false;
+            }
+            source = object.data;
+            if (object.timeStamp === currentTimeStamp) {
+                return false;
+            } else {
+                pending = true;
+                newSize = object.size;
+                newTimeStamp = object.timeStamp;
+            }
+        }
+
+        if (!source) {
+            return false;
+        }
+
+        let file = null;
+        let { blob, extension, size } = this.#decodeBase64(source);
+
+        if (blob && extension) {
+            if (extension === ".gltf") {
+                const assetContainerJSON = JSON.parse(await blob.text());
+                await this.#replaceSceneURIAsync(assetContainerJSON, source);
+                source = `data:${JSON.stringify(assetContainerJSON)}`;
+            } else {
+                file = new File([blob], `file${extension}`, {
+                    type: blob.type,
+                });
+            }
+            if (!pending) {
+                if (currentTimeStamp === null && currentSize === size) {
+                    return false;
+                } else {
+                    pending = true;
+                    newSize = size;
+                    newTimeStamp = null;
+                }
+            }
+        } else {
+            const extMatch = source.match(/\.(gltf|glb)(\?|#|$)/i);
+            extension = extMatch ? `.${extMatch[1].toLowerCase()}` : ".gltf";
+            let [fileSize, fileTimeStamp] = [await this.#fileStorage.getSize(source), await this.#fileStorage.getTimeStamp(source)];
+            if (currentSize === fileSize && currentTimeStamp === fileTimeStamp) {
+                return false;
+            } else {
+                pending = true;
+                newSize = fileSize;
+                newTimeStamp = fileTimeStamp;
+                if (extension === ".gltf") {
+                    const assetContainerBlob = await this.#fileStorage.getBlob(source);
+                    const assetContainerJSON = JSON.parse(await assetContainerBlob.text());
+                    await this.#replaceSceneURIAsync(assetContainerJSON, source);
+                    source = `data:${JSON.stringify(assetContainerJSON)}`;
+                } else {
+                    source = await this.#fileStorage.getURL(source);
+                }
+            }
+        }
+        return { source: file || source, size: newSize, timeStamp: newTimeStamp, extension: extension };
+    }
+}