Joint types

29 · Joints and drives

One small articulation per joint type: a revolute hinge, a prismatic slider on a tilted axis, a ball joint, a D6 joint with a sprung vertical slide and two rotations, and a fixed joint. Steel simulates all of them in reduced coordinates, so the joints themselves never drift apart.

drag to orbit · scroll to zoom

0.00 s

What to look at

The hinge swings in a plane, and the ball joint swings in a cone.
The slider slides until its tip reaches the floor, and the D6 link bobs on its spring while it swings.
The fixed link does not move.

Key parameter

add_joint_revolute / _prismatic / _ball / _d6 / _fixed / _free

Put a tree's joints in one add_articulation call. D6 axes take JointDofConfig with their own stiffness, damping and limits.

Try changing

Give the D6 a third angular axis.
Add limits to the prismatic joint and pass enable_joint_limits=True.

Concept

Reduced-coordinate joints

What it is

Each tree joint contributes only the coordinates it allows: one for a hinge or slider, a quaternion for a ball, any mix for D6. The motion is computed in those coordinates, so tree joints never separate, with no rows and no iterations.

In this scene

Five joint types move freely or not at all as their coordinates allow, with zero joint error.

Considerations

Cost: Dense factorization grows roughly with the cube of an articulation's DOF count; Steel uses sparse factors for branched trees when supported.
Interactions: Joints outside the tree become loop-closure rows.
Use it when: Model robots as trees and close loops only where the mechanism needs it.

The script

cd tutorials && python 29_joint_types.py prints each variant's final metric; --record out.json also writes the replay. Every tutorial imports replay.py from the same folder.

29_joint_types.py
replay.py

# SPDX-FileCopyrightText: Copyright (c) 2026 Skild AI and the Steel contributors
# SPDX-License-Identifier: Apache-2.0

"""Joint types: revolute, prismatic, ball, D6 and fixed joints in one articulation each."""

import math

import newton
import warp as wp
from newton.solvers import SolverSteel

from replay import Recorder

DT = 1.0 / 240.0
SUBSTEPS = 8
Dof = newton.ModelBuilder.JointDofConfig


def tf(x, y, z, q=None):
    return wp.transform((x, y, z), q if q is not None else wp.quat_identity())


def pendulum_link(builder, x):
    link = builder.add_link(xform=tf(x, 0.0, 0.6))
    builder.add_shape_capsule(link, xform=tf(0.0, 0.0, -0.15), radius=0.02, half_height=0.13)
    builder.add_shape_box(link, xform=tf(0.0, 0.0, -0.3), hx=0.05, hy=0.05, hz=0.05)
    return link


def build():
    builder = newton.ModelBuilder()
    builder.add_ground_plane()
    anchor = newton.ModelBuilder.ShapeConfig(density=0.0, has_shape_collision=False)
    joints = []
    for i, kind in enumerate(["revolute", "prismatic", "ball", "d6", "fixed"]):
        x = 0.6 * i - 1.2
        builder.add_shape_sphere(-1, xform=tf(x, 0.0, 0.6), radius=0.025, cfg=anchor)
        link = pendulum_link(builder, x)
        pivot = tf(x, 0.0, 0.6)
        if kind == "revolute":
            j = builder.add_joint_revolute(-1, link, axis=newton.Axis.Y, parent_xform=pivot)
        elif kind == "prismatic":
            # slides along an axis tilted 0.5 rad from vertical
            j = builder.add_joint_prismatic(
                -1, link, axis=(math.sin(0.5), 0.0, -math.cos(0.5)), parent_xform=pivot
            )
        elif kind == "ball":
            j = builder.add_joint_ball(-1, link, parent_xform=pivot)
        elif kind == "d6":
            # one linear DOF along z and two rotations: a spring-hung pendulum
            j = builder.add_joint_d6(
                -1,
                link,
                parent_xform=pivot,
                linear_axes=[Dof(axis=newton.Axis.Z, stiffness=200.0, damping=2.0)],
                angular_axes=[Dof(axis=newton.Axis.X), Dof(axis=newton.Axis.Y)],
            )
        else:
            j = builder.add_joint_fixed(-1, link, parent_xform=pivot)
        builder.add_articulation([j])
        joints.append(j)
    model = builder.finalize()
    # start every joint away from rest so each one moves
    q = model.joint_q.numpy()
    starts = model.joint_q_start.numpy()
    q[starts[0]] = 1.0
    ball_q = wp.quat_from_axis_angle(wp.normalize(wp.vec3(1.0, 1.0, 0.0)), 0.9)
    q[starts[2] : starts[2] + 4] = [ball_q[0], ball_q[1], ball_q[2], ball_q[3]]
    q[starts[3] + 1 : starts[3] + 3] = [0.6, 0.3]
    model.joint_q.assign(q)
    return model


