mujoco-react 9.1.0 → 9.3.0

package/README.md

@@ -165,11 +165,24 @@ visual scenarios as data, pass the scenario directly; the component resolves the
 splat asset and paired MJCF collision proxy metadata for you.
 
 ```tsx
-import { SplatEnvironment, withSplatEnvironment } from "mujoco-react";
+import { MujocoCanvas, SplatEnvironment, useSplatSceneConfig } from "mujoco-react";
 
-<SplatEnvironment scenario={scenario} renderer="custom" />;
+const splat = useSplatSceneConfig({ sceneConfig, scenario });
+
+<MujocoCanvas config={splat.sceneConfig}>
+  {splat.environment ? (
+    <SplatEnvironment environment={splat.environment} renderer="custom">
+      <MySplatRenderer src={splat.environment.splat.src} />
+    </SplatEnvironment>
+  ) : null}
+</MujocoCanvas>;
 ```
 
+Use `splat.readiness` or `getSplatEnvironmentReadiness(scenario)` to gate
+authoring and import flows. The status distinguishes disabled scenarios,
+missing splat assets, missing MJCF collision proxies, unsupported Spark formats,
+and ready paired environments.
+
 For MuJoCo + 3DGS composition, derive the collision environment from the same
 splat metadata and pass the resulting config to `<MujocoCanvas>`:
 
@@ -192,16 +205,18 @@ npm install @sparkjsdev/spark
 ```tsx
 import {
   SparkSplatEnvironment,
-  useSparkSplatLifecycle,
+  useSparkSplatEnvironment,
 } from "mujoco-react/spark";
 
 function Scene() {
-  const splat = useSparkSplatLifecycle();
+  const splat = useSparkSplatEnvironment({ sceneConfig, scenario });
 
   return (
-    <MujocoCanvas config={sceneConfig} gl={{ preserveDrawingBuffer: true }}>
-      <SparkSplatEnvironment scenario={scenario} hideGroundMeshes {...splat.props} />
-      <StatusBadge status={splat.status} error={splat.error} />
+    <MujocoCanvas config={splat.sceneConfig} gl={{ preserveDrawingBuffer: true }}>
+      {splat.environment ? (
+        <SparkSplatEnvironment hideGroundMeshes {...splat.props} />
+      ) : null}
+      <StatusBadge status={splat.lifecycle.status} error={splat.lifecycle.error} />
     </MujocoCanvas>
   );
 }
@@ -213,18 +228,20 @@ function Scene() {
 ## Write Controllers
 
 ```tsx
-import { useBeforePhysicsStep } from "mujoco-react";
+import { RobotActuators, useBeforePhysicsStep, useCtrl } from "mujoco-react";
 
 function MyController() {
+  const shoulder = useCtrl(RobotActuators.franka.actuator1);
+
   useBeforePhysicsStep(({ data }) => {
-    data.ctrl[0] = Math.sin(data.time);
+    shoulder.write(Math.sin(data.time));
   });
 
   return null;
 }
 ```
 
-Controllers are just React children that read sensors, write `data.ctrl`, apply forces, or call the `MujocoSimAPI` at physics-step time.
+Controllers are just React children that read sensors, write named controls, apply forces, or call the `MujocoSimAPI` at physics-step time.
 
 With generated resource values, reusable controllers can be scoped to one robot without hand-typing names:
 
@@ -388,15 +405,20 @@ function useWebSocketControls(url: string) {
 For reusable controllers with typed config, default merging, and children, use the `createController` factory:
 
 ```tsx
