# 0.4.1 ## Fixes - Fixed inaccurate density authoring when only mass was specified - Fixed inaccurate mass authoring for visuals - Visual geoms within `inertiagrouprange` contribute to body mass in MuJoCo, and were previously authored as disabled colliders so USD would accumulate that mass - Per AOUSD Physics WG, a disabled collider should not contribute mass to its body. It is a bug in OpenUSD implementation that should not be exploited - Such geoms are now authored as purely visual, with MuJoCo's compiled mass, center of mass, and inertia authored on the owning body via `UsdPhysics.MassAPI` - Bodies whose mass comes solely from true colliders are left as-is, matching the authored intent of the MJCF - Per UsdPhysics docs, when no explicit body mass is specified, engines must accumulate implicit mass of the body using collider mass & volume - Fixed `newton:damping` authoring to be in degrees for angular joints - Fixed `newton:mimicCoef0` authoring to be in degrees for angular joints - MJCF authors joint equality constraints in the joint's position units (radians for hinge) - `NewtonMimicAPI` documents `coef0` in degrees, so this needs to be converted - Slide followers were already correct as were `coef1`, which is dimensionless. - Important: Newton 1.4 and older fail to handle the degrees-to-radians conversion for `coef0` when loading USD assets - This is fixed in Newton 1.5 and newer - Fixed material friction to author both static & dynamic friction from `geom/friction[0]` - While MuJoCo only has one value for the sliding friction bounding tangential force in the friction cone, it should apply whether a contact is stuck or slipping; in USD the equates to both `physics:staticFriction` and `physics:dynamicFriction` - Fixed accidental `MjSpec` mutation caused by model compilation - We now copy the MjSpec before compilation to ensure the original spec remains immutable - Fixed the reported geom `id` in mesh fitting warning diagnostic messages # 0.4.0 ## Features - Author `NewtonJointAPI` - Direct value authoring for `newton:armature`, `newton:friction`, and `newton:damping` - The equivalent `mjc:armature`, `mjc:frictionloss`, and `mjc:damping` are still authored as well, for applications not yet parsing `NewtonJointAPI` - Converted value authoring for `newton:limitStiffness/damping` from `mjc:solreflimit` for limited joints, including angular per-degree scaling. - Author `newton:jointsAddMobility = true` on all articulation roots, reflecting the intent of MuJoCo's joint description. ## Breaking Changes - Stopped authoring MJC schema aliases which have been deprecated in MuJoCo 3.10 - Affects some scene options, collision margin/gap, mesh max hull vertices, material rolling/torsional friction, and equality mimic metadata - All affected attributes have Newton equivalents which are now parsed in both MuJoCo and Newton. - Mapped MuJoCo `margin` directly to `newton:contactMargin` and `gap` to `newton:contactGap`, matching the MuJoCo 3.10 margin/gap semantics ## Fixes - Aligned converter output with MuJoCo 3.10 USD decoder expectations - Bodies with fixed child bodies are now considered articulation roots ## Dependencies - Updated to `newton-usd-schemas>=0.4.0` - Locked `mujoco` to `>=3.10.0,<3.11` to avoid breaking changes in 3.11.x # 0.3.0 ## Features - Apply `NewtonSiteAPI` on site prims alongside `MjcSiteAPI` - Apply `NewtonMassAPI` with `newton:massModel = "shell"` on collision geoms with shell inertia - Author `newton:inertia` compact tensor on bodies with full inertia matrices - Author `newton:contactStiffness` and `newton:contactDamping` on physics materials (computed from MuJoCo solref) ## Fixes - Fixed `mjc:flag:multiccd` authoring; it was changed to a disable bit flag in mujoco 3.8+ ## Dependencies - Updated to `newton-usd-schemas>=0.3.1` - Locked `mujoco` to `>=3.8.1,<3.9` to avoid breaking changes in 3.9.x # 0.2.0 ## Fixes - Fixed mesh/texture conversion for mujoco's `attach` assets - Fixed runtime compliance with mujoco 3.8.0 - Force-author `mjc:flag:multiccd` since the mjc schema property does not match the runtime data model in 3.8.0 - Stiffness & damping in joints and tendons is now authored from the linear term of mujoco's new polynomial force profiles, as the mjc schema only exposes the linear coefficients. ## Dependencies - Updated to `mujoco>=3.8.0` # 0.1.0 ## Fixes - Visual geoms with default density & within the `inertiagrouprange` now contribute to the mass of a body - They are now colliders, with collision disabled, with the `MassAPI` applied and `physics:density` authored - This change only happens if `inertiafromgeom` is "auto" or "true" - Normalized the `physics:principleAxes` to pass UsdPhysics validation tests - Skipped authoring `physics:principalAxes` and `physics:diagonalInertia` when the mujoco inertia is (0, 0, 0) - This is invalid in UsdPhysics, but in MuJoCo it occurs on static base bodies welded to the world. - Adjusted margin authoring to match newton runtime - `newton:contactMargin = geom.margin - geom.gap` - This change may be reverted in the future, when newton & mujoco margin/gap semantics are re-aligned ## Documentation - Added a "Verified in Newton" column to the benchmark report - Note no robots have been manually verified yet, we will update this column over time ## Dependencies - Updated to `usd-exchange==2.2.2` - Updated to `newton-usd-schemas>=0.1.0` # 0.1.0a7 ## Features - Added support for Connect, Joint, and Weld Equalities - Added support for contact excludes via `UsdPhysics.FilteredPairsAPI` ## Dependencies - Updated to `newton-usd-schemas>=0.1.0rc3` # 0.1.0a6 ## Features - Added `NewtonPhysics` schema authoring alongside `UsdPhysics` & `MjcPhysics` equivalents - Added fixed & spatial tendon conversion - Improved OBJ & STL conversion performance ## Fixes - Fixed unnamed bodies using a generic name "Body" - Fixed geom density is now authored even when it matches the default MJCF value - Fixed color/opacity/emission to respect mujoco defaults overrides - Fixed sRGB to linear colorspace conversion for diffuse color - Fixed specular color is not ignored as it does not map to `UsdPreviewSurface` appropriately - Fixed OBJs with n-gons are now supported ## Dependencies - Added `newton-usd-schemas>=0.1.0rc2` - Updated to `mujoco>=3.5.0` # 0.1.0a5 ## Features - Added material interfaces and made materials instanceable ## Fixes - Fixed material emission ## Documentation - Fixed license linter ## Dependencies - Updated to `usd-exchange==2.2.0` # 0.1.0a4 ## Fixes - Fixed `AssetPath` returned by `Converter.convert()` when layer structure is disabled ## CI/CD - Added public CI/CD coverage for Linux ARM ## Dependencies - Updated to `usd-exchange==2.2.0rc2` - Updated to `mujoco==3.4.0` due to ABI breaking changes in the 3.3 series # 0.1.0a3 ## Features - Added geom fitting around a mesh using mujoco's native fitting algorithm - Simplified Gprim authoring using usd-exchange ## Fixes - Removed `ArticulationRootAPI` from non-jointed bodies - Work around an issue with mujoco's `apirate` & `island` compiler options (by locking to older mujoco) ## Documentation - Updated copyright notice as "The Newton Developers" to align with other Newton projects. License remains Apache 2.0 - Fixed citation syntax - Simplified GitHub Issue forms - Updated Menageries benchmarks with latest results - Clarified that nested bodies are now officially supported in USD 25.11 - They also work in Newton using USD 25.05 and MuJoCO using any USD runtime ## CI/CD - Added public CI/CD coverage for Windows & Linux x86 ## Dependencies - Updated to `usd-exchange==2.1.0` - Locked to `mujoco==3.3.5` due to an ABI breaking change in recent releases. - This will be unlocked once we adopt 3.4.0 to move past the break - Fixed deployment dev dependencies # 0.1.0a2 ## Documentation - Improved PyPI README & standard pyproject urls - Updated docs for Newton governance standards - Switched from implicit DCO to explicit CLA for code contributions - Switched Code of Conduct from an adapted Contributor Covenant to the exact Linux Foundation Code of Conduct - Switched security policy from an NVIDIA specific policy to the Newton governance policy # 0.1.0a1 ## Features - **USD Asset Structure** - Output Assets are completely standalone with no dependencies on the source MJCF, OBJ, or STL files - Atomic Component structure with Asset Interface layer and payloaded contents - Separate geometry, material, and physics content layers for easy asset-reuse across domains - Library-based asset references for meshes and materials to avoid heavy data duplication - Explicit USD stage metadata with units (meters, kilograms) and up-axis (Z) - **Body Conversion** - MuJoCo bodies are converted as `UsdGeom.Xform` prims with `UsdPhysics.RigidBodyAPI` applied - worldbody becomes the `defaultPrim` on the `Usd.Stage` - All bodies under the worldbody have `UsdPhysics.ArticulationRootAPI` applied to indicate the root of each kinematic tree - Bodies are nested in USD, exactly as in the source MJCF - Complete mass properties including explicit inertia & center of mass via `UsdPhysics.MassAPI` - Mocap bodies are supported via `UsdPhysics.RigidBodyAPI.kinematicEnabled` - **Joint Conversion** - Hinge joints as `UsdPhysics.RevoluteJoint` with angular limits - Slide joints as `UsdPhysics.PrismaticJoint` with linear limits - Ball joints as `UsdPhysics.SphericalJoint` with cone angle limits - Free joints (bodies are free by default in USD) - `UsdPhysics.FixedJoints` for fully constrained parent/child bodies - All joints have automatic joint frame alignment between Body0 and Body1, accounting for MuJoCo joint axis, position, and orientation. - `MjcJointAPI` is applied to all joints specifying additional properties (e.g. armature, damping, friction loss, spring-damper) - **Geom Conversion** - All visual and collision geometry is converted to USD - Visuals are set with `default` UsdPurpose and colliders with `guide` UsdPurpose - `UsdPhysics.CollisionAPI` and `MjcCollisionAPI` are applied to colliders - Friction is provided via a bound `UsdShade.Material` with `UsdPhysics.MaterialAPI` specifying sliding (dynamic) friction and `MjcMaterialAPI` specifying torsional and rolling friction - All other MuJoCo collision properties are authored using `MjcCollisionAPI` - Meshes as `UsdGeom.Mesh` - Automatic mesh library generation with reference-based asset structure, to avoid duplicate topology - STL files converted to USD using `numpy-stl` and `usd-exchange` with normal processing - OBJ files converted using `tinyobjloader` and `usd-exchange` with UV coordinates and normal mapping - `UsdPhysics.MeshCollisionAPI` and `MjcMeshCollisionAPI` applied to mesh colliders with convex hull and inertia attributes - Planes as `UsdGeom.Plane` with infinite plane support - Spheres as `UsdGeom.Sphere` - Boxes as `UsdGeom.Cube` with scale transforms - Cylinders as `UsdGeom.Cylinder` - Capsules as `UsdGeom.Capsule` - **Site Conversion** - MuJoCo sites are converted as additional geometry prims, with `guide` UsdPurpose and `MjcSiteAPI` applied - **Visual Material and Texture Conversion** - `UsdPreviewSurface` materials with color, opacity, roughness, metallic, specular, and emissive properties - PNG texture support with automatic texture copying and path resolution - Color and opacity overrides on geometry are handled via `primvars:displayColor` and `primvars:displayOpacity` - **Actuator Conversion** - MuJoCo Actuators are converted as `MjcActuator` prims with `UsdRelationships` to the affected bodies, joints, and sites - **Simulation Options** - Gravity direction and magnitude conversion via `UsdPhysics.Scene` - All other MuJoCo options & flags via `MjcSceneAPI` applied on the `UsdPhysics.Scene` - **Prim Naming** - If MuJoCo names are not valid USD specifiers the are automatically transcoded & made unique & valid - Display name metadata preserves the original MuJoCo element names on the USD Prims - **Command Line Interface** - Input is an MJCF file and default output is a USD Layer as a structured Atomic Component with an Asset Interface USDA layer - All heavy data is compressed binary data (via USDC layers) while lightweight data is plain text for legibility - Optional comment string embedded into all authored USD Layers - Optional Stage flattening for single-file output - Optionally skip the `UsdPhysics.Scene` (this may be desirable for multi-asset setups) - Error handling with graceful failures - Enable verbose output for debugging (exposes any traceback info) - **Python API** - Full programmatic access via `mujoco_usd_converter.Converter` class with configurable parameters for all CLI flags - Enables interactive editing of the MJCF data before conversion or of the USD Layers after conversion # Known Limitations ## USD Data Conversion - **USD Asset Structure** - The value inheritance provided by MuJoCo's `defaults`, `class`, and `childclass` mechanism is baked down - The values are preserved faithfully on the inheriting Prims - A more accurate data mapping would use `UsdInherits` composition arcs to preserve modularity - MJCF attach, composite, and flexcomp mechanisms are baked down rather than preserved via composition arcs - This matches behavior of the MuJoCo parser - **Body Conversion** - Body gravcomp is authored as a custom attribute rather than an official MjcPhysics schema - **Joint Conversion** - Custom user properties on MuJoCo joints are not converted - **Geom Conversion** - Inline XML mesh topology is not implemented for meshes without files - Ellipsoid conversion is not implemented - Height Field conversion is not implemented - Signed Distance Field conversion is not implemented - Collision filtering via the `contype` & `conaffinity` algorithm is not implemented - Collision property overrides via contact/pair is not implemented - **Visual Material and Texture Conversion** - Secondary texture layers are not supported beyond the main diffuse texture - Primvars driving surface color and opacity are not supported - Primvars on geometry are supported only when there is no bound visual `UsdShade.Material` - More accurate PBR materials (e.g. OpenPBR via UsdMtlx) are not implemented - Only standard 2D file textures via texcoord mapping are supported. Texture Patterns or projections are not implemented. - This limits some of the more advanced features of the MuJoCo material/texture system, most notably checkerboards on ground planes - **Frames (extra Transforms)** - Single `Frame` elements are supported, but recursive frame support is not implemented - All frames are baked down onto the respective body, geom, site transforms rather than introduce intermediate prims - This matches behavior of the MuJoCo parser - **Other Elements** - Keyframe authoring via `MjcKeyframe` is not implemented - Camera conversion to `UsdGeom.Camera` is not implemented - Light conversion to `UsdLux` Prims is not implemented - Sensor state conversion is not implemented - Deformable flex & skin conversion is not implemented - The Visual, Statistic, and Size properties which control MuJoCo Simulate's default visualization and interactivity options are not preserved - Custom MuJoCo plugins & extensions are not mapped to USD ## Using the USD Asset in MuJoCo Simulate - MuJoCo's native USD Importer may alter Prim names, mesh topology, and other properties. - The simulation results when loading USD in MuJoCo should match the source MJCF, but a perfect round-trip of MJCF XML is not expected. ## Using the USD Asset in other USD Ecosystem applications - As with MJCF and `MjSpec`, the USD Asset contains nested rigid bodies within articulations. - Support for nested bodies in UsdPhysics is fairly new (as of USD 25.11), and some existing applications may not support this style of nesting. - Certain typed prims (e.g. `MjcActuator`) and applied APIs (e.g. `MjcJointAPI`) are MuJoCo specific - These likely will not import into other applications, unless special care is taken to account for the `MjcPhysics` schemas - Multiple joints targeting the same two bodies are converted to USD, but this can cause an over-constrained system for maximal coordinate simulators. - For example, 2 hinge joints operating in different axes may be interpreted as a 0 DOF system (rather than the 2 DOF system that was intended).