mujoco-react 8.9.1 → 8.10.0

package/README.md

@@ -32,7 +32,6 @@ export default defineConfig({
     mujocoReact({
       models: {
         franka: "models/panda/scene.xml",
-        spot: "models/spot/scene.xml",
       },
     }),
   ],
@@ -57,15 +56,6 @@ const generatedRobotResources = {
     geoms: { floor: "floor" },
     keyframes: { home: "home" },
   },
-  spot: {
-    actuators: { fl_hx: "fl_hx", fl_hy: "fl_hy", fl_kn: "fl_kn" },
-    sensors: {},
-    bodies: { body: "body", fl_hip: "fl_hip", fl_uleg: "fl_uleg" },
-    joints: { fl_hx: "fl_hx", fl_hy: "fl_hy", fl_kn: "fl_kn" },
-    sites: {},
-    geoms: { floor: "floor" },
-    keyframes: { home: "home" },
-  },
 };
 
 registerRobotResources(generatedRobotResources);
@@ -82,19 +72,10 @@ declare module "mujoco-react" {
         geoms: "floor";
         keyframes: "home";
       };
-      spot: {
-        actuators: "fl_hx" | "fl_hy" | "fl_kn";
-        sensors: never;
-        bodies: "body" | "fl_hip" | "fl_uleg";
-        joints: "fl_hx" | "fl_hy" | "fl_kn";
-        sites: never;
-        geoms: "floor";
-        keyframes: "home";
-      };
     };
-    actuators: "joint1" | "joint2" | "joint3" | "gripper" | "fl_hx" | "fl_hy" | "fl_kn";
+    actuators: "joint1" | "joint2" | "joint3" | "gripper";
     sensors: "force_sensor" | "torque_sensor";
-    bodies: "link0" | "link1" | "hand" | "body" | "fl_hip" | "fl_uleg";
+    bodies: "link0" | "link1" | "hand";
   }
 }
 ```
@@ -104,7 +85,7 @@ Once generated, hooks like `useCtrl`, `useSensor`, `useBodyState`, and API metho
 Non-Vite projects can generate the same file with:
 
 ```bash
-npx mujoco-react codegen franka=models/panda/scene.xml spot=models/spot/scene.xml
+npx mujoco-react codegen franka=models/panda/scene.xml
 ```
 
 ## Load a Model
@@ -160,6 +141,50 @@ Use it as a child of `<MujocoCanvas>`:
 </MujocoCanvas>
 ```
 
+## Gaussian Splat Environments
+
+Gaussian splats are visual context; MuJoCo XML remains the source of physics, contacts, and task fixtures. Pair each splat asset with collision proxy metadata so scene variants, rollouts, and datasets preserve both sides of the environment.
+
+Use the renderer-agnostic boundary from the main package:
+
+```tsx
+import { SplatEnvironment } from "mujoco-react";
+
+<SplatEnvironment
+  src="/models/lab/scene.spz"
+  format="spz"
+  collisionProxyMetadata={{
+    xmlPath: "/models/lab/collision.xml",
+    status: "validated",
+    primitives: ["plane", "box"],
+  }}
+/>;
+```
+
+For first-class Spark rendering, install Spark and import the optional adapter:
+
+```bash
+npm install @sparkjsdev/spark
+```
+
+```tsx
+import { SparkSplatEnvironment } from "mujoco-react/spark";
+
+<MujocoCanvas config={sceneConfig} gl={{ preserveDrawingBuffer: true }}>
+  <SparkSplatEnvironment
+    src="/models/lab/scene.spz"
+    format="spz"
+    collisionProxyMetadata={{
+      xmlPath: "/models/lab/collision.xml",
+      status: "validated",
+      primitives: ["plane", "box"],
+    }}
+    hideGroundMeshes
+    onStatusChange={(status) => console.log(status)}
+  />
+</MujocoCanvas>;
+```
+
 ## Write Controllers
 
 ```tsx

package/bin/mujoco-react.mjs

@@ -6,7 +6,7 @@ import { generateMujocoRegister } from '../dist/vite.js';
 const usage = `
 Usage:
   mujoco-react codegen <scene.xml> [...more.xml] [--out src/mujoco-register.gen.ts] [--watch]
-  mujoco-react codegen franka=models/panda/scene.xml spot=models/spot/scene.xml
+  mujoco-react codegen franka=models/panda/scene.xml
 
 Vite users usually do not need this command. Prefer:
 

package/dist/chunk-KGFRKPLS.js

