cyberwave-robot-format 0.1.3

Universal robot description schema and format converters for Cyberwave

Cyberwave Robot Format

Universal robot description schema and format converters for Cyberwave.

Overview

This package provides:

• Universal Schema: A canonical representation for robotic assets (CommonSchema)
• Format Importers: Parse URDF, MJCF into the universal schema
• Format Exporters: Export universal schema to URDF, MJCF
• Validation: Schema validation and consistency checks

Structure

cyberwave_robot_format/
├── schema.py           # Core schema definitions (CommonSchema, Link, Joint, etc.)
├── core.py             # Base classes for parsers/exporters
├── urdf/               # URDF parser and exporter
├── mjcf/               # MJCF (MuJoCo) parser and exporter
├── mesh/               # Mesh processing utilities
├── math_utils.py       # Math utilities (Vector3, Quaternion, etc.)
└── utils.py            # General utilities

Usage

Parse URDF

from cyberwave_robot_format import CommonSchema
from cyberwave_robot_format.urdf import URDFParser

# Parse a URDF file
parser = URDFParser()
schema = parser.parse("path/to/robot.urdf")

# Validate the schema
issues = schema.validate()
if issues:
    print("Validation issues:", issues)

# Access robot components
for link in schema.links:
    print(f"Link: {link.name}, mass: {link.mass}")

for joint in schema.joints:
    print(f"Joint: {joint.name}, type: {joint.type}")

Parse MJCF (MuJoCo)

from cyberwave_robot_format.mjcf import MJCFParser

# Parse a MuJoCo XML file
parser = MJCFParser()
schema = parser.parse("path/to/robot.xml")

# Access actuators
for actuator in schema.actuators:
    print(f"Actuator: {actuator.name}, joint: {actuator.joint}")

Export to MJCF

from cyberwave_robot_format.mjcf import MJCFExporter

# Export schema to MuJoCo format
exporter = MJCFExporter()
exporter.export(schema, "output/robot.xml")

Infer URDF mimic joints (gripper coupling)

When a URDF has coupled finger / gripper joints but no <mimic> tags, infer pairs from kinematics and write a new {stem}-mimic-joint.urdf (the original file is never modified).

from pathlib import Path
from cyberwave_robot_format.urdf import (
    infer_mimic_joints,
    infer_and_patch_if_needed,
    write_mimic_patched_urdf,
)

result = infer_mimic_joints("robot.urdf")
for m in result.inferred_mimics:
    print(m.driver_joint, "→", m.slave_joint, "mult", m.multiplier, "conf", m.confidence)

# Write patched URDF when confidence ≥ 0.85 (default)
patched = infer_and_patch_if_needed(Path("robot.urdf"))
if patched.output_path:
    print("Wrote", patched.output_path)

Multiplier defaults

Context	Default
URDF <mimic> if multiplier omitted	1
offset omitted	0
Inference for opposing prismatic jaws	Often -1 when complementary limits validate

Inference checks opposing axes, complementary joint limits, and samples driver positions so slave = multiplier × driver + offset stays within slave limits. Pass an optional mjcf_path to seed coeffs from MuJoCo equality constraints.

Used by Cyberwave backend seed_controllers --infer-mimic-from-urdf and src/lib/urdf_mimic_utils.py. See cyberwave-backend/docs/mimic-joints.md for the full platform workflow (autogen, teleop, MQTT).

Cloud-Native Scene Export

Export complete scenes with meshes to ZIP files, supporting cloud storage and in-memory conversion:

from cyberwave_robot_format.mjcf import export_mujoco_zip_cloud
from cyberwave_robot_format.urdf import export_urdf_zip_cloud

# Cloud-safe resolver with in-memory DAE→OBJ conversion
def s3_resolver(filename: str) -> tuple[str, bytes] | None:
    """Download from S3 and convert in memory."""
    mesh_bytes = s3.get_object(Bucket='meshes', Key=filename)['Body'].read()

    if filename.endswith('.dae'):
        obj_bytes = convert_dae_to_obj_in_memory(mesh_bytes)
        return (filename.replace('.dae', '.obj'), obj_bytes)

    return (Path(filename).name, mesh_bytes)

# Export with cloud resolver (mesh_resolver is required)
mujoco_zip = export_mujoco_zip_cloud(
    schema,
    s3_resolver,
    strict_missing_meshes=True  # Fail fast on missing meshes
)

urdf_zip = export_urdf_zip_cloud(schema, s3_resolver)

Development

Install in editable mode:

pip install -e .

Run tests:

pytest

Acknowledgments

This project incorporates portions of code from [https://github.com/thanhndv212/robot_format_converter](Robot Format Converter) (Apache 2.0 licensed).

Original repository: https://github.com/thanhndv212/robot_format_converter

We thank the original authors for their initial work.

@software{robot_format_converter,
author = {Nguyen, Thanh},
title = {Robot Format Converter: Universal Robot Description Format Converter},
year = {2025},
url = {https://github.com/thanhndv212/robot_format_converter},
version = {1.0.0}
}