cyberwave-robot-format 0.1.2__py3-none-any.whl

cyberwave_robot_format/__init__.py

@@ -0,0 +1,80 @@
+"""Cyberwave Robot Format - Universal robot description schema and format converters.
+
+This package provides a unified schema for representing robotic assets and tools
+for converting between different robot description formats (URDF, MJCF, SDF, etc.).
+"""
+
+from cyberwave_robot_format.schema import (
+    Actuator,
+    ActuatorType,
+    Collision,
+    CollisionConfig,
+    CollisionExclude,
+    CollisionGroup,
+    CollisionPair,
+    CommonSchema,
+    Contact,
+    ContactSurface,
+    Geometry,
+    GeometryType,
+    Inertia,
+    Joint,
+    JointDynamics,
+    JointLimits,
+    JointType,
+    Link,
+    Material,
+    Metadata,
+    Physics,
+    PhysicsSolver,
+    Pose,
+    Quaternion,
+    Scene,
+    Sensor,
+    Vector3,
+    Visual,
+)
+from cyberwave_robot_format.urdf import URDFParser, URDFExporter, export_urdf_zip_cloud, export_urdf_scene_xml
+from cyberwave_robot_format.mjcf import MJCFParser, MJCFExporter, export_mujoco_zip_cloud, export_mujoco_scene_xml
+from cyberwave_robot_format.schema_export import export_universal_schema_json
+
+__version__ = "0.1.0"
+__all__ = [
+    "CommonSchema",
+    "Link",
+    "Joint",
+    "Visual",
+    "Collision",
+    "CollisionConfig",
+    "CollisionExclude",
+    "CollisionGroup",
+    "CollisionPair",
+    "Geometry",
+    "Material",
+    "Pose",
+    "Vector3",
+    "Quaternion",
+    "Inertia",
+    "JointType",
+    "GeometryType",
+    "JointLimits",
+    "JointDynamics",
+    "Actuator",
+    "ActuatorType",
+    "Sensor",
+    "Contact",
+    "ContactSurface",
+    "Physics",
+    "PhysicsSolver",
+    "Scene",
+    "Metadata",
+    "URDFParser",
+    "URDFExporter",
+    "MJCFParser",
+    "MJCFExporter",
+    "export_mujoco_zip_cloud",
+    "export_mujoco_scene_xml",
+    "export_urdf_zip_cloud",
+    "export_urdf_scene_xml",
+    "export_universal_schema_json",
+]

cyberwave_robot_format/core.py

