mujoco-react 9.4.0 → 9.5.0

package/src/components/Debug.tsx

@@ -11,6 +11,7 @@ import type { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoContext } from '../core/MujocoSimProvider';
 import { getName } from '../core/SceneLoader';
+import { CAPTURE_EXCLUDE_KEY } from '../rendering/cameraFrameCapture';
 import { getContact, withContacts } from '../types';
 import type { DebugProps } from '../types';
 
@@ -25,9 +26,20 @@ const JOINT_COLORS: Record<number, number> = {
 const _v3a = new THREE.Vector3();
 const _v3b = new THREE.Vector3();
 const _quat = new THREE.Quaternion();
+const _cameraMatrix = new THREE.Matrix4();
 const _contactPos = new THREE.Vector3();
 const _contactNormal = new THREE.Vector3();
 const MAX_CONTACT_ARROWS = 50;
+const CAMERA_DEBUG_LENGTH = 0.12;
+const CAMERA_DEBUG_FRUSTUM_DEPTH = 0.08;
+
+type CameraDebugObject = THREE.Group & {
+  userData: {
+    cameraId: number;
+    frustum: THREE.LineSegments;
+    label?: THREE.Sprite;
+  };
+};
 
 /**
  * Declarative debug visualization component.
@@ -37,6 +49,7 @@ export function Debug({
   showGeoms = false,
   showSites = false,
   showJoints = false,
+  showCameras = false,
   showContacts = false,
   showCOM = false,
   showInertia = false,
@@ -55,6 +68,7 @@ export function Debug({
     const geoms: THREE.Object3D[] = [];
     const sites: THREE.Object3D[] = [];
     const joints: THREE.Object3D[] = [];
+    const cameras: CameraDebugObject[] = [];
     const comMarkers: THREE.Object3D[] = [];
 
     // Wireframe geoms
@@ -179,6 +193,83 @@ export function Debug({
       }
     }
 
+    if (showCameras && model.ncam && model.name_camadr) {
+      for (let i = 0; i < model.ncam; i++) {
+        const group = new THREE.Group() as CameraDebugObject;
+        group.userData.cameraId = i;
+        group.renderOrder = 999;
+        group.frustumCulled = false;
+
+        const marker = new THREE.Mesh(
+          new THREE.BoxGeometry(0.014, 0.009, 0.006),
+          new THREE.MeshBasicMaterial({ color: 0x38bdf8, depthTest: false })
+        );
+        marker.renderOrder = 999;
+        marker.frustumCulled = false;
+        group.add(marker);
+
+        const forward = new THREE.ArrowHelper(
+          new THREE.Vector3(0, 0, -1),
+          new THREE.Vector3(),
+          CAMERA_DEBUG_LENGTH,
+          0x38bdf8,
+          CAMERA_DEBUG_LENGTH * 0.24,
+          CAMERA_DEBUG_LENGTH * 0.11
+        );
+        forward.renderOrder = 999;
+        forward.frustumCulled = false;
+        forward.line.material = new THREE.LineBasicMaterial({
+          color: 0x38bdf8,
+          depthTest: false,
+        });
+        (forward.cone.material as THREE.MeshBasicMaterial).depthTest = false;
+        group.add(forward);
+
+        const frustumGeometry = new THREE.BufferGeometry();
+        frustumGeometry.setAttribute(
+          'position',
+          new THREE.Float32BufferAttribute(new Float32Array(8 * 2 * 3), 3)
+        );
+        const frustum = new THREE.LineSegments(
+          frustumGeometry,
+          new THREE.LineBasicMaterial({
+            color: 0x38bdf8,
+            transparent: true,
+            opacity: 0.8,
+            depthTest: false,
+          })
+        );
+        frustum.renderOrder = 999;
+        frustum.frustumCulled = false;
+        group.userData.frustum = frustum;
+        group.add(frustum);
+
+        const canvas = document.createElement('canvas');
+        canvas.width = 256;
+        canvas.height = 64;
+        const ctx = canvas.getContext('2d')!;
+        ctx.fillStyle = '#38bdf8';
+        ctx.font = 'bold 32px monospace';
+        ctx.textAlign = 'center';
+        ctx.fillText(getName(model, model.name_camadr[i]), 128, 42);
+        const texture = new THREE.CanvasTexture(canvas);
+        const sprite = new THREE.Sprite(
+          new THREE.SpriteMaterial({
+            map: texture,
+            depthTest: false,
+            transparent: true,
+          })
+        );
+        sprite.position.set(0, 0.014, 0.01);
+        sprite.scale.set(0.04, 0.01, 1);
+        sprite.renderOrder = 999;
+        group.userData.label = sprite;
+        group.add(sprite);
+
+        cameras.push(group);
+      }
+    }
+
     // COM markers
     if (showCOM) {
       for (let i = 1; i < model.nbody; i++) {
@@ -190,8 +281,8 @@ export function Debug({
       }
     }
 
-    return { geoms, sites, joints, comMarkers };
-  }, [status, mjModelRef, showGeoms, showSites, showJoints, showCOM]);
+    return { geoms, sites, joints, cameras, comMarkers };
+  }, [status, mjModelRef, showGeoms, showSites, showJoints, showCameras, showCOM]);
 
   // Add/remove debug objects from scene
   useEffect(() => {
@@ -202,6 +293,7 @@ export function Debug({
       ...debugGeometry.geoms,
       ...debugGeometry.sites,
       ...debugGeometry.joints,
+      ...debugGeometry.cameras,
       ...debugGeometry.comMarkers,
     ];
     for (const obj of allObjects) group.add(obj);
@@ -281,6 +373,59 @@ export function Debug({
       }
     }
 
+    const camXpos = data.cam_xpos;
+    const camXmat = data.cam_xmat;
+    if (camXpos && camXmat) {
+      for (const group of debugGeometry.cameras) {
+        const cameraId = group.userData.cameraId;
+        const i3 = cameraId * 3;
+        const i9 = cameraId * 9;
+        group.position.set(
+          camXpos[i3],
+          camXpos[i3 + 1],
+          camXpos[i3 + 2]
+        );
+        _cameraMatrix.set(
+          camXmat[i9], camXmat[i9 + 1], camXmat[i9 + 2], 0,
+          camXmat[i9 + 3], camXmat[i9 + 4], camXmat[i9 + 5], 0,
+          camXmat[i9 + 6], camXmat[i9 + 7], camXmat[i9 + 8], 0,
+          0, 0, 0, 1
+        );
+        group.quaternion.setFromRotationMatrix(_cameraMatrix);
+
+        const fovy = model.cam_fovy?.[cameraId] ?? 45;
+        const halfHeight = Math.tan(THREE.MathUtils.degToRad(fovy) / 2) *
+          CAMERA_DEBUG_FRUSTUM_DEPTH;
+        const halfWidth = halfHeight * 4 / 3;
+        const positions = group.userData.frustum.geometry.attributes.position;
+        const array = positions.array as Float32Array;
+        const points = [
+          [0, 0, 0],
+          [-halfWidth, halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [0, 0, 0],
+          [halfWidth, halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [0, 0, 0],
+          [halfWidth, -halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [0, 0, 0],
+          [-halfWidth, -halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [-halfWidth, halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [halfWidth, halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [halfWidth, halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [halfWidth, -halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [halfWidth, -halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [-halfWidth, -halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [-halfWidth, -halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+          [-halfWidth, halfHeight, -CAMERA_DEBUG_FRUSTUM_DEPTH],
+        ];
+        for (let i = 0; i < points.length; i += 1) {
+          array[i * 3] = points[i][0];
+          array[i * 3 + 1] = points[i][1];
+          array[i * 3 + 2] = points[i][2];
+        }
+        positions.needsUpdate = true;
+      }
+    }
+
     // Update COM markers
     for (const mesh of debugGeometry.comMarkers) {
       const bid = mesh.userData.bodyId;
@@ -358,7 +503,13 @@ export function Debug({
   if (status !== 'ready') return null;
 
   return (
-    <group {...groupProps}>
+    <group
+      {...groupProps}
+      userData={{
+        ...groupProps.userData,
+        [CAPTURE_EXCLUDE_KEY]: true,
+      }}
+    >
       <group ref={groupRef} />
       {showContacts && <group ref={contactGroupRef} />}
     </group>

package/src/components/DragInteraction.tsx

@@ -8,6 +8,7 @@ import type { ThreeElements } from '@react-three/fiber';
 import { useEffect, useRef } from 'react';
 import * as THREE from 'three';
 import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
+import { CAPTURE_EXCLUDE_KEY } from '../rendering/cameraFrameCapture';
 import type { DragInteractionProps } from '../types';
 
 // Preallocated temps to avoid GC pressure
@@ -60,6 +61,7 @@ export function DragInteraction({
       0.1,
       0xff4444,
     );
+    arrow.userData[CAPTURE_EXCLUDE_KEY] = true;
     arrow.visible = false;
     // Make arrow semi-transparent
     (arrow.line.material as THREE.LineBasicMaterial).transparent = true;

package/src/components/IkGizmo.tsx

@@ -9,6 +9,7 @@ import { useEffect, useRef } from 'react';
 import * as THREE from 'three';
 import { useMujocoContext } from '../core/MujocoSimProvider';
 import { findSiteByName } from '../core/SceneLoader';
+import { CAPTURE_EXCLUDE_KEY } from '../rendering/cameraFrameCapture';
 import type { IkGizmoProps } from '../types';
 
 // Preallocated temps to avoid GC pressure in useFrame
@@ -83,7 +84,10 @@ export function IkGizmo({ controller, siteName, scale = 0.18, onDrag }: IkGizmoP
   if (status !== 'ready') return null;
 
   return (
-    <group ref={wrapperRef}>
+    <group
+      ref={wrapperRef}
+      userData={{ [CAPTURE_EXCLUDE_KEY]: true }}
+    >
       <PivotControls
         ref={pivotRef}
         autoTransform

package/src/core/MujocoSimProvider.tsx

@@ -148,12 +148,12 @@ function vector3FromArray(values: ArrayLike<number>, offset: number): [number, n
   return [values[offset], values[offset + 1], values[offset + 2]];
 }
 
-function quaternionFromArray(values: ArrayLike<number>, offset: number): [number, number, number, number] {
+function quaternionFromMujocoQuat(values: ArrayLike<number>, offset: number): [number, number, number, number] {
   return [
-    values[offset],
     values[offset + 1],
     values[offset + 2],
     values[offset + 3],
+    values[offset],
   ];
 }
 
@@ -993,7 +993,7 @@ export function MujocoSimProvider({
           ? vector3FromArray(model.cam_pos, posOffset)
           : null,
         quaternion: model.cam_quat
-          ? quaternionFromArray(model.cam_quat, quatOffset)
+          ? quaternionFromMujocoQuat(model.cam_quat, quatOffset)
           : null,
       });
     }
@@ -1024,7 +1024,7 @@ export function MujocoSimProvider({
         const quaternion = data.cam_xmat
           ? quaternionFromXmat(data.cam_xmat, cameraId * 9)
           : model.cam_quat
-            ? quaternionFromArray(model.cam_quat, cameraId * 4)
+            ? quaternionFromMujocoQuat(model.cam_quat, cameraId * 4)
             : undefined;
 
         if (!position || !quaternion) {
@@ -1442,7 +1442,7 @@ export function MujocoSimProvider({
           const cameraFrames: Record<string, CameraFrameCaptureResult> = {};
           for (const { key, captureOptions, mountedSource, session } of captureSessions) {
             const resolvedCaptureOptions = resolveCameraCaptureOptions(captureOptions);
-            const cameraFrame = session.captureDataUrl({
+            const cameraFrame = await session.captureDataUrlAsync({
               ...resolvedCaptureOptions,
               source: mountedSource ?? resolvedCaptureOptions.source,
             });

package/src/index.ts

@@ -113,6 +113,7 @@ export type {
   MountedCameraSequenceRecordResult,
 } from './hooks/useMountedCameraSequenceRecorder';
 export {
+  CAPTURE_EXCLUDE_KEY,
   captureCameraFrame,
   captureCameraFrameBlob,
   createCameraFrameCaptureSession,

package/src/rendering/cameraFrameCapture.ts

@@ -24,11 +24,66 @@ export interface CameraFrameCaptureSession {
     height: number;
     source: CameraFrameCaptureSource;
   };
+  captureAsync(options?: CameraFrameCaptureOptions): Promise<{
+    canvas: HTMLCanvasElement;
+    camera: THREE.Camera;
+    width: number;
+    height: number;
+    source: CameraFrameCaptureSource;
+  }>;
   captureDataUrl(options?: CameraFrameCaptureOptions): CameraFrameCaptureResult;
+  captureDataUrlAsync(
+    options?: CameraFrameCaptureOptions
+  ): Promise<CameraFrameCaptureResult>;
   captureBlob(options?: CameraFrameCaptureOptions): Promise<CameraFrameCaptureBlobResult>;
   dispose(): void;
 }
 
+export const CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY =
+  'mujocoReactCameraFrameCaptureRender';
+export const CAPTURE_EXCLUDE_KEY =
+  'mujoco.capture.exclude';
+
+export type CameraFrameCaptureRenderInput = {
+  renderer: THREE.WebGLRenderer;
+  scene: THREE.Scene;
+  camera: THREE.Camera;
+  target: THREE.WebGLRenderTarget;
+  width: number;
+  height: number;
+};
+
+export type CameraFrameCaptureRenderResult = {
+  pixels: Uint8Array;
+  width?: number;
+  height?: number;
+  flipY?: boolean;
+};
+
+type CameraFrameCaptureRender = (
+  input: CameraFrameCaptureRenderInput
+) =>
+  | CameraFrameCaptureRenderResult
+  | null
+  | undefined
+  | Promise<CameraFrameCaptureRenderResult | null | undefined>;
+
+type RendererState = {
+  target: THREE.WebGLRenderTarget | null;
+  xrEnabled: boolean;
+  viewport: THREE.Vector4;
+  scissor: THREE.Vector4;
+  scissorTest: boolean;
+  clearColor: THREE.Color;
+  clearAlpha: number;
+  autoClear: boolean;
+};
+
+type VisibilityState = {
+  object: THREE.Object3D;
+  visible: boolean;
+};
+
 function toVector3(
   value: CameraFrameCaptureVector3 | undefined,
   fallback: THREE.Vector3
@@ -136,21 +191,79 @@ function readRenderTargetToCanvas(
   pixels: Uint8Array,
   imageData: ImageData,
   width: number,
-  height: number
+  height: number,
+  outputColorSpace: string
 ) {
   renderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
 
   const rowBytes = width * 4;
+  const encodeSrgb = outputColorSpace === THREE.SRGBColorSpace;
   for (let y = 0; y < height; y += 1) {
     const sourceStart = (height - y - 1) * rowBytes;
     const targetStart = y * rowBytes;
+    const row = pixels.subarray(sourceStart, sourceStart + rowBytes);
+    if (!encodeSrgb) {
+      imageData.data.set(row, targetStart);
+      continue;
+    }
+
+    for (let x = 0; x < rowBytes; x += 4) {
+      const pixelOffset = targetStart + x;
+      imageData.data[pixelOffset] = linearByteToSrgbByte(row[x]);
+      imageData.data[pixelOffset + 1] = linearByteToSrgbByte(row[x + 1]);
+      imageData.data[pixelOffset + 2] = linearByteToSrgbByte(row[x + 2]);
+      imageData.data[pixelOffset + 3] = row[x + 3];
+    }
+  }
+  context.putImageData(imageData, 0, 0);
+  return canvas;
+}
+
+function linearByteToSrgbByte(value: number) {
+  const normalized = value / 255;
+  const encoded =
+    normalized <= 0.0031308
+      ? normalized * 12.92
+      : 1.055 * Math.pow(normalized, 1 / 2.4) - 0.055;
+  return Math.min(255, Math.max(0, Math.round(encoded * 255)));
+}
+
+function readPixelsToCanvas(
+  pixels: Uint8Array,
+  context: CanvasRenderingContext2D,
+  imageData: ImageData,
+  width: number,
+  height: number,
+  flipY = true
+) {
+  const rowBytes = width * 4;
+  for (let y = 0; y < height; y += 1) {
+    const sourceY = flipY ? height - y - 1 : y;
+    const sourceStart = sourceY * rowBytes;
+    const targetStart = y * rowBytes;
     imageData.data.set(
       pixels.subarray(sourceStart, sourceStart + rowBytes),
       targetStart
     );
   }
   context.putImageData(imageData, 0, 0);
-  return canvas;
+}
+
+function hideExcludedCaptureObjects(scene: THREE.Scene): VisibilityState[] {
+  const hidden: VisibilityState[] = [];
+  scene.traverse((object) => {
+    if (!object.visible) return;
+    if (!object.userData[CAPTURE_EXCLUDE_KEY]) return;
+    hidden.push({ object, visible: object.visible });
+    object.visible = false;
+  });
+  return hidden;
+}
+
+function restoreObjectVisibility(hidden: VisibilityState[]) {
+  for (const { object, visible } of hidden) {
+    object.visible = visible;
+  }
 }
 
 function getCameraFrameCaptureSource(
@@ -173,6 +286,52 @@ function getCameraFrameCaptureSource(
   return { kind: 'fallback-camera' };
 }
 
+function saveRendererState(renderer: THREE.WebGLRenderer): RendererState {
+  const viewport = new THREE.Vector4();
+  const scissor = new THREE.Vector4();
+  const clearColor = new THREE.Color();
+  renderer.getViewport(viewport);
+  renderer.getScissor(scissor);
+  renderer.getClearColor(clearColor);
+  return {
+    target: renderer.getRenderTarget(),
+    xrEnabled: renderer.xr.enabled,
+    viewport,
+    scissor,
+    scissorTest: renderer.getScissorTest(),
+    clearColor,
+    clearAlpha: renderer.getClearAlpha(),
+    autoClear: renderer.autoClear,
+  };
+}
+
+function restoreRendererState(
+  renderer: THREE.WebGLRenderer,
+  state: RendererState
+) {
+  renderer.setRenderTarget(state.target);
+  renderer.xr.enabled = state.xrEnabled;
+  renderer.setViewport(state.viewport);
+  renderer.setScissor(state.scissor);
+  renderer.setScissorTest(state.scissorTest);
+  renderer.setClearColor(state.clearColor, state.clearAlpha);
+  renderer.autoClear = state.autoClear;
+}
+
+function getCaptureRenderer(
+  scene: THREE.Scene
+): CameraFrameCaptureRender | null {
+  const renderers: CameraFrameCaptureRender[] = [];
+  scene.traverse((object) => {
+    if (renderers.length) return;
+    const render = object.userData[
+      CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY
+    ] as CameraFrameCaptureRender | undefined;
+    if (typeof render === 'function') renderers.push(render);
+  });
+  return renderers[0] ?? null;
+}
+
 export function createCameraFrameCaptureSession(
   renderer: THREE.WebGLRenderer,
   scene: THREE.Scene,
@@ -198,7 +357,7 @@ export function createCameraFrameCaptureSession(
   const pixels = new Uint8Array(width * height * 4);
   const imageData = drawContext.createImageData(width, height);
 
-  function capture(nextOptions: CameraFrameCaptureOptions = {}) {
+  function resolveCaptureOptions(nextOptions: CameraFrameCaptureOptions = {}) {
     const captureOptions = { ...options, ...nextOptions };
     const nextDimensions = getCaptureDimensions(renderer, captureOptions);
     if (
@@ -218,13 +377,20 @@ export function createCameraFrameCaptureSession(
       height
     );
 
-    const previousTarget = renderer.getRenderTarget();
-    const previousXrEnabled = renderer.xr.enabled;
+    return captureOptions;
+  }
+
+  function renderPreparedCapture(captureOptions: CameraFrameCaptureOptions) {
+    const previousState = saveRendererState(renderer);
+    const hidden = hideExcludedCaptureObjects(scene);
 
     scene.updateMatrixWorld(true);
     try {
       renderer.xr.enabled = false;
       renderer.setRenderTarget(target);
+      renderer.setViewport(0, 0, width, height);
+      renderer.setScissor(0, 0, width, height);
+      renderer.setScissorTest(false);
       renderer.clear();
       renderer.render(scene, camera);
       readRenderTargetToCanvas(
@@ -235,7 +401,8 @@ export function createCameraFrameCaptureSession(
         pixels,
         imageData,
         width,
-        height
+        height,
+        renderer.outputColorSpace
       );
       return {
         canvas,
@@ -245,15 +412,69 @@ export function createCameraFrameCaptureSession(
         source: getCameraFrameCaptureSource(captureOptions),
       };
     } finally {
-      renderer.setRenderTarget(previousTarget);
-      renderer.xr.enabled = previousXrEnabled;
+      restoreObjectVisibility(hidden);
+      restoreRendererState(renderer, previousState);
+    }
+  }
+
+  function capture(nextOptions: CameraFrameCaptureOptions = {}) {
+    return renderPreparedCapture(resolveCaptureOptions(nextOptions));
+  }
+
+  async function captureAsync(nextOptions: CameraFrameCaptureOptions = {}) {
+    const captureOptions = resolveCaptureOptions(nextOptions);
+    scene.updateMatrixWorld(true);
+    const captureRenderer = getCaptureRenderer(scene);
+    if (captureRenderer) {
+      const previousState = saveRendererState(renderer);
+      const hidden = hideExcludedCaptureObjects(scene);
+      try {
+        renderer.xr.enabled = false;
+        const captureResult = await captureRenderer({
+          renderer,
+          scene,
+          camera,
+          target,
+          width,
+          height,
+        });
+        if (captureResult) {
+          const captureWidth = captureResult.width ?? width;
+          const captureHeight = captureResult.height ?? height;
+          if (captureWidth !== width || captureHeight !== height) {
+            throw new Error(
+              'Camera frame capture renderer returned unexpected dimensions.'
+            );
+          }
+          readPixelsToCanvas(
+            captureResult.pixels,
+            drawContext,
+            imageData,
+            width,
+            height,
+            captureResult.flipY ?? true
+          );
+          return {
+            canvas,
+            camera,
+            width,
+            height,
+            source: getCameraFrameCaptureSource(captureOptions),
+          };
+        }
+      } finally {
+        restoreObjectVisibility(hidden);
+        restoreRendererState(renderer, previousState);
+      }
     }
+    return renderPreparedCapture(captureOptions);
   }
 
   return {
     width,
     height,
     capture,
+    captureAsync,
     captureDataUrl(nextOptions = {}) {
       const type = nextOptions.type ?? options.type ?? 'image/png';
       const result = capture(nextOptions);
@@ -266,9 +487,21 @@ export function createCameraFrameCaptureSession(
         type,
       };
     },
+    async captureDataUrlAsync(nextOptions = {}) {
+      const type = nextOptions.type ?? options.type ?? 'image/png';
+      const result = await captureAsync(nextOptions);
+      return {
+        ...result,
+        dataUrl: result.canvas.toDataURL(
+          type,
+          nextOptions.quality ?? options.quality
+        ),
+        type,
+      };
+    },
     async captureBlob(nextOptions = {}) {
       const type = nextOptions.type ?? options.type ?? 'image/png';
-      const result = capture(nextOptions);
+      const result = await captureAsync(nextOptions);
       const blob = await new Promise<Blob>((resolve, reject) => {
         result.canvas.toBlob(
           (nextBlob) => {
@@ -313,17 +546,22 @@ export async function captureCameraFrame(
   options: CameraFrameCaptureOptions = {}
 ): Promise<CameraFrameCaptureResult> {
   const type = options.type ?? 'image/png';
-  const result = renderCameraFrameToCanvas(
+  const session = createCameraFrameCaptureSession(
     renderer,
     scene,
     fallbackCamera,
     options
   );
-  return {
-    ...result,
-    dataUrl: result.canvas.toDataURL(type, options.quality),
-    type,
-  };
+  try {
+    const result = await session.captureAsync();
+    return {
+      ...result,
+      dataUrl: result.canvas.toDataURL(type, options.quality),
+      type,
+    };
+  } finally {
+    session.dispose();
+  }
 }
 
 export async function captureCameraFrameBlob(
@@ -332,22 +570,15 @@ export async function captureCameraFrameBlob(
   fallbackCamera: THREE.Camera,
   options: CameraFrameCaptureOptions = {}
 ): Promise<CameraFrameCaptureBlobResult> {
-  const type = options.type ?? 'image/png';
-  const result = renderCameraFrameToCanvas(
+  const session = createCameraFrameCaptureSession(
     renderer,
     scene,
     fallbackCamera,
     options
   );
-  const blob = await new Promise<Blob>((resolve, reject) => {
-    result.canvas.toBlob(
-      (nextBlob) => {
-        if (nextBlob) resolve(nextBlob);
-        else reject(new Error('Camera frame capture did not produce a Blob.'));
-      },
-      type,
-      options.quality
-    );
-  });
-  return { ...result, blob, type };
+  try {
+    return await session.captureBlob();
+  } finally {
+    session.dispose();
+  }
 }