feat: release v0.4 with textured Microban visuals

This commit is contained in:
2026-10-29 15:55:17 +08:00
parent 1965281004
commit f85f0c1237
37 changed files with 911 additions and 15 deletions
@@ -218,6 +218,21 @@ export function validatePackage(config) {
}
if (config.adapter === "generic" && config.render.source !== "mjcf_visual")
throw new Error("render.source: generic runtime requires mjcf_visual");
const visualBodies = new Set();
for (const visual of config.render.body_visuals ?? []) {
if (config.adapter !== "generic")
throw new Error("render.body_visuals: requires the generic runtime");
if (visualBodies.has(visual.body))
throw new Error(`render.body_visuals: duplicate body ${visual.body}`);
visualBodies.add(visual.body);
if (
visual.quaternion &&
Math.abs(Math.hypot(...visual.quaternion) - 1) > 1e-6
)
throw new Error(
"render.body_visuals: quaternion must have unit length (xyzw)",
);
}
return config;
}
export { schema as robotSchema };
+28
View File
@@ -379,6 +379,34 @@
"source": {
"enum": ["glb", "mjcf_visual"]
},
"body_visuals": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": ["body", "path"],
"additionalProperties": false,
"properties": {
"body": { "type": "string", "minLength": 1 },
"path": {
"type": "string",
"pattern": "^(?!/)(?!.*\\.\\.)[^\\\\:?#]+\\.glb$"
},
"position": {
"type": "array",
"minItems": 3,
"maxItems": 3,
"items": { "type": "number" }
},
"quaternion": {
"type": "array",
"minItems": 4,
"maxItems": 4,
"items": { "type": "number" }
}
}
}
},
"groups": {
"type": "array",
"items": {
+111
View File
@@ -0,0 +1,111 @@
import * as THREE from "three";
import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
import { fetchChecked } from "../loader/PackageLoader.js";
// Body GLBs must be self-contained: external image/buffer URIs would bypass
// PackageLoader's same-origin, hosting-prefix and signed-URL handling.
export function validateBodyGlb(buffer) {
const view = new DataView(buffer);
if (
buffer.byteLength < 20 ||
view.getUint32(0, true) !== 0x46546c67 ||
view.getUint32(4, true) !== 2 ||
view.getUint32(8, true) !== buffer.byteLength ||
view.getUint32(16, true) !== 0x4e4f534a ||
view.getUint32(12, true) > buffer.byteLength - 20
)
throw new Error("Body visual: invalid GLB (check git lfs pull)");
const json = JSON.parse(
new TextDecoder().decode(
new Uint8Array(buffer, 20, view.getUint32(12, true)),
),
);
for (const asset of [...(json.buffers ?? []), ...(json.images ?? [])])
if (asset.uri && !asset.uri.startsWith("data:"))
throw new Error("Body visual: GLB must embed all buffers and images");
return json;
}
// Visual-only layer. Nothing here changes the compiled model, qpos, collision
// geoms or policy inputs. Each attachment follows a MuJoCo body, not an
// independently animated skeleton or the compiler-recentered STL geom frame.
export class BodyVisuals {
static async load(mujoco, model, data, pkg) {
const specs = pkg.config.render.body_visuals ?? [];
const ids = specs.map(({ body }) => {
const id = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_BODY.value, body);
if (id <= 0) throw new Error(`Body visual: missing robot body ${body}`);
return id;
});
const visuals = new BodyVisuals(data);
const loader = new GLTFLoader();
try {
// Sequential parsing keeps ownership unambiguous on a failed candidate:
// no outstanding parse may allocate resources after dispose() returns.
for (let i = 0; i < specs.length; i++) {
const spec = specs[i];
const bytes = await fetchChecked(pkg.asset(spec.path), "bytes");
validateBodyGlb(bytes);
const gltf = await loader.parseAsync(bytes, "");
// Retain every scene for cleanup, including non-default glTF scenes.
visuals.scenes.push(...gltf.scenes);
const frame = new THREE.Group();
frame.name = `body-visual:${spec.body}`;
gltf.scene.position.fromArray(spec.position ?? [0, 0, 0]);
gltf.scene.quaternion.fromArray(spec.quaternion ?? [0, 0, 0, 1]);
frame.add(gltf.scene);
visuals.root.add(frame);
visuals.items.push({ id: ids[i], frame });
}
visuals.sync();
return visuals;
} catch (error) {
visuals.dispose();
throw error;
}
}
constructor(data) {
this.data = data;
this.root = new THREE.Group();
this.root.name = "body-visuals";
this.items = [];
this.scenes = [];
}
sync() {
for (const { id, frame } of this.items) {
frame.position.fromArray(this.data.xpos, id * 3);
const a = id * 4,
q = this.data.xquat;
frame.quaternion.set(q[a + 1], q[a + 2], q[a + 3], q[a]);
}
}
dispose() {
if (this.disposed) return;
this.disposed = true;
const geometries = new Set(),
materials = new Set(),
textures = new Set(),
images = new Set();
for (const scene of this.scenes)
scene.traverse((object) => {
if (object.geometry) geometries.add(object.geometry);
for (const material of [object.material].flat().filter(Boolean)) {
materials.add(material);
for (const value of Object.values(material))
if (value?.isTexture) textures.add(value);
}
});
for (const geometry of geometries) geometry.dispose();
for (const material of materials) material.dispose();
for (const texture of textures) {
for (const image of [texture.source?.data].flat().filter(Boolean))
images.add(image);
texture.dispose();
}
for (const image of images) image.close?.();
this.root.removeFromParent();
this.root.clear();
this.scenes = [];
this.items = [];
}
}
+16
View File
@@ -1,5 +1,6 @@
import * as THREE from "three";
import { applyWorldGrid } from "./WorldRenderer.js";
import { BodyVisuals } from "./BodyVisuals.js";
// Geometry is compiled MuJoCo geometry, not raw STL: compiler-applied mesh
// scale/centering is already represented by vertices + geom transforms.
export class RigRenderer {
@@ -91,7 +92,21 @@ export class RigRenderer {
throw error;
}
}
async loadBodyVisuals(mujoco, pkg) {
if (!pkg.config.render.body_visuals?.length) return;
this.bodyVisuals = await BodyVisuals.load(
mujoco,
this.model,
this.data,
pkg,
);
const replaced = new Set(this.bodyVisuals.items.map(({ id }) => id));
for (const { id, mesh } of this.items)
if (replaced.has(this.model.geom_bodyid[id])) mesh.visible = false;
this.root.add(this.bodyVisuals.root);
}
sync() {
this.bodyVisuals?.sync();
const p = this.data.geom_xpos,
r = this.data.geom_xmat,
m = this.matrix;
@@ -120,6 +135,7 @@ export class RigRenderer {
}
}
dispose() {
this.bodyVisuals?.dispose();
for (const g of this.geometries.values()) g.dispose();
for (const m of this.materials) m.dispose();
this.geometries.clear();
+1
View File
@@ -89,6 +89,7 @@ export class RobotRuntime {
}
const { ctx, obs, actions, controller } = policies.get(primary.id);
rig = new RigRenderer(sim.model, sim.data, { ...config.render, world });
await rig.loadBodyVisuals(mujoco, pkg);
worldPresentation = await options.createWorldPresentation?.({
sim,
rig,