def simulate(rec, label):
    model = build()
    solver = SolverSteel(model)
    pipeline = newton.CollisionPipeline(model)
    contacts = pipeline.contacts()
    state_0, state_1, control = model.state(), model.state(), model.control()
    newton.eval_fk(model, model.joint_q, model.joint_qd, state_0)

    run = rec.variant(label, model)
    for _ in range(rec.frames(5.0)):
        q = state_0.body_q.numpy()
        # height of each link's tip, 0.3 m down its local z axis
        tip_z = q[:, 2] - 0.3 * (1.0 - 2.0 * (q[:, 3] ** 2 + q[:, 4] ** 2))
        run.frame(
            state_0,
            **{
                name: tip_z[i]
                for i, name in enumerate(["revolute", "prismatic", "ball", "d6", "fixed"])
            },
        )
        for _ in range(SUBSTEPS):
            pipeline.collide(state_0, contacts)
            solver.step(state_0, state_1, control, contacts, DT)
            state_0, state_1 = state_1, state_0
    run.check(solver)


if __name__ == "__main__":
    rec = Recorder()
    simulate(rec, "revolute | prismatic | ball | D6 | fixed")
    rec.save()

# SPDX-FileCopyrightText: Copyright (c) 2026 Skild AI and the Steel contributors
# SPDX-License-Identifier: Apache-2.0

"""Record Steel tutorial runs as replay JSON for the tutorials page, or print a summary.

Every tutorial imports this module. ``python NN_name.py`` runs the variants and prints
the final metric of each; ``--record out.json`` also writes body poses, shapes and metric
series that the page replays in 3D.
"""

import argparse
import base64
import json
import os
import subprocess
import sys
import time

import newton
import numpy as np
import warp as wp

from source_hash import source_sha256

_RENDERED_TYPES = {
    newton.GeoType.PLANE,
    newton.GeoType.SPHERE,
    newton.GeoType.CAPSULE,
    newton.GeoType.ELLIPSOID,
    newton.GeoType.CYLINDER,
    newton.GeoType.BOX,
    newton.GeoType.MESH,
    newton.GeoType.CONE,
    newton.GeoType.CONVEX_MESH,
}


class Recorder:
    """Collect the variants of one tutorial; ``fps`` is the replay frame rate."""

    def __init__(self, fps: int = 30):
        parser = argparse.ArgumentParser()
        parser.add_argument(
            "--record", metavar="OUT.json", help="write a replay file for the tutorials page"
        )
        parser.add_argument("--device", default=None, help="Warp device, for example cuda:0")
        self.args = parser.parse_args()
        if self.args.device:
            wp.set_device(self.args.device)
        self.fps = fps
        self.script = os.path.abspath(sys.argv[0])
        self.variants: list[Variant] = []

    def frames(self, seconds: float) -> int:
        """Number of replay frames in ``seconds``, including the first."""
        return int(round(seconds * self.fps)) + 1

    def variant(
        self,
        label: str,
        model: newton.Model,
        *,
        ghost: bool = False,
        slot: int | None = None,
        scene: str | None = None,
    ) -> "Variant":
        """Start one run; ``ghost`` overlays run ``slot``, ``scene`` groups runs for charts."""
        variant = Variant(label, model, self.fps, ghost, slot, scene)
        self.variants.append(variant)
        return variant

    def save(self) -> None:
        """Print a summary and, with ``--record``, write the replay file."""
        for variant in self.variants:
            last = variant.metrics[-1] if variant.metrics else {}
            flag = "  (rows dropped)" if variant.overflow else ""
            print(f"{variant.label:<48} {json.dumps(last)}  {variant.wall:.2f} s{flag}")
        if not self.args.record:
            return
        source_sha = source_sha256(self.script)
        doc = {
            "script": os.path.basename(self.script),
            "script_sha256": source_sha,
            "newton_commit": _newton_commit(),
            "newton_version": newton.__version__,
            "warp_version": wp.config.version,
            "gpu": wp.get_device().name,
            "fps": self.fps,
            "variants": [v.to_json() for v in self.variants],
        }
        with open(self.args.record, "w") as f:
            json.dump(doc, f, separators=(",", ":"))
        print(f"wrote {self.args.record}")


