@needle-tools/engine 4.8.7 → 4.8.8-next.857d744

package/src/engine-components/OrbitControls.ts

@@ -649,12 +649,12 @@ export class OrbitControls extends Behaviour implements ICameraController {
             if (this._lookTargetLerpActive) {
                 this._lookTargetLerp01 += this.context.time.deltaTime / this._lookTargetLerpDuration;
                 if (this._lookTargetLerp01 >= 1) {
-                    this._controls.target.copy(this._lookTargetEndPosition);
+                    this.lerpLookTarget(this._lookTargetEndPosition, this._lookTargetEndPosition, 1);
                     this._lookTargetLerpActive = false;
                     this.dispatchEvent(new CameraTargetReachedEvent(this, "lookat"));
                 } else {
                     const t = Mathf.easeInOutCubic(this._lookTargetLerp01);
-                    this._controls.target.lerpVectors(this._lookTargetStartPosition, this._lookTargetEndPosition, t);
+                    this.lerpLookTarget(this._lookTargetStartPosition, this._lookTargetEndPosition, t);
                 }
             }
 
@@ -729,7 +729,9 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
             // this._controls.zoomToCursor = this.zoomToCursor;
             if (!this.context.isInXR) {
-                if (!freeCam && this.lookAtConstraint?.locked) this.setLookTargetFromConstraint(0, this.lookAtConstraint01);
+                if (!freeCam && this.lookAtConstraint?.locked && !this._lookTargetLerpActive) {
+                    this.setLookTargetFromConstraint(0, this.lookAtConstraint01);
+                }
                 this._controls.update(this.context.time.deltaTime);
 
                 if (debug) {
@@ -910,7 +912,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
         }
 
         if (immediateOrDuration === true) {
-            this._controls.target.copy(this._lookTargetEndPosition);
+            this.lerpLookTarget(this._lookTargetEndPosition, this._lookTargetEndPosition, 1);
         }
         else {
             this._lookTargetLerpActive = true;
@@ -941,20 +943,18 @@ export class OrbitControls extends Behaviour implements ICameraController {
             const target = sources[index];
             if (target) {
                 target.getWorldPosition(this._lookTargetEndPosition);
-                this.lerpLookTarget(this._lookTargetEndPosition, t);
+                this.lerpLookTarget(this._controls.target, this._lookTargetEndPosition, t);
                 return true;
             }
         }
         return false;
     }
 
-    /** @deprecated use `controls.target.lerp(position, delta)` */
-    public lerpTarget(position: Vector3, delta: number) { return this.lerpLookTarget(position, delta); }
-
-    private lerpLookTarget(position: Vector3, delta: number) {
+    private lerpLookTarget(start: Vector3, position: Vector3, t: number) {
         if (!this._controls) return;
-        if (delta >= 1) this._controls.target.copy(position);
-        else this._controls.target.lerp(position, delta);
+        if (t >= 1) this._controls.target.copy(position);
+        else this._controls.target.lerpVectors(start, position, t);
+        if (this.lookAtConstraint) this.lookAtConstraint.setConstraintPosition(this._controls.target);
     }
 
     private setTargetFromRaycast(ray?: Ray, immediateOrDuration: number | boolean = false): boolean {
@@ -1063,7 +1063,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
             return;
         }
 
-        const verticalFov = options.fov || camera.fov;
+        const verticalFov = fov;
         const horizontalFov = 2 * Math.atan(Math.tan(verticalFov * Math.PI / 360 / 2) * camera.aspect) / Math.PI * 360;
         const fitHeightDistance = size.y / (2 * Math.atan(Math.PI * verticalFov / 360));
         const fitWidthDistance = size.x / (2 * Math.atan(Math.PI * horizontalFov / 360));
@@ -1161,16 +1161,19 @@ declare type FitCameraOptions = {
      * The objects to fit the camera to. If not provided the scene children will be used
      */
     objects?: Object3D[] | Object3D;
-    /** Fit offset: A factor to multiply the distance to the objects by
-     * @default 1.1
-     */
-    fitOffset?: number,
     /** If true the camera will move immediately to the new position, otherwise it will lerp 
      * @default false
      */
     immediate?: boolean,
+
     /** If set to "y" the camera will be centered in the y axis */
     centerCamera?: "none" | "y",
     cameraNearFar?: "keep" | "auto",
+
     fov?: number,
+
+    /** Fit offset: A factor to multiply the distance to the objects by
+     * @default 1.1
+     */
+    fitOffset?: number,
 }

package/src/engine-components/export/usdz/Extension.ts

@@ -21,5 +21,5 @@ export interface IUSDExporterExtension {
     onAfterBuildDocument?(context: USDZExporterContext);
     onExportObject?(object: Object3D, model: USDObject, context: USDZExporterContext);
     onAfterSerialize?(context: USDZExporterContext);
-    onAfterHierarchy?(context: USDZExporterContext, writer: USDWriter);
+    onAfterHierarchy?(context: USDZExporterContext, writer: USDWriter) : void | Promise<void>;
 }

package/src/engine-components/export/usdz/ThreeUSDZExporter.ts

@@ -1082,7 +1082,7 @@ async function parseDocument( context: USDZExporterContext, afterStageRoot: () =
 	Progress.end("export-usdz-xforms");
 
 	Progress.report("export-usdz", "invoke onAfterHierarchy");
-	invokeAll( context, 'onAfterHierarchy', writer );
+	await invokeAll( context, 'onAfterHierarchy', writer );
 
 	writer.closeBlock();
 	writer.closeBlock();

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -1,5 +1,5 @@
 import { NEEDLE_progressive } from "@needle-tools/gltf-progressive";
-import { Euler, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
+import { Euler, EventDispatcher, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { hasProLicense } from "../../../engine/engine_license.js";
@@ -29,6 +29,7 @@ import { USDZUIExtension } from "./extensions/USDZUI.js";
 import { USDZExporter as ThreeUSDZExporter } from "./ThreeUSDZExporter.js";
 import { disableObjectsAtStart, registerAnimatorsImplictly, registerAudioSourcesImplictly } from "./utils/animationutils.js";
 import { ensureQuicklookLinkIsCreated } from "./utils/quicklook.js";
+import { EventList } from "../../EventList.js";
 
 const debug = getParam("debugusdz");
 const debugUsdzPruning = getParam("debugusdzpruning");
@@ -71,6 +72,9 @@ export class CustomBranding {
  */
 export class USDZExporter extends Behaviour {
 
+    static readonly beforeExport = new EventList<{ exporter: USDZExporter }>();
+    static readonly afterExport = new EventList<{ exporter: USDZExporter }>();
+
     /**
      * Assign the object to export as USDZ file. If undefined or null, the whole scene will be exported.
      */
@@ -210,7 +214,7 @@ export class USDZExporter extends Behaviour {
      * Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
      * @returns a Promise<Blob> containing the USDZ file
      */
-    async exportAndOpen() : Promise<Blob | null> {
+    async exportAndOpen(): Promise<Blob | null> {
 
         let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
         name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
@@ -221,7 +225,7 @@ export class USDZExporter extends Behaviour {
         }
 
         if (!this.link) this.link = ensureQuicklookLinkIsCreated(this.context, DeviceUtilities.supportsQuickLookAR());
-        
+
         // ability to specify a custom USDZ file to be used instead of a dynamic one
         if (this.customUsdzFile) {
             if (debug) console.log("Exporting custom usdz", this.customUsdzFile)
@@ -234,14 +238,19 @@ export class USDZExporter extends Behaviour {
             return null;
         }
 
-        const blob = await this.export(this.objectToExport);
+        USDZExporter.beforeExport.invoke({ exporter: this });
+        const blob = await this.export(this.objectToExport)
+            .finally(() => {
+                USDZExporter.afterExport.invoke({ exporter: this });
+            });
+
         if (!blob) {
             console.error("USDZ generation failed. Please report a bug", this);
             return null;
         }
 
         if (debug) console.log("USDZ generation done. Downloading as " + name);
-        
+
         // TODO Potentially we have to detect QuickLook availability here,
         // and download the file instead. But browsers keep changing how they deal with non-user-initiated downloads...
         // https://webkit.org/blog/8421/viewing-augmented-reality-assets-in-safari-for-ios/#:~:text=inside%20the%20anchor.-,Feature%20Detection,-To%20detect%20support
@@ -364,7 +373,7 @@ export class USDZExporter extends Behaviour {
         if (this.interactive) {
             defaultExtensions.push(new BehaviorExtension());
             defaultExtensions.push(new AudioExtension());
-            
+
             // If physics are enabled, and there are any Rigidbody components in the scene,
             // add the PhysicsExtension to the default extensions.
             if (globalThis["NEEDLE_USE_RAPIER"]) {
@@ -632,13 +641,13 @@ export class USDZExporter extends Behaviour {
     private _rootPositionBeforeExport: Vector3 = new Vector3();
     private _rootRotationBeforeExport: Quaternion = new Quaternion();
     private _rootScaleBeforeExport: Vector3 = new Vector3();
-    
-    getARScaleAndTarget(): { scale: number, _invertForward: boolean, target: Object3D, sessionRoot: Object3D | null} {
-        if (!this.objectToExport) return { scale: 1, _invertForward: false, target: this.gameObject, sessionRoot: null};
+
+    getARScaleAndTarget(): { scale: number, _invertForward: boolean, target: Object3D, sessionRoot: Object3D | null } {
+        if (!this.objectToExport) return { scale: 1, _invertForward: false, target: this.gameObject, sessionRoot: null };
 
         const xr = GameObject.findObjectOfType(WebXR);
         let sessionRoot = GameObject.getComponentInParent(this.objectToExport, WebARSessionRoot);
-        if(!sessionRoot) sessionRoot = GameObject.getComponentInChildren(this.objectToExport, WebARSessionRoot);
+        if (!sessionRoot) sessionRoot = GameObject.getComponentInChildren(this.objectToExport, WebARSessionRoot);
 
         let arScale = 1;
         let _invertForward = false;
@@ -653,7 +662,7 @@ export class USDZExporter extends Behaviour {
             // eslint-disable-next-line deprecation/deprecation
             _invertForward = sessionRoot.invertForward;
         }
-        
+
         const scale = 1 / arScale;
         const result = { scale, _invertForward, target, sessionRoot: sessionRoot?.gameObject ?? null };
         return result;
@@ -699,7 +708,7 @@ export class USDZExporter extends Behaviour {
     private createQuicklookButton() {
         const buttoncontainer = WebXRButtonFactory.getOrCreate();
         const button = buttoncontainer.createQuicklookButton();
-        if(!button.parentNode) this.context.menu.appendChild(button);
+        if (!button.parentNode) this.context.menu.appendChild(button);
         return button;
     }
 }

package/src/engine-components/webxr/WebXRImageTracking.ts

@@ -1,17 +1,18 @@
-import { Matrix4, Object3D, Quaternion, Vector3 } from "three";
+import { ImageBitmapLoader, Matrix4, Object3D, Quaternion, Vector3 } from "three";
 import { Object3DEventMap } from "three";
 
 import { isDevEnvironment, showBalloonWarning } from "../../engine/debug/index.js";
 import { AssetReference } from "../../engine/engine_addressables.js";
 import { serializable } from "../../engine/engine_serialization.js";
 import { IGameObject } from "../../engine/engine_types.js";
-import { CircularBuffer, DeviceUtilities, getParam } from "../../engine/engine_utils.js";
+import { CircularBuffer, delay, DeviceUtilities, getParam } from "../../engine/engine_utils.js";
 import { type NeedleXREventArgs, NeedleXRSession } from "../../engine/xr/api.js";
 import { IUSDExporterExtension } from "../../engine-components/export/usdz/Extension.js";
 import { imageToCanvas, USDObject, USDWriter, USDZExporterContext } from "../../engine-components/export/usdz/ThreeUSDZExporter.js";
 import { USDZExporter } from "../../engine-components/export/usdz/USDZExporter.js";
 import { Behaviour, GameObject } from "../Component.js";
 import { Renderer } from "../Renderer.js";
+import { Context } from "../../engine/engine_context.js";
 
 // https://github.com/immersive-web/marker-tracking/blob/main/explainer.md
 
@@ -147,90 +148,122 @@ export class WebXRImageTrackingModel {
 
 class ImageTrackingExtension implements IUSDExporterExtension {
 
+
+
+    readonly isImageTrackingExtension = true;
     get extensionName() { return "image-tracking"; }
 
-    private filename: string;
-    private widthInMeters: number;
-    private imageData: Uint8Array;
 
-    constructor(filename: string, imageData: Uint8Array, widthInMeters: number) {
-        this.filename = filename;
-        this.imageData = imageData;
-        this.widthInMeters = widthInMeters;
+    constructor(private readonly exporter: USDZExporter, private readonly component: WebXRImageTracking) {
+        if (debug) console.log(this);
+        this.exporter.anchoringType = "image";
+    }
+
+    // set during export
+    private shouldExport: boolean = true;
+
+    private filename: string = "marker.png";
+    private imageModel: WebXRImageTrackingModel | null = null;
+
+    onBeforeBuildDocument(_context: USDZExporterContext) {
+
+        // check if this extension is the first image tracking extension in the list
+        // since iOS can only track one image at a time we only allow one image tracking extension to be active
+        // we have to determine this at the earlierst export callback
+        // all subsequent export callbacks should then check is shouldExport is set to true
+        // this should only be the case for exactly one extension
+        const index = this.exporter.extensions
+            .filter(e => {
+                const ext = (e as ImageTrackingExtension);
+                return ext.isImageTrackingExtension && ext.component.activeAndEnabled && ext.component.trackedImages?.length > 0;
+            })
+            .indexOf(this);
+        this.shouldExport = index === 0;
+        if (!this.shouldExport) return;
+
+        // Warn if more than one tracked image is used for USDZ; that's not supported at the moment.
+        if (this.component.trackedImages?.length > 1) {
+            if (debug || isDevEnvironment()) {
+                showBalloonWarning("USDZ: Only one tracked image is supported.");
+                console.warn("USDZ: Only one tracked image is supported. Will choose the first one in the trackedImages list");
+            }
+        }
     }
 
     onAfterHierarchy(_context: USDZExporterContext, writer: USDWriter) {
+        if (!this.shouldExport) return;
+
         const iOSVersion = DeviceUtilities.getiOSVersion();
         const majorVersion = iOSVersion ? parseInt(iOSVersion.split(".")[0]) : 18;
         const workaroundForFB16119331 = majorVersion >= 18;
         const multiplier = workaroundForFB16119331 ? 1 : 100;
         writer.beginBlock(`def Preliminary_ReferenceImage "AnchoringReferenceImage"`);
         writer.appendLine(`uniform asset image = @image_tracking/` + this.filename + `@`);
-        writer.appendLine(`uniform double physicalWidth = ` + (this.widthInMeters * multiplier).toFixed(8));
+        writer.appendLine(`uniform double physicalWidth = ` + (this.imageModel!.widthInMeters * multiplier).toFixed(8));
         writer.closeBlock();
+
     }
 
-    onBeforeBuildDocument(_context: USDZExporterContext) {
-        const imageTracking = GameObject.findObjectOfType(WebXRImageTracking);
-        if (!imageTracking || !imageTracking.trackedImages) return;
+    async onAfterSerialize(context: USDZExporterContext) {
+        if (!this.shouldExport) return;
 
-        // Warn if more than one tracked image is used for USDZ; that's not supported at the moment.
-        if (imageTracking.trackedImages.length > 1) 
-        {
-            if (isDevEnvironment()) showBalloonWarning("USDZ: Only one tracked image is supported.");
-            console.warn("USDZ: Only one tracked image is supported.");
-        }
-    }
+        const imageModel = this.imageModel;
+        const img = _imageElements.get(imageModel!.image!)!;
 
-    onAfterSerialize(context: USDZExporterContext) {
-        context.files['image_tracking/' + this.filename] = this.imageData;
+        const canvas = await imageToCanvas(img);
+        const blob = await canvas.convertToBlob({ type: 'image/png' });
+        const arrayBuffer = await blob.arrayBuffer();
+        context.files['image_tracking/' + this.filename] = new Uint8Array(arrayBuffer);
     }
 
     onExportObject(object: Object3D<Object3DEventMap>, model: USDObject, _context: USDZExporterContext) {
-        const imageTracking = GameObject.findObjectOfType(WebXRImageTracking);
-        if (!imageTracking || !imageTracking.trackedImages) return;
+        if (!this.shouldExport) return;
 
+        const imageTracking = this.component;
+        if (!imageTracking || !imageTracking.trackedImages?.length || !imageTracking.activeAndEnabled) return;
 
-        for (const trackedImage of imageTracking.trackedImages) {
-            if (trackedImage.object?.asset === object) {
-                const exporter = GameObject.findObjectOfType(USDZExporter);
-                if (!exporter) continue;
+        // we only care about the first image
+        const trackedImage = imageTracking.trackedImages[0];
 
-                const { scale, target } = exporter.getARScaleAndTarget();
+        if (trackedImage.object?.asset === object) {
+            this.imageModel = trackedImage;
 
-                // We have to reset the image tracking object's position and rotation, because QuickLook applies them.
-                // On Android WebXR they're replaced by the tracked data
-                let parent = object;
-                const relativeMatrix = new Matrix4();
-                if (object !== target) {
-                    while (parent.parent && parent.parent !== target) {
-                        parent = parent.parent;
-                        relativeMatrix.premultiply(parent.matrix);
-                    }
+            const { scale, target } = this.exporter.getARScaleAndTarget();
+
+            // We have to reset the image tracking object's position and rotation, because QuickLook applies them.
+            // On Android WebXR they're replaced by the tracked data
+            let parent = object;
+
+            const relativeMatrix = new Matrix4();
+            if (object !== target) {
+                while (parent && parent.parent && parent.parent !== target) {
+                    parent = parent.parent;
+                    relativeMatrix.premultiply(parent.matrix);
                 }
-                const mat = relativeMatrix
-                    .clone()
-                    .invert()
-                // apply session root scale again after undoing the world transformation
-                model.setMatrix(mat.scale(new Vector3(scale, scale, scale)));
-
-                // Unfortunately looks like Apple's docs are incomplete:
-                // https://developer.apple.com/documentation/realitykit/preliminary_anchoringapi#Nest-and-Layer-Anchorable-Prims
-                // In practice, it seems that nesting is not allowed – no image tracking will be applied to nested objects.
-                // Thus, we can't have separate transforms for "regularly placing content" and "placing content with an image marker".
-                // model.extraSchemas.push("Preliminary_AnchoringAPI");
-                // model.addEventListener("serialize", (_writer: USDWriter, _context: USDZExporterContext) => {
-                    // writer.appendLine( `token preliminary:anchoring:type = "image"` );
-                    // writer.appendLine( `rel preliminary:imageAnchoring:referenceImage = </${context.document.name}/Scenes/Scene/AnchoringReferenceImage>` );
-                // });
-
-                // We can only apply this to the first tracked image, more are not supported by QuickLook.
-                break;
             }
+            const mat = relativeMatrix
+                .clone()
+                .invert()
+            // apply session root scale again after undoing the world transformation
+            model.setMatrix(mat.scale(new Vector3(scale, scale, scale)));
+
+
+            // Unfortunately looks like Apple's docs are incomplete:
+            // https://developer.apple.com/documentation/realitykit/preliminary_anchoringapi#Nest-and-Layer-Anchorable-Prims
+            // In practice, it seems that nesting is not allowed – no image tracking will be applied to nested objects.
+            // Thus, we can't have separate transforms for "regularly placing content" and "placing content with an image marker".
+            // model.extraSchemas.push("Preliminary_AnchoringAPI");
+            // model.addEventListener("serialize", (_writer: USDWriter, _context: USDZExporterContext) => {
+            // writer.appendLine( `token preliminary:anchoring:type = "image"` );
+            // writer.appendLine( `rel preliminary:imageAnchoring:referenceImage = </${context.document.name}/Scenes/Scene/AnchoringReferenceImage>` );
+            // });
+
+            // We can only apply this to the first tracked image, more are not supported by QuickLook.
         }
     }
 }
 
+
 /**
  * @category XR
  * @group Components
@@ -238,14 +271,13 @@ class ImageTrackingExtension implements IUSDExporterExtension {
 export class WebXRImageTracking extends Behaviour {
 
     @serializable(WebXRImageTrackingModel)
-    trackedImages?: WebXRImageTrackingModel[];
+    trackedImages: WebXRImageTrackingModel[] = [];
 
     /** Applies smoothing based on detected jitter to the tracked image. */
     @serializable()
     smooth: boolean = true;
 
     private readonly trackedImageIndexMap: Map<number, WebXRImageTrackingModel> = new Map();
-    private static _imageElements: Map<string, ImageBitmap | null> = new Map();
 
     /** @returns true if image tracking is supported on this device. This may return false at runtime if the user's browser did not enable webxr incubations */
     get supported() { return this._supported; }
@@ -257,38 +289,24 @@ export class WebXRImageTracking extends Behaviour {
         if (!this.trackedImages) return;
         for (const trackedImage of this.trackedImages) {
             if (trackedImage.image) {
-                if (WebXRImageTracking._imageElements.has(trackedImage.image)) {
-                    // already loaded
-                }
-                else {
-                    const url = trackedImage.image;
-                    WebXRImageTracking._imageElements.set(url, null);
-                    const imageElement = document.createElement("img") as HTMLImageElement;
-                    imageElement.src = url;
-                    imageElement.addEventListener("load", async () => {
-                        const img = await createImageBitmap(imageElement);
-                        WebXRImageTracking._imageElements.set(url, img);
-
-                        // read back Uint8Array to use in USDZ - 
-                        // TODO better would be to do that once we actually need it
-                        const canvas = await imageToCanvas(img);
-                        if (canvas) {
-                            const blob = await canvas.convertToBlob({ type: 'image/png' });
-                            const arrayBuffer = await blob.arrayBuffer();
-
-                            const exporter = GameObject.findObjectOfType(USDZExporter);
-                            if (exporter && this.trackedImages) {
-                                exporter.extensions.push(
-                                    new ImageTrackingExtension("marker.png", new Uint8Array(arrayBuffer), this.trackedImages[0].widthInMeters)
-                                );
-                                exporter.anchoringType = "image";
-                            }
-                        }
-                    });
-                }
+                loadImage(trackedImage.image);
             }
         }
     }
+    onEnable() {
+        USDZExporter.beforeExport.addEventListener(this.onBeforeUSDZExport);
+    }
+    onDisable(): void {
+        USDZExporter.beforeExport.removeEventListener(this.onBeforeUSDZExport);
+    }
+
+    private onBeforeUSDZExport = (args: { exporter: USDZExporter }) => {
+        if (this.activeAndEnabled && this.trackedImages?.length) {
+            args.exporter.extensions.push(new ImageTrackingExtension(args.exporter, this));
+        }
+    }
+
+
 
     onBeforeXR(_mode: XRSessionMode, args: XRSessionInit & { trackedImages: Array<any> }): void {
         // console.log("onXRRequested", args, this.trackedImages)
@@ -300,7 +318,7 @@ export class WebXRImageTracking extends Behaviour {
             args.trackedImages = [];
             for (const trackedImage of this.trackedImages) {
                 if (trackedImage.image?.length && trackedImage.widthInMeters > 0) {
-                    const bitmap = WebXRImageTracking._imageElements.get(trackedImage.image);
+                    const bitmap = _imageElements.get(trackedImage.image);
                     if (bitmap) {
                         this.trackedImageIndexMap.set(args.trackedImages.length, trackedImage);
                         args.trackedImages.push({
@@ -337,7 +355,7 @@ export class WebXRImageTracking extends Behaviour {
 
     onLeaveXR(_args: NeedleXREventArgs): void {
 
-        if(!this.supported && DeviceUtilities.isAndroidDevice()) {
+        if (!this.supported && DeviceUtilities.isAndroidDevice()) {
             showBalloonWarning(this.webXRIncubationsWarning);
         }
 
@@ -364,7 +382,7 @@ export class WebXRImageTracking extends Behaviour {
     private readonly imageToObjectMap = new Map<WebXRImageTrackingModel, { object: Object3D | null, frames: number, lastTrackingTime: number }>();
     private readonly currentImages: WebXRTrackedImage[] = [];
 
-    
+
     private readonly webXRIncubationsWarning = "Image tracking is currently not supported on this device. On Chrome for Android, you can enable the <a target=\"_blank\" href=\"#\" onclick=\"() => console.log('I')\">chrome://flags/#webxr-incubations</a> flag.";
 
     onUpdateXR(args: NeedleXREventArgs): void {
@@ -517,4 +535,34 @@ export class WebXRImageTracking extends Behaviour {
             }
         }
     }
+}
+
+
+
+
+const _imageElements: Map<string, ImageBitmap | null> = new Map();
+const _imageLoadingPromises: Map<string, Promise<boolean>> = new Map();
+
+async function loadImage(url: string) {
+    if (_imageElements.has(url)) {
+        if (_imageLoadingPromises.has(url)) return _imageLoadingPromises.get(url);
+        return Promise.resolve(true);
+    }
+    const promise = new Promise<boolean>(res => {
+        _imageElements.set(url, null);
+        const imageElement = document.createElement("img") as HTMLImageElement;
+        imageElement.src = url;
+        imageElement.addEventListener("load", async () => {
+            const img = await createImageBitmap(imageElement);
+            _imageElements.set(url, img);
+            res(true);
+        });
+    });
+
+    _imageLoadingPromises.set(url, promise);
+    promise.finally(() => {
+        _imageLoadingPromises.delete(url);
+    });
+
+    return promise;
 }