Skip to content

novaphy.io

Asset import / export utilities for robotics and digital-content pipelines: URDF, MJCF, OpenUSD scene 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.
OpenUSD OpenUsdImporter → UsdStageData → SceneBuilderEngine Importer + stage data classes. NovaPhy does not yet expose schema resolvers (SchemaResolverNewton/MuJoCo/PhysX) like newton.usd; mapping fidelity is conservative.

For URDF and OpenUSD, 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

# OpenUSD
stage    = novaphy.OpenUsdImporter().import_file("scene.usda")
result2  = engine.build_from_openusd(stage)

For MJCF, skip the parser class and call ModelBuilder directly:

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

When to Use SceneBuilderEngine vs ModelBuilder

  • ModelBuilder — programmatic scene construction (add bodies / joints by hand, MJCF 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.
UrdfModelData Parsed URDF model data.
UrdfParser URDF file parser.
UrdfVisual URDF visual element.

OpenUSD

Class Description
OpenUsdImporter OpenUSD scene importer.
UsdAnimationTrack USD animation track entry.
UsdPrim USD prim entry.
UsdStageData Parsed USD stage data.

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 is intentionally focused on the common robot subset:

  • <worldbody> with nested <body> elements
  • box, sphere, capsule, cylinder, and plane geoms
  • hinge, slide, ball, and free joints
  • <inertial> mass / diagonal inertia blocks
  • world-level <option gravity="...">

Deferred MJCF features include equality / mimic constraints, tendons and cables, mesh / hfield / SDF geoms, and materials / textures.

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.

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.