Cloth and cables in Newton

Newton computes XPBD cloth, VBD cloth, and twisting cables. Isaac Sim displays the saved solver states.

  • Newton
  • Warp
  • OpenUSD
  • Isaac Sim
Cloth and cables in Newton
Recorded runExample run and recording

How it works

How the data moves
  1. InputConnected geometrymesh vertices + material + fixed points

    A grid describes cloth. Cable bodies have stiffness and joints.

  2. ProcessSolve the motionforces + contacts → updated XYZ positions

    Newton advances the model. Official example tests check the resulting state.

  3. OutputInspect the recorded statestime-sampled USD · result.json · GUI MP4

    Replay the solver output in Isaac Sim and check finite positions and deformation.

A flexible object needs more than one pose

A rigid box can be described by a position and rotation. Cloth needs the positions of many connected vertices. Newton advances those positions under forces and solves constraints such as stretching, bending and contact. XPBD and VBD use different solving methods; the official examples also configure different materials and substeps, so these runs illustrate behavior rather than rank solver quality. Official cloth example · Cable twist example

A mesh, material parameters and fixed points become forces, solved particle positions and a USD animation

Data Example from this experiment Meaning
Cloth grid --width 64 --height 32 Resolution arguments for the official example.
Render mesh positions points.shape = [2145, 3] One XYZ position in meters per rendered vertex.
Moving particle positions positions.shape = [2112, 3] The exported moving-particle array; it does not have the same count as the complete render mesh.
Animation 240 stored samples over 4 seconds Recorded solver states that the GUI can revisit.
Cable center positions [192, 3] Center-of-mass positions for cable bodies in the exported scene.

For example, a row [0.2, 1.3, 0.8] means a point is 0.2 m along X, 1.3 m along Y and 0.8 m above the Z origin. Changing the next row of animation time moves that point; it is not a color value or a robot action. This row is an explanatory example, while the full run measurements are in recorded.json.

What does the video show?

Newton computes the motion on the GPU and writes time-sampled OpenUSD. Isaac Sim opens that file and displays the recorded states. The capture is the actual Isaac Sim viewport, cropped from the application window. The solver is Newton; this GUI recording is a replay, with a playback speed of 0.65× and a short hold at the end. Shots appear in the order XPBD cloth, VBD cloth and cable twist. The three cable variants use the official example’s different stiffness values.

First time? Get the lab files

Open a terminal on the Isaac Sim machine for GPU labs, or on your own computer for CPU-only steps. Press Enter after each line. You can copy a multi-line command block as a whole.

Shell
cd "$HOME"
git clone https://github.com/james-joobs/awesome-nvidia-physical-ai.git
cd awesome-nvidia-physical-ai
pwd

This example clones into your home folder. If you already cloned the repo, skip git clone and enter your project folder. In each new terminal, check that pwd ends in awesome-nvidia-physical-ai so commands can find the labs/ files.

Run it

Prepare the Python environment

Use Linux with an NVIDIA GPU and a Newton environment that includes its examples, NumPy and usd-core. These runs used Newton 1.9.0.dev0 and Warp 1.17.0. The API of a different Newton version can change; check python -m newton.examples cloth_hanging --help first. Newton examples

Open a terminal in this repository. Replace the Python path below with the Python inside your Newton environment. The first command checks the environment; the second computes all three cases and saves them to a new folder.

Shell
python3 labs/cli.py --json doctor newton-materials --python /path/to/newton-env/bin/python
python3 labs/cli.py --json run newton-materials \
  --python /path/to/newton-env/bin/python --output ./runs/newton-materials-001
python3 labs/cli.py --json verify ./runs/newton-materials-001

Watch the motion in Isaac Sim

In File → Open, open a *-review.usda file from your output folder and choose FilmCamera in the viewport. Keep the referenced .usd next to it. Drag the timeline to inspect the deformation. Use the script below to record the actual application window on an X11 desktop. Here python must belong to your Isaac Lab environment; it can be a different environment from Newton.

Shell
python labs/physics/capture_gui.py ./runs/newton-materials-001 ./runs/newton-gui-001 \
  /path/to/ffmpeg --plan ./runs/newton-materials-001/takes.json --viz kit

The recorded GUI environment was Isaac Sim 6.1.0.0, launched through Isaac Lab. GUI setup · CLI reference

Check the result

The run fails if an official --test command fails, point arrays contain NaN/Inf, or no animated points are found. result.json includes the official example source hashes, array shapes, displacement and time range. The maximum stored-vertex displacements were about 5.06 m for XPBD cloth and 4.28 m for VBD cloth in this setup. They show deformation, not accuracy scores.

run.json stores command and artifact hashes. verify checks these again. capture.json separately records the GUI version and captured takes. Keep solver success and successful GUI capture as separate checks: one does not guarantee the other. Physics and contact experiments · Newton principles

Example run and recording

Source code

run.pyView files on GitHub
Python
"""Run official Newton material examples and prepare USD scenes for GUI review.

Requires Newton's example dependencies, numpy and usd-core in this interpreter.
The generated USD contains recorded solver states; Isaac Sim displays a replay.
"""
import argparse
import hashlib
import importlib
import json
from pathlib import Path
import subprocess
import sys
import time

import newton
import numpy as np
import warp
from pxr import Gf, Usd, UsdGeom, UsdLux


CASES = {
    "cloth-xpbd": ("cloth_hanging", ["--solver", "xpbd", "--width", "64", "--height", "32"],
                   "newton.examples.cloth.example_cloth_hanging"),
    "cloth-vbd": ("cloth_hanging", ["--solver", "vbd", "--width", "64", "--height", "32"],
                  "newton.examples.cloth.example_cloth_hanging"),
    "cable-twist": ("cable_twist", [], "newton.examples.cable.example_cable_twist"),
}


