mujoco-react 12.2.0 → 12.3.0

package/dist/onnx.d.ts

@@ -1,5 +1,5 @@
 import * as ort from 'onnxruntime-web';
-import { P as PolicyActionChunk } from './types-CF-BZXtW.js';
+import { P as PolicyActionChunk } from './types-1ONW9gUW.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';

package/dist/spark.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _sparkjsdev_spark from '@sparkjsdev/spark';
-import { S as SplatEnvironmentProps, a as PairedSplatEnvironmentConfig, b as SceneConfig, c as SplatEnvironmentReadiness, V as VisualScenarioConfig } from './types-CF-BZXtW.js';
+import { S as SplatEnvironmentProps, a as PairedSplatEnvironmentConfig, b as SceneConfig, c as SplatEnvironmentReadiness, V as VisualScenarioConfig } from './types-1ONW9gUW.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';

package/dist/spark.js

@@ -1,4 +1,4 @@
-import { useSplatSceneConfig, useSplatEnvironment, SplatEnvironment, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY } from './chunk-SP72GTOD.js';
+import { useSplatSceneConfig, useSplatEnvironment, SplatEnvironment, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY } from './chunk-FVSVETBC.js';
 import { useThree } from '@react-three/fiber';
 import { useMemo, useState, useEffect, useCallback, useRef } from 'react';
 import * as THREE from 'three';

package/dist/{types-CF-BZXtW.d.ts → types-1ONW9gUW.d.ts}