class Variant:
    """One recorded run: a pose per frame for every body, plus named metric values."""

    def __init__(self, label, model, fps, ghost, slot, scene):
        self.label, self.model, self.fps, self.ghost, self.slot = label, model, fps, ghost, slot
        self.scene = scene
        self.poses: list[np.ndarray] = []
        self.metrics: list[dict] = []
        self.awake: list[list[int]] = []
        self.particles: list[np.ndarray] = []
        self.overflow = False
        self.start = time.perf_counter()
        self.wall = 0.0

    def frame(self, state: newton.State, awake=None, particles=None, **metrics) -> None:
        """Record ``state.body_q``, optional awake flags, particle positions and metric values."""
        self.poses.append(state.body_q.numpy().astype(np.float32).copy())
        if particles is not None:
            self.particles.append(particles.numpy().astype(np.float32).copy())
        self.metrics.append({k: _round(v) for k, v in metrics.items()})
        if awake is not None:
            self.awake.append([int(x) for x in awake.numpy()])
        self.wall = time.perf_counter() - self.start

    def check(self, solver) -> None:
        """Note whether the solver dropped rows; call once after the run."""
        try:
            solver.check_constraint_capacity()
        except RuntimeError:
            self.overflow = True

    def to_json(self) -> dict:
        poses = (
            np.stack(self.poses)
            if self.poses
            else np.zeros((0, self.model.body_count, 7), np.float32)
        )
        return {
            "label": self.label,
            "fps": self.fps,
            "ghost": self.ghost,
            "slot": self.slot,
            "scene": self.scene,
            "bodies": int(self.model.body_count),
            "frames": int(poses.shape[0]),
            "poses": base64.b64encode(poses.astype(np.float32).tobytes()).decode(),
            "shapes": _shape_table(self.model),
            "metric": self.metrics,
            "awake": self.awake or None,
            "particles": self._particles_json(),
            "wall_s": round(self.wall, 3),
            "overflow": self.overflow,
        }

    def _particles_json(self):
        if not self.particles:
            return None
        frames = np.stack(self.particles)
        tris = self.model.tri_indices
        radius = self.model.particle_radius.numpy()
        return {
            "count": int(frames.shape[1]),
            "frames": base64.b64encode(frames.astype(np.float32).tobytes()).decode(),
            "radius": round(float(radius.mean()), 5) if radius.size else 0.0,
            "tris": [int(v) for v in tris.numpy().reshape(-1)]
            if tris is not None and tris.shape[0]
            else None,
        }


def _shape_table(model):
    types = model.shape_type.numpy()
    scales = model.shape_scale.numpy()
    xforms = model.shape_transform.numpy()
    bodies = model.shape_body.numpy()
    flags = model.shape_flags.numpy()
    shapes = []
    for i, t in enumerate(types):
        if int(t) not in _RENDERED_TYPES or not flags[i] & int(newton.ShapeFlags.VISIBLE):
            continue
        shape = {
            "b": int(bodies[i]),
            "t": int(t),
            "s": [round(float(v), 5) for v in scales[i]],
            "x": [round(float(v), 6) for v in xforms[i]],
        }
        if int(t) in (newton.GeoType.MESH, newton.GeoType.CONVEX_MESH):
            mesh = model.shape_source[i]
            shape["v"] = [round(float(v), 5) for v in np.asarray(mesh.vertices).reshape(-1)]
            shape["i"] = [int(v) for v in np.asarray(mesh.indices).reshape(-1)]
        shapes.append(shape)
    return shapes


def _round(value):
    value = float(value)
    return round(value, 5) if np.isfinite(value) else None


def _newton_commit():
    if os.environ.get("NEWTON_COMMIT"):
        return os.environ["NEWTON_COMMIT"]
    try:
        root = os.path.dirname(os.path.dirname(newton.__file__))
        return subprocess.check_output(["git", "-C", root, "rev-parse", "HEAD"], text=True).strip()
    except (OSError, subprocess.CalledProcessError):
        return None

Recorded with SolverSteel on Newton 1.9.0.dev0, Warp 1.19.0, NVIDIA RTX PRO 6000 Blackwell Server Edition. Replays read the state back every frame, so they are not a speed benchmark. Script · page text

Steel docs and tutorials are licensed under Apache-2.0. Third-party notices. "Skild", "Skild AI" and the Skild logo are trademarks of Skild AI and are not licensed under Apache-2.0.