mujoco-react 9.1.0 → 9.3.0

package/src/hooks/useCameraFrameCapture.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * React state wrapper around MuJoCo/R3F offscreen camera-frame capture.
+ */
+
+import { useCallback, useState } from 'react';
+import { useMujoco } from '../core/MujocoSimProvider';
+import type {
+  CameraFrameCaptureAPI,
+  CameraFrameCaptureOptions,
+  FrameCaptureStatus,
+} from '../types';
+
+export function useCameraFrameCapture(
+  defaultOptions: CameraFrameCaptureOptions = {}
+): CameraFrameCaptureAPI {
+  const mujoco = useMujoco();
+  const [status, setStatus] = useState<FrameCaptureStatus>('idle');
+  const [error, setError] = useState<Error | null>(null);
+
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setError(null);
+  }, []);
+
+  const capture = useCallback(
+    async (options: CameraFrameCaptureOptions = {}) => {
+      if (!mujoco.api) {
+        throw new Error('MuJoCo scene is not ready for camera frame capture.');
+      }
+
+      setStatus('capturing');
+      setError(null);
+
+      try {
+        const result = await mujoco.api.captureCameraFrame({
+          ...defaultOptions,
+          ...options,
+        });
+        setStatus('captured');
+        return result;
+      } catch (nextError) {
+        const error =
+          nextError instanceof Error
+            ? nextError
+            : new Error('Unable to capture the requested camera frame.');
+        setError(error);
+        setStatus('error');
+        throw error;
+      }
+    },
+    [defaultOptions, mujoco.api]
+  );
+
+  const captureBlob = useCallback(
+    async (options: CameraFrameCaptureOptions = {}) => {
+      if (!mujoco.api) {
+        throw new Error('MuJoCo scene is not ready for camera frame capture.');
+      }
+
+      setStatus('capturing');
+      setError(null);
+
+      try {
+        const result = await mujoco.api.captureCameraFrameBlob({
+          ...defaultOptions,
+          ...options,
+        });
+        setStatus('captured');
+        return result;
+      } catch (nextError) {
+        const error =
+          nextError instanceof Error
+            ? nextError
+            : new Error('Unable to capture the requested camera frame.');
+        setError(error);
+        setStatus('error');
+        throw error;
+      }
+    },
+    [defaultOptions, mujoco.api]
+  );
+
+  return {
+    status,
+    error,
+    isCapturing: status === 'capturing',
+    capture,
+    captureBlob,
+    reset,
+  };
+}

package/src/hooks/useCameraSequenceRecorder.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * React state wrapper around fixed-camera simulation sequence recording.
+ */
+
+import { useCallback, useState } from 'react';
+import { useMujoco } from '../core/MujocoSimProvider';
+import type {
+  CameraFrameSequenceOptions,
+  CameraFrameSequenceRecorderAPI,
+  FrameCaptureStatus,
+} from '../types';
+
+export function useCameraSequenceRecorder(): CameraFrameSequenceRecorderAPI {
+  const mujoco = useMujoco();
+  const [status, setStatus] = useState<FrameCaptureStatus>('idle');
+  const [error, setError] = useState<Error | null>(null);
+
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setError(null);
+  }, []);
+
+  const record = useCallback(
+    async (options: CameraFrameSequenceOptions) => {
+      if (!mujoco.api) {
+        throw new Error('MuJoCo scene is not ready for camera sequence recording.');
+      }
+
+      setStatus('capturing');
+      setError(null);
+
+      try {
+        const result = await mujoco.api.recordCameraSequence(options);
+        setStatus('captured');
+        return result;
+      } catch (nextError) {
+        const error =
+          nextError instanceof Error
+            ? nextError
+            : new Error('Unable to record the requested camera sequence.');
+        setError(error);
+        setStatus('error');
+        throw error;
+      }
+    },
+    [mujoco.api]
+  );
+
+  return {
+    status,
+    error,
+    isRecording: status === 'capturing',
+    record,
+    reset,
+  };
+}