@@ -126,8 +126,10 @@ interface CameraFramePixelsResult {
 }
 /** An owned, aligned RGB-D observation from one render. Scene units must be meters. */
 interface CameraRGBDResult {
-    /** Interleaved sRGB bytes (RGB), row-major, top-left origin. */
+    /** Interleaved RGB bytes, row-major, top-left origin. sRGB by default. */
     rgb: Uint8Array;
+    /** Transfer function for RGB bytes. Missing on older observations means sRGB. */
+    rgbColorSpace?: 'srgb' | 'linear-srgb';
     /** Positive camera-axis distance (-view Z) in meters, not Euclidean range.
      * Background / no depth-writing surface is +Infinity. Same pixel order as rgb. */
     depth: Float32Array;
@@ -1526,6 +1528,9 @@ interface CameraFrameRenderIsolationOptions {
     cache?: boolean;
 }
 interface CameraFrameCaptureOptions {
+    /** RGB-D byte transfer function. Defaults to sRGB. Linear readback preserves
+     * unencoded target bytes, as used by MuJoCo's classic offscreen renderer. */
+    rgbColorSpace?: 'srgb' | 'linear-srgb';
     /** Snapshot (default) waits for splat preparation. Preview reuses the latest
      * sorted splats while updating in the background for responsive live motion.
      * useCameraStream defaults to preview; policy/dataset captures stay snapshot.
@@ -1718,6 +1723,10 @@ type MujocoMeshNormalSmoothing = boolean | {
     tolerance?: number;
 };
 interface MujocoRenderOptions {
+    /** Opt into classic MuJoCo material/lighting equations for native camera research.
+     * Standard PBR rendering remains the default. Classic currently excludes
+     * shadows, planar reflections, and non-spot/directional lights. */
+    appearance?: 'standard' | 'mujoco-classic';
     /**
      * Smooth mesh normals by welding duplicate vertices before recomputing normals.
      * Useful for faceted STL visuals; keep off for exact policy-render parity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "12.2.0",
+  "version": "12.3.0",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",
@@ -66,7 +66,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test:runtime": "tsup --config tests/tsup.config.ts && node --test .test-dist/runtime.js .test-dist/simulation-runtime.js .test-dist/camera-capture.js"
+    "test:runtime": "tsup --config tests/tsup.config.ts && node --test .test-dist/runtime.js .test-dist/simulation-runtime.js .test-dist/camera-capture.js .test-dist/classic-appearance.js"
   },
   "peerDependencies": {
     "@react-three/drei": ">=9",

package/src/components/SceneRenderer.tsx

@@ -23,9 +23,9 @@ export interface SceneRendererProps extends Omit<ThreeElements['group'], 'ref'>
 
 function getRenderOptionsKey(renderOptions: MujocoRenderOptions | undefined) {
   const smoothing = renderOptions?.meshNormalSmoothing;
-  if (!smoothing) return 'default';
-  if (smoothing === true) return 'meshNormalSmoothing:true';
-  return `meshNormalSmoothing:${smoothing.tolerance ?? 'default'}`;
+  if (!smoothing) return renderOptions?.appearance ?? 'standard';
+  if (smoothing === true) return `${renderOptions?.appearance ?? 'standard'}:meshNormalSmoothing:true`;
+  return `${renderOptions?.appearance ?? 'standard'}:meshNormalSmoothing:${smoothing.tolerance ?? 'default'}`;
 }
 
 export function SceneRenderer({ renderOptions, ...props }: SceneRendererProps) {
@@ -78,24 +78,46 @@ export function SceneRenderer({ renderOptions, ...props }: SceneRendererProps) {
 
     // Create body groups with geometry
     const refs: (THREE.Group | null)[] = [];
-    for (let i = 0; i < model.nbody; i++) {
-      const bodyGroup = new THREE.Group();
-      bodyGroup.userData.bodyID = i;
-      const bodyName = getName(model, model.name_bodyadr[i]);
-
-      if (!hiddenBodiesRef.current.has(bodyName)) {
-        for (let g = 0; g < model.ngeom; g++) {
-          if (model.geom_bodyid[g] === i) {
-            const mesh = geomBuilder.create(model, g);
-            if (mesh) bodyGroup.add(mesh);
+    const dispose = () => {
+      for (const body of refs) {
+        body?.parent?.remove(body);
+        body?.traverse(object => {
+          const mesh = object as THREE.Mesh;
+          if (!mesh.isMesh) return;
+          mesh.geometry.dispose();
+          for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) material.dispose();
+        });
+      }
+      geomBuilder.dispose();
+      prevModelRef.current = null;
+      prevRenderOptionsKeyRef.current = null;
+      prevHiddenVersionRef.current = null;
+      if (bodyRefs.current === refs) bodyRefs.current = [];
+    };
+    try {
+      for (let i = 0; i < model.nbody; i++) {
+        const bodyGroup = new THREE.Group();
+        refs.push(bodyGroup);
+        bodyGroup.userData.bodyID = i;
+        const bodyName = getName(model, model.name_bodyadr[i]);
+
+        if (!hiddenBodiesRef.current.has(bodyName)) {
+          for (let g = 0; g < model.ngeom; g++) {
+            if (model.geom_bodyid[g] === i) {
+              const mesh = geomBuilder.create(model, g, mjDataRef.current ?? undefined);
+              if (mesh) bodyGroup.add(mesh);
+            }
           }
         }
-      }
 
-      group.add(bodyGroup);
-      refs.push(bodyGroup);
+        group.add(bodyGroup);
+      }
+    } catch (error) {
+      dispose();
+      throw error;
     }
     bodyRefs.current = refs;
+    return dispose;
   }, [status, geomBuilder, mjModelRef, renderOptionsKey, hiddenBodiesRef, hiddenBodiesVersion]);
 
   const syncBodiesToData = useCallback(() => {

package/src/index.ts

@@ -421,6 +421,7 @@ export type {
   CameraFrameSequenceSampleInput,
   CameraFrameSequenceStepInput,
   MujocoCanvasProps,
+  MujocoRenderOptions,
   MujocoContextValue,
   // Hook return types
   FrameCaptureAPI,

package/src/rendering/GeomBuilder.ts

@@ -6,9 +6,10 @@
 
 import * as THREE from 'three';
 import { mergeVertices } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+import { createMujocoClassicMaterial, createClassicPlaneGeometry } from './mujocoClassicMaterial';
 import { CapsuleGeometry } from './CapsuleGeometry';
 import { getName } from '../core/SceneLoader';
-import { MujocoModel, MujocoModule, MujocoRenderOptions } from '../types';
+import { MujocoModel, MujocoModule, MujocoRenderOptions, MujocoData } from '../types';
 
 const DEFAULT_MESH_NORMAL_SMOOTHING_TOLERANCE = 1e-4;
 
@@ -93,7 +94,15 @@ export class GeomBuilder {
      * Creates a Three.js Object3D (usually a Mesh) for a specific geometry in the MuJoCo model.
      * Returns null if the geometry shouldn't be rendered (e.g., invisible collision triggers).
      */
-    create(mjModel: MujocoModel, g: number): THREE.Object3D | null {
+    dispose() {
+        for (const texture of this.textureCache.values()) texture.dispose();
+        this.textureCache.clear();
+    }
+
+    create(mjModel: MujocoModel, g: number, data?: MujocoData): THREE.Object3D | null {
+        const classic = this.renderOptions?.appearance === 'mujoco-classic';
+        if (classic && !data) throw new Error('Classic appearance requires live MuJoCo data');
+        if (classic && this.renderOptions?.meshNormalSmoothing) throw new Error('Classic appearance uses MuJoCo mesh normals; meshNormalSmoothing is not supported');
         // 1. Check if this geom is meant to be visible
         // Group 3 in MuJoCo is conventionally used for invisible 'helper' geoms.
         if (mjModel.geom_group[g] === 3) return null;
@@ -108,7 +117,7 @@ export class GeomBuilder {
         // Sometimes color is on the geom itself, sometimes it uses a shared material definition.
         const matId = mjModel.geom_matid[g];
         const color = new THREE.Color(0xffffff);
-        const map = this.getMaterialTexture(mjModel, matId);
+        const map = classic ? null : this.getMaterialTexture(mjModel, matId);
         let opacity = 1.0;
 
         if (matId >= 0) {
@@ -132,7 +141,7 @@ export class GeomBuilder {
 
         if (type === getVal(MG.mjGEOM_PLANE)) {
             // Planes are infinite in MuJoCo, but Three needs finite UVs for textured captures.
-            geo = new THREE.PlaneGeometry(size[0] * 2 || 5, size[1] * 2 || 5);
+            geo = classic ? createClassicPlaneGeometry(mjModel, g) : new THREE.PlaneGeometry(size[0] * 2 || 5, size[1] * 2 || 5);
         } else if (type === getVal(MG.mjGEOM_SPHERE)) {
             geo = new THREE.SphereGeometry(size[0], 24, 24);
         } else if (type === getVal(MG.mjGEOM_CAPSULE)) {
@@ -156,27 +165,37 @@ export class GeomBuilder {
             const fNum = mjModel.mesh_facenum[mId];
 
             const tAdr = mjModel.mesh_texcoordadr?.[mId] ?? -1;
-            if (map && tAdr >= 0 && mjModel.mesh_texcoord && mjModel.mesh_facetexcoord) {
+            if (classic || (map && tAdr >= 0 && mjModel.mesh_texcoord && mjModel.mesh_facetexcoord)) {
                 // Textured mesh. MuJoCo indexes texcoords per face corner
                 // (mesh_facetexcoord), independently of the vertex indices, so
                 // the geometry must be de-indexed to carry a 'uv' attribute.
                 const corners = fNum * 3;
                 const positions = new Float32Array(corners * 3);
-                const uvs = new Float32Array(corners * 2);
+                const hasUV = tAdr >= 0 && mjModel.mesh_texcoord && mjModel.mesh_facetexcoord;
+                const uvs = hasUV ? new Float32Array(corners * 2) : undefined;
+                const normalModel = mjModel as MujocoModel & { mesh_normaladr: Int32Array; mesh_facenormal: Int32Array };
+                const normals = classic ? new Float32Array(corners * 3) : undefined;
+                if (classic && (!normalModel.mesh_normaladr || !normalModel.mesh_facenormal)) throw new Error('Classic appearance requires MuJoCo mesh face normals');
                 for (let c = 0; c < corners; c++) {
                     const v = vAdr + mjModel.mesh_face[fAdr * 3 + c];
                     positions[c * 3] = mjModel.mesh_vert[v * 3];
                     positions[c * 3 + 1] = mjModel.mesh_vert[v * 3 + 1];
                     positions[c * 3 + 2] = mjModel.mesh_vert[v * 3 + 2];
-                    const t = tAdr + mjModel.mesh_facetexcoord[fAdr * 3 + c];
-                    uvs[c * 2] = mjModel.mesh_texcoord[t * 2];
-                    // MuJoCo stores V with image-top origin; flip back to GL convention.
-                    uvs[c * 2 + 1] = 1 - mjModel.mesh_texcoord[t * 2 + 1];
+                    if (uvs) {
+                        const t = tAdr + mjModel.mesh_facetexcoord![fAdr * 3 + c];
+                        uvs[c * 2] = mjModel.mesh_texcoord![t * 2];
+                        uvs[c * 2 + 1] = 1 - mjModel.mesh_texcoord![t * 2 + 1];
+                    }
+                    if (normals) {
+                        const n = normalModel.mesh_normaladr[mId] + normalModel.mesh_facenormal[fAdr * 3 + c];
+                        normals.set(mjModel.mesh_normal.subarray(n * 3, n * 3 + 3), c * 3);
+                    }
                 }
                 geo = new THREE.BufferGeometry();
                 geo.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
-                geo.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2));
-                geo.computeVertexNormals();
+                if (uvs) geo.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2));
+                if (normals) geo.setAttribute('normal', new THREE.Float32BufferAttribute(normals, 3));
+                else geo.computeVertexNormals();
             } else {
                 geo = new THREE.BufferGeometry();
                 // 'position' attribute = vertices
@@ -194,12 +213,12 @@ export class GeomBuilder {
         // 5. Construct the final Mesh
         if (geo) {
             const isPlane = type === getVal(MG.mjGEOM_PLANE);
-            const materialMap = isPlane && map ? map.clone() : map;
+            const materialMap = !classic && isPlane && map ? map.clone() : map;
             if (isPlane && materialMap) {
                 materialMap.repeat.multiplyScalar(2.5);
                 materialMap.needsUpdate = true;
             }
-            const mesh = new THREE.Mesh(geo, new THREE.MeshStandardMaterial({
+            const mesh = new THREE.Mesh(geo, classic ? createMujocoClassicMaterial(mjModel, data!, g) : new THREE.MeshStandardMaterial({
                 color,
                 map: materialMap,
                 transparent: opacity < 1,
@@ -207,6 +226,7 @@ export class GeomBuilder {
                 roughness: 0.6,
                 metalness: 0
             }));
+            if (materialMap && materialMap !== map) mesh.material.addEventListener('dispose', () => materialMap.dispose());
             mesh.castShadow = type !== getVal(MG.mjGEOM_PLANE);
             mesh.receiveShadow = true;
 

package/src/rendering/cameraFrameCapture.ts

@@ -6,6 +6,7 @@
  */
 
 import * as THREE from 'three';
+import { linearByteToSrgbByte } from './captureColor';
 import { createMetricDepthReader } from './metricDepth';
 import type {
   CameraFrameCaptureBlobResult,
@@ -35,8 +36,10 @@ export interface CameraFramePixelsResult {
 
 /** An owned, aligned RGB-D observation from one render. Scene units must be meters. */
 export interface CameraRGBDResult {
-  /** Interleaved sRGB bytes (RGB), row-major, top-left origin. */
+  /** Interleaved RGB bytes, row-major, top-left origin. sRGB by default. */
   rgb: Uint8Array;
+  /** Transfer function for RGB bytes. Missing on older observations means sRGB. */
+  rgbColorSpace?: 'srgb' | 'linear-srgb';
   /** Positive camera-axis distance (-view Z) in meters, not Euclidean range.
    * Background / no depth-writing surface is +Infinity. Same pixel order as rgb. */
   depth: Float32Array;
@@ -429,14 +432,6 @@ function readRenderTargetToCanvas(
   return canvas;
 }
 
-function linearByteToSrgbByte(value: number) {
-  const normalized = value / 255;
-  const encoded =
-    normalized <= 0.0031308
-      ? normalized * 12.92
-      : 1.055 * Math.pow(normalized, 1 / 2.4) - 0.055;
-  return Math.min(255, Math.max(0, Math.round(encoded * 255)));
-}
 
 function readPixelsToCanvas(
   pixels: Uint8Array,
@@ -833,6 +828,10 @@ export function createCameraFrameCaptureSession(
       target.depthTexture = new THREE.DepthTexture(width, height, THREE.UnsignedIntType);
       depthReader = createMetricDepthReader(width, height, target.depthTexture);
     }
+    const rgbColorSpace = nextOptions.rgbColorSpace ?? options.rgbColorSpace ?? 'srgb';
+    if (rgbColorSpace !== 'srgb' && rgbColorSpace !== 'linear-srgb') {
+      throw new Error('RGB-D capture requires srgb or linear-srgb RGB bytes');
+    }
     const rgb = new Uint8Array(width * height * 3);
     let depth!: Float32Array;
     renderCaptureToTarget(captureOptions, () => {
@@ -843,14 +842,14 @@ export function createCameraFrameCaptureSession(
           const src = ((height - y - 1) * width + sx) * 4;
           const dst = (y * width + x) * 3;
           for (let c = 0; c < 3; c++) {
-            rgb[dst + c] = linearByteToSrgbByte(pixels[src + c]);
+            rgb[dst + c] = rgbColorSpace === 'srgb' ? linearByteToSrgbByte(pixels[src + c]) : pixels[src + c];
           }
         }
       }
       depth = depthReader!.read(sessionRenderer, camera, captureOptions.flipX ?? false);
     });
     return {
-      rgb, depth, width, height,
+      rgb, rgbColorSpace, depth, width, height,
       source: getCameraFrameCaptureSource(captureOptions),
       origin: 'top-left', depthUnits: 'meters', depthConvention: 'camera-z',
       flipX: captureOptions.flipX ?? false,

package/src/rendering/captureColor.ts

@@ -0,0 +1,15 @@
+/** @license SPDX-License-Identifier: Apache-2.0 */
+
+// GPU readback supplies bytes: compute the exact existing transfer function
+// once per possible input, instead of exponentiating every captured channel.
+const linearToSrgb = Uint8Array.from({ length: 256 }, (_, value) => {
+  const normalized = value / 255;
+  const encoded = normalized <= 0.0031308
+    ? normalized * 12.92
+    : 1.055 * Math.pow(normalized, 1 / 2.4) - 0.055;
+  return Math.min(255, Math.max(0, Math.round(encoded * 255)));
+});
+
+export function linearByteToSrgbByte(value: number): number {
+  return linearToSrgb[value];
+}

package/src/rendering/mujocoClassicMaterial.ts

@@ -0,0 +1,203 @@
+/** @license SPDX-License-Identifier: Apache-2.0 */
+import * as THREE from 'three';
+import type { MujocoData, MujocoModel } from '../types';
+
+const MAX_LIGHTS = 8;
+const vertexShader = `
+  uniform vec4 diffuse;
+  uniform float emission, specular, shininess;
+  uniform int lightCount;
+  uniform float lightMode[8];
+  uniform vec3 lightPos[8], lightDir[8], lightAmbient[8], lightDiffuse[8], lightSpecular[8], lightAttenuation[8];
+  uniform float lightCutoff[8], lightExponent[8];
+  uniform bool explicitUV;
+  uniform vec2 repeatScale;
+  uniform vec3 cubeScale;
+  varying vec3 cubeCoord;
+  varying vec4 litColor;
+  varying vec2 texCoord;
+  void main() {
+    vec4 p = modelViewMatrix * vec4(position, 1.0);
+    vec3 n = normalize(normalMatrix * normal);
+    vec3 v = normalize(-p.xyz);
+    vec3 rgb = diffuse.rgb * emission;
+    if (lightCount == 0) rgb += diffuse.rgb * 0.3;
+    for (int i=0; i<8; i++) {
+      if (i>=lightCount) break;
+      vec3 l;
+      float attenuation = 1.0;
+      if (lightMode[i] > 1.5) l = vec3(0.0, 0.0, 1.0);
+      else if (lightMode[i] > 0.5) l = normalize(-(viewMatrix * vec4(lightDir[i],0.0)).xyz);
+      else {
+        vec3 delta = (viewMatrix * vec4(lightPos[i],1.0)).xyz - p.xyz;
+        float distance = length(delta);
+        l = normalize(delta);
+        vec3 a = lightAttenuation[i];
+        attenuation = 1.0 / max(1e-8, a.x+a.y*distance+a.z*distance*distance);
+        vec3 direction = normalize((viewMatrix * vec4(lightDir[i],0.0)).xyz);
+        float spot = dot(-l,direction);
+        if(lightCutoff[i] >= -1.0) attenuation *= spot >= lightCutoff[i] ? (lightExponent[i] > 0.0 ? pow(max(0.0,spot),lightExponent[i]) : 1.0) : 0.0;
+      }
+      float lambert = max(0.0,dot(n,l));
+      vec3 h = normalize(l+v);
+      float shine = lambert > 0.0 && specular > 0.0 ? (shininess > 0.0 ? pow(max(0.0,dot(n,h)),shininess) : 1.0) : 0.0;
+      rgb += attenuation*(diffuse.rgb*(lightAmbient[i]+lambert*lightDiffuse[i])+specular*shine*lightSpecular[i]);
+    }
+    litColor = vec4(clamp(rgb,0.0,1.0),diffuse.a);
+    cubeCoord = position*cubeScale;
+    texCoord = explicitUV ? vec2(uv.x,1.0-uv.y) : vec2(.5*repeatScale.x*position.x-.5,-.5*repeatScale.y*position.y-.5);
+    gl_Position = projectionMatrix*p;
+  }`;
+const fragmentShader = `
+  uniform bool useMap;
+  uniform sampler2D colorMap;
+  uniform bool useCube;
+  uniform samplerCube cubeMap;
+  varying vec3 cubeCoord;
+  varying vec4 litColor;
+  varying vec2 texCoord;
+  void main() {
+    gl_FragColor = litColor * (useMap ? texture2D(colorMap,texCoord) : (useCube ? textureCube(cubeMap,cubeCoord) : vec4(1.0)));
+  }`;
+
+interface ClassicVisualModel {
+  vis: { headlight: { active: number; ambient: Float32Array; diffuse: Float32Array; specular: Float32Array } };
+  tex_type: Int32Array;
+  tex_colorspace: Int32Array;
+  mat_emission: Float32Array;
+  mat_specular: Float32Array;
+  mat_shininess: Float32Array;
+  light_ambient: Float32Array;
+}
+interface ClassicLightData { light_xpos: Float64Array; light_xdir: Float64Array }
+
+const textureCache = new WeakMap<MujocoModel, Map<number, { texture: THREE.Texture; references: number }>>();
+function acquireTexture(model: MujocoModel, id: number) {
+  const m = model as MujocoModel & ClassicVisualModel;
+  let cache = textureCache.get(model);
+  if (!cache) { cache = new Map(); textureCache.set(model, cache); }
+  let entry = cache.get(id);
+  if (!entry) {
+    const width = model.tex_width[id], height = model.tex_height[id], channels = model.tex_nchannel[id];
+    if (channels !== 3 && channels !== 4) throw new Error('Classic RGB textures require three or four channels');
+    const bytes = model.tex_data.subarray(model.tex_adr[id],model.tex_adr[id]+width*height*channels);
+    const rgba = new Uint8Array(width*height*4);
+    for(let i=0;i<width*height;i++) {
+      rgba.set(bytes.subarray(i*channels,i*channels+3),i*4);
+      rgba[i*4+3] = channels === 4 ? bytes[i*channels+3] : 255;
+    }
+    let texture: THREE.Texture;
+    if(m.tex_type[id] === 0) {
+      texture = new THREE.DataTexture(rgba,width,height,THREE.RGBAFormat);
+      texture.colorSpace = m.tex_colorspace[id] === 2 ? THREE.SRGBColorSpace : THREE.LinearSRGBColorSpace;
+      texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
+      texture.magFilter = THREE.LinearFilter;
+      texture.minFilter = THREE.LinearMipmapLinearFilter;
+      texture.generateMipmaps = true;
+    } else if(m.tex_type[id] === 1) {
+      if(height !== 6*width) throw new Error('Classic cube texture must contain six square faces');
+      const faces = Array.from({length:6},(_,i)=>new THREE.DataTexture(rgba.subarray(i*width*width*4,(i+1)*width*width*4),width,width,THREE.RGBAFormat));
+      // WebGLTextures supports DataTexture cube faces; older @types/three
+      // narrows this constructor to DOM images only.
+      texture = new THREE.CubeTexture(faces as unknown as HTMLImageElement[]);
+      // MuJoCo's classic cube upload uses a linear RGB internal format.
+      texture.colorSpace = THREE.LinearSRGBColorSpace;
+    } else throw new Error('Classic materials require a 2D or cube RGB texture');
+    texture.flipY=false; texture.needsUpdate=true;
+    entry={texture,references:0}; cache.set(id,entry);
+  }
+  entry.references++;
+  const retained=entry;
+  return { texture:entry.texture, release() {
+    if(--retained.references===0) { retained.texture.dispose(); cache!.delete(id); }
+  }};
+}
+
+/** Finite planes use the same grid spacing as MuJoCo's classic display lists. */
+export function createClassicPlaneGeometry(model: MujocoModel, geom: number) {
+  const size = model.geom_size.subarray(geom*3,geom*3+3);
+  if(size[0]<=0 || size[1]<=0) throw new Error('Classic appearance currently requires finite plane extents');
+  const axis = (half:number) => {
+    const step=Math.max(size[2],half/98);
+    let count=Math.floor(half/step); count-=count%2;
+    const pad=half-count*step; count+=2;
+    const grid:number[]=[];
+    for(let i=0;i<count;i++) {
+      const left=i===0 ? -half : -half+pad+(i-1)*2*step;
+      const right=left+(i===0 || i===count-1 ? pad : 2*step);
+      grid[i]=left;grid[i+1]=Math.max(left,right);
+    }
+    return grid;
+  };
+  const x=axis(size[0]),y=axis(size[1]),positions:number[]=[],normals:number[]=[],indices:number[]=[];
+  for(const py of y)for(const px of x){positions.push(px,py,0);normals.push(0,0,1);}
+  for(let row=0;row<y.length-1;row++)for(let col=0;col<x.length-1;col++) {
+    const a=row*x.length+col,b=a+1,c=a+x.length,d=c+1;
+    indices.push(a,b,d,a,d,c);
+  }
+  const geometry=new THREE.BufferGeometry();
+  geometry.setAttribute('position',new THREE.Float32BufferAttribute(positions,3));
+  geometry.setAttribute('normal',new THREE.Float32BufferAttribute(normals,3));
+  geometry.setIndex(indices);return geometry;
+}
+
+/** Opt-in classic-OpenGL equations. Produces native display-code RGB values;
+ * request linear RGB-D readback for comparisons. Shadows and planar
+ * reflections are outside this material adapter's scope. */
+export function createMujocoClassicMaterial(model: MujocoModel, data: MujocoData,
+  geom: number): THREE.ShaderMaterial {
+  const m = model as MujocoModel & ClassicVisualModel, d = data as MujocoData & ClassicLightData;
+  for (const name of ['tex_type','tex_colorspace','mat_emission','mat_specular','mat_shininess','light_ambient'] as const) {
+    if(!m[name] || typeof m[name].length !== 'number') throw new Error(`Classic appearance requires model.${name}`);
+  }
+  if(!m.vis?.headlight || !d.light_xpos || !d.light_xdir) throw new Error('Classic appearance requires MuJoCo visual/light state');
+  const mat = model.geom_matid[geom], rgba = Array.from(model.geom_rgba.slice(4*geom,4*geom+4));
+  if (mat >= 0 && rgba.every((v,i)=>v === [0.5,0.5,0.5,1][i])) rgba.splice(0,4,...model.mat_rgba.slice(4*mat,4*mat+4));
+  const roles = model.mat_texid.length / Math.max(1,model.mat_rgba.length/4);
+  const textureId = mat >= 0 ? model.mat_texid[mat*roles+1] : -1;
+  const retained = textureId >= 0 ? acquireTexture(model,textureId) : undefined;
+  const texture = retained?.texture ?? null;
+  const vectors = () => Array.from({length:MAX_LIGHTS},()=>new THREE.Vector3());
+  const uniforms = {
+    diffuse:{value:new THREE.Vector4(...rgba as [number,number,number,number])},
+    emission:{value:mat>=0?m.mat_emission[mat]:0}, specular:{value:mat>=0?m.mat_specular[mat]:.5},
+    shininess:{value:128*(mat>=0?m.mat_shininess[mat]:.5)},
+    lightCount:{value:0},lightMode:{value:new Float32Array(MAX_LIGHTS)},
+    lightPos:{value:vectors()},lightDir:{value:vectors()},lightAmbient:{value:vectors()},lightDiffuse:{value:vectors()},lightSpecular:{value:vectors()},lightAttenuation:{value:vectors()},
+    lightCutoff:{value:new Float32Array(MAX_LIGHTS)},lightExponent:{value:new Float32Array(MAX_LIGHTS)},
+    explicitUV:{value:Number(model.geom_type[geom])===7 && (model.mesh_texcoordadr?.[model.geom_dataid[geom]]??-1)>=0},
+    repeatScale:{value:new THREE.Vector2(mat>=0?model.mat_texrepeat[mat*2]:1,mat>=0?model.mat_texrepeat[mat*2+1]:1)},
+    useMap:{value:!!texture && m.tex_type[textureId]===0},colorMap:{value:texture && m.tex_type[textureId]===0 ? texture : null},
+    useCube:{value:!!texture && m.tex_type[textureId]===1},cubeMap:{value:texture && m.tex_type[textureId]===1 ? texture : null},
+    cubeScale:{value:new THREE.Vector3(1,1,1)},
+  };
+  if(mat>=0 && !model.mat_texuniform[mat]) {
+    const size=model.geom_size;
+    uniforms.repeatScale.value.x/=size[geom*3]||1;uniforms.repeatScale.value.y/=size[geom*3+1]||1;
+  }
+  const isMeshOrPlane=Number(model.geom_type[geom])===7 || Number(model.geom_type[geom])===0;
+  const uniform=mat>=0 && model.mat_texuniform[mat];
+  for(let i=0;i<3;i++) uniforms.cubeScale.value.setComponent(i,isMeshOrPlane ? (uniform ? model.geom_size[geom*3+i] : 1) : (uniform ? 1 : 1/(model.geom_size[geom*3+i]||1)));
+  const material=new THREE.ShaderMaterial({uniforms,vertexShader,fragmentShader,toneMapped:false,side:THREE.DoubleSide,transparent:rgba[3]<1,depthWrite:rgba[3]>=1});
+  const head=m.vis.headlight;
+  material.onBeforeRender=()=>{
+    let count=0;
+    const add=(mode:number,pos:ArrayLike<number>,dir:ArrayLike<number>,ambient:ArrayLike<number>,diffuse:ArrayLike<number>,specular:ArrayLike<number>,attenuation:ArrayLike<number>,cutoff:number,exponent:number)=>{
+      if(count>=MAX_LIGHTS)throw new Error('Classic appearance supports at most eight lights');
+      uniforms.lightMode.value[count]=mode;
+      for(const [uniform,value] of [[uniforms.lightPos,pos],[uniforms.lightDir,dir],[uniforms.lightAmbient,ambient],[uniforms.lightDiffuse,diffuse],[uniforms.lightSpecular,specular],[uniforms.lightAttenuation,attenuation]] as const)uniform.value[count].fromArray(value);
+      uniforms.lightCutoff.value[count]=cutoff >= 180 ? -2 : Math.cos(cutoff*Math.PI/180);uniforms.lightExponent.value[count]=exponent;count++;
+    };
+    if(head.active)add(2,[0,0,0],[0,0,-1],head.ambient,head.diffuse,head.specular,[1,0,0],180,0);
+    for(let i=0;i<model.nlight;i++)if(m.light_active[i]){
+      const type=m.light_type[i];
+      if(type!==0&&type!==1)throw new Error('Classic appearance requires spot or directional MJCF lights');
+      const slice=(a:ArrayLike<number>)=>[a[i*3],a[i*3+1],a[i*3+2]];
+      add(type,slice(d.light_xpos),slice(d.light_xdir),slice(m.light_ambient),slice(m.light_diffuse),slice(m.light_specular),slice(m.light_attenuation),m.light_cutoff[i],m.light_exponent[i]);
+    }
+    uniforms.lightCount.value=count;material.uniformsNeedUpdate=true;
+  };
+  let released=false;
+  material.addEventListener('dispose',()=>{if(!released){retained?.release();released=true;}});
+  return material;
+}

package/src/types.ts

@@ -1680,6 +1680,9 @@ export interface CameraFrameRenderIsolationOptions {
 }
 
 export interface CameraFrameCaptureOptions {
+  /** RGB-D byte transfer function. Defaults to sRGB. Linear readback preserves
+   * unencoded target bytes, as used by MuJoCo's classic offscreen renderer. */
+  rgbColorSpace?: 'srgb' | 'linear-srgb';
   /** Snapshot (default) waits for splat preparation. Preview reuses the latest
    * sorted splats while updating in the background for responsive live motion.
    * useCameraStream defaults to preview; policy/dataset captures stay snapshot.
@@ -1883,6 +1886,10 @@ export type MujocoMeshNormalSmoothing =
   };
 
 export interface MujocoRenderOptions {
+  /** Opt into classic MuJoCo material/lighting equations for native camera research.
+   * Standard PBR rendering remains the default. Classic currently excludes
+   * shadows, planar reflections, and non-spot/directional lights. */
+  appearance?: 'standard' | 'mujoco-classic';
   /**
    * Smooth mesh normals by welding duplicate vertices before recomputing normals.
    * Useful for faceted STL visuals; keep off for exact policy-render parity.