urdf-mujoco-converter 0.1.0__tar.gz

urdf_mujoco_converter-0.1.0/.github/workflows/check.yml

@@ -0,0 +1,18 @@
+name: Check
+on: [push, pull_request]
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.11', '3.12']
+    env:
+      UV_PYTHON: ${{ matrix.python }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --locked --python ${{ matrix.python }}
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest
+      - run: uv build

urdf_mujoco_converter-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/urdf-mujoco-converter
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Verify release version
+        run: |
+          uv run --no-project --python 3.12 python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path('pyproject.toml').read_text())['project']['version']
+          assert os.environ['GITHUB_REF_NAME'] == f'v{version}', 'Tag must match project version'
+          PY
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/*
+      - run: uv publish --trusted-publishing always

urdf_mujoco_converter-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+MUJOCO_LOG.TXT

urdf_mujoco_converter-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

urdf_mujoco_converter-0.1.0/AGENTS.md

@@ -0,0 +1,11 @@
+# Development rules
+
+- Keep one URDF-to-MJCF conversion path and a small public Python interface.
+- Follow Google Python Style Guide; use Google-style docstrings and type annotations.
+- Use `uv` for environments, dependencies, tests, lint and builds.
+- Keep physics explicit. Never invent inertials or silently drop articulation.
+- Reject planar/floating URDF joints. Preserve scalar mimic, including valid chains.
+- Keep scenes, root motion and controllers downstream. Accept explicitly authored native actuator XML; never choose drive gains or rewrite source geometry/inertials.
+- Keep USD/Newton dependencies in separate integration environments.
+- Run `just check` before handing off code changes.
+- Do not commit or publish without user authorization.

urdf_mujoco_converter-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: urdf-mujoco-converter
+Version: 0.1.0
+Summary: Strict URDF to MJCF conversion with portable mesh assets.
+Project-URL: Repository, https://github.com/ruziniuuuuu/urdf-mujoco-converter
+Project-URL: Documentation, https://github.com/ruziniuuuuu/urdf-mujoco-converter/blob/main/docs/conversion.md
+Project-URL: Issues, https://github.com/ruziniuuuuu/urdf-mujoco-converter/issues
+Requires-Python: >=3.11
+Requires-Dist: mujoco<3.12,>=3.11
+Requires-Dist: numpy<3,>=2
+Requires-Dist: pillow<13,>=11
+Requires-Dist: scipy<2,>=1.11
+Requires-Dist: trimesh<5,>=4.6
+Description-Content-Type: text/markdown
+
+# urdf-mujoco-converter
+
+Convert expanded URDF into validated MJCF with portable meshes and textures.
+Preserves fixed frames, explicit inertials, scalar joints and mimic chains.
+Requires Python 3.11+.
+
+```bash
+uvx --from urdf-mujoco-converter==0.1.0 urdf-mujoco-converter \
+  robot.urdf output/robot --package robot_description=/path/to/robot_description \
+  --config physics.xml
+```
+
+`uvx` installs the released tool in uv's cache; no project virtual environment or
+source checkout is needed. Omit `--config` when no additional MJCF parameters are
+required. Repeat it to compose native XML files. For a persistent CLI installation,
+use `uv tool install urdf-mujoco-converter==0.1.0`.
+
+```python
+from urdf_mujoco_converter import convert
+
+result = convert(
+    "robot.urdf",
+    "output/robot",
+    packages={"robot_description": "/path/to/robot_description"},
+    config="physics.xml",  # Optional native MJCF XML configuration.
+)
+print(result.mjcf_path)
+```
+
+Output: `robot.xml`, `robot.meta.json`, `meshes/` and, when needed, `textures/`.
+Each output directory belongs exclusively to one source URDF and is replaced
+only after successful MuJoCo compilation.
+
+OBJ, STL and static GLB are supported. `planar`/`floating` joints are errors.
+Nonconvex collisions require explicit `--allow-convex-hull` approximation.
+Native XML supplies explicit simulation settings, actuators and sensors.
+Scenes, root motion and higher-level controllers remain downstream.
+
+See [conversion contract](docs/conversion.md), [architecture](docs/architecture.md)
+and [Newton/USD compatibility and checks](docs/newton-compatibility.md).
+
+For development, clone the repository, run `uv sync --locked`, then `just check`
+and `just build`. See [publishing](docs/publishing.md) for release maintenance.

urdf_mujoco_converter-0.1.0/README.md

@@ -0,0 +1,43 @@
+# urdf-mujoco-converter
+
+Convert expanded URDF into validated MJCF with portable meshes and textures.
+Preserves fixed frames, explicit inertials, scalar joints and mimic chains.
+Requires Python 3.11+.
+
+```bash
+uvx --from urdf-mujoco-converter==0.1.0 urdf-mujoco-converter \
+  robot.urdf output/robot --package robot_description=/path/to/robot_description \
+  --config physics.xml
+```
+
+`uvx` installs the released tool in uv's cache; no project virtual environment or
+source checkout is needed. Omit `--config` when no additional MJCF parameters are
+required. Repeat it to compose native XML files. For a persistent CLI installation,
+use `uv tool install urdf-mujoco-converter==0.1.0`.
+
+```python
+from urdf_mujoco_converter import convert
+
+result = convert(
+    "robot.urdf",
+    "output/robot",
+    packages={"robot_description": "/path/to/robot_description"},
+    config="physics.xml",  # Optional native MJCF XML configuration.
+)
+print(result.mjcf_path)
+```
+
+Output: `robot.xml`, `robot.meta.json`, `meshes/` and, when needed, `textures/`.
+Each output directory belongs exclusively to one source URDF and is replaced
+only after successful MuJoCo compilation.
+
+OBJ, STL and static GLB are supported. `planar`/`floating` joints are errors.
+Nonconvex collisions require explicit `--allow-convex-hull` approximation.
+Native XML supplies explicit simulation settings, actuators and sensors.
+Scenes, root motion and higher-level controllers remain downstream.
+
+See [conversion contract](docs/conversion.md), [architecture](docs/architecture.md)
+and [Newton/USD compatibility and checks](docs/newton-compatibility.md).
+
+For development, clone the repository, run `uv sync --locked`, then `just check`
+and `just build`. See [publishing](docs/publishing.md) for release maintenance.

urdf_mujoco_converter-0.1.0/docs/architecture.md

@@ -0,0 +1,44 @@
+# Architecture
+
+The public surface is `convert(...) -> ConversionResult`, `ConversionError` and
+`Diagnostic` and `MjcfConfig`. The CLI only parses arguments, configures logging and calls that
+function. Internal XML trees and implementation classes are private.
+
+```text
+expanded URDF + optional scoped native XML fragments
+  -> validate graph, supported joints and mimic references
+  -> resolve local assets and export geometry/material parts
+  -> emit MJCF and source-joint metadata in a sibling staging directory
+  -> compose XML, resolve resources and enforce component ownership
+  -> compile with MuJoCo and verify source geometry/physics are unchanged
+  -> resolve equivalent native position damping to explicit kv
+  -> replace the directory owned by this source URDF
+```
+
+| Module | Responsibility |
+| --- | --- |
+| `_convert.py` | Public operation, ownership checks, staging, compilation, publication |
+| `_urdf.py` | URDF graph and mimic validation |
+| `_mjcf.py` | Coordinates, inertials, joints, geometry bindings, metadata |
+| `_mesh.py` | Resource resolution, scene transforms, material partitions, portable files |
+| `_config.py` | Native XML composition, scoped names, references and resource closure |
+| `_validation.py` | Native compilation, source invariants and actuator diagnostics |
+| `_common.py` | Results, diagnostics and numeric/XML helpers |
+| `cli.py` | Command-line arguments and exit status |
+
+ElementTree is the source and destination representation. There is no second
+robot IR, backend adapter hierarchy, plugin registry or configurable stage graph.
+Per-conversion mesh/material caches belong to the exporter instance and cannot
+leak across conversions. Adding another supported mesh format should extend this
+boundary with representative tests, not add another conversion pipeline.
+
+MuJoCo is a required validator. Newton and OpenUSD are optional integration tools
+in separate environments, because their tested MuJoCo requirements differ.
+`tools/check_newton.py` exercises the checked-in mimic example through both
+import paths. It does not become a runtime dependency.
+
+Use Google-style Python docstrings and typed interfaces. Run `just check` for
+lint, formatting and behavioral tests, and `just build` for distribution artifacts.
+Tests exercise `convert()` and compiled MuJoCo behavior. Asset-specific integration
+results belong in the compatibility document; do not hardcode Galbot paths or
+physical corrections into the converter.

urdf_mujoco_converter-0.1.0/docs/conversion.md

@@ -0,0 +1,279 @@
+# Conversion contract
+
+## Inputs and public API
+
+```python
+convert(urdf_path, output_dir, *, config=None, packages=None,
+        allow_convex_hull=False) -> ConversionResult
+```
+
+Input must be one expanded URDF file. Expand Xacro upstream; ROS is not required.
+Relative resources resolve against the URDF directory, including legitimate `..`
+references. Absolute local paths are accepted. `package://name/path` requires an
+explicit `packages={"name": "/package/root"}` mapping and cannot escape that root.
+Network URLs and missing resources are errors. GLB must embed buffers and images.
+
+The result contains `mjcf_path`, `metadata_path`, `metadata` and `diagnostics`.
+Invalid inputs raise `ConversionError`; filesystem failures may raise `OSError`.
+The CLI accepts the same options through repeatable `--config`, repeatable
+`--package NAME=PATH`, and `--allow-convex-hull`. Success prints the MJCF path to
+stdout; diagnostics go to stderr; conversion failure exits with status 1.
+
+## Output and ownership
+
+```text
+output_dir/
+  robot.xml
+  robot.meta.json
+  meshes/          # When mesh geometry exists.
+  textures/        # When textures exist.
+```
+
+All file references in MJCF are relative and contained in this directory. Source
+meshes are not modified. Generated filenames are unique sequential names, shared
+within the conversion where possible. Output is movable without its source files.
+
+A nonempty directory is replaceable only if its metadata identifies this generator
+and the same absolute source URDF path. Never put hand-maintained files in it:
+**the whole owned directory is replaced**. A different URDF must use a different
+output directory. Input URDF/config/mesh/material resources cannot be inside the
+output directory. Output-directory symlinks are rejected.
+
+A sibling staging directory is compiled before publication. A sibling lock rejects
+concurrent conversions to the same destination. Replacement uses a backup/rename
+sequence with rollback if publication fails. This protects against normal
+conversion errors; it is not a crash-durable filesystem transaction. If a process
+is killed during publication, inspect sibling `.NAME.backup-*`/`.NAME.stage-*`
+directories before removing the stale `.NAME.conversion.lock`. Do not remove the
+lock while another conversion is active. Renaming a source file changes ownership.
+
+## Frames, physical data and joints
+
+Units are metres, kilograms, seconds and radians. Link bodies retain original
+names. Each child body uses the incoming URDF joint origin relative to its parent.
+URDF RPY means `Rz(yaw) Ry(pitch) Rx(roll)`; MJCF quaternions use `w x y z`.
+Joint axes are normalized in the joint/child-link frame; scalar joint refs are zero.
+Fixed joints have no MJCF joint, but their link bodies remain, including massless
+mounting frames. No free root joint or world anchor body is generated.
+Actuators are added only when explicitly defined in the XML configuration.
+The resulting root is stationary until the downstream loader adds motion.
+
+Explicit mass and COM are preserved. Full symmetric inertias are rotated from the
+URDF inertial frame into the link frame. No mesh-density inference, dummy mass or
+automatic inertia balancing is used. Invalid positive-mass inertias are errors.
+Zero-mass/zero-inertia fixed frames are allowed; missing moving-link physics must
+still satisfy MuJoCo's actual compiler. Compilation is not physical calibration.
+
+| URDF joint | Conversion |
+| --- | --- |
+| `fixed` | Body only; metadata maps to `[]` |
+| `revolute` | Hinge with required ordered lower/upper limits |
+| `continuous` | Unlimited hinge |
+| `prismatic` | Slide with required ordered lower/upper limits |
+| `planar`, `floating`, unknown | Explicit error before conversion |
+
+Planar/floating are intentionally rejected, rather than approximated or ignored.
+Compound mappings are possible in MuJoCo, but have different downstream import
+semantics; see the compatibility document. Downstream root-motion configuration is
+separate from support for these URDF joint types.
+
+URDF joint damping maps to `damping`; friction maps to `frictionloss`. Effort and
+velocity are source metadata only: the converter does not create control limits
+or choose actuator gains. Explicit actuator XML controls clamping. Safety-controller, calibration, transmission, Gazebo and ros2_control
+extensions are not converted and produce diagnostics when present.
+
+Mimic maps to MJCF joint equality:
+
+```text
+q_follower = offset + multiplier * q_leader
+joint1 = follower; joint2 = leader; polycoef = [offset, multiplier, 0, 0, 0]
+```
+
+Negative/zero multipliers, nonzero offsets and acyclic chains are supported.
+Missing/fixed targets, cycles and mixing angular/linear joints are errors. Mimic
+remains a **soft equality constraint**, not a reduced-coordinate substitution;
+it retains scalar DOFs and may have numerical residuals. A nonzero offset may
+make the all-zero initial state inconsistent. Choose a consistent initial pose
+and solver parameters downstream; do not assume bit-exact kinematic coupling.
+Conflicting follower/leader limits are not automatically reconciled.
+
+## Geometry and materials
+
+Box, sphere and cylinder primitives are supported. Mesh inputs are OBJ, STL and
+static GLB 2.0. Other mesh formats are explicitly rejected for now.
+
+Scene instances and material partitions become separate geoms. Scene transforms
+are applied before the URDF mesh scale, including nonuniform/negative scales;
+normals use the inverse transpose and reflection winding is corrected. The URDF
+visual/collision origin remains a geom transform. No surface simplification,
+recentring or implicit unit conversion is applied.
+
+Each exported OBJ contains one shape, with normals and UVs when available. A
+single-triangle visual is subdivided into four triangles with interpolated UVs
+and normals, preserving its surface, because MuJoCo requires four mesh vertices.
+This produces an INFO diagnostic. Visual mesh assets use `inertia="shell"` so
+planar surfaces compile; link inertias remain explicit (`inertiafromgeom=false`).
+
+Visuals use `contype=0`, `conaffinity=0`, group 2. Collisions use group 3 and native
+MuJoCo filtering. Each collision mesh/material part must be a closed convex solid.
+Nonconvex/open collision meshes error by default. `allow_convex_hull=True` replaces
+each offending part with a convex hull and emits a warning. It can fill holes and
+bridge gaps; it does not perform convex decomposition. Even files named
+`convex_hull` are checked. Provide separate convex parts upstream when appropriate.
+
+Basic RGBA and base-color textures are retained. Textures become uniquely named
+PNG files; OBJ material-library filenames are not relied on downstream. Explicit
+URDF materials take precedence over mesh materials. GLTF PBR is approximated to
+base color/texture with a warning: metallic/roughness, normal/emissive maps,
+alpha modes and other lighting features are not reproduced. Color values follow
+the mesh loader's basic-color interpretation, not a promise of colorimetric
+identity across renderers. Mesh vertex/face colors must be uniform; varying colors
+require a baked texture. Skinning, animation, morph targets, required GLTF
+extensions, non-default UV sets and texture transforms are unsupported.
+
+## Native XML configuration
+
+`config` accepts an XML path, a `MjcfConfig`, or a sequence of these. YAML and
+Python property mappings are not accepted. CLI `--config` is repeatable.
+Files use `<mujoco>` or `<mujocoinclude>` roots without attributes:
+
+```xml
+<mujoco>
+  <option integrator="implicitfast" cone="elliptic" iterations="50">
+    <flag energy="enable"/>
+  </option>
+  <worldbody>
+    <body name="shoulder_link">
+      <joint name="shoulder" damping="0.5" armature="0.1"/>
+      <site name="tip" pos="0 0 0.1" size="0.01"/>
+    </body>
+  </worldbody>
+  <actuator>
+    <position name="shoulder_ctrl" joint="shoulder" kp="100"
+              dampratio="1" inheritrange="1" forcerange="-80 80"/>
+  </actuator>
+  <sensor><jointpos name="shoulder_position" joint="shoulder"/></sensor>
+</mujoco>
+```
+
+The XML layer does not maintain a physics-field whitelist. MuJoCo validates native
+attributes, nested `option/flag`, defaults, actuator types, sensors, tendons,
+contacts, equality constraints, custom data, keyframes and rendering settings.
+Availability follows the installed MuJoCo version, within the source-authority
+boundary below. Native `default` inheritance is retained: it does not override
+attributes explicitly written on generated elements. Assign named classes or
+explicitly update the relevant object. The compiler enables `autolimits` by
+default; URDF joint limits remain explicit.
+
+**Named updates are converter composition semantics, not native include semantics.**
+A `worldbody/body` selects an existing URDF link body by name, without repeating
+its full ancestry. Nested bodies must match their actual immediate parent.
+Existing named joints/geoms update in place; missing targets fail. Geoms are named
+`<link>_<visual|collision>_<URDF index>_<material part index>`, with zero-based indices.
+Sites, cameras, lights and plugin attachments may be added to existing bodies.
+Existing mimic equalities are named `mimic_<follower joint>` and may receive solver
+parameters, but their joint references, polynomial and activation are protected.
+New top-level definitions are added using ordinary MJCF elements. Duplicate names
+or repeated assignments to the same setting fail, including across files; there
+is no last-file-wins override mechanism.
+
+URDF owns body/joint topology, geometry, frames, limits, mass and inertia. They
+cannot be rewritten through XML configuration, including indirectly through
+compiler/default settings. A native compilation before/after composition compares
+source bodies, joints, geoms, meshes and mimic relations. New bodies/joints/geoms,
+inertials, model attachment and deformable geometry belong in the source model or
+a downstream scene, not this configuration layer. Invalid native features fail
+compilation; nothing is silently omitted to make a model importable.
+
+Use the optional descriptor for component ownership and repeated instances:
+
+```python
+from urdf_mujoco_converter import MjcfConfig, convert
+
+convert("robot.urdf", "output", config=[
+    "shared.xml",
+    MjcfConfig("hand.xml", prefix="left_", bodies=("palm", "finger")),
+])
+```
+
+Here the expanded input URDF already contains `left_palm`, `left_finger`, etc.
+The descriptor prefixes XML definitions and owned object references, including
+mimic names, named default classes and typed sensor references. File paths and
+plugin identifiers are not renamed. `bodies` declares unprefixed URDF links;
+updates and references outside the component fail. Component defaults must be
+named classes; `childclass` cannot leak into another component's descendants.
+Global compiler/option/size/visual/statistic settings require a robot-wide or empty
+body scope; keyframes require an unscoped document. Components may reference shared
+assets/classes.
+
+Local `<include file="..."/>` expands recursively, with cycle checking. Resources
+resolve against the declaring XML file; compiler mesh/texture/asset directories
+apply within that input document and are consumed during packaging. Assets are
+copied into output `meshes/` or `textures/`; `strippath=true` is rejected because it
+would break those references. Package URIs use the same explicit package map as
+URDF resources. Missing files, input/output overlap and escaping package paths
+fail. No network resources are fetched. Native plugin libraries must already be
+registered in the runtime; they are not bundled as mesh resources.
+
+Actuators use native clamping semantics and native `gear`, gains, transmission,
+activation and control ranges. URDF effort/velocity metadata is not automatically
+turned into motor limits. Position `inheritrange="1"` uses the current joint range;
+force bounds must be explicit. A position servo does not enforce velocity limits.
+Position damping ratios, including inherited defaults, are resolved by MuJoCo to
+explicit `kv` before publication. This equivalence is logged and recorded; changing
+downstream inertia does not retune the exported `kv` automatically.
+
+See [examples/physics.xml](../examples/physics.xml). Native MJCF validity and
+Newton/USD compatibility are separate requirements: run independent compatibility
+checks for the intended downstream features; never silently discard unsupported
+features or restrict the native configuration schema to Newton's current subset.
+
+## Metadata and diagnostics
+
+```json
+{
+  "schema_version": 1,
+  "generated_by": "urdf-mujoco-converter",
+  "source_urdf": "/absolute/source/robot.urdf",
+  "joints": {
+    "shoulder": {
+      "urdf_type": "revolute",
+      "mjcf_joints": ["shoulder"],
+      "source_limits": {"effort": 80.0, "velocity": 2.0}
+    }
+  },
+  "diagnostics": []
+}
+```
+
+`source_urdf` is ownership/provenance, not a runtime resource dependency. Missing
+source limit fields are omitted, not guessed. No unstable qpos/qvel indices are
+stored. The sidecar is not automatically consumed by the USD converter or Newton.
+
+`configuration` records input files, component scopes, prefixes and resource
+dependencies. `simulation_profile.actuators` records compiled actuator names,
+joint targets, gains, biases, clamping flags and ranges; multiple actuators on a
+joint remain separate records. The final XML contains the complete native model.
+
+Each diagnostic has `level`, `code`, `message`, `context`. Codes currently include
+`xml_configuration`, `xml_parameter`, `resolved_damping_ratio`, `material_approximation`, `collision_convex_hull`,
+`visual_triangle_subdivision`, `source_limits_metadata_only`, `downstream_extension`.
+Identical notices are deduplicated per conversion. The library uses the standard
+`urdf_mujoco_converter` logger without configuring global handlers; exceptions are
+reported as ERROR by the CLI. Failed conversions return no success result.
+
+An empty body scope (`bodies=()`) declares shared settings/assets without permission
+to update or reference any URDF body, joint or geom. The asset library uses this
+for its shared configuration; component files declare their owned bodies.
+
+Native compilation is followed by a finite-number check: MuJoCo can warn and
+accept NaN attributes, but the converter rejects nonfinite compiled fields.
+
+In a separate Newton environment, `python tools/check_actuators.py MODEL.xml
+MODEL.usda` compares joint-actuator gains, damping, transmissions, limits and
+sampled forces through both import paths. It fails on mismatches or unsupported
+transmissions/ambiguous targets. Importer warnings remain visible in its report;
+this check does not certify other MJCF features or contact dynamics.
+
+The same check is available as `just check-actuators NEWTON_PYTHON MODEL.xml MODEL.usda`,
+where `NEWTON_PYTHON` is the Python executable in the separate Newton environment.