MotrixSimWeb/tools/export_mjcf_manifest.py

667 lines
24 KiB
Python

#!/usr/bin/env python3
"""Export a small Three.js preview manifest from an MJCF-like XML scene.
This is intentionally conservative: it maps visible geoms and mesh references
into the browser manifest without pretending to cover every simulator feature.
Unsupported data is preserved as names/ids where possible and visualized through
fallbacks on the frontend.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import math
import posixpath
import sys
import xml.etree.ElementTree as ET
from pathlib import Path
from typing import Any
from urllib.parse import quote, urlparse
INTERNAL_SOURCE_DIR = "__motrix_source_dir"
INTERNAL_MESH_DIR = "__motrix_mesh_dir"
INTERNAL_ASSET_DIR = "__motrix_asset_dir"
INTERNAL_TEXTURE_DIR = "__motrix_texture_dir"
INTERNAL_ANGLE_MODE = "__motrix_angle_mode"
def floats(raw: str | None, default: list[float]) -> list[float]:
if not raw:
return list(default)
try:
return [float(part) for part in raw.replace(",", " ").split()]
except ValueError:
return list(default)
def ints(raw: str | None, default: list[int]) -> list[int]:
if not raw:
return list(default)
try:
return [int(float(part)) for part in raw.replace(",", " ").split()]
except ValueError:
return list(default)
def rgba_to_hex(raw: str | None, fallback: str) -> tuple[str, float]:
values = floats(raw, [])
if len(values) < 3:
return fallback, 1.0
rgb = [max(0, min(255, int(round(v * 255)))) for v in values[:3]]
alpha = values[3] if len(values) > 3 else 1.0
return "#{:02x}{:02x}{:02x}".format(*rgb), max(0.0, min(1.0, alpha))
def rgb_to_hex(raw: str | None, fallback: str) -> str:
color, _ = rgba_to_hex(raw, fallback)
return color
def float_attr(raw: str | None, fallback: float) -> float:
if raw is None:
return fallback
try:
return float(raw)
except ValueError:
return fallback
def infer_mesh_format(path: str) -> str | None:
suffix = Path(path).suffix.lower()
return {
".gltf": "gltf",
".glb": "glb",
".obj": "obj",
".stl": "stl",
}.get(suffix)
def normalize_quat_xyzw(quat: list[float]) -> list[float]:
length = math.sqrt(sum(v * v for v in quat))
if length <= 1e-12:
return [0.0, 0.0, 0.0, 1.0]
return [v / length for v in quat]
def normalize_vec(vec: list[float]) -> list[float]:
length = math.sqrt(sum(v * v for v in vec))
if length <= 1e-12:
return [0.0, 0.0, 0.0]
return [v / length for v in vec]
def dot(a: list[float], b: list[float]) -> float:
return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
def cross(a: list[float], b: list[float]) -> list[float]:
return [
a[1] * b[2] - a[2] * b[1],
a[2] * b[0] - a[0] * b[2],
a[0] * b[1] - a[1] * b[0],
]
def angle_to_radians(value: float, attrs: dict[str, str]) -> float:
if attrs.get(INTERNAL_ANGLE_MODE, "degree") == "radian":
return value
return math.radians(value)
def mjcf_quat(raw: str | None) -> list[float]:
values = floats(raw, [])
if len(values) < 4:
return [0.0, 0.0, 0.0, 1.0]
# MJCF XML stores quaternions as w x y z. The browser manifest uses x y z w.
w, x, y, z = values[:4]
return normalize_quat_xyzw([x, y, z, w])
def quat_mul(a: list[float], b: list[float]) -> list[float]:
ax, ay, az, aw = a
bx, by, bz, bw = b
return normalize_quat_xyzw([
aw * bx + ax * bw + ay * bz - az * by,
aw * by - ax * bz + ay * bw + az * bx,
aw * bz + ax * by - ay * bx + az * bw,
aw * bw - ax * bx - ay * by - az * bz,
])
def quat_from_euler_xyz(raw: str | None) -> list[float]:
return quat_from_euler_xyz_with_attrs(raw, {})
def quat_from_euler_xyz_with_attrs(raw: str | None, attrs: dict[str, str]) -> list[float]:
rx, ry, rz = [angle_to_radians(value, attrs) for value in floats(raw, [0, 0, 0])[:3]]
cx, sx = math.cos(rx / 2), math.sin(rx / 2)
cy, sy = math.cos(ry / 2), math.sin(ry / 2)
cz, sz = math.cos(rz / 2), math.sin(rz / 2)
return normalize_quat_xyzw([
sx * cy * cz + cx * sy * sz,
cx * sy * cz - sx * cy * sz,
cx * cy * sz + sx * sy * cz,
cx * cy * cz - sx * sy * sz,
])
def quat_from_axis_angle(raw: str | None, attrs: dict[str, str]) -> list[float]:
values = floats(raw, [])
if len(values) < 4:
return [0.0, 0.0, 0.0, 1.0]
axis = normalize_vec(values[:3])
angle = angle_to_radians(values[3], attrs)
half = angle / 2
sin_half = math.sin(half)
return normalize_quat_xyzw([axis[0] * sin_half, axis[1] * sin_half, axis[2] * sin_half, math.cos(half)])
def quat_from_unit_vectors(source: list[float], target: list[float]) -> list[float]:
source_n = normalize_vec(source)
target_n = normalize_vec(target)
d = dot(source_n, target_n)
if d < -0.999999:
axis = cross([1.0, 0.0, 0.0], source_n)
if dot(axis, axis) < 1e-10:
axis = cross([0.0, 1.0, 0.0], source_n)
axis = normalize_vec(axis)
return [axis[0], axis[1], axis[2], 0.0]
axis = cross(source_n, target_n)
return normalize_quat_xyzw([axis[0], axis[1], axis[2], 1.0 + d])
def quat_from_matrix_columns(x_axis: list[float], y_axis: list[float], z_axis: list[float]) -> list[float]:
m00, m01, m02 = x_axis[0], y_axis[0], z_axis[0]
m10, m11, m12 = x_axis[1], y_axis[1], z_axis[1]
m20, m21, m22 = x_axis[2], y_axis[2], z_axis[2]
trace = m00 + m11 + m22
if trace > 0:
s = math.sqrt(trace + 1.0) * 2
return normalize_quat_xyzw([
(m21 - m12) / s,
(m02 - m20) / s,
(m10 - m01) / s,
0.25 * s,
])
if m00 > m11 and m00 > m22:
s = math.sqrt(1.0 + m00 - m11 - m22) * 2
return normalize_quat_xyzw([
0.25 * s,
(m01 + m10) / s,
(m02 + m20) / s,
(m21 - m12) / s,
])
if m11 > m22:
s = math.sqrt(1.0 + m11 - m00 - m22) * 2
return normalize_quat_xyzw([
(m01 + m10) / s,
0.25 * s,
(m12 + m21) / s,
(m02 - m20) / s,
])
s = math.sqrt(1.0 + m22 - m00 - m11) * 2
return normalize_quat_xyzw([
(m02 + m20) / s,
(m12 + m21) / s,
0.25 * s,
(m10 - m01) / s,
])
def quat_from_xyaxes(raw: str | None) -> list[float]:
values = floats(raw, [])
if len(values) < 6:
return [0.0, 0.0, 0.0, 1.0]
x_axis = normalize_vec(values[:3])
y_raw = normalize_vec(values[3:6])
z_axis = normalize_vec(cross(x_axis, y_raw))
y_axis = normalize_vec(cross(z_axis, x_axis))
return quat_from_matrix_columns(x_axis, y_axis, z_axis)
def quat_from_zaxis(raw: str | None) -> list[float]:
values = floats(raw, [])
if len(values) < 3:
return [0.0, 0.0, 0.0, 1.0]
return quat_from_unit_vectors([0.0, 0.0, 1.0], values[:3])
def orientation_quat(attrs: dict[str, str]) -> list[float]:
if attrs.get("quat"):
return mjcf_quat(attrs.get("quat"))
if attrs.get("euler"):
return quat_from_euler_xyz_with_attrs(attrs.get("euler"), attrs)
if attrs.get("axisangle"):
return quat_from_axis_angle(attrs.get("axisangle"), attrs)
if attrs.get("xyaxes"):
return quat_from_xyaxes(attrs.get("xyaxes"))
if attrs.get("zaxis"):
return quat_from_zaxis(attrs.get("zaxis"))
return [0.0, 0.0, 0.0, 1.0]
def rotate_vec(quat: list[float], vec: list[float]) -> list[float]:
x, y, z = vec
qx, qy, qz, qw = quat
# q * v * q^-1, expanded to avoid a dependency in the exporter.
tx = 2 * (qy * z - qz * y)
ty = 2 * (qz * x - qx * z)
tz = 2 * (qx * y - qy * x)
return [
x + qw * tx + (qy * tz - qz * ty),
y + qw * ty + (qz * tx - qx * tz),
z + qw * tz + (qx * ty - qy * tx),
]
def compose_pose(
parent_position: list[float],
parent_quat: list[float],
local_position: list[float],
local_quat: list[float],
) -> tuple[list[float], list[float]]:
rotated = rotate_vec(parent_quat, local_position)
return (
[parent_position[0] + rotated[0], parent_position[1] + rotated[1], parent_position[2] + rotated[2]],
quat_mul(parent_quat, local_quat),
)
def annotate_document(root: ET.Element, source_path: Path) -> None:
compiler = root.find("compiler")
mesh_dir = compiler.get("meshdir") if compiler is not None else None
asset_dir = compiler.get("assetdir") if compiler is not None else None
texture_dir = compiler.get("texturedir") if compiler is not None else None
angle_mode = compiler.get("angle", "degree") if compiler is not None else "degree"
source_dir = source_path.parent.resolve().as_posix()
for element in root.iter():
element.set(INTERNAL_SOURCE_DIR, source_dir)
if mesh_dir:
element.set(INTERNAL_MESH_DIR, mesh_dir)
if asset_dir:
element.set(INTERNAL_ASSET_DIR, asset_dir)
if texture_dir:
element.set(INTERNAL_TEXTURE_DIR, texture_dir)
element.set(INTERNAL_ANGLE_MODE, angle_mode)
def load_xml_with_includes(scene_path: Path) -> ET.Element:
def parse(path: Path, stack: tuple[Path, ...]) -> ET.Element:
resolved = path.resolve()
if resolved in stack:
cycle = " -> ".join(p.as_posix() for p in (*stack, resolved))
raise ValueError(f"cyclic MJCF include detected: {cycle}")
root = ET.parse(resolved).getroot()
annotate_document(root, resolved)
expand_includes(root, resolved.parent, (*stack, resolved))
return root
def expand_includes(element: ET.Element, base_dir: Path, stack: tuple[Path, ...]) -> None:
expanded: list[ET.Element] = []
for child in list(element):
if child.tag == "include":
include_file = child.get("file")
if not include_file:
continue
included_root = parse((base_dir / include_file).resolve(), stack)
expanded.extend(list(included_root))
continue
child_source = child.get(INTERNAL_SOURCE_DIR)
child_base = Path(child_source) if child_source else base_dir
expand_includes(child, child_base, stack)
expanded.append(child)
element[:] = expanded
return parse(scene_path, ())
def public_attrs(element: ET.Element) -> dict[str, str]:
return {
key: value
for key, value in element.attrib.items()
if not key.startswith("__motrix_")
}
def default_geom_attrs(root: ET.Element) -> dict[str, dict[str, str]]:
defaults: dict[str, dict[str, str]] = {}
def walk(default: ET.Element, inherited_geom: dict[str, str]) -> None:
current_geom = dict(inherited_geom)
geom = default.find("geom")
if geom is not None:
current_geom.update(public_attrs(geom))
class_name = default.get("class")
if class_name and current_geom:
defaults[class_name] = dict(current_geom)
for child in default.findall("default"):
walk(child, current_geom)
for default in root.findall("default"):
walk(default, {})
return defaults
def apply_default_attrs(element: ET.Element, defaults: dict[str, dict[str, str]]) -> dict[str, str]:
attrs: dict[str, str] = {}
class_name = element.get("class")
if class_name:
attrs.update(defaults.get(class_name, {}))
attrs.update(public_attrs(element))
attrs[INTERNAL_ANGLE_MODE] = element.get(INTERNAL_ANGLE_MODE, "degree")
return attrs
def is_collision_geom(attrs: dict[str, str]) -> bool:
class_name = (attrs.get("class") or "").lower()
if "collision" in class_name:
return True
return attrs.get("group") == "3"
def asset_url_for(asset_path: Path, scene_dir: Path, asset_base: str) -> str:
resolved = asset_path.resolve()
try:
rel = resolved.relative_to(scene_dir.resolve()).as_posix()
except ValueError:
digest = hashlib.sha1(resolved.as_posix().encode("utf-8")).hexdigest()[:10]
rel = posixpath.join("_external", f"{digest}_{resolved.name}")
encoded = "/".join(quote(part) for part in rel.split("/"))
return posixpath.join(asset_base.rstrip("/"), encoded)
def asset_mapping_key(url: str) -> str:
parsed = urlparse(url)
return parsed.path if parsed.scheme else url
def fromto_pose(raw: str | None) -> tuple[list[float], list[float], float] | None:
values = floats(raw, [])
if len(values) < 6:
return None
start = values[:3]
end = values[3:6]
delta = [end[0] - start[0], end[1] - start[1], end[2] - start[2]]
length = math.sqrt(dot(delta, delta))
if length <= 1e-12:
return None
midpoint = [(start[0] + end[0]) / 2, (start[1] + end[1]) / 2, (start[2] + end[2]) / 2]
quat = quat_from_unit_vectors([0.0, 0.0, 1.0], delta)
return midpoint, quat, length
def resolve_asset_file(element: ET.Element, file_name: str, scene_path: Path, kind: str) -> Path:
source_dir = Path(element.get(INTERNAL_SOURCE_DIR, scene_path.parent.as_posix()))
if Path(file_name).is_absolute():
return Path(file_name)
if kind == "texture":
subdir = element.get(INTERNAL_TEXTURE_DIR) or element.get(INTERNAL_ASSET_DIR)
else:
subdir = element.get(INTERNAL_MESH_DIR) or element.get(INTERNAL_ASSET_DIR)
if subdir:
return source_dir / subdir / file_name
return source_dir / file_name
def geom_to_geometry(attrs: dict[str, str], meshes: dict[str, dict[str, Any]]) -> dict[str, Any]:
geom_type = attrs.get("type")
size = floats(attrs.get("size"), [])
mesh_name = attrs.get("mesh")
if mesh_name and mesh_name in meshes:
mesh = meshes[mesh_name]
if mesh.get("url"):
url = mesh["url"]
geometry: dict[str, Any] = {"kind": "mesh", "url": url}
fmt = infer_mesh_format(url)
if fmt:
geometry["format"] = fmt
else:
geometry = {"kind": "convexMesh", "vertices": mesh.get("vertices", [])}
if mesh.get("faces"):
geometry["faces"] = mesh["faces"]
return geometry
fromto = fromto_pose(attrs.get("fromto"))
fromto_length = fromto[2] if fromto else None
if not geom_type and fromto_length is not None:
geom_type = "capsule"
if geom_type == "sphere":
return {"kind": "primitive", "primitive": "sphere", "radius": size[0] if size else 0.25}
if geom_type == "capsule":
return {
"kind": "primitive",
"primitive": "capsule",
"radius": size[0] if size else 0.1,
"length": fromto_length if fromto_length is not None else 2 * (size[1] if len(size) > 1 else 0.5),
}
if geom_type == "cylinder":
return {
"kind": "primitive",
"primitive": "cylinder",
"radius": size[0] if size else 0.1,
"length": fromto_length if fromto_length is not None else 2 * (size[1] if len(size) > 1 else 0.5),
}
if geom_type == "plane":
sx = size[0] if size else 4
sy = size[1] if len(size) > 1 else sx
return {"kind": "primitive", "primitive": "plane", "size": [2 * sx, 0, 2 * sy]}
# MJCF box size is half extent.
if geom_type == "box" or size:
if len(size) >= 3:
return {"kind": "primitive", "primitive": "box", "size": [2 * size[0], 2 * size[1], 2 * size[2]]}
if len(size) == 1:
return {"kind": "primitive", "primitive": "sphere", "radius": size[0]}
return {"kind": "primitive", "primitive": "box", "size": [0.3, 0.3, 0.3]}
def body_name(body: ET.Element, path: str, index: int) -> str:
return body.get("name") or f"{path}/body_{index}".strip("/")
def collect_manifest(scene_path: Path, asset_base: str) -> dict[str, Any]:
scene_path = scene_path.resolve()
root = load_xml_with_includes(scene_path)
defaults = default_geom_attrs(root)
material_by_id: dict[str, dict[str, Any]] = {
"default": {"id": "default", "color": "#93c5fd", "roughness": 0.65},
"fallback": {"id": "fallback", "color": "#fb7185", "wireframe": True},
}
meshes: dict[str, dict[str, Any]] = {}
textures: dict[str, dict[str, Any]] = {}
asset_files: dict[str, str] = {}
for asset in root.findall("asset"):
for texture in asset.findall("texture"):
name = texture.get("name")
if not name or texture.get("type") == "skybox":
continue
file_name = texture.get("file")
if file_name:
file_path = resolve_asset_file(texture, file_name, scene_path, "texture")
url = asset_url_for(file_path, scene_path.parent, asset_base)
textures[name] = {"url": url}
asset_files[asset_mapping_key(url)] = file_path.resolve().as_posix()
elif texture.get("builtin") == "checker":
textures[name] = {
"kind": "checker",
"colors": [
rgb_to_hex(texture.get("rgb1"), "#718096"),
rgb_to_hex(texture.get("rgb2"), "#e5e7eb"),
],
}
for material in asset.findall("material"):
mid = material.get("name")
if not mid:
continue
texture_name = material.get("texture")
if not texture_name:
for layer in material.findall("layer"):
if layer.get("role", "rgb") == "rgb" and layer.get("texture"):
texture_name = layer.get("texture")
break
color, opacity = rgba_to_hex(material.get("rgba"), "#ffffff" if texture_name else "#93c5fd")
spec: dict[str, Any] = {
"id": mid,
"color": color,
"opacity": opacity,
"roughness": float_attr(material.get("roughness"), 0.7),
"metalness": float_attr(material.get("metallic") or material.get("metalness"), 0.0),
}
if texture_name and texture_name in textures:
texture_spec = textures[texture_name]
if texture_spec.get("url"):
spec["textureUrl"] = texture_spec["url"]
elif texture_spec.get("kind") == "checker":
spec["textureKind"] = "checker"
spec["textureColors"] = texture_spec["colors"]
repeat = floats(material.get("texrepeat"), [1, 1])
spec["textureRepeat"] = [repeat[0], repeat[1] if len(repeat) > 1 else repeat[0]]
material_by_id[mid] = spec
for mesh in asset.findall("mesh"):
file_name = mesh.get("file")
name = mesh.get("name") or (Path(file_name).stem if file_name else None)
if not name:
continue
scale = floats(mesh.get("scale"), [1, 1, 1])
scale = [scale[0], scale[1] if len(scale) > 1 else scale[0], scale[2] if len(scale) > 2 else scale[0]]
if file_name:
file_path = resolve_asset_file(mesh, file_name, scene_path, "mesh")
url = asset_url_for(file_path, scene_path.parent, asset_base)
meshes[name] = {"url": url, "scale": scale}
asset_files[asset_mapping_key(url)] = file_path.resolve().as_posix()
# OBJ files can reference sidecar MTL/texture files. The previewer
# supplies its own material, but serving sidecars keeps this bridge
# useful for assets that embed auxiliary references.
if file_path.suffix.lower() == ".obj":
maybe_mtl = file_path.with_suffix(".mtl")
if maybe_mtl.exists():
mtl_url = asset_url_for(maybe_mtl, scene_path.parent, asset_base)
asset_files[asset_mapping_key(mtl_url)] = maybe_mtl.resolve().as_posix()
elif mesh.get("vertex"):
meshes[name] = {
"vertices": floats(mesh.get("vertex"), []),
"faces": ints(mesh.get("face"), []),
"scale": scale,
}
objects: list[dict[str, Any]] = []
body_counter = 0
geom_counter = 0
def walk_body(parent: ET.Element, path: str, parent_position: list[float], parent_quat: list[float]) -> None:
nonlocal body_counter, geom_counter
for geom in parent.findall("geom"):
attrs = apply_default_attrs(geom, defaults)
if is_collision_geom(attrs):
continue
geom_counter += 1
gid = attrs.get("name") or f"geom_{geom_counter}"
material = attrs.get("material") or "default"
if attrs.get("rgba") and material == "default":
material = f"{gid}_rgba"
color, opacity = rgba_to_hex(attrs.get("rgba"), "#93c5fd")
material_by_id[material] = {"id": material, "color": color, "opacity": opacity, "roughness": 0.7}
local_position = floats(attrs.get("pos"), [0, 0, 0])
local_quat = orientation_quat(attrs)
fromto = fromto_pose(attrs.get("fromto"))
if fromto:
local_position, local_quat, _ = fromto
if path:
geom_position, geom_quat = local_position, local_quat
else:
geom_position, geom_quat = compose_pose(
parent_position,
parent_quat,
local_position,
local_quat,
)
pose: dict[str, Any] = {
"position": geom_position,
"quaternion": geom_quat,
}
mesh_name = attrs.get("mesh")
if mesh_name and mesh_name in meshes:
mesh_scale = meshes[mesh_name].get("scale")
if mesh_scale and mesh_scale != [1, 1, 1]:
pose["scale"] = mesh_scale
obj: dict[str, Any] = {
"id": gid,
"name": gid,
"geometry": geom_to_geometry(attrs, meshes),
"material": material,
"pose": pose,
"castShadow": True,
"receiveShadow": True,
}
if path:
obj["body"] = path
objects.append(obj)
for child in parent.findall("body"):
body_counter += 1
name = body_name(child, path, body_counter)
child_position, child_quat = compose_pose(
parent_position,
parent_quat,
floats(child.get("pos"), [0, 0, 0]),
orientation_quat(child.attrib),
)
walk_body(child, name, child_position, child_quat)
for worldbody in root.findall("worldbody"):
walk_body(worldbody, "", [0, 0, 0], [0, 0, 0, 1])
if not objects:
objects.append({
"id": "empty_scene_marker",
"geometry": {"kind": "primitive", "primitive": "axes", "size": [1, 1, 1]},
"pose": {"position": [0, 0, 0]},
})
return {
"version": "0.1",
"name": scene_path.name,
"description": f"Generated from {scene_path.as_posix()}",
"units": "m",
"coordinateSystem": {"up": "Z", "handedness": "right"},
"materials": list(material_by_id.values()),
"objects": objects,
"lights": [
{"type": "hemisphere", "color": "#dbeafe", "intensity": 0.65},
{"type": "directional", "color": "#ffffff", "intensity": 2.2, "position": [4, -5, 7]},
],
"camera": {"position": [5, -7, 4], "target": [0, 0, 1], "fov": 48},
"state": {"mode": "poll", "url": "/state", "controlUrl": "/control", "pollIntervalMs": 50},
"_assetFiles": asset_files,
}
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("scene", type=Path)
parser.add_argument("--asset-base", default="/assets")
parser.add_argument("--output", type=Path)
args = parser.parse_args()
manifest = collect_manifest(args.scene, args.asset_base)
payload = json.dumps(manifest, ensure_ascii=False, indent=2)
if args.output:
args.output.write_text(payload + "\n", encoding="utf-8")
else:
sys.stdout.write(payload + "\n")
return 0
if __name__ == "__main__":
raise SystemExit(main())