@@ -0,0 +1,370 @@
+"""
+Core format conversion engine and orchestration classes.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .schema import CommonSchema, Material
+from .utils import detect_format, validate_schema
+
+logger = logging.getLogger(__name__)
+
+
+class ParseError(Exception):
+    """Exception raised during parsing errors."""
+
+    pass
+
+
+class ValidationError(Exception):
+    """Exception raised during validation errors."""
+
+    pass
+
+
+@dataclass
+class ParseContext:
+    """Context information for parsing operations with enhanced error tracking."""
+
+    file_path: Path
+    base_dir: Path
+    materials: dict[str, Material] = field(default_factory=dict)
+    meshes: dict[str, str] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    def add_warning(self, message: str, element: str | None = None) -> None:
+        """Add warning message with optional element context."""
+        if element:
+            message = f"{element}: {message}"
+        self.warnings.append(message)
+        logger.warning(message)
+
+    def add_error(self, message: str, element: str | None = None) -> None:
+        """Add error message with optional element context."""
+        if element:
+            message = f"{element}: {message}"
+        self.errors.append(message)
+        logger.error(message)
+
+
+class BaseParser(ABC):
+    """Base class for format parsers."""
+
+    @abstractmethod
+    def parse(self, input_path: str | Path) -> CommonSchema:
+        """Parse input file and return common schema representation."""
+
+    @abstractmethod
+    def can_parse(self, file_path: str | Path) -> bool:
+        """Check if this parser can handle the given file."""
+
+
+class BaseExporter(ABC):
+    """Base class for format exporters."""
+
+    @abstractmethod
+    def export(self, schema: CommonSchema, output_path: str | Path) -> None:
+        """Export common schema to target format."""
+
+    def get_extension(self) -> str:
+        """Return the file extension for this format."""
+        raise NotImplementedError("Subclasses must implement get_extension()")
+
+
+class ConversionEngine:
+    """Core conversion engine that orchestrates format conversions.
+
+    The engine maintains a registry of parsers and exporters for different
+    formats and handles the conversion workflow between them via the common
+    schema intermediate representation.
+
+    Example:
+        >>> engine = ConversionEngine()
+        >>> engine.register_parser('urdf', URDFParser())
+        >>> engine.register_exporter('sdf', SDFExporter())
+        >>> engine.convert('robot.urdf', 'robot.sdf')
+    """
+
+    def __init__(self):
+        self.parsers: dict[str, BaseParser] = {}
+        self.exporters: dict[str, BaseExporter] = {}
+
+    def register_parser(self, format_name: str, parser: BaseParser) -> None:
+        """Register a parser for a specific format."""
+        self.parsers[format_name.lower()] = parser
+        logger.debug("Registered parser for format: %s.", format_name)
+
+    def register_exporter(self, format_name: str, exporter: BaseExporter) -> None:
+        """Register an exporter for a specific format."""
+        self.exporters[format_name.lower()] = exporter
+        logger.debug("Registered exporter for format: %s.", format_name)
+
+    def get_parser(self, format_name: str) -> BaseParser | None:
+        """Get parser for a specific format."""
+        return self.parsers.get(format_name.lower())
+
+    def get_exporter(self, format_name: str) -> BaseExporter | None:
+        """Get exporter for a specific format."""
+        return self.exporters.get(format_name.lower())
+
+    def detect_format(self, file_path: str | Path) -> str | None:
+        """Detect format of a file using registered parsers."""
+        file_path = Path(file_path)
+
+        # Try each parser to see if it can parse the file
+        for format_name, parser in self.parsers.items():
+            if parser.can_parse(file_path):
+                return format_name
+
+        # Fall back to utility function
+        return detect_format(file_path)
+
+    def get_supported_formats(self) -> dict[str, list[str]]:
+        """Return supported formats for parsing and exporting."""
+        return {
+            "parsers": list(self.parsers.keys()),
+            "exporters": list(self.exporters.keys()),
+        }
+
+    def convert(
+        self,
+        input_path: str | Path,
+        output_path: str | Path,
+        source_format: str | None = None,
+        target_format: str | None = None,
+        validation: bool = True,
+    ) -> CommonSchema:
+        """Convert between robot description formats.
+
+        Args:
+            input_path: Path to input file
+            output_path: Path to output file
+            source_format: Source format (auto-detected if None)
+            target_format: Target format (inferred from extension if None)
+            validation: Whether to validate schema during conversion
+
+        Returns:
+            CommonSchema representation of the robot model.
+
+        Raises:
+            ValueError: If formats are unsupported or conversion fails.
+            FileNotFoundError: If input file doesn't exist.
+        """
+        input_path = Path(input_path)
+        output_path = Path(output_path)
+
+        if not input_path.exists():
+            raise FileNotFoundError(f"Input file not found: {input_path}")
+
+        # Auto-detect source format if not specified
+        if source_format is None:
+            source_format = self.detect_format(input_path)
+            if source_format is None:
+                raise ValueError(f"Cannot detect format for: {input_path}")
+
+        # Infer target format from extension if not specified
+        if target_format is None:
+            target_format = output_path.suffix.lstrip(".").lower()
+
+        # Get appropriate parser and exporter
+        parser = self.parsers.get(source_format.lower())
+        if parser is None:
+            raise ValueError(f"No parser found for format: {source_format}")
+
+        exporter = self.exporters.get(target_format.lower())
+        if exporter is None:
+            raise ValueError(f"No exporter found for format: {target_format}")
+
+        # Parse input to common schema
+        logger.info("Parsing %s file: %s.", source_format.upper(), input_path)
+        schema = parser.parse(input_path)
+
+        # Validate schema if requested
+        if validation:
+            logger.debug("Validating intermediate schema.")
+            validate_schema(schema)
+
+        # Export to target format
+        logger.info("Exporting to %s: %s.", target_format.upper(), output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        exporter.export(schema, output_path)
+
+        logger.info("Conversion complete: %s -> %s.", input_path, output_path)
+        return schema
+
+
+class FormatConverter:
+    """High-level interface for robot format conversions.
+
+    This class provides a simplified API for common conversion tasks,
+    with built-in parsers and exporters for standard formats.
+
+    Example:
+        >>> converter = FormatConverter()
+        >>> converter.urdf_to_sdf('robot.urdf', 'robot.sdf')
+        >>> converter.batch_convert('models/', 'output/', 'urdf', 'mjcf')
+    """
+
+    def __init__(self):
+        self.engine = ConversionEngine()
+        self._register_default_processors()
+
+    def _register_default_processors(self) -> None:
+        """Register default parsers and exporters for standard formats."""
+        # Import from submodules
+        from .mjcf import MJCFExporter, MJCFParser
+        from .obj import OBJMTLExporter, OBJMTLParser
+        from .schema_io import SchemaExporter, SchemaParser
+        from .sdf import SDFExporter, SDFParser
+        from .urdf import URDFExporter, URDFParser
+
+        # Register parsers
+        self.engine.register_parser("urdf", URDFParser())
+        self.engine.register_parser("sdf", SDFParser())
+        self.engine.register_parser("mjcf", MJCFParser())
+        self.engine.register_parser("xml", MJCFParser())  # MJCF is XML
+        self.engine.register_parser("schema", SchemaParser())
+        self.engine.register_parser("yaml", SchemaParser())
+        self.engine.register_parser("json", SchemaParser())
+        self.engine.register_parser("obj", OBJMTLParser())
+
+        # Register exporters
+        self.engine.register_exporter("urdf", URDFExporter())
+        self.engine.register_exporter("sdf", SDFExporter())
+        self.engine.register_exporter("mjcf", MJCFExporter())
+        self.engine.register_exporter("xml", MJCFExporter())
+        self.engine.register_exporter("schema", SchemaExporter())
+        self.engine.register_exporter("yaml", SchemaExporter())
+        self.engine.register_exporter("json", SchemaExporter())
+        self.engine.register_exporter("obj", OBJMTLExporter())
+
+        # Try to register USD support if available
+        try:
+            from .usd import USDExporter, USDParser
+
+            self.engine.register_parser("usd", USDParser())
+            self.engine.register_parser("usda", USDParser())
+            self.engine.register_exporter("usd", USDExporter())
+            self.engine.register_exporter("usda", USDExporter())
+        except ImportError:
+            logger.debug("USD support not available (missing pxr module).")
+
+    def convert(
+        self, input_path: str | Path, output_path: str | Path, **kwargs
+    ) -> CommonSchema:
+        """Convert between formats using the conversion engine."""
+        return self.engine.convert(input_path, output_path, **kwargs)
+
+    def urdf_to_sdf(self, urdf_path: str, sdf_path: str) -> CommonSchema:
+        """Convert URDF to SDF format."""
+        return self.convert(
+            urdf_path, sdf_path, source_format="urdf", target_format="sdf"
+        )
+
+    def urdf_to_mjcf(self, urdf_path: str, mjcf_path: str) -> CommonSchema:
+        """Convert URDF to MJCF format."""
+        return self.convert(
+            urdf_path, mjcf_path, source_format="urdf", target_format="mjcf"
+        )
+
+    def sdf_to_urdf(self, sdf_path: str, urdf_path: str) -> CommonSchema:
+        """Convert SDF to URDF format."""
+        return self.convert(
+            sdf_path, urdf_path, source_format="sdf", target_format="urdf"
+        )
+
+    def to_schema(self, input_path: str, schema_path: str) -> CommonSchema:
+        """Convert any supported format to common schema."""
+        return self.convert(input_path, schema_path, target_format="schema")
+
+    def from_schema(
+        self, schema_path: str, output_path: str, target_format: str | None = None
+    ) -> CommonSchema:
+        """Convert from common schema to any supported format."""
+        return self.convert(
+            schema_path,
+            output_path,
+            source_format="schema",
+            target_format=target_format,
+        )
+
+    def batch_convert(
+        self,
+        input_dir: str | Path,
+        output_dir: str | Path,
+        source_format: str,
+        target_format: str,
+        pattern: str = "*",
+    ) -> list[Path]:
+        """Batch convert files in a directory.
+
+        Args:
+            input_dir: Input directory path
+            output_dir: Output directory path
+            source_format: Source file format
+            target_format: Target file format
+            pattern: File pattern to match (default: "*")
+
+        Returns:
+            List of successfully converted output files.
+        """
+        input_dir = Path(input_dir)
+        output_dir = Path(output_dir)
+
+        if not input_dir.exists():
+            raise FileNotFoundError(f"Input directory not found: {input_dir}")
+
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Find matching files
+        # If pattern already includes extension, use it directly
+        # Otherwise, append the source format extension
+        if pattern.endswith(f".{source_format}") or "*" in pattern:
+            # Pattern already specifies the extension
+            input_files = list(input_dir.glob(pattern))
+        else:
+            ext = f".{source_format}"
+            input_files = list(input_dir.glob(f"{pattern}{ext}"))
+
+        if not input_files:
+            logger.warning("No %s files found in %s.", source_format, input_dir)
+            return []
+
+        converted_files = []
+        target_ext = f".{target_format}"
+
+        for input_file in input_files:
+            output_file = output_dir / (input_file.stem + target_ext)
+            try:
+                self.convert(
+                    input_file,
+                    output_file,
+                    source_format=source_format,
+                    target_format=target_format,
+                )
+                converted_files.append(output_file)
+            except Exception as e:
+                logger.error("Failed to convert %s: %s.", input_file, e)
+
+        logger.info(
+            "Batch conversion complete: %s/%s files converted.",
+            len(converted_files),
+            len(input_files),
+        )
+        return converted_files
+
+    def get_conversion_matrix(self) -> dict[str, list[str]]:
+        """Get matrix of supported conversion paths."""
+        formats = self.engine.get_supported_formats()
+        matrix = {}
+
+        for source_fmt in formats["parsers"]:
+            matrix[source_fmt] = formats["exporters"]
+
+        return matrix

cyberwave_robot_format/math_utils.py

@@ -0,0 +1,110 @@
+"""
+Math utilities for robot format conversion.
+
+This module provides common mathematical types used across the format conversion
+pipeline: vectors, quaternions, poses, and inertia tensors.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class Vector3:
+    """3D vector representation."""
+
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+
+    def to_list(self) -> list[float]:
+        """Convert to list format."""
+        return [self.x, self.y, self.z]
+
+    def to_array(self) -> np.ndarray:
+        """Convert to numpy array."""
+        return np.array([self.x, self.y, self.z])
+
+    @classmethod
+    def from_list(cls, values: list[float]) -> Vector3:
+        """Create from list of values."""
+        return cls(values[0], values[1], values[2])
+
+
+@dataclass
+class Quaternion:
+    """Quaternion representation for rotations."""
+
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+    w: float = 1.0
+
+    def to_list(self) -> list[float]:
+        """Convert to list format [x, y, z, w]."""
+        return [self.x, self.y, self.z, self.w]
+
+    @classmethod
+    def from_rpy(cls, roll: float, pitch: float, yaw: float) -> Quaternion:
+        """Create quaternion from roll-pitch-yaw angles (Fixed XYZ convention)."""
+        cy = math.cos(yaw * 0.5)
+        sy = math.sin(yaw * 0.5)
+        cp = math.cos(pitch * 0.5)
+        sp = math.sin(pitch * 0.5)
+        cr = math.cos(roll * 0.5)
+        sr = math.sin(roll * 0.5)
+
+        w = cr * cp * cy + sr * sp * sy
+        x = sr * cp * cy - cr * sp * sy
+        y = cr * sp * cy + sr * cp * sy
+        z = cr * cp * sy - sr * sp * cy
+
+        return cls(x, y, z, w)
+
+
+@dataclass
+class Pose:
+    """6DOF pose representation."""
+
+    position: Vector3 = None  # type: ignore[assignment]
+    orientation: Quaternion = None  # type: ignore[assignment]
+
+    def __post_init__(self) -> None:
+        if self.position is None:
+            self.position = Vector3()
+        if self.orientation is None:
+            self.orientation = Quaternion()
+
+    @classmethod
+    def from_xyzrpy(cls, xyz: list[float], rpy: list[float]) -> Pose:
+        """Create pose from position and RPY orientation."""
+        return cls(
+            position=Vector3.from_list(xyz),
+            orientation=Quaternion.from_rpy(rpy[0], rpy[1], rpy[2]),
+        )
+
+
+@dataclass
+class Inertia:
+    """Inertia tensor representation."""
+
+    ixx: float = 0.0
+    iyy: float = 0.0
+    izz: float = 0.0
+    ixy: float = 0.0
+    ixz: float = 0.0
+    iyz: float = 0.0
+
+    def to_matrix(self) -> np.ndarray:
+        """Convert to 3x3 inertia matrix."""
+        return np.array(
+            [
+                [self.ixx, self.ixy, self.ixz],
+                [self.ixy, self.iyy, self.iyz],
+                [self.ixz, self.iyz, self.izz],
+            ]
+        )

cyberwave_robot_format/mesh/__init__.py

@@ -0,0 +1,13 @@
+from cyberwave_robot_format.mesh.processing import (
+    convert_dae_to_obj,
+    convert_mesh_bytes_to_obj,
+    get_mesh_lookup_key,
+)
+from cyberwave_robot_format.mesh.resolution import resolve_mesh_uri
+
+__all__ = [
+    "convert_dae_to_obj",
+    "convert_mesh_bytes_to_obj",
+    "get_mesh_lookup_key",
+    "resolve_mesh_uri",
+]