useFrameCapture

Capture still frames from a canvas-backed scene

Capture a still image from a MuJoCo/R3F canvas. This is useful for dataset provenance, visual regression checks, thumbnails, and policy rollout reports.

For WebGL scenes, pass gl={{ preserveDrawingBuffer: true }} to MujocoCanvas when you need deterministic captures after the frame presents.

Signature

useFrameCapture(options?: {
  target?: HTMLCanvasElement | HTMLElement | React.RefObject<HTMLElement | HTMLCanvasElement | null>
  type?: string
  quality?: number
  waitForAnimationFrame?: boolean
}): {
  status: "idle" | "capturing" | "captured" | "error"
  error: Error | null
  isCapturing: boolean
  capture: (options?: FrameCaptureOptions) => Promise<FrameCaptureResult>
  captureBlob: (options?: FrameCaptureOptions) => Promise<FrameCaptureBlobResult>
  reset: () => void
}

Usage

When you use MujocoCanvas, the forwarded MujocoSimAPI exposes capture methods directly:

import { useRef } from "react";
import { MujocoCanvas } from "mujoco-react";
import type { MujocoSimAPI } from "mujoco-react";

function SceneCapture({ config }) {
  const apiRef = useRef<MujocoSimAPI>(null);

  async function saveFrame() {
    const frame = await apiRef.current?.captureFrame({ type: "image/png" });
    await fetch("/api/captures/frame", {
      method: "POST",
      body: JSON.stringify({ dataUrl: frame?.dataUrl }),
    });
  }

  return (
    <>
      <MujocoCanvas
        ref={apiRef}
        config={config}
        gl={{ preserveDrawingBuffer: true }}
      />
      <button onClick={saveFrame}>Capture frame</button>
    </>
  );
}

Use the hook when you own the canvas or want to capture a container:

import { useRef } from "react";
import { MujocoCanvas, useFrameCapture } from "mujoco-react";

function SceneCapture({ config }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const frameCapture = useFrameCapture({
    target: containerRef,
    type: "image/png",
  });

  async function saveFrame() {
    const frame = await frameCapture.capture();
    await fetch("/api/captures/frame", {
      method: "POST",
      body: JSON.stringify({ dataUrl: frame.dataUrl }),
    });
  }

  return (
    <div ref={containerRef}>
      <MujocoCanvas
        config={config}
        gl={{ preserveDrawingBuffer: true }}
      />
      <button onClick={saveFrame} disabled={frameCapture.isCapturing}>
        Capture frame
      </button>
    </div>
  );
}

Standalone Helpers

import { captureFrame, captureFrameBlob } from "mujoco-react";

const image = await captureFrame({ target: containerElement });
const blob = await captureFrameBlob({ target: canvasElement });

MujocoSimAPI also exposes getCanvas(), captureFrame(), and captureFrameBlob() for the common MujocoCanvas ref path.

Options

Field	Type	Default	Description
target	HTMLCanvasElement, HTMLElement, or ref	required	Canvas or container that contains a canvas
type	string	"image/png"	Output MIME type
quality	number	browser default	JPEG/WebP quality where supported
waitForAnimationFrame	boolean	true	Wait one frame before capture

Notes

• A container target uses the first descendant canvas.
• capture() returns a data URL for JSON/API payloads.
• captureBlob() returns a Blob for file uploads or object URLs.
• Browser canvas security rules apply: cross-origin textures can taint the canvas.