@@ -0,0 +1,186 @@
+import { useMemo } from 'react';
+import * as THREE from 'three';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+
+// src/components/VisualScenario.tsx
+var DEFAULT_BACKGROUND = "#181a1f";
+function ScenarioLighting({
+  preset = "studio",
+  castShadow = true,
+  intensity = 1
+}) {
+  if (preset === "warehouse") {
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("ambientLight", { intensity: 0.18 * intensity }),
+      /* @__PURE__ */ jsx(
+        "directionalLight",
+        {
+          position: [3.5, -2, 5],
+          intensity: 2.2 * intensity,
+          castShadow
+        }
+      ),
+      /* @__PURE__ */ jsx("directionalLight", { position: [-2, 1.5, 2.5], intensity: 0.25 * intensity })
+    ] });
+  }
+  if (preset === "low-light") {
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("ambientLight", { intensity: 0.08 * intensity }),
+      /* @__PURE__ */ jsx(
+        "directionalLight",
+        {
+          position: [2, -2, 3],
+          intensity: 0.75 * intensity,
+          castShadow
+        }
+      ),
+      /* @__PURE__ */ jsx("pointLight", { position: [-0.5, -0.8, 1.3], intensity: 0.6 * intensity })
+    ] });
+  }
+  if (preset === "splat") {
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("ambientLight", { intensity: 0.42 * intensity }),
+      /* @__PURE__ */ jsx(
+        "directionalLight",
+        {
+          position: [1.8, -2.4, 3.5],
+          intensity: 1.2 * intensity,
+          castShadow
+        }
+      ),
+      /* @__PURE__ */ jsx("pointLight", { position: [0.4, 0.2, 1.4], intensity: 0.35 * intensity })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("ambientLight", { intensity: 0.35 * intensity }),
+    /* @__PURE__ */ jsx(
+      "directionalLight",
+      {
+        position: [2.5, -3, 4],
+        intensity: 1.6 * intensity,
+        castShadow
+      }
+    )
+  ] });
+}
+function getScenarioBackground(preset, fallback = DEFAULT_BACKGROUND) {
+  if (preset === "warehouse") return "#20242b";
+  if (preset === "low-light") return "#0f1115";
+  if (preset === "splat") return "#1b1f24";
+  return fallback;
+}
+function getScenarioCameraPosition(basePosition, scenario) {
+  const [x, y, z] = basePosition;
+  const jitter = scenario?.camera?.jitter ?? 0;
+  return [
+    Number((x + jitter * 0.6).toFixed(3)),
+    Number((y - jitter * 0.4).toFixed(3)),
+    Number((z + jitter * 0.25).toFixed(3))
+  ];
+}
+function SplatEnvironment({
+  environment,
+  src,
+  format,
+  collisionProxy,
+  collisionProxyMetadata,
+  children,
+  showPlaceholder = true,
+  ...groupProps
+}) {
+  const metadata = useSplatEnvironment({
+    environment,
+    src,
+    format,
+    collisionProxy: collisionProxyMetadata
+  });
+  const existingUserData = typeof groupProps.userData === "object" && groupProps.userData !== null ? groupProps.userData : {};
+  return /* @__PURE__ */ jsxs(
+    "group",
+    {
+      ...groupProps,
+      userData: {
+        ...existingUserData,
+        ...metadata.userData
+      },
+      children: [
+        children,
+        children || !showPlaceholder ? null : /* @__PURE__ */ jsx(SplatPlaceholder, {}),
+        collisionProxy
+      ]
+    }
+  );
+}
+function useSplatEnvironment({
+  environment,
+  src,
+  format,
+  collisionProxy
+}) {
+  const resolvedSrc = src ?? environment?.splat.src;
+  const resolvedFormat = format ?? environment?.splat.format ?? "spz";
+  const resolvedCollisionProxy = collisionProxy ?? environment?.collisionProxy;
+  return useMemo(
+    () => ({
+      src: resolvedSrc,
+      format: resolvedFormat,
+      collisionProxy: resolvedCollisionProxy,
+      userData: createSplatEnvironmentUserData({
+        environment,
+        src: resolvedSrc,
+        format: resolvedFormat,
+        collisionProxy: resolvedCollisionProxy
+      })
+    }),
+    [environment, resolvedSrc, resolvedFormat, resolvedCollisionProxy]
+  );
+}
+function createSplatEnvironmentUserData({
+  environment,
+  src,
+  format = "spz",
+  collisionProxy
+}) {
+  return {
+    role: "splat-environment",
+    environmentId: environment?.id,
+    environmentLabel: environment?.label,
+    splatSrc: src,
+    splatFormat: format,
+    splatRenderer: environment?.splat.renderer,
+    collisionProxyStatus: collisionProxy?.status ?? "missing",
+    collisionProxyXmlPath: collisionProxy?.xmlPath,
+    collisionProxyPrimitives: collisionProxy?.primitives ?? []
+  };
+}
+function createSparkSplatViewerUrl({
+  viewerUrl,
+  splatSrc
+}) {
+  const url = new URL(viewerUrl, "http://mujoco-react.local");
+  url.searchParams.set("splat", splatSrc);
+  return viewerUrl.startsWith("http") ? url.toString() : `${url.pathname}${url.search}`;
+}
+function SplatPlaceholder() {
+  return /* @__PURE__ */ jsx("group", { children: /* @__PURE__ */ jsxs("mesh", { position: [0, 0, 1.2], children: [
+    /* @__PURE__ */ jsx("boxGeometry", { args: [2.4, 2.4, 2.4] }),
+    /* @__PURE__ */ jsx(
+      "meshBasicMaterial",
+      {
+        color: "#8b8b8b",
+        transparent: true,
+        opacity: 0.06,
+        wireframe: true,
+        side: THREE.DoubleSide
+      }
+    )
+  ] }) });
+}
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { ScenarioLighting, SplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, getScenarioBackground, getScenarioCameraPosition, useSplatEnvironment };
+//# sourceMappingURL=chunk-KGFRKPLS.js.map
+//# sourceMappingURL=chunk-KGFRKPLS.js.map