package/src/hooks/useMountedCameraSequenceRecorder.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * React state wrapper for named MuJoCo camera/site/body sequence recording.
+ */
+
+import { useCallback, useState } from 'react';
+import { useMujoco } from '../core/MujocoSimProvider';
+import {
+  createMountedCameraFrameSequencePlanFromApi,
+  recordMountedCameraFrameSequence,
+  type MountedCameraFrameSequencePlan,
+  type MountedCameraFrameSequencePlanOptions,
+  type MountedCameraFrameSequenceRecordOptions,
+  type MountedCameraFrameSequenceRecordResult,
+} from '../rendering/cameraFrameSource';
+import type {
+  CameraFrameSequenceRecorderAPI,
+  FrameCaptureStatus,
+} from '../types';
+
+export type MountedCameraSequencePlanOptions =
+  MountedCameraFrameSequencePlanOptions;
+export type MountedCameraSequenceRecordOptions =
+  MountedCameraFrameSequenceRecordOptions;
+export type MountedCameraSequenceRecordResult =
+  MountedCameraFrameSequenceRecordResult;
+
+export interface MountedCameraSequenceRecorderAPI
+  extends Omit<CameraFrameSequenceRecorderAPI, 'record'> {
+  createPlan: (
+    cameraKeys: readonly string[],
+    options?: MountedCameraSequencePlanOptions
+  ) => MountedCameraFrameSequencePlan;
+  record: (
+    options: MountedCameraSequenceRecordOptions
+  ) => Promise<MountedCameraSequenceRecordResult>;
+}
+
+export function useMountedCameraSequenceRecorder(
+  defaultOptions: MountedCameraSequencePlanOptions = {}
+): MountedCameraSequenceRecorderAPI {
+  const mujoco = useMujoco();
+  const [status, setStatus] = useState<FrameCaptureStatus>('idle');
+  const [error, setError] = useState<Error | null>(null);
+
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setError(null);
+  }, []);
+
+  const createPlan = useCallback(
+    (
+      cameraKeys: readonly string[],
+      options: MountedCameraSequencePlanOptions = {}
+    ) => {
+      if (!mujoco.api) {
+        throw new Error('MuJoCo scene is not ready for mounted camera sequence planning.');
+      }
+
+      return createMountedCameraFrameSequencePlanFromApi(mujoco.api, cameraKeys, {
+        ...defaultOptions,
+        ...options,
+      });
+    },
+    [defaultOptions, mujoco.api]
+  );
+
+  const record = useCallback(
+    async (options: MountedCameraSequenceRecordOptions) => {
+      if (!mujoco.api) {
+        throw new Error('MuJoCo scene is not ready for mounted camera sequence recording.');
+      }
+
+      setStatus('capturing');
+      setError(null);
+
+      try {
+        const result = await recordMountedCameraFrameSequence(mujoco.api, {
+          ...defaultOptions,
+          ...options,
+        });
+        setStatus('captured');
+        return result;
+      } catch (nextError) {
+        const error =
+          nextError instanceof Error
+            ? nextError
+            : new Error('Unable to record the requested mounted camera sequence.');
+        setError(error);
+        setStatus('error');
+        throw error;
+      }
+    },
+    [defaultOptions, mujoco.api]
+  );
+
+  return {
+    status,
+    error,
+    isRecording: status === 'capturing',
+    createPlan,
+    record,
+    reset,
+  };
+}

package/src/index.ts

@@ -48,9 +48,11 @@ export {
   createPairedSplatEnvironment,
   createSparkSplatViewerUrl,
   createSplatEnvironmentUserData,
+  getSplatEnvironmentReadiness,
   getScenarioBackground,
   getScenarioCameraPosition,
   useSplatEnvironment,
+  useSplatSceneConfig,
   useVisualScenarioEffects,
   withSplatEnvironment,
 } from './components/VisualScenario';
@@ -82,6 +84,49 @@ export {
   captureFrameBlob,
   useFrameCapture,
 } from './hooks/useFrameCapture';
