Files
chenlin a8be5e0134 feat: release v0.5 with shared interactive arenas and textured RP1
Unify lighting and line-colour controls across robots, replace the football with a shared layout of draggable physical props, and import the supplied RP1 GLBs without changing trained physics or policies.

Include reproducible visual import/provenance, regression coverage and verification records. Verified 66 unit tests, 55 browser tests and production-build checks.
2026-10-30 14:14:03 +08:00

209 lines
11 KiB
Python

#!/usr/bin/env python3
"""Import the user's 63 textured parts onto the existing 25-body/24-DOF RP1.
Usage: python3 app/scripts/import-rp1-visuals.py ARCHIVE HAND_FIXED_URDF
No MJCF, STL, policy, motion or physical joint is changed. The source's fixed
finger poses and neutral wrist yaw/pitch are composed into two visual-only
wrist GLBs. Source images/materials/binary vertex data are retained verbatim.
"""
import copy
import hashlib
import json
import math
from pathlib import Path
import struct
import sys
import xml.etree.ElementTree as ET
import zipfile
def sha(data):
return hashlib.sha256(data).hexdigest()
def read_glb(data):
if len(data) < 20:
raise ValueError("Truncated GLB")
magic, version, length, size, kind = struct.unpack_from("<5I", data)
if (magic, version, length, kind) != (0x46546C67, 2, len(data), 0x4E4F534A):
raise ValueError("Invalid GLB (possibly an LFS pointer)")
doc = json.loads(data[20:20 + size])
offset = 20 + size
binary_size, binary_kind = struct.unpack_from("<2I", data, offset)
if binary_kind != 0x004E4942 or offset + 8 + binary_size != len(data):
raise ValueError("Expected one embedded BIN chunk")
for asset in [*doc.get("buffers", []), *doc.get("images", [])]:
if "uri" in asset:
raise ValueError("GLBs must embed all images and buffers")
if len(doc["buffers"]) != 1 or any(k in doc for k in ["skins", "animations", "extensionsRequired"]):
raise ValueError("Expected static, self-contained body GLB")
return doc, data[offset + 8:offset + 8 + binary_size]
def identity():
return [[float(i == j) for j in range(4)] for i in range(4)]
def multiply(a, b):
return [[sum(a[i][k] * b[k][j] for k in range(4)) for j in range(4)] for i in range(4)]
def origin_matrix(origin):
result = identity()
if origin is None:
return result
xyz = list(map(float, origin.get("xyz", "0 0 0").split()))
roll, pitch, yaw = map(float, origin.get("rpy", "0 0 0").split())
cr, sr, cp, sp, cy, sy = math.cos(roll), math.sin(roll), math.cos(pitch), math.sin(pitch), math.cos(yaw), math.sin(yaw)
# URDF fixed-axis XYZ = Rz(yaw) Ry(pitch) Rx(roll).
rotation = [[cy * cp, cy * sp * sr - sy * cr, cy * sp * cr + sy * sr],
[sy * cp, sy * sp * sr + cy * cr, sy * sp * cr - cy * sr],
[-sp, cp * sr, cp * cr]]
for i in range(3):
result[i][:3] = rotation[i]
result[i][3] = xyz[i]
return result
def assemble(parts):
keys = ["nodes", "materials", "meshes", "textures", "images", "accessors", "bufferViews", "samplers"]
out = {"asset": {"version": "2.0", "generator": "microduck RP1 visual-only fixed-hand assembler"},
"scene": 0, "scenes": [{"name": "Fixed wrist and hand", "nodes": []}],
**{key: [] for key in keys}}
binary = bytearray()
# Blender's source GLBs are Y-up; the URDF matrices are Z-up.
c = [[1, 0, 0, 0], [0, 0, 1, 0], [0, -1, 0, 0], [0, 0, 0, 1]]
cinv = [[1, 0, 0, 0], [0, 0, -1, 0], [0, 1, 0, 0], [0, 0, 0, 1]]
for name, data, transform in parts:
doc, payload = read_glb(data)
if doc.get("extensionsUsed"):
raise ValueError("Unexpected extension in wrist part; review remapping")
offsets = {key: len(out[key]) for key in keys}
start = len(binary)
binary.extend(payload)
binary.extend(b"\0" * (-len(binary) % 4))
for key in keys:
for original in doc[key]:
item = copy.deepcopy(original)
if key == "bufferViews":
item["buffer"] = 0
item["byteOffset"] = item.get("byteOffset", 0) + start
elif key == "accessors":
if "sparse" in item:
raise ValueError("Sparse accessor requires explicit remapping")
if "bufferView" in item:
item["bufferView"] += offsets["bufferViews"]
elif key == "images":
item["bufferView"] += offsets["bufferViews"]
elif key == "textures":
item["source"] += offsets["images"]
if "sampler" in item:
item["sampler"] += offsets["samplers"]
elif key == "materials":
def textures(value):
if isinstance(value, dict):
for field, child in value.items():
if field.endswith("Texture") and isinstance(child, dict) and "index" in child:
child["index"] += offsets["textures"]
else:
textures(child)
elif isinstance(value, list):
for child in value:
textures(child)
textures(item)
elif key == "meshes":
for primitive in item["primitives"]:
primitive["attributes"] = {k: v + offsets["accessors"] for k, v in primitive["attributes"].items()}
for field, table in [("indices", "accessors"), ("material", "materials")]:
if field in primitive:
primitive[field] += offsets[table]
elif key == "nodes":
if "mesh" in item:
item["mesh"] += offsets["meshes"]
if "children" in item:
item["children"] = [v + offsets["nodes"] for v in item["children"]]
out[key].append(item)
matrix = multiply(multiply(c, transform), cinv)
out["scenes"][0]["nodes"].append(len(out["nodes"]))
out["nodes"].append({"name": f"source-part:{name}", "extras": {"sourcePart": name}, "matrix": [matrix[i][j] for j in range(4) for i in range(4)],
"children": [v + offsets["nodes"] for v in doc["scenes"][doc.get("scene", 0)]["nodes"]]})
out["buffers"] = [{"byteLength": len(binary)}]
encoded = json.dumps(out, separators=(",", ":")).encode()
encoded += b" " * (-len(encoded) % 4)
total = 12 + 8 + len(encoded) + 8 + len(binary)
return struct.pack("<5I", 0x46546C67, 2, total, len(encoded), 0x4E4F534A) + encoded + struct.pack("<2I", len(binary), 0x004E4942) + binary
def import_visuals(archive, urdf):
target = Path(__file__).resolve().parents[1] / "public/robots/rp1"
source_root = ET.fromstring(urdf.read_bytes())
links = {link.get("name"): link for link in source_root.findall("link")}
expected = {}
for name, link in links.items():
mesh = Path(link.find("visual/geometry/mesh").get("filename")).stem
expected[name] = f"{name}__visual_0__{mesh}.glb"
with zipfile.ZipFile(archive) as source:
if sorted(source.namelist()) != sorted(expected.values()) or len(expected) != 63:
raise ValueError("Archive must contain exactly the 63 hand-model body GLBs")
inputs = {name: source.read(file) for name, file in expected.items()}
for data in inputs.values():
read_glb(data)
model = ET.parse(target / "model.xml").getroot()
physical = [body.get("name") for body in model.findall(".//worldbody//body")]
parents = {j.find("child").get("link"): j for j in source_root.findall("joint")}
output, mappings = {}, {}
for body in physical:
if not body.endswith("_wrist_link"):
name = expected[body]
output[name] = inputs[body]
mappings[body] = {"path": f"visuals/{name}", "parts": [body]}
continue
side = body.split("_")[0]
anchor = f"{side}_wrist_roll_link"
prefix = "lh_" if side == "left" else "rh_"
names = [name for name in links if name.startswith(f"{side}_wrist_") or name.startswith(prefix)]
parts = []
for name in names:
relative = identity()
node = name
while node != anchor:
joint = parents[node]
# The extra two wrist axes are visual-only at neutral; hand
# joints come from the upstream fixed-hand URDF.
if joint.get("type") != "fixed" and "wrist" not in joint.get("name", ""):
raise ValueError("Unexpected moving hand joint")
relative = multiply(origin_matrix(joint.find("origin")), relative)
node = joint.find("parent").get("link")
parts.append((name, inputs[name], relative))
file = f"{body}__fixed_hand.glb"
output[file] = assemble(parts)
mappings[body] = {"path": f"visuals/{file}", "parts": names}
used = [name for mapping in mappings.values() for name in mapping["parts"]]
if sorted(used) != sorted(links) or len(physical) != 25:
raise ValueError("Every source part must map exactly once to 25 physical bodies")
for data in output.values():
read_glb(data)
# Commit only after all inputs and assembled outputs validate. No ZIP extraction.
(target / "visuals").mkdir(exist_ok=True)
(target / "visuals/rp1_hand_fixed.urdf").write_bytes(urdf.read_bytes())
records = [{"file": "visuals/rp1_hand_fixed.urdf", "sha256": sha(urdf.read_bytes())}]
for name, data in output.items():
(target / "visuals" / name).write_bytes(data)
records.append({"file": f"visuals/{name}", "sha256": sha(data)})
config = json.loads((target / "robot.json").read_text())
config["render"]["body_visuals"] = [{"body": body, "path": mappings[body]["path"],
"quaternion": [math.sqrt(0.5), 0, 0, math.sqrt(0.5)]} for body in physical]
(target / "robot.json").write_text(json.dumps(config, indent=2) + "\n")
manifest = {"source": f"User-provided {archive.name}", "archive_sha256": sha(archive.read_bytes()),
"license": "Not supplied in the archive; local evaluation only. Confirm redistribution rights.",
"coordinate_conversion": "Source GLBs are Blender Y-up; attachments rotate +90 degrees about X into MuJoCo body Z-up.",
"assembly": "25 physical body attachments; 20 source parts per wrist (neutral extra wrist axes and fixed fingers). No physical joints added.",
"input_files": [{"file": expected[name], "sha256": sha(data)} for name, data in inputs.items()],
"body_mapping": mappings, "files": records}
(target / "visual-source-manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
print(f"Imported {len(inputs)} source GLBs into {len(physical)} body attachments; physics/policies untouched")
if __name__ == "__main__":
import_visuals(Path(sys.argv[1]), Path(sys.argv[2]))