newton-usd-schemas 0.1.0a1

OpenUSD schema definitions for the Newton physics engine

newton-usd-schemas

:warning: This project is in pre-alpha development. :warning:

:warning: It is not used by the Newton runtime. :warning:

:warning: Do not use these schemas yet. :warning:

Overview

Newton USD schemas provide extensions to OpenUSD's UsdPhysics specification, allowing USD layers to fully specify the Newton runtime data model.

These schemas can be deployed into any python runtime with USD support, allowing content creators to author Newton compatible robots, props, and environments in any application of their choice, without requiring the Newton runtime itself.

This project is part of Newton, a Linux Foundation project which is community-built and maintained.

Get Started

These schemas are codeless, in that they contain no compiled code nor any public API of their own. Since codeless schemas do not provide any code, clients do not need to recompile USD to use or update these schemas. They are deployed as a python module via a wheel package for convenience, as all Newton projects use pyproject based dependencies & most USD authoring workflows include a python runtime.

To start using the schemas, install the python wheel into a virtual environment using your favorite package manager:

python -m venv .venv
source .venv/bin/activate
pip install newton-usd-schemas

At runtime, simply import the module to register the schemas with OpenUSD.

Important: Schemas must be registered before the Usd.SchemaRegistry is initialized. Make sure to import the module very early in the process.

import newton_usd_schemas  # this registers the schema
from pxr import Usd, UsdPhysics

stage: Usd.Stage = Usd.Stage.CreateInMemory()

# create a UsdPhysics.Scene and set gravity
scene: UsdPhysics.Scene = UsdPhysics.Scene.Define(stage, "/scene")
scene.GetGravityMagnitudeAttr().Set(9.81)

# apply a Newton schema and set some of its attributes
prim: Usd.Prim = scene.GetPrim()
prim.ApplyAPI("NewtonSceneAPI")
prim.GetAttribute("newton:timeStepPerSecond").Set(500)  # 2ms

stage.Export("/tmp/my_robot.usd")

Once a USD layer is authored to storage, it can be loaded into a Newton runtime using Newton's USD Parsing mechanism.

Design Principles

Newton schemas follow a minimalist approach to determine which attributes should be included, and are similar to the philosophy that UsdPhysics and the Newton API follow for capturing parameters that generalize across simulators. We view the Newton schemas as a proving and staging ground for physics parameters that should eventually be eligible for promotion into the UsdPhysics standard.

A USD attribute belongs in the Newton schema if it meets one of these criteria:

1. Clear Physical Meaning: The attribute represents a physically meaningful quantity rather than a modeling or approximation parameter (e.g., simulation time step dt, or gravitational acceleration), and is supported by at least one Newton solver.

2. Cross-Solver Support: The attribute has a direct (or transformable) correspondence to parameters supported by at least two Newton solvers. This mainly applies to physical modeling parameters (e.g., a viscous joint friction coefficient).

For solver-specific or workflow-specific parameters that are not in UsdPhysics or the Newton schema, Newton supports solver-specific schemas (e.g., mjcPhysics) or custom attributes.

Contribution Guidelines

Contributions from the community are welcome. See CONTRIBUTING.md to learn about contributing via GitHub issues, as well as building the project from source and our development workflow.

General contribution guidelines for Newton repositories are available here.

Community

For questions about these newton-usd-schemas, feel free to join or start a GitHub Discussions.

By participating in this community, you agree to abide by the Linux Foundation Code of Conduct.

References

• Newton documentation
• OpenUSD API Docs
• OpenUSD User Docs
• NVIDIA OpenUSD Resources and Learning

License

newton-usd-schemas is provided under the Apache License, Version 2.0