+export { useCameraFrameCapture } from './hooks/useCameraFrameCapture';
+export { useCameraSequenceRecorder } from './hooks/useCameraSequenceRecorder';
+export { useMountedCameraSequenceRecorder } from './hooks/useMountedCameraSequenceRecorder';
+export type {
+  MountedCameraSequencePlanOptions,
+  MountedCameraSequenceRecorderAPI,
+  MountedCameraSequenceRecordOptions,
+  MountedCameraSequenceRecordResult,
+} from './hooks/useMountedCameraSequenceRecorder';
+export {
+  captureCameraFrame,
+  captureCameraFrameBlob,
+  createCameraFrameCaptureSession,
+  renderCameraFrameToCanvas,
+} from './rendering/cameraFrameCapture';
+export {
+  createMountedCameraFrameSequenceReadiness,
+  MountedCameraFrameSequenceReadinessStatus,
+  createMountedCameraFrameSequencePlanFromApi,
+  createMountedCameraFrameSequencePlan,
+  getCameraFrameCaptureSourceTarget,
+  getMountedCameraFrameCaptureSource,
+  isMountedCameraFrameCaptureSource,
+  recordMountedCameraFrameSequence,
+  resolveMountedCameraFrameSource,
+} from './rendering/cameraFrameSource';
+export type {
+  CameraFrameMountSelector,
+  CreateMountedCameraFrameSequencePlanOptions,
+  MountedCameraFrameCaptureSource,
+  MountedCameraFrameSequencePlanOptions,
+  MountedCameraFrameSequenceRecorderTarget,
+  MountedCameraFrameSequenceCameraOptions,
+  MountedCameraFrameSequenceDefaults,
+  MountedCameraFrameSequencePlan,
+  MountedCameraFrameSequenceReadiness,
+  MountedCameraFrameSequenceRecordOptions,
+  MountedCameraFrameSequenceRecordResult,
+  MountedCameraFrameSequenceSourceReadiness,
+  NamedCameraFrameResource,
+  ResolveMountedCameraFrameSourceOptions,
+  ResolvedMountedCameraFrameSource,
+} from './rendering/cameraFrameSource';
 export { useCtrlNoise } from './hooks/useCtrlNoise';
 export { useBodyMeshes } from './hooks/useBodyMeshes';
 export { useSelectionHighlight } from './hooks/useSelectionHighlight';
@@ -123,6 +168,7 @@ export type {
   SiteInfo,
   ActuatorInfo,
   SensorInfo,
+  CameraInfo,
   // Contacts
   ContactInfo,
   // Raycast
@@ -165,8 +211,11 @@ export type {
   SplatScenarioConfig,
   SplatCollisionProxyConfig,
   PairedSplatEnvironmentConfig,
+  SplatEnvironmentReadiness,
   SplatEnvironmentMetadataInput,
   SplatEnvironmentMetadata,
+  SplatSceneConfigInput,
+  SplatSceneConfigState,
   SplatSceneInput,
   VisualScenarioConfig,
   ScenarioLightingProps,
@@ -181,6 +230,21 @@ export type {
   // API
   MujocoSimAPI,
   MujocoFrameCaptureOptions,
+  CameraFrameCaptureAPI,
+  CameraFrameCaptureBlobResult,
+  CameraFrameCaptureOptions,
+  CameraFrameCaptureQuaternion,
+  CameraFrameCaptureResult,
+  CameraFrameCaptureSource,
+  CameraFrameCaptureVector3,
+  CameraFrameSequenceCamera,
+  CameraFrameSequenceCameraSummary,
+  CameraFrameSequenceFrame,
+  CameraFrameSequenceOptions,
+  CameraFrameSequenceRecorderAPI,
+  CameraFrameSequenceResult,
+  CameraFrameSequenceSampleInput,
+  CameraFrameSequenceStepInput,
   MujocoCanvasProps,
   MujocoContextValue,
   // Hook return types
@@ -209,6 +273,7 @@ export type {
   Sites,
   Geoms,
   Keyframes,
+  Cameras,
 } from './types';
 
 export {
@@ -221,6 +286,8 @@ export {
   RobotSites,
   RobotGeoms,
   RobotKeyframes,
+  RobotCameras,
+  SplatEnvironmentReadinessStatus,
 } from './types';
 
 // Re-export MuJoCo types for convenience