mujoco-react 8.4.2 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "8.4.2",
+  "version": "8.5.0",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",

package/src/core/ObservationBuilder.ts

@@ -0,0 +1,120 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  Bodies,
+  MujocoData,
+  MujocoModel,
+  ObservationConfig,
+  ObservationLayoutItem,
+  ObservationResult,
+} from '../types';
+import { findBodyByName, findSensorByName, findSiteByName } from './SceneLoader';
+
+function append(
+  values: number[],
+  layout: ObservationLayoutItem[],
+  name: string,
+  chunk: ArrayLike<number>
+) {
+  const start = values.length;
+  for (let i = 0; i < chunk.length; i++) values.push(chunk[i] ?? 0);
+  layout.push({ name, start, size: chunk.length });
+}
+
+function appendScalar(
+  values: number[],
+  layout: ObservationLayoutItem[],
+  name: string,
+  value: number
+) {
+  const start = values.length;
+  values.push(value);
+  layout.push({ name, start, size: 1 });
+}
+
+function namedBodyList(names: Bodies | readonly Bodies[] | undefined): readonly Bodies[] {
+  if (!names) return [];
+  return typeof names === 'string' ? [names] : names;
+}
+
+function normalizedGravity(model: MujocoModel): [number, number, number] {
+  const gx = model.opt.gravity[0] ?? 0;
+  const gy = model.opt.gravity[1] ?? 0;
+  const gz = model.opt.gravity[2] ?? -9.81;
+  const length = Math.hypot(gx, gy, gz);
+  if (length === 0) return [0, 0, 0];
+  return [gx / length, gy / length, gz / length];
+}
+
+function rotateWorldVectorToBody(data: MujocoData, bodyId: number, world: readonly [number, number, number]): [number, number, number] {
+  const adr = bodyId * 4;
+  const w = data.xquat[adr] ?? 1;
+  const x = -(data.xquat[adr + 1] ?? 0);
+  const y = -(data.xquat[adr + 2] ?? 0);
+  const z = -(data.xquat[adr + 3] ?? 0);
+  const vx = world[0];
+  const vy = world[1];
+  const vz = world[2];
+
+  const tx = 2 * (y * vz - z * vy);
+  const ty = 2 * (z * vx - x * vz);
+  const tz = 2 * (x * vy - y * vx);
+
+  return [
+    vx + w * tx + y * tz - z * ty,
+    vy + w * ty + z * tx - x * tz,
+    vz + w * tz + x * ty - y * tx,
+  ];
+}
+
+/**
+ * Build a flat observation vector plus a layout map from live MuJoCo state.
+ *
+ * Missing named resources are skipped. The returned layout is the source of
+ * truth for the vector produced from the current model.
+ */
+export function buildObservation(
+  model: MujocoModel,
+  data: MujocoData,
+  config: ObservationConfig
+): ObservationResult {
+  const values: number[] = [];
+  const layout: ObservationLayoutItem[] = [];
+
+  if (config.time) appendScalar(values, layout, 'time', data.time);
+  if (config.qpos) append(values, layout, 'qpos', data.qpos);
+  if (config.qvel) append(values, layout, 'qvel', data.qvel);
+  if (config.ctrl) append(values, layout, 'ctrl', data.ctrl);
+  if (config.act) append(values, layout, 'act', data.act);
+  if (config.sensordata) append(values, layout, 'sensordata', data.sensordata);
+
+  for (const name of config.sensors ?? []) {
+    const sensorId = findSensorByName(model, name);
+    if (sensorId < 0) continue;
+    const start = model.sensor_adr[sensorId] ?? 0;
+    const dim = model.sensor_dim[sensorId] ?? 0;
+    append(values, layout, `sensor:${name}`, data.sensordata.subarray(start, start + dim));
+  }
+
+  for (const name of config.sites ?? []) {
+    const siteId = findSiteByName(model, name);
+    if (siteId < 0) continue;
+    const start = siteId * 3;
+    append(values, layout, `site:${name}:xpos`, data.site_xpos.subarray(start, start + 3));
+  }
+
+  const gravity = normalizedGravity(model);
+  for (const name of namedBodyList(config.projectedGravity)) {
+    const bodyId = findBodyByName(model, name);
+    if (bodyId < 0) continue;
+    append(values, layout, `projectedGravity:${name}`, rotateWorldVectorToBody(data, bodyId, gravity));
+  }
+
+  return {
+    values: config.output === 'float64' ? new Float64Array(values) : new Float32Array(values),
+    layout,
+  };
+}

package/src/hooks/useObservation.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useMemo, useRef } from 'react';
+import { useMujocoContext } from '../core/MujocoSimProvider';
+import { buildObservation } from '../core/ObservationBuilder';
+import type { ObservationConfig, ObservationHandle, ObservationResult } from '../types';
+
+const EMPTY_OBSERVATION: ObservationResult = {
+  values: new Float32Array(0),
+  layout: [],
+};
+
+/**
+ * Live observation reader for policy loops and telemetry.
+ *
+ * The handle is stable; call `read()` inside callbacks to sample the latest
+ * MuJoCo model/data state without forcing React renders.
+ */
+export function useObservation(config: ObservationConfig): ObservationHandle {
+  const { mjModelRef, mjDataRef } = useMujocoContext();
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  return useMemo(() => ({
+    read() {
+      const model = mjModelRef.current;
+      const data = mjDataRef.current;
+      if (!model || !data) return EMPTY_OBSERVATION;
+      return buildObservation(model, data, configRef.current);
+    },
+    readValues() {
+      return this.read().values;
+    },
+  }), [mjDataRef, mjModelRef]);
+}

package/src/index.ts

@@ -26,6 +26,7 @@ export {
   resolveControlGroup,
   createContiguousControlGroup,
 } from './core/SceneLoader';
+export { buildObservation } from './core/ObservationBuilder';
 
 // Controller factory
 export { createController, createControllerHook } from './core/createController';
@@ -57,6 +58,7 @@ export { useCtrl } from './hooks/useCtrl';
 export { useContacts, useContactEvents } from './hooks/useContacts';
 export { useKeyboardTeleop } from './hooks/useKeyboardTeleop';
 export { usePolicy } from './hooks/usePolicy';
+export { useObservation } from './hooks/useObservation';
 export { useTrajectoryPlayer } from './hooks/useTrajectoryPlayer';
 export { useTrajectoryRecorder } from './hooks/useTrajectoryRecorder';
 export { useGamepad } from './hooks/useGamepad';
@@ -112,6 +114,12 @@ export type {
   KeyboardTeleopConfig,
   // Policy
   PolicyConfig,
+  // Observations
+  ObservationConfig,
+  ObservationHandle,
+  ObservationLayoutItem,
+  ObservationOutput,
+  ObservationResult,
   // Component props
   BodyProps,
   IkGizmoProps,

package/src/types.ts

@@ -595,6 +595,51 @@ export interface PolicyConfig {
   onAction: (action: Float32Array | Float64Array | number[], model: MujocoModel, data: MujocoData) => void;
 }
 
+// ---- Observation Builder ----
+
+export type ObservationOutput = 'float32' | 'float64';
+
+export interface ObservationConfig {
+  /** Include scalar simulation time. */
+  time?: boolean;
+  /** Include all qpos values. */
+  qpos?: boolean;
+  /** Include all qvel values. */
+  qvel?: boolean;
+  /** Include all ctrl values. */
+  ctrl?: boolean;
+  /** Include all actuator activation values. */
+  act?: boolean;
+  /** Include all raw sensordata values. */
+  sensordata?: boolean;
+  /** Include named sensor values in the configured order. */
+  sensors?: readonly Sensors[];
+  /** Include named site world positions in the configured order. */
+  sites?: readonly Sites[];
+  /** Include world gravity projected into each named body's local frame. */
+  projectedGravity?: Bodies | readonly Bodies[];
+  /** Output array type. Defaults to Float32Array. */
+  output?: ObservationOutput;
+}
+
+export interface ObservationLayoutItem {
+  name: string;
+  start: number;
+  size: number;
+}
+
+export interface ObservationResult {
+  values: Float32Array | Float64Array;
+  layout: ObservationLayoutItem[];
+}
+
+export interface ObservationHandle {
+  /** Read a fresh observation from the current live MuJoCo model/data refs. */
+  read(): ObservationResult;
+  /** Read just the vector values for policy inference. */
+  readValues(): Float32Array | Float64Array;
+}
+
 // ---- Debug Component (spec 6.1) ----
 
 export interface DebugProps {