-import { createController, useCtrl, useBeforePhysicsStep } from "mujoco-react";
+import {
+  RobotActuators,
+  createController,
+  useBeforePhysicsStep,
+  useCtrl,
+} from "mujoco-react";
 
 export const MyController = createController<{ gain: number }>(
   { name: "MyController", defaultConfig: { gain: 1.0 } },
   ({ config, children }) => {
-    const shoulder = useCtrl("shoulder");
+    const shoulder = useCtrl(RobotActuators.franka.actuator1);
 
-    useBeforePhysicsStep(() => {
-      shoulder.write(config.gain * Math.sin(Date.now() / 1000));
+    useBeforePhysicsStep(({ data }) => {
+      shoulder.write(config.gain * Math.sin(data.time));
     });
 
     return <>{children}</>;
@@ -826,8 +848,12 @@ if (mujoco) {
 Run logic **before** `mj_step` each frame. Write to `data.ctrl`, apply forces, drive automation.
 
 ```tsx
+import { RobotActuators, useBeforePhysicsStep, useCtrl } from "mujoco-react";
+
+const shoulder = useCtrl(RobotActuators.franka.actuator1);
+
 useBeforePhysicsStep(({ data }) => {
-  data.ctrl[0] = Math.sin(data.time);
+  shoulder.write(Math.sin(data.time));
 });
 ```
 
@@ -861,8 +887,8 @@ Read sensor values by name. Returns a `SensorHandle` with `read()`, `dim`, and `
 ```tsx
 import { RobotSensors, useSensor } from "mujoco-react";
 
-const force = useSensor(RobotSensors.franka.force_sensor);
-// force.read() -> Float64Array, force.dim -> number
+const imu = useSensor(RobotSensors.g1["imu-torso-angular-velocity"]);
+// imu.read() -> Float64Array, imu.dim -> number
 ```
 
 ### `useBodyState(name)`
@@ -997,6 +1023,84 @@ const blob = await apiRef.current?.captureFrameBlob({ type: "image/png" });
 Use `useFrameCapture()` or the standalone `captureFrame()` helpers when you own
 the canvas or want to capture a custom container.
 
+Use `captureCameraFrame()` / `captureCameraFrameBlob()` when dataset generation
+needs an offscreen camera render at a stable resolution without moving the
+user's interactive viewport. Pass `cameraName`, `siteName`, or `bodyName` to
+record true MuJoCo-mounted camera frames; the returned image includes
+`source.kind` so dataset pipelines can reject fallback or synthetic fixed poses.
+
+Use `recordCameraSequence()` / `useCameraSequenceRecorder()` to step policy
+rollouts and capture synchronized per-camera frames from one or more MuJoCo
+camera configs. Sequence recording requires mounted MuJoCo camera, site, or
+body selectors by default; use still capture APIs for synthetic debug poses.
+
+For LeRobot-style datasets, prefer the named-camera wrapper. It resolves task
+camera keys to MuJoCo cameras/sites/bodies, records the sequence, and returns
+the plan and readiness summary alongside frame provenance:
+
+```tsx
+const sequence = await recordMountedCameraFrameSequence(api, {
+  cameraKeys: ["head", "left_wrist", "right_wrist"],
+  aliases: {
+    head: [{ siteName: "head_camera_rgb_optical_frame" }],
+    left_wrist: [{ siteName: "left_wrist_camera_optical_frame" }],
+    right_wrist: [{ siteName: "right_wrist_camera_optical_frame" }],
+  },
+  defaults: {
+    width: 640,
+    height: 480,
+    type: "image/png",
+    fov: 45,
+    near: 0.01,
+    far: 100,
+  },
+  frames: 16,
+  stepsPerFrame: 1,
+  retainFrames: false,
+  requireMountedSources: true,
+  onFrame: ({ frameIndex, cameras }) => {
+    queueLeRobotImages(frameIndex, cameras);
+  },
+});
+
+sequence.readiness.ready; // true when every requested stream resolved
+sequence.plan.missingKeys; // unresolved task cameras, if requireAll is false
+sequence.cameraSummaries.head.source; // mounted source provenance
+```
+
+`recordMountedCameraFrameSequence()` requires all requested `cameraKeys` by
+default so dataset recording cannot silently omit a camera stream. Set
+`requireAll: false` only for exploratory tooling that can tolerate partial
+camera coverage.
+
+Inside `<MujocoCanvas>` children, `useMountedCameraSequenceRecorder()` exposes
+the same planning and recording surface with React status/error state.
+
+Use `resolveMountedCameraFrameSource()` when dataset feature names need to map
+to named MuJoCo cameras, sites, or bodies before recording. The helper accepts
+the model resource lists plus app-level aliases and returns both the capture
+selector and the mounted-source provenance that should be stored beside the
+dataset:
+
+```tsx
+const resolved = resolveMountedCameraFrameSource("head", {
+  cameras: api.getCameras(),
+  sites: api.getSites(),
+  bodies: api.getBodies(),
+  aliases: {
+    head: [{ siteName: "head_camera_rgb_optical_frame" }],
+  },
+});
+
+if (!resolved) throw new Error("head does not resolve to a MuJoCo source");
+
+await api.recordCameraSequence({
+  frames: 16,
+  requireMountedSources: true,
+  cameras: [{ key: "head", width: 640, height: 480, ...resolved.selector }],
+});
+```
+
 ### `useCtrlNoise(config)`
 
 Apply Gaussian noise to controls for robustness testing:

package/dist/{chunk-33CV6HSV.js → chunk-T3GVZJ4F.js}

@@ -3,7 +3,88 @@ import { useEffect, useMemo } from 'react';
 import * as THREE from 'three';
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 
-// src/components/VisualScenario.tsx
+// src/types.ts
+var runtimeRobotResources = {};
+var REGISTER_RESOURCE_KEYS = ["actuators", "sensors", "bodies", "joints", "sites", "geoms", "keyframes", "cameras"];
+function createEmptyRuntimeResources() {
+  return {
+    actuators: {},
+    sensors: {},
+    bodies: {},
+    joints: {},
+    sites: {},
+    geoms: {},
+    keyframes: {},
+    cameras: {}
+  };
+}
+function registerRobotResources(resources) {
+  for (const [robot, robotResources] of Object.entries(resources)) {
+    const existing = runtimeRobotResources[robot] ?? createEmptyRuntimeResources();
+    for (const key of REGISTER_RESOURCE_KEYS) {
+      existing[key] = { ...existing[key], ...robotResources[key] ?? {} };
+    }
+    runtimeRobotResources[robot] = existing;
+  }
+}
+function createResourceCategory(key) {
+  return new Proxy({}, {
+    get(_target, robot) {
+      if (typeof robot !== "string") return void 0;
+      return runtimeRobotResources[robot]?.[key] ?? {};
+    },
+    ownKeys() {
+      return Reflect.ownKeys(runtimeRobotResources);
+    },
+    getOwnPropertyDescriptor(_target, robot) {
+      if (typeof robot !== "string" || !(robot in runtimeRobotResources)) return void 0;
+      return { enumerable: true, configurable: true };
+    }
+  });
+}
+var RobotResources = new Proxy(runtimeRobotResources, {
+  get(target, robot) {
+    if (typeof robot !== "string") return void 0;
+    return target[robot] ?? createEmptyRuntimeResources();
+  },
+  ownKeys(target) {
+    return Reflect.ownKeys(target);
+  },
+  getOwnPropertyDescriptor(target, robot) {
+    if (typeof robot !== "string" || !(robot in target)) return void 0;
+    return { enumerable: true, configurable: true };
+  }
+});
+var RobotActuators = createResourceCategory("actuators");
+var RobotSensors = createResourceCategory("sensors");
+var RobotBodies = createResourceCategory("bodies");
+var RobotJoints = createResourceCategory("joints");
+var RobotSites = createResourceCategory("sites");
+var RobotGeoms = createResourceCategory("geoms");
+var RobotKeyframes = createResourceCategory("keyframes");
+var RobotCameras = createResourceCategory("cameras");
+function getContact(contacts, i) {
+  try {
+    return contacts.get(i);
+  } catch {
+    return void 0;
+  }
+}
+function withContacts(data, read) {
+  const contacts = data.contact;
+  try {
+    return read(contacts);
+  } finally {
+    contacts.delete?.();
+  }
+}
+var SplatEnvironmentReadinessStatus = {
+  Disabled: "disabled",
+  MissingSplat: "missing-splat",
+  MissingCollisionProxy: "missing-collision-proxy",
+  UnsupportedFormat: "unsupported-format",
+  Ready: "ready"
+};
 var DEFAULT_BACKGROUND = "#181a1f";
 function ScenarioLighting({
   preset = "studio",
@@ -205,21 +286,151 @@ function useSplatEnvironment({
   const resolvedSrc = src ?? scenarioEnvironment?.splat.src ?? scenario?.splat?.src;
   const resolvedFormat = format ?? scenarioEnvironment?.splat.format ?? scenario?.splat?.format ?? "spz";
   const resolvedCollisionProxy = collisionProxy ?? scenarioEnvironment?.collisionProxy ?? scenario?.splat?.collisionProxy ?? void 0;
+  const readiness = useMemo(
+    () => getSplatEnvironmentReadiness({
+      environment: scenarioEnvironment,
+      scenario,
+      renderer,
+      src: resolvedSrc,
+      format: resolvedFormat,
+      collisionProxy: resolvedCollisionProxy
+    }),
+    [
+      collisionProxy,
+      renderer,
+      resolvedCollisionProxy,
+      resolvedFormat,
+      resolvedSrc,
+      scenario,
+      scenarioEnvironment
+    ]
+  );
   return useMemo(
     () => ({
       src: resolvedSrc,
       format: resolvedFormat,
       collisionProxy: resolvedCollisionProxy,
+      readiness,
       userData: createSplatEnvironmentUserData({
         environment: scenarioEnvironment,
         src: resolvedSrc,
         format: resolvedFormat,
-        collisionProxy: resolvedCollisionProxy
+        collisionProxy: resolvedCollisionProxy,
+        readiness
       })
     }),
-    [scenarioEnvironment, resolvedSrc, resolvedFormat, resolvedCollisionProxy]
+    [
+      scenarioEnvironment,
+      resolvedSrc,
+      resolvedFormat,
+      resolvedCollisionProxy,
+      readiness
+    ]
+  );
+}
+function useSplatSceneConfig({
+  sceneConfig,
+  scenario,
+  environment,
+  enabled = true,
+  renderer
+}) {
+  const resolvedEnvironment = useMemo(
+    () => enabled ? environment ?? (scenario ? createPairedSplatEnvironment(scenario, { renderer }) : void 0) : void 0,
+    [enabled, environment, renderer, scenario]
+  );
+  const readiness = useMemo(
+    () => getSplatEnvironmentReadiness({
+      environment: resolvedEnvironment,
+      scenario,
+      renderer,
+      enabled
+    }),
+    [enabled, renderer, resolvedEnvironment, scenario]
+  );
+  const resolvedSceneConfig = useMemo(
+    () => resolvedEnvironment ? withSplatEnvironment(sceneConfig, resolvedEnvironment) : sceneConfig,
+    [resolvedEnvironment, sceneConfig]
+  );
+  return useMemo(
+    () => ({
+      environment: resolvedEnvironment,
+      sceneConfig: resolvedSceneConfig,
+      enabled: enabled && readiness.status !== SplatEnvironmentReadinessStatus.Disabled,
+      readiness
+    }),
+    [enabled, readiness, resolvedEnvironment, resolvedSceneConfig]
   );
 }
+function getSplatEnvironmentReadiness({
+  environment,
+  scenario,
+  renderer,
+  src,
+  format,
+  collisionProxy,
+  enabled = true
+}) {
+  const splat = scenario?.splat;
+  const resolvedSrc = src ?? environment?.splat.src ?? splat?.src;
+  const resolvedFormat = format ?? environment?.splat.format ?? splat?.format ?? "spz";
+  const resolvedRenderer = renderer ?? environment?.splat.renderer;
+  const resolvedCollisionProxy = collisionProxy ?? environment?.collisionProxy ?? splat?.collisionProxy ?? void 0;
+  const requiresCollisionProxy = splat?.requiresCollisionProxy ?? true;
+  if (!enabled || splat && splat.enabled === false && !environment) {
+    return {
+      status: SplatEnvironmentReadinessStatus.Disabled,
+      ready: false,
+      requiresCollisionProxy,
+      missing: [],
+      format: resolvedFormat,
+      renderer: resolvedRenderer,
+      message: "Splat environment is disabled."
+    };
+  }
+  if (!resolvedSrc) {
+    return {
+      status: SplatEnvironmentReadinessStatus.MissingSplat,
+      ready: false,
+      requiresCollisionProxy,
+      missing: ["splat"],
+      format: resolvedFormat,
+      renderer: resolvedRenderer,
+      message: "Splat environment is missing a visual asset source."
+    };
+  }
+  if (resolvedRenderer === "spark" && resolvedFormat !== "spz") {
+    return {
+      status: SplatEnvironmentReadinessStatus.UnsupportedFormat,
+      ready: false,
+      requiresCollisionProxy,
+      missing: [],
+      format: resolvedFormat,
+      renderer: resolvedRenderer,
+      message: `Spark splat rendering requires .spz assets; received ${resolvedFormat}.`
+    };
+  }
+  if (requiresCollisionProxy && !resolvedCollisionProxy?.xmlPath) {
+    return {
+      status: SplatEnvironmentReadinessStatus.MissingCollisionProxy,
+      ready: false,
+      requiresCollisionProxy,
+      missing: ["collisionProxy"],
+      format: resolvedFormat,
+      renderer: resolvedRenderer,
+      message: "Splat environment is missing paired MJCF collision proxy XML."
+    };
+  }
+  return {
+    status: SplatEnvironmentReadinessStatus.Ready,
+    ready: true,
+    requiresCollisionProxy,
+    missing: [],
+    format: resolvedFormat,
+    renderer: resolvedRenderer,
+    message: requiresCollisionProxy ? "Splat environment has visual asset and collision proxy metadata." : "Splat environment has a visual asset and does not require collision proxy metadata."
+  };
+}
 function createPairedSplatEnvironment(scenario, options = {}) {
   const splat = scenario.splat;
   const collisionProxy = splat?.collisionProxy;
@@ -277,7 +488,8 @@ function createSplatEnvironmentUserData({
   environment,
   src,
   format = "spz",
-  collisionProxy
+  collisionProxy,
+  readiness
 }) {
   return {
     role: "splat-environment",
@@ -288,7 +500,9 @@ function createSplatEnvironmentUserData({
     splatRenderer: environment?.splat.renderer,
     collisionProxyStatus: collisionProxy?.status ?? "missing",
     collisionProxyXmlPath: collisionProxy?.xmlPath,
-    collisionProxyPrimitives: collisionProxy?.primitives ?? []
+    collisionProxyPrimitives: collisionProxy?.primitives ?? [],
+    readinessStatus: readiness?.status,
+    readinessMessage: readiness?.message
   };
 }
 function createSparkSplatViewerUrl({
@@ -395,6 +609,6 @@ function clamp01(value) {
  * SPDX-License-Identifier: Apache-2.0
  */
 
-export { ScenarioLighting, SplatEnvironment, VisualScenarioEffects, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, getScenarioBackground, getScenarioCameraPosition, useSplatEnvironment, useVisualScenarioEffects, withSplatEnvironment };
-//# sourceMappingURL=chunk-33CV6HSV.js.map
-//# sourceMappingURL=chunk-33CV6HSV.js.map
+export { RobotActuators, RobotBodies, RobotCameras, RobotGeoms, RobotJoints, RobotKeyframes, RobotResources, RobotSensors, RobotSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, registerRobotResources, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, withContacts, withSplatEnvironment };
+//# sourceMappingURL=chunk-T3GVZJ4F.js.map
+//# sourceMappingURL=chunk-T3GVZJ4F.js.map