def inspect_and_frame(path, name):
    stage = Usd.Stage.Open(str(path))
    if not stage or stage.GetEndTimeCode() <= stage.GetStartTimeCode():
        raise RuntimeError(f"No animated USD: {path}")
    low, high = np.full(3, np.inf), np.full(3, -np.inf)
    animated = []
    for prim in stage.Traverse():
        for attribute_name in ("points", "positions"):
            attribute = prim.GetAttribute(attribute_name)
            if not attribute or len(attribute.GetTimeSamples()) < 2:
                continue
            times = attribute.GetTimeSamples()
            samples = [np.asarray(attribute.Get(t), dtype=float) for t in (times[0], times[len(times)//2], times[-1])]
            if not all(array.ndim == 2 and array.shape[1] == 3 and np.isfinite(array).all() for array in samples):
                raise RuntimeError(f"Invalid point data: {prim.GetPath()}")
            nonempty = [array for array in samples if len(array)]
            if not nonempty:
                continue
            low = np.minimum(low, np.concatenate(nonempty).min(axis=0))
            high = np.maximum(high, np.concatenate(nonempty).max(axis=0))
            same_shape = samples[0].shape == samples[-1].shape
            displacement = float(np.max(np.linalg.norm(samples[-1] - samples[0], axis=1))) if same_shape and len(samples[0]) else None
            animated.append({"prim": str(prim.GetPath()), "attribute": attribute_name,
                             "first_shape": list(samples[0].shape), "time_samples": len(times),
                             "max_displacement_m": displacement})
    if not animated or not np.isfinite(low).all():
        raise RuntimeError("No animated point arrays to verify")
    # A separate camera layer leaves the official solver output intact.
    review = Usd.Stage.CreateNew(str(path.parent / f"{name}-review.usda"))
    review.GetRootLayer().subLayerPaths = [path.name]
    review.SetStartTimeCode(stage.GetStartTimeCode())
    review.SetEndTimeCode(stage.GetEndTimeCode())
    review.SetTimeCodesPerSecond(stage.GetTimeCodesPerSecond())
    UsdGeom.SetStageUpAxis(review, UsdGeom.Tokens.z)
    UsdGeom.SetStageMetersPerUnit(review, 1.0)
    world = UsdGeom.Xform.Define(review, "/World")
    review.SetDefaultPrim(world.GetPrim())
    center = (low + high)/2
    radius = max(1.0, float(np.linalg.norm(high-low)))
    eye = center + np.array([0.8, -1.25, 0.65])*radius*1.3
    camera = UsdGeom.Camera.Define(review, "/World/FilmCamera")
    look = Gf.Matrix4d().SetLookAt(Gf.Vec3d(*eye), Gf.Vec3d(*center), Gf.Vec3d(0,0,1))
    UsdGeom.Xformable(camera).AddTransformOp().Set(look.GetInverse())
    camera.CreateFocalLengthAttr(36)
    camera.CreateHorizontalApertureAttr(36)
    camera.CreateVerticalApertureAttr(20.25)
    camera.CreateClippingRangeAttr(Gf.Vec2f(0.01, radius*100))
    dome = UsdLux.DomeLight.Define(review, "/World/DomeLight")
    dome.CreateIntensityAttr(650)
    sun = UsdLux.DistantLight.Define(review, "/World/Sun")
    sun.CreateIntensityAttr(2000)
    UsdGeom.Xformable(sun).AddRotateXYZOp().Set(Gf.Vec3f(315, 20, 35))
    review.GetRootLayer().Save()
    return {"animated_arrays": animated, "bounds_m": [low.tolist(), high.tolist()],
            "simulated_seconds": (stage.GetEndTimeCode()-stage.GetStartTimeCode()) / stage.GetTimeCodesPerSecond(),
            "review_scene": f"{name}-review.usda"}


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("output", type=Path)
    parser.add_argument("--cases", nargs="+", choices=list(CASES), default=list(CASES))
    parser.add_argument("--frames", type=int, default=240)
    args = parser.parse_args()
    if args.frames < 60:
        parser.error("Use at least 60 frames for a meaningful material experiment")
    args.output.mkdir(parents=True, exist_ok=True)
    report = {"engine": "Newton", "version": newton.__version__, "warp": warp.__version__,
              "recording_mode": "solver-usd-replay", "cases": []}
    plan = []
    for name in args.cases:
        example, parameters, module_name = CASES[name]
        path = args.output.resolve() / f"{name}.usd"
        if path.exists():
            raise FileExistsError(path)
        command = [sys.executable, "-m", "newton.examples", example, *parameters,
                   "--device", "cuda:0", "--viewer", "usd", "--output-path", str(path),
                   "--num-frames", str(args.frames), "--test"]
        source = Path(importlib.import_module(module_name).__file__)
        start = time.monotonic()
        with (args.output / f"{name}.log").open("w") as log:
            subprocess.run(command, stdout=log, stderr=subprocess.STDOUT, check=True)
        row = {"case": name, "command": command, "official_tests_passed": True,
               "source_sha256": hashlib.sha256(source.read_bytes()).hexdigest(),
               "wall_seconds": round(time.monotonic()-start, 2), **inspect_and_frame(path, name)}
        report["cases"].append(row)
        plan.append([name, f"{name}-review", "FilmCamera", 0, 0.65, 8])
        print(json.dumps(row), flush=True)
    (args.output / "result.json").write_text(json.dumps(report, indent=2) + "\n")
    (args.output / "takes.json").write_text(json.dumps(plan, indent=2) + "\n")


if __name__ == "__main__":
    main()