package/dist/chunk-KGFRKPLS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/VisualScenario.tsx"],"names":[],"mappings":"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","file":"chunk-KGFRKPLS.js","sourcesContent":["/**\n * @license\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport type { ThreeElements } from '@react-three/fiber';\nimport type { ReactNode } from 'react';\nimport { useMemo } from 'react';\nimport * as THREE from 'three';\nimport type {\n  PairedSplatEnvironmentConfig,\n  SplatCollisionProxyConfig,\n  SplatEnvironmentMetadata,\n  SplatEnvironmentMetadataInput,\n  SplatFormat,\n  ScenarioLightingPreset,\n  ScenarioLightingProps,\n  SplatEnvironmentProps,\n  VisualScenarioConfig,\n} from '../types';\n\nconst DEFAULT_BACKGROUND = '#181a1f';\n\nexport function ScenarioLighting({\n  preset = 'studio',\n  castShadow = true,\n  intensity = 1,\n}: ScenarioLightingProps) {\n  if (preset === 'warehouse') {\n    return (\n      <>\n        <ambientLight intensity={0.18 * intensity} />\n        <directionalLight\n          position={[3.5, -2, 5]}\n          intensity={2.2 * intensity}\n          castShadow={castShadow}\n        />\n        <directionalLight position={[-2, 1.5, 2.5]} intensity={0.25 * intensity} />\n      </>\n    );\n  }\n\n  if (preset === 'low-light') {\n    return (\n      <>\n        <ambientLight intensity={0.08 * intensity} />\n        <directionalLight\n          position={[2, -2, 3]}\n          intensity={0.75 * intensity}\n          castShadow={castShadow}\n        />\n        <pointLight position={[-0.5, -0.8, 1.3]} intensity={0.6 * intensity} />\n      </>\n    );\n  }\n\n  if (preset === 'splat') {\n    return (\n      <>\n        <ambientLight intensity={0.42 * intensity} />\n        <directionalLight\n          position={[1.8, -2.4, 3.5]}\n          intensity={1.2 * intensity}\n          castShadow={castShadow}\n        />\n        <pointLight position={[0.4, 0.2, 1.4]} intensity={0.35 * intensity} />\n      </>\n    );\n  }\n\n  return (\n    <>\n      <ambientLight intensity={0.35 * intensity} />\n      <directionalLight\n        position={[2.5, -3, 4]}\n        intensity={1.6 * intensity}\n        castShadow={castShadow}\n      />\n    </>\n  );\n}\n\nexport function getScenarioBackground(\n  preset: ScenarioLightingPreset | undefined,\n  fallback = DEFAULT_BACKGROUND\n) {\n  if (preset === 'warehouse') return '#20242b';\n  if (preset === 'low-light') return '#0f1115';\n  if (preset === 'splat') return '#1b1f24';\n  return fallback;\n}\n\nexport function getScenarioCameraPosition(\n  basePosition: readonly [number, number, number],\n  scenario?: Pick<VisualScenarioConfig, 'camera'>\n): [number, number, number] {\n  const [x, y, z] = basePosition;\n  const jitter = scenario?.camera?.jitter ?? 0;\n\n  return [\n    Number((x + jitter * 0.6).toFixed(3)),\n    Number((y - jitter * 0.4).toFixed(3)),\n    Number((z + jitter * 0.25).toFixed(3)),\n  ];\n}\n\n/**\n * Renderer-agnostic Gaussian splat environment boundary.\n *\n * This component intentionally does not import a specific 3DGS renderer. Pass a\n * Spark/GaussianSplats3D object as `children` once the app chooses a renderer,\n * and pass MuJoCo/MJCF collision proxy visuals via `collisionProxy`.\n */\nexport function SplatEnvironment({\n  environment,\n  src,\n  format,\n  collisionProxy,\n  collisionProxyMetadata,\n  children,\n  showPlaceholder = true,\n  ...groupProps\n}: SplatEnvironmentProps) {\n  const metadata = useSplatEnvironment({\n    environment,\n    src,\n    format,\n    collisionProxy: collisionProxyMetadata,\n  });\n  const existingUserData =\n    typeof groupProps.userData === 'object' && groupProps.userData !== null\n      ? groupProps.userData\n      : {};\n\n  return (\n    <group\n      {...groupProps}\n      userData={{\n        ...existingUserData,\n        ...metadata.userData,\n      }}\n    >\n      {children}\n      {children || !showPlaceholder ? null : <SplatPlaceholder />}\n      {collisionProxy}\n    </group>\n  );\n}\n\nexport function useSplatEnvironment({\n  environment,\n  src,\n  format,\n  collisionProxy,\n}: SplatEnvironmentMetadataInput): SplatEnvironmentMetadata {\n  const resolvedSrc = src ?? environment?.splat.src;\n  const resolvedFormat = format ?? environment?.splat.format ?? 'spz';\n  const resolvedCollisionProxy = collisionProxy ?? environment?.collisionProxy;\n\n  return useMemo(\n    () => ({\n      src: resolvedSrc,\n      format: resolvedFormat,\n      collisionProxy: resolvedCollisionProxy,\n      userData: createSplatEnvironmentUserData({\n        environment,\n        src: resolvedSrc,\n        format: resolvedFormat,\n        collisionProxy: resolvedCollisionProxy,\n      }),\n    }),\n    [environment, resolvedSrc, resolvedFormat, resolvedCollisionProxy]\n  );\n}\n\nexport function createSplatEnvironmentUserData({\n  environment,\n  src,\n  format = 'spz',\n  collisionProxy,\n}: {\n  environment?: PairedSplatEnvironmentConfig;\n  src?: string;\n  format?: SplatFormat;\n  collisionProxy?: SplatCollisionProxyConfig;\n}) {\n  return {\n    role: 'splat-environment',\n    environmentId: environment?.id,\n    environmentLabel: environment?.label,\n    splatSrc: src,\n    splatFormat: format,\n    splatRenderer: environment?.splat.renderer,\n    collisionProxyStatus: collisionProxy?.status ?? 'missing',\n    collisionProxyXmlPath: collisionProxy?.xmlPath,\n    collisionProxyPrimitives: collisionProxy?.primitives ?? [],\n  };\n}\n\nexport function createSparkSplatViewerUrl({\n  viewerUrl,\n  splatSrc,\n}: {\n  viewerUrl: string;\n  splatSrc: string;\n}) {\n  const url = new URL(viewerUrl, 'http://mujoco-react.local');\n  url.searchParams.set('splat', splatSrc);\n  return viewerUrl.startsWith('http') ? url.toString() : `${url.pathname}${url.search}`;\n}\n\nfunction SplatPlaceholder() {\n  return (\n    <group>\n      <mesh position={[0, 0, 1.2]}>\n        <boxGeometry args={[2.4, 2.4, 2.4]} />\n        <meshBasicMaterial\n          color=\"#8b8b8b\"\n          transparent\n          opacity={0.06}\n          wireframe\n          side={THREE.DoubleSide}\n        />\n      </mesh>\n    </group>\n  );\n}\n\nexport type SplatCollisionProxy = ReactNode | ThreeElements['group'];\n"]}