Skip to content

novaphy.io

Asset import / export utilities for robotics and digital-content pipelines: URDF, MJCF, conservative USDA-text loading, scene build metadata, simulation recording / export, and feature-completeness checking. These symbols live at the top level of novaphy; they are grouped here to mirror Newton's newton.usd and importer-related APIs.

Support Depth at a Glance

NovaPhy supports three asset formats with different levels of integration depth:

Format Entry point Coverage today
URDF UrdfParser → UrdfModelData → SceneBuilderEngine First-class. Full data-class family for links / joints / visual / collision / inertial / geometry.
MJCF (MuJoCo XML) ModelBuilder.add_mjcf(path) / add_mjcf_string(xml) Convenience methods on ModelBuilder only — no separate parser class. Returns the articulation index.
PhysX USDA articulation ModelBuilder.add_usd(path, ...) Direct text-file import for supported rigid bodies, joints, and collision shapes.
USDA text snapshot OpenUsdImporter → UsdStageData → SceneBuilderEngine Smaller lightweight snapshot parser; not an OpenUSD runtime or schema resolver.

For URDF and the USDA text snapshot, the typical end-to-end flow is:

import novaphy

# URDF
parser   = novaphy.UrdfParser()
data     = parser.parse_file("robot.urdf")
engine   = novaphy.SceneBuilderEngine()
result   = engine.build_from_urdf(data, novaphy.UrdfImportOptions())
model    = result.model

# USDA text snapshot
stage    = novaphy.OpenUsdImporter(min_supported_version=1.0).import_file("scene.usda")
result2  = engine.build_from_openusd(stage)

For MJCF or a PhysX USDA articulation, skip the parser class and call ModelBuilder directly:

builder = novaphy.ModelBuilder()
art_idx = builder.add_mjcf("robot.xml")
root_body = builder.add_usd("robot.usda")
model   = builder.finalize()

When to Use SceneBuilderEngine vs ModelBuilder

  • ModelBuilder — programmatic scene construction (add bodies / joints by hand, MJCF / PhysX USDA convenience). Fastest path when assets are simple or generated.
  • SceneBuilderEngine — orchestrated build from parsed URDF / USD with metadata recovery (link / joint / shape names, source paths). Use this when the partner application needs to round-trip names and references back into NovaPhy.

Recording and Feature Checks

SimulationExporter records keyframes / collision events / constraint reactions for offline analysis. FeatureCompletenessChecker walks an imported asset against a feature checklist to flag unsupported URDF / USD features before they cause silent issues.

URDF

Class Description
UrdfCollision URDF collision element.
UrdfGeometry URDF geometry payload.
UrdfGeometryType URDF geometry type enumeration.
UrdfImportOptions URDF import behaviour switches.
UrdfInertial URDF inertial block.
UrdfJoint URDF joint description.
UrdfLink URDF link description.
UrdfMaterial URDF material / texture metadata, including resolved texture paths.
UrdfMeshCollisionMode Mesh collision import mode: box fallback, triangle mesh, convex hull, skip, or error.
UrdfTransmission Parsed URDF transmission metadata for drive-default recovery.
UrdfGazeboExtension Parsed Gazebo contact / friction extension metadata.
UrdfAssetIssue One asset-audit issue entry.
UrdfAssetAuditReport Aggregate asset-audit report returned by SceneBuilderEngine.audit_urdf(...).
UrdfModelData Parsed URDF model data.
UrdfParser URDF file parser.
UrdfVisual URDF visual element.

URDF mesh collision behavior is controlled through UrdfImportOptions.mesh_collision_mode. Use TriangleMesh or ConvexHull when the mesh exists and should be used for collision, BoxFallback for a conservative bounding-box proxy, Skip to omit unresolved mesh collisions, and Error to fail fast when a required collision mesh is missing.

Use SceneBuilderEngine.audit_urdf(data, options) before building partner assets. The report counts missing meshes / textures, unsupported joints, mimic metadata that is not runtime-backed, transmission drive-default usage, and unsupported xacro constructs.

USDA text subset

Class Description
OpenUsdImporter Conservative USDA-like text snapshot parser.
UsdAnimationTrack USD animation track entry.
UsdPrim USD prim entry.
UsdStageData Parsed text-stage snapshot.

MJCF

NovaPhy adds two convenience methods directly on ModelBuilder for in-memory or path-based MJCF parsing:

  • ModelBuilder.add_mjcf(xml_path)
  • ModelBuilder.add_mjcf_string(xml_text)

Both return the articulation index that was added, or -1 when the file contains no bodies.

Current MJCF coverage includes:

  • nested <worldbody> / <body> trees, <inertial> blocks, sites, and box, sphere, capsule, cylinder, plane, and mesh geoms
  • hinge, slide, ball, and free joints; multiple hinge/slide joints on one body can be combined into a D6 joint
  • <compiler>, <option>, default classes, and recursive includes
  • general, position, velocity, and motor actuators, plus explicit collision pairs
  • connect, weld, and joint equality rows
  • fixed and spatial tendons

Mesh assets are imported by default (parse_meshes=True). Sites, visuals, equality conversion, root transforms, fixed-joint collapsing, and other import behavior can be controlled through ModelBuilder.add_mjcf(...) keyword arguments.

Features intentionally deferred are HFIELD and SDF geometry plus material/texture rendering.

Scene Build Pipeline

Class Description
SceneBuilderEngine High-level scene build orchestrator.
SceneBuildMetadata Aggregate scene build metadata.
SceneBuildResult Result of a scene build pass.
SceneJointMetadata Scene joint metadata.
SceneLinkMetadata Scene link metadata.
SceneShapeMetadata Scene shape metadata.
SceneAppendOptions Options for appending an imported scene into an existing ModelBuilder.
SceneAppendResult Index offsets and appended body / shape / joint indices.

SceneBuilderEngine.build_from_urdf(...) returns a finalized model plus metadata. When composing multiple imported assets into one scene, call SceneBuilderEngine.append_to_builder(builder, scene, SceneAppendOptions()) before builder.finalize().

Recording and Export

Class Description
RecordedCollisionEvent Recorded collision event entry.
RecordedConstraintReaction Recorded constraint reaction entry.
RecordedKeyframe Recorded keyframe entry.
SimulationExporter Simulation results exporter.

Feature Completeness

Class Description
FeatureCheckItem Per-feature check entry.
FeatureCheckReport Aggregate feature check report.
FeatureCompletenessChecker Importer / exporter feature coverage checker.