mujoco-react 9.3.0 → 9.4.0

package/src/components/VisualScenario.tsx

@@ -26,6 +26,8 @@ import type {
   ScenarioLightingProps,
   SplatEnvironmentProps,
   VisualScenarioConfig,
+  VisualScenarioExecutionContext,
+  VisualScenarioExecutionContextInput,
   VisualScenarioEffectsProps,
 } from '../types';
 
@@ -114,6 +116,84 @@ export function getScenarioCameraPosition(
   ];
 }
 
+export function useVisualScenarioExecutionContext({
+  scenario,
+  environment,
+  renderer,
+  variantId,
+  enabled,
+}: VisualScenarioExecutionContextInput): VisualScenarioExecutionContext {
+  return useMemo(
+    () =>
+      createVisualScenarioExecutionContext({
+        scenario,
+        environment,
+        renderer,
+        variantId,
+        enabled,
+      }),
+    [enabled, environment, renderer, scenario, variantId]
+  );
+}
+
+export function createVisualScenarioExecutionContext({
+  scenario,
+  environment,
+  renderer,
+  variantId,
+  enabled = true,
+}: VisualScenarioExecutionContextInput): VisualScenarioExecutionContext {
+  const pairedEnvironment =
+    environment ??
+    (scenario ? createPairedSplatEnvironment(scenario, { renderer }) : undefined);
+  const splat = scenario?.splat;
+  const collisionProxy =
+    pairedEnvironment?.collisionProxy ?? splat?.collisionProxy ?? undefined;
+  const readiness = getSplatEnvironmentReadiness({
+    environment: pairedEnvironment,
+    scenario,
+    renderer,
+    enabled,
+  });
+  const format =
+    pairedEnvironment?.splat.format ?? splat?.format ?? readiness.format ?? 'spz';
+
+  return {
+    scenarioId: scenario?.id ?? pairedEnvironment?.id ?? 'visual-scenario',
+    scenarioLabel:
+      scenario?.label ?? pairedEnvironment?.label ?? 'Visual scenario',
+    variantId,
+    seed: scenario?.seed ?? 0,
+    lighting: scenario?.lighting ?? 'studio',
+    environment: scenario?.environment,
+    camera: {
+      jitter: scenario?.camera?.jitter ?? 0,
+      exposure: scenario?.camera?.exposure ?? 1,
+      noise: scenario?.camera?.noise ?? 0,
+      blur: scenario?.camera?.blur ?? 0,
+    },
+    materials: {
+      randomizeObjectColors: Boolean(
+        scenario?.materials?.randomizeObjectColors
+      ),
+      randomizeTableMaterial: Boolean(
+        scenario?.materials?.randomizeTableMaterial
+      ),
+      roughness: scenario?.materials?.roughness,
+      metalness: scenario?.materials?.metalness,
+    },
+    splatEnabled: Boolean(splat?.enabled || pairedEnvironment),
+    splatSrc: pairedEnvironment?.splat.src ?? splat?.src,
+    splatFormat: format,
+    splatRenderer: renderer ?? pairedEnvironment?.splat.renderer,
+    collisionProxyXmlPath: collisionProxy?.xmlPath,
+    collisionProxyStatus: collisionProxy?.status,
+    collisionProxyPrimitives: collisionProxy?.primitives ?? [],
+    readiness,
+    transformSource: 'visualScenario.camera',
+  };
+}
+
 export function VisualScenarioEffects(props: VisualScenarioEffectsProps) {
   useVisualScenarioEffects(props);
   return null;
@@ -341,43 +421,55 @@ export function useSplatSceneConfig({
   enabled = true,
   renderer,
 }: SplatSceneConfigInput): SplatSceneConfigState {
-  const resolvedEnvironment = useMemo(
-    () =>
-      enabled
-        ? environment ??
-          (scenario
-            ? createPairedSplatEnvironment(scenario, { renderer })
-            : undefined)
-        : undefined,
-    [enabled, environment, renderer, scenario]
-  );
-  const readiness = useMemo(
+  return useMemo(
     () =>
-      getSplatEnvironmentReadiness({
-        environment: resolvedEnvironment,
+      createSplatSceneConfig({
+        sceneConfig,
         scenario,
-        renderer,
+        environment,
         enabled,
+        renderer,
       }),
-    [enabled, renderer, resolvedEnvironment, scenario]
-  );
-  const resolvedSceneConfig = useMemo(
-    () =>
-      resolvedEnvironment
-        ? withSplatEnvironment(sceneConfig, resolvedEnvironment)
-        : sceneConfig,
-    [resolvedEnvironment, sceneConfig]
+    [enabled, environment, renderer, scenario, sceneConfig]
   );
+}
 
-  return useMemo(
-    () => ({
-      environment: resolvedEnvironment,
-      sceneConfig: resolvedSceneConfig,
-      enabled: enabled && readiness.status !== SplatEnvironmentReadinessStatus.Disabled,
-      readiness,
-    }),
-    [enabled, readiness, resolvedEnvironment, resolvedSceneConfig]
-  );
+/**
+ * Resolve a visual scenario's paired splat environment without requiring React.
+ *
+ * Use this in codegen, import validators, backend handoff metadata, or app code
+ * that needs the same behavior as `useSplatSceneConfig` outside a component.
+ */
+export function createSplatSceneConfig({
+  sceneConfig,
+  scenario,
+  environment,
+  enabled = true,
+  renderer,
+}: SplatSceneConfigInput): SplatSceneConfigState {
+  const resolvedEnvironment = enabled
+    ? environment ??
+      (scenario
+        ? createPairedSplatEnvironment(scenario, { renderer })
+        : undefined)
+    : undefined;
+  const readiness = getSplatEnvironmentReadiness({
+    environment: resolvedEnvironment,
+    scenario,
+    renderer,
+    enabled,
+  });
+  const resolvedSceneConfig = resolvedEnvironment
+    ? withSplatEnvironment(sceneConfig, resolvedEnvironment, { renderer })
+    : sceneConfig;
+
+  return {
+    environment: resolvedEnvironment,
+    sceneConfig: resolvedSceneConfig,
+    enabled:
+      enabled && readiness.status !== SplatEnvironmentReadinessStatus.Disabled,
+    readiness,
+  };
 }
 
 export function getSplatEnvironmentReadiness({
@@ -468,9 +560,9 @@ export function getSplatEnvironmentReadiness({
 }
 
 /**
- * Convert a generic visual scenario splat block into a paired visual/physics
- * environment config. Returns undefined until both the splat asset and MJCF
- * collision proxy are present.
+ * Convert a generic visual scenario splat block into a composable splat
+ * environment config. Visual-only splats are valid; readiness reports whether
+ * a paired MJCF collision proxy is required before training/physics handoff.
  */
 export function createPairedSplatEnvironment(
   scenario: Pick<VisualScenarioConfig, 'id' | 'label' | 'environment' | 'splat'>,
@@ -484,7 +576,7 @@ export function createPairedSplatEnvironment(
   const splat = scenario.splat;
   const collisionProxy = splat?.collisionProxy;
 
-  if (!splat?.enabled || !splat.src || !collisionProxy?.xmlPath) {
+  if (!splat?.enabled || !splat.src) {
     return undefined;
   }
 
@@ -501,15 +593,22 @@ export function createPairedSplatEnvironment(
       format: splat.format ?? 'spz',
       renderer: options.renderer,
     },
-    collisionProxy: {
-      ...collisionProxy,
-      xmlPath: collisionProxy.xmlPath,
-    },
+    collisionProxy: collisionProxy?.xmlPath
+      ? {
+          ...collisionProxy,
+          xmlPath: collisionProxy.xmlPath,
+        }
+      : undefined,
   };
 }
 
 function isPairedSplatEnvironment(input: SplatSceneInput): input is PairedSplatEnvironmentConfig {
-  return !!input && 'collisionProxy' in input && 'splat' in input;
+  return (
+    !!input &&
+    'splat' in input &&
+    !!input.splat &&
+    !('enabled' in input.splat)
+  );
 }
 
 function sceneRelativePath(sceneConfig: SceneConfig, path: string): string {
@@ -549,7 +648,7 @@ export function withSplatEnvironment(
     : input
       ? createPairedSplatEnvironment(input, options)
       : undefined;
-  const xmlPath = environment?.collisionProxy.xmlPath;
+  const xmlPath = environment?.collisionProxy?.xmlPath;
   if (!xmlPath) return sceneConfig;
 
   return {

package/src/core/MujocoSimProvider.tsx

@@ -1471,7 +1471,7 @@ export function MujocoSimProvider({
 
           const frame = {
             frameIndex,
-            time: getTime(),
+            time: data.time,
             cameras: cameraFrames,
           };
           if (retainFrames) {

package/src/hooks/useMountedCameraSequenceRecorder.ts

@@ -8,10 +8,12 @@
 import { useCallback, useState } from 'react';
 import { useMujoco } from '../core/MujocoSimProvider';
 import {
+  createMountedCameraFrameSequenceReadiness,
   createMountedCameraFrameSequencePlanFromApi,
   recordMountedCameraFrameSequence,
   type MountedCameraFrameSequencePlan,
   type MountedCameraFrameSequencePlanOptions,
+  type MountedCameraFrameSequenceReadiness,
   type MountedCameraFrameSequenceRecordOptions,
   type MountedCameraFrameSequenceRecordResult,
 } from '../rendering/cameraFrameSource';
@@ -26,13 +28,22 @@ export type MountedCameraSequenceRecordOptions =
   MountedCameraFrameSequenceRecordOptions;
 export type MountedCameraSequenceRecordResult =
   MountedCameraFrameSequenceRecordResult;
+export type MountedCameraSequenceReadiness =
+  MountedCameraFrameSequenceReadiness;
 
 export interface MountedCameraSequenceRecorderAPI
   extends Omit<CameraFrameSequenceRecorderAPI, 'record'> {
+  plan: MountedCameraFrameSequencePlan | null;
+  readiness: MountedCameraSequenceReadiness | null;
+  result: MountedCameraSequenceRecordResult | null;
   createPlan: (
     cameraKeys: readonly string[],
     options?: MountedCameraSequencePlanOptions
   ) => MountedCameraFrameSequencePlan;
+  checkReadiness: (
+    cameraKeys: readonly string[],
+    options?: MountedCameraSequencePlanOptions
+  ) => MountedCameraSequenceReadiness;
   record: (
     options: MountedCameraSequenceRecordOptions
   ) => Promise<MountedCameraSequenceRecordResult>;
@@ -44,10 +55,19 @@ export function useMountedCameraSequenceRecorder(
   const mujoco = useMujoco();
   const [status, setStatus] = useState<FrameCaptureStatus>('idle');
   const [error, setError] = useState<Error | null>(null);
+  const [plan, setPlan] = useState<MountedCameraFrameSequencePlan | null>(null);
+  const [readiness, setReadiness] =
+    useState<MountedCameraSequenceReadiness | null>(null);
+  const [result, setResult] = useState<MountedCameraSequenceRecordResult | null>(
+    null
+  );
 
   const reset = useCallback(() => {
     setStatus('idle');
     setError(null);
+    setPlan(null);
+    setReadiness(null);
+    setResult(null);
   }, []);
 
   const createPlan = useCallback(
@@ -59,14 +79,34 @@ export function useMountedCameraSequenceRecorder(
         throw new Error('MuJoCo scene is not ready for mounted camera sequence planning.');
       }
 
-      return createMountedCameraFrameSequencePlanFromApi(mujoco.api, cameraKeys, {
-        ...defaultOptions,
-        ...options,
-      });
+      const nextPlan = createMountedCameraFrameSequencePlanFromApi(
+        mujoco.api,
+        cameraKeys,
+        {
+          ...defaultOptions,
+          ...options,
+        }
+      );
+      setPlan(nextPlan);
+      setReadiness(null);
+      return nextPlan;
     },
     [defaultOptions, mujoco.api]
   );
 
+  const checkReadiness = useCallback(
+    (
+      cameraKeys: readonly string[],
+      options: MountedCameraSequencePlanOptions = {}
+    ) => {
+      const nextPlan = createPlan(cameraKeys, options);
+      const nextReadiness = createMountedCameraFrameSequenceReadiness(nextPlan);
+      setReadiness(nextReadiness);
+      return nextReadiness;
+    },
+    [createPlan]
+  );
+
   const record = useCallback(
     async (options: MountedCameraSequenceRecordOptions) => {
       if (!mujoco.api) {
@@ -75,14 +115,18 @@ export function useMountedCameraSequenceRecorder(
 
       setStatus('capturing');
       setError(null);
+      setResult(null);
 
       try {
-        const result = await recordMountedCameraFrameSequence(mujoco.api, {
+        const nextResult = await recordMountedCameraFrameSequence(mujoco.api, {
           ...defaultOptions,
           ...options,
         });
+        setPlan(nextResult.plan);
+        setReadiness(nextResult.readiness);
+        setResult(nextResult);
         setStatus('captured');
-        return result;
+        return nextResult;
       } catch (nextError) {
         const error =
           nextError instanceof Error
@@ -99,8 +143,12 @@ export function useMountedCameraSequenceRecorder(
   return {
     status,
     error,
+    plan,
+    readiness,
+    result,
     isRecording: status === 'capturing',
     createPlan,
+    checkReadiness,
     record,
     reset,
   };

package/src/index.ts

@@ -48,14 +48,32 @@ export {
   createPairedSplatEnvironment,
   createSparkSplatViewerUrl,
   createSplatEnvironmentUserData,
+  createSplatSceneConfig,
+  createVisualScenarioExecutionContext,
   getSplatEnvironmentReadiness,
   getScenarioBackground,
   getScenarioCameraPosition,
   useSplatEnvironment,
   useSplatSceneConfig,
+  useVisualScenarioExecutionContext,
   useVisualScenarioEffects,
   withSplatEnvironment,
 } from './components/VisualScenario';
+export {
+  canFetchSplatCollisionProxyXml,
+  fetchSplatCollisionProxyXml,
+  parseSplatCollisionProxyGeoms,
+  SplatCollisionProxyPreview,
+  useSplatCollisionProxyGeoms,
+} from './components/SplatCollisionProxyPreview';
+export type {
+  SplatCollisionProxyGeomPreview,
+  SplatCollisionProxyGeomsState,
+  SplatCollisionProxyPreviewProps,
+  SplatCollisionProxyPreviewStatus,
+  SplatCollisionProxyPreviewVector3,
+  UseSplatCollisionProxyGeomsOptions,
+} from './components/SplatCollisionProxyPreview';
 export { Debug } from './components/Debug';
 export { TendonRenderer } from './components/TendonRenderer';
 export { FlexRenderer } from './components/FlexRenderer';
@@ -90,6 +108,7 @@ export { useMountedCameraSequenceRecorder } from './hooks/useMountedCameraSequen
 export type {
   MountedCameraSequencePlanOptions,
   MountedCameraSequenceRecorderAPI,
+  MountedCameraSequenceReadiness,
   MountedCameraSequenceRecordOptions,
   MountedCameraSequenceRecordResult,
 } from './hooks/useMountedCameraSequenceRecorder';
@@ -100,8 +119,12 @@ export {
   renderCameraFrameToCanvas,
 } from './rendering/cameraFrameCapture';
 export {
+  createMountedCameraFrameSequenceManifest,
   createMountedCameraFrameSequenceReadiness,
+  createMountedCameraFrameSourceSuggestions,
+  MountedCameraFrameSequenceManifestStatus,
   MountedCameraFrameSequenceReadinessStatus,
+  MountedCameraFrameSourceSuggestionMatch,
   createMountedCameraFrameSequencePlanFromApi,
   createMountedCameraFrameSequencePlan,
   getCameraFrameCaptureSourceTarget,
@@ -112,8 +135,10 @@ export {
 } from './rendering/cameraFrameSource';
 export type {
   CameraFrameMountSelector,
+  CreateMountedCameraFrameSequenceManifestOptions,
   CreateMountedCameraFrameSequencePlanOptions,
   MountedCameraFrameCaptureSource,
+  MountedCameraFrameSequenceManifest,
   MountedCameraFrameSequencePlanOptions,
   MountedCameraFrameSequenceRecorderTarget,
   MountedCameraFrameSequenceCameraOptions,
@@ -123,6 +148,8 @@ export type {
   MountedCameraFrameSequenceRecordOptions,
   MountedCameraFrameSequenceRecordResult,
   MountedCameraFrameSequenceSourceReadiness,
+  MountedCameraFrameSequenceStreamSummary,
+  MountedCameraFrameSourceSuggestion,
   NamedCameraFrameResource,
   ResolveMountedCameraFrameSourceOptions,
   ResolvedMountedCameraFrameSource,
@@ -214,6 +241,10 @@ export type {
   SplatEnvironmentReadiness,
   SplatEnvironmentMetadataInput,
   SplatEnvironmentMetadata,
+  VisualScenarioExecutionContext,
+  VisualScenarioExecutionContextInput,
+  ResolvedScenarioCameraConfig,
+  ResolvedScenarioMaterialConfig,
   SplatSceneConfigInput,
   SplatSceneConfigState,
   SplatSceneInput,