Articulations

MJCF, URDF, and USD loaders produce a common ArticulationDesc. Load a robot, then pass its data to world.add_articulation().

Load a robot

Choose the loader for your file:

# world is an existing KangSimWorld.
data: ke.asset.ArticulationDesc = world.load_mjcf("robot.xml", order="DFS")
# Or:
data = world.load_urdf("robot.urdf", order="DFS")
data = world.load_usd("robot.usd", order="DFS")

USD requires a native build with USE_USD enabled. It selects the default prim; pass prim_path="/Robot" to select a different robot subtree.

Format	Supported joints	3-axis rotation
MJCF	Fixed, Revolute (hinge)	3 orthogonal Revolute joints on one body
URDF	Fixed, Revolute, Prismatic	3 Revolute joints with intermediate links
USD	Fixed, Revolute, Prismatic	3 Revolute joints with intermediate links

Native MJCF ball/slide and USD Spherical joint import are not supported.

Create the articulation

config = ke.physics.ArticulationConfig.free_base()

record = world.add_articulation(
    data,
    env_id=0,
    obj_id=0,
    name="robot",
    config=config,
)
robot = record.articulation

For all three formats, choose ArticulationConfig.free_base() for a floating root or ArticulationConfig.fixed_base() for a fixed root.

The following visualization example uses an MJCF asset:

Use the same order for loading and visualization.

robot_visual = visual.add_articulation_scene_graph(
    0,
    0,
    mjcf_path,
    path="/robot",
    order="DFS",
    material=robot_material,
)

Control example

Run the complete control example with an MJCF file:

python ./python/examples/mjcf_dof_control.py /path/to/robot.xml

Complete source: mjcf_dof_control.py

"""Generic MJCF articulation DOF position-control viewer."""

from __future__ import annotations

import argparse
import math
from pathlib import Path

import numpy as np

import kangengine as ke
from kangengine import imgui, keys


def package_asset_path(*parts: str) -> str:
    return str(Path(ke.__file__).resolve().parent / "assets" / Path(*parts))


def default_mjcf_path() -> Path:
    return Path(package_asset_path("characters", "kw", "kw.xml"))


class MjcfDofControlApp(ke.App):
    """Load an MJCF articulation and expose every DOF as an ImGui slider."""

    window_title = "MJCF DOF Control"
    object_name = "mjcf"
    prim_base_path = "/mjcf"
    camera_pos = (3.8, -5.4, 1.2)
    camera_target = (0.0, 0.0, 0.45)
    # None preserves per-geom MJCF rgba. Set an RGBA tuple to force a single
    # override color for the whole articulation.
    visual_color = None  # np.array([1,1,1, 1.0])
    ground_size = 10.0
    root_pos = (0.0, 0.0, 1.5)
    root_rot_xyzw = (0.0, 0.0, 0.0, 1.0)
    fixed_base = False
    order = "DFS"
    sim_dt = 1.0 / 240.0
    step_substeps = 4
    default_kp = 120.0
    default_kd = 12.0
    default_anim_amp = 0.35
    default_anim_speed = 1.0
    default_contact_force_scale = 0.002
    contact_force_threshold = 1e-3
    visual_alpha_with_collision = 0.1
    drag_force_debug_path = "/debug/mjcf_drag_force"
    drag_force_target_debug_path = "/debug/mjcf_drag_force_target"

    def __init__(self, mjcf_path: str | Path):
        super().__init__()
        self.mjcf_path = str(Path(mjcf_path).expanduser().resolve())

    def setup(self):
        self.timing = self.configure_timing(
            ke.SimulationTimingConfig.from_dt(
                physics_dt=self.sim_dt,
                fixed_dt=self.sim_dt * self.step_substeps,
                render_hz=60.0,
            )
        )
        self.set_simulation_hotkeys_enabled(True)
        self.elapsed = 0.0
        self.kp = float(self.default_kp)
        self.kd = float(self.default_kd)
        self.animate = True
        self.anim_amp = float(self.default_anim_amp)
        self.anim_speed = float(self.default_anim_speed)
        self.show_collision = False
        self.show_contact_forces = False
        self.contact_force_scale = float(self.default_contact_force_scale)
        self.contact_force_view = None
        self.contact_force_color = np.array([[1.0, 0.25, 0.05, 1.0]], dtype=np.float32)
        self.empty_vec3 = np.empty((0, 3), dtype=np.float32)
        self.empty_vec4 = np.empty((0, 4), dtype=np.float32)
        red = ke.ColorLibrary.get(ke.ColorType.RED)
        magenta = ke.ColorLibrary.get(ke.ColorType.MAGENTA)
        self.drag_force_line_color = np.array(
            [[red.r, red.g, red.b, red.a]], dtype=np.float32
        )
        self.drag_force_target_color = np.array(
            [[magenta.r, magenta.g, magenta.b, magenta.a]], dtype=np.float32
        )
        self.drag_force_line_starts = np.empty((3, 3), dtype=np.float32)
        self.drag_force_line_ends = np.empty((3, 3), dtype=np.float32)
        self.drag_force_up_z = np.array([0.0, 0.0, 1.0], dtype=np.float32)
        self.drag_force_up_y = np.array([0.0, 1.0, 0.0], dtype=np.float32)
        self.drag_force_enabled = True
        self.drag_force_stiffness = 750.0
        self.drag_force_damping = 75.0
        self.drag_force_max = 300.0
        self.drag_force_arrow_scale = 0.003
        self.show_drag_force_arrow = True
        self._drag_force_body_id = None
        self._drag_force_local_anchor = None
        self._drag_force_target = None
        self._drag_force_anchor_world = None
        self._drag_force_vector = None
        self._clear_drag_force_arrow()

        self.configure_camera()
        self.standard_materials = self.create_standard_materials()
        self.debug_material = self.standard_materials.common
        self.create_world()
        self.load_articulation()
        self._reset()
        self.print_summary()

    def configure_camera(self):
        self.get_camera().set_camera_pos(ke.Vec3(*self.camera_pos))
        self.get_camera().set_target_pos(ke.Vec3(*self.camera_target))

    def create_world(self):
        self.world = ke.sim.KangSimWorld(
            num_envs=1,
            sim_dt=self.timing.physics_dt,
            add_ground=True,
        )
        self.visual = ke.visual.sim.SimWorldVisualizer(self, self.world)

        self.ground_view = self.scene.add_ground(
            "/ground",
            scale=float(self.ground_size),
            material=self.standard_materials.ground,
        )

    def load_articulation(self):
        data = self.world.load_mjcf(self.mjcf_path, order=self.order)
        self.obj_id = 0
        config = (
            ke.physics.ArticulationConfig.fixed_base()
            if self.fixed_base
            else ke.physics.ArticulationConfig.free_base()
        )
        self.robot = self.world.add_articulation(
            data,
            env_id=0,
            obj_id=self.obj_id,
            name=self.object_name,
            config=config,
        ).articulation

        self.articulation_visual_view = self.visual.add_articulation_scene_graph(
            0,
            self.obj_id,
            self.mjcf_path,
            path=self.prim_base_path,
            order=self.order,
            material=self.standard_materials.pbr,
            collision_path=f"{self.prim_base_path}_collision",
            show_collision=self.show_collision,
            color=(
                None
                if self.visual_color is None
                else np.array(self.visual_color, dtype=np.float32)
            ),
        )
        self.visual_body_prims = self.articulation_visual_view.prims
        # self.collision_body_prims = self.articulation_visual_view.collision_visuals

        self.num_dofs = self.robot.num_dofs()
        self.dof_names = self.world.state.get_obj_dof_names(self.obj_id)
        self.dof_limits = np.asarray(
            self.world.state.get_obj_dof_limits(self.obj_id), dtype=np.float32
        )
        if self.dof_limits.shape != (self.num_dofs, 2):
            self.dof_limits = np.tile(
                np.array([-math.pi, math.pi], dtype=np.float32),
                (self.num_dofs, 1),
            )
        self.targets = self.initial_targets()

    def initial_targets(self) -> np.ndarray:
        return np.zeros(self.num_dofs, dtype=np.float32)

    def print_summary(self):
        print(
            f"{self.object_name} loaded: links={self.robot.num_links()} dofs={self.num_dofs}"
        )
        print("DOFs:", ", ".join(self.dof_names))
        print("XML:", self.mjcf_path)

    def _reset(self):
        self.elapsed = 0.0
        self.targets[:] = self.initial_targets()
        self.world.set_root_state(
            None,
            self.obj_id,
            np.array(self.root_pos, dtype=np.float32),
            np.array(self.root_rot_xyzw, dtype=np.float32),
        )
        self.world.set_dof_state(None, self.obj_id, self.targets)
        self.world.set_cmd(
            None,
            self.obj_id,
            self.targets,
            mode=ke.sim.ControlMode.POS,
            kp=self.kp,
            kd=self.kd,
        )
        self.world.step(substeps=0, apply_commands=False)
        self.visual.sync()
        self._update_contact_force_arrows()
        self._clear_drag_force()

    def _animated_targets(self):
        out = np.zeros_like(self.targets)
        for i in range(self.num_dofs):
            lo, hi = self.slider_limits(i)
            span = max(0.0, min(float(hi - lo) * 0.35, self.anim_amp))
            center = 0.5 * float(lo + hi)
            phase = self.elapsed * self.anim_speed + i * 0.75
            out[i] = np.clip(center + span * math.sin(phase), lo, hi)
        return out

    def slider_limits(self, dof_index: int) -> tuple[float, float]:
        lo, hi = self.dof_limits[dof_index]
        if not np.isfinite(lo) or not np.isfinite(hi) or hi <= lo:
            return -math.pi, math.pi
        return float(lo), float(hi)

    def pre_update(self):
        if self.was_key_pressed(keys.R):
            self._reset()
        if self.was_key_pressed(keys.Q):
            self.animate = not self.animate

    def fixed_update(self, fixed_dt):
        self.elapsed += fixed_dt
        if self.animate:
            self.targets[:] = self._animated_targets()

        self.world.set_cmd(
            None,
            self.obj_id,
            self.targets,
            mode=ke.sim.ControlMode.POS,
            kp=self.kp,
            kd=self.kd,
        )
        self.world.advance(fixed_dt)

    def pre_render(self):
        self.visual.sync()
        self._update_contact_force_arrows()
        self._update_drag_force_arrow()
        self.check_error()

    def on_force_drag_begin(self, result, target):
        if not self.drag_force_enabled or not result.hit:
            self._clear_drag_force()
            return

        pick = self.articulation_visual_view.pick_body(result)
        if pick is None:
            self._clear_drag_force()
            return

        self._drag_force_body_id = int(pick.body_id)
        body_state = self._drag_body_state(self._drag_force_body_id)
        if body_state is None:
            return
        body_pos, body_rot, _, _ = body_state
        hit_pos = self._vec3_to_np(result.position)
        self._drag_force_local_anchor = self._quat_inverse_rotate_xyzw(
            body_rot, hit_pos - body_pos
        )
        self._drag_force_target = self._vec3_to_np(target)
        self._apply_drag_force()
        self._update_drag_force_arrow()

    def on_force_drag_update(self, result, target):
        if not self.drag_force_enabled or self._drag_force_body_id is None:
            self._clear_drag_force()
            return
        self._drag_force_target = self._vec3_to_np(target)
        self._apply_drag_force()
        self._update_drag_force_arrow()

    def on_force_drag_end(self):
        self._clear_drag_force()

    def _apply_drag_force(self):
        if (
            self._drag_force_body_id is None
            or self._drag_force_local_anchor is None
            or self._drag_force_target is None
        ):
            return
        body_state = self._drag_body_state(self._drag_force_body_id)
        if body_state is None:
            return
        body_pos, body_rot, body_vel, body_ang_vel = body_state
        radius = self._quat_rotate_xyzw(body_rot, self._drag_force_local_anchor)
        anchor_world = body_pos + radius
        point_vel = body_vel + np.cross(body_ang_vel, radius)
        force = (self._drag_force_target - anchor_world) * float(
            self.drag_force_stiffness
        ) - point_vel * float(self.drag_force_damping)
        norm = float(np.linalg.norm(force))
        if norm > float(self.drag_force_max) > 0.0:
            force *= float(self.drag_force_max) / norm
        self._drag_force_anchor_world = anchor_world.astype(np.float32)
        self._drag_force_vector = force.astype(np.float32)
        self.world.set_body_force_at_position(
            0,
            self.obj_id,
            self._drag_force_body_id,
            force.astype(np.float32),
            anchor_world.astype(np.float32),
        )

    def _clear_drag_force_arrow(self):
        self.clear_debug_lines(self.drag_force_debug_path)
        self.clear_debug_points(self.drag_force_target_debug_path)

    def _update_drag_force_arrow(self):
        if (
            not self.show_drag_force_arrow
            or self._drag_force_anchor_world is None
            or self._drag_force_vector is None
            or self._drag_force_target is None
        ):
            self._clear_drag_force_arrow()
            return

        start = self._drag_force_anchor_world
        force = self._drag_force_vector
        force_len = float(np.linalg.norm(force))
        if force_len < 1e-5:
            self._clear_drag_force_arrow()
            return

        direction = force / force_len
        end = start + force * float(self.drag_force_arrow_scale)
        shaft_len = float(np.linalg.norm(end - start))
        head_len = min(max(shaft_len * 0.25, 0.04), 0.18)

        side = np.cross(direction, self.drag_force_up_z)
        if np.linalg.norm(side) < 1e-5:
            side = np.cross(direction, self.drag_force_up_y)
        side = side / max(float(np.linalg.norm(side)), 1e-8)

        back = end - direction * head_len
        left = back + side * head_len * 0.45
        right = back - side * head_len * 0.45
        self.drag_force_line_starts[0] = start
        self.drag_force_line_starts[1] = end
        self.drag_force_line_starts[2] = end
        self.drag_force_line_ends[0] = end
        self.drag_force_line_ends[1] = left
        self.drag_force_line_ends[2] = right
        self.log_debug_lines(
            self.drag_force_debug_path,
            self.drag_force_line_starts,
            self.drag_force_line_ends,
            self.drag_force_line_color,
            3.0,
        )
        self.log_debug_points(
            self.drag_force_target_debug_path,
            self._drag_force_target.reshape(1, 3),
            self.drag_force_target_color,
            10.0,
        )

    def _drag_body_state(self, body_id: int):
        body_pos = self._state_array(self.world.state.get_body_pos(self.obj_id)[0])
        if body_id >= body_pos.shape[0]:
            self._clear_drag_force()
            return None
        body_rot = self._state_array(self.world.state.get_body_rot(self.obj_id)[0])
        body_vel = self._state_array(self.world.state.get_body_vel(self.obj_id)[0])
        body_ang_vel = self._state_array(
            self.world.state.get_body_ang_vel(self.obj_id)[0]
        )
        return (
            body_pos[body_id],
            body_rot[body_id],
            body_vel[body_id],
            body_ang_vel[body_id],
        )

    def _clear_drag_force(self):
        if getattr(self, "_drag_force_body_id", None) is not None:
            self.world.set_body_force(
                0,
                self.obj_id,
                int(self._drag_force_body_id),
                np.zeros(3, dtype=np.float32),
            )
        self._drag_force_body_id = None
        self._drag_force_local_anchor = None
        self._drag_force_target = None

    def _clear_contact_force_arrows(self):
        if self.contact_force_view is None:
            return
        self.contact_force_view.update_arrows(
            self.empty_vec3,
            self.empty_vec3,
            self.empty_vec4,
        )

    def _update_contact_force_arrows(self):
        if not self.show_contact_forces:
            self._clear_contact_force_arrows()
            return

        # Body-aggregated force visualization.
        # the arrows start at link origins instead of real contact points.
        # body_pos = np.asarray(
        #     self.world.state.get_body_pos(self.obj_id)[0], dtype=np.float32
        # )
        # forces = np.asarray(
        #     self.world.state.get_contact_forces(self.obj_id)[0], dtype=np.float32
        # )
        # active = np.linalg.norm(forces, axis=1) > float(self.contact_force_threshold)
        # starts = body_pos[active]
        # ends = starts + forces[active] * float(self.contact_force_scale)

        contacts = self.world.physics.get_contacts()
        starts = []
        ends = []
        dt = max(float(self.world.sim_dt), 1e-8)
        for contact in contacts:
            position = self._vec3_to_np(contact.position)
            force = self._vec3_to_np(contact.impulse) / dt
            if np.linalg.norm(force) <= float(self.contact_force_threshold):
                continue
            starts.append(position)
            ends.append(position + force * float(self.contact_force_scale))

        if not starts:
            self._clear_contact_force_arrows()
            return

        starts = np.asarray(starts, dtype=np.float32)
        ends = np.asarray(ends, dtype=np.float32)
        colors = np.repeat(self.contact_force_color, starts.shape[0], axis=0)

        if self.contact_force_view is None:
            self.contact_force_view = self.scene.log_arrows(
                "/debug/contact_forces",
                self.debug_material,
                starts,
                ends,
                colors,
                0.015,
                12,
            )
        else:
            self.contact_force_view.update_arrows(starts, ends, colors)

    @staticmethod
    def _vec3_to_np(value) -> np.ndarray:
        return np.array(
            [float(value.x), float(value.y), float(value.z)], dtype=np.float32
        )

    @staticmethod
    def _state_array(value) -> np.ndarray:
        if hasattr(value, "detach"):
            value = value.detach().cpu().numpy()
        return np.asarray(value, dtype=np.float32)

    @staticmethod
    def _quat_rotate_xyzw(quat, vector) -> np.ndarray:
        q = np.asarray(quat, dtype=np.float32)
        v = np.asarray(vector, dtype=np.float32)
        qv = q[:3]
        t = 2.0 * np.cross(qv, v)
        return (v + q[3] * t + np.cross(qv, t)).astype(np.float32)

    @classmethod
    def _quat_inverse_rotate_xyzw(cls, quat, vector) -> np.ndarray:
        q = np.asarray(quat, dtype=np.float32).copy()
        q[:3] *= -1.0
        return cls._quat_rotate_xyzw(q, vector)

    def _set_visual_alpha(self, alpha: float):
        if self.visual_color is None:
            self.articulation_visual_view.set_alpha(alpha)
            return
        color = np.array(self.visual_color, dtype=np.float32).reshape(-1)
        if color.size == 3:
            color = np.concatenate([color, np.ones(1, dtype=np.float32)])
        color = color[:4].copy()
        color[3] = float(alpha)
        self.articulation_visual_view.set_color(color)

    def _set_collision_visible(self, visible: bool):
        self.show_collision = bool(visible)
        self.articulation_visual_view.set_collision_visible(self.show_collision)
        self._set_visual_alpha(
            self.visual_alpha_with_collision if self.show_collision else 1.0
        )

    def render(self):
        imgui.begin(self.window_title)
        state = "paused" if self.is_simulation_paused() else "running"
        imgui.text(f"State: {state}")
        imgui.text(
            "Enter: play/pause    Space: pause/step    R: reset    Q: auto motion"
        )
        imgui.text(f"Links: {self.robot.num_links()}  DOFs: {self.num_dofs}")
        imgui.text(Path(self.mjcf_path).name)
        imgui.separator()
        _, self.kp = imgui.slider_float("kp", self.kp, 0.0, 1000.0)
        _, self.kd = imgui.slider_float("kd", self.kd, 0.0, 80.0)
        _, self.animate = imgui.checkbox("Animate targets", self.animate)
        _, self.anim_amp = imgui.slider_float("anim amplitude", self.anim_amp, 0.0, 1.5)
        _, self.anim_speed = imgui.slider_float("anim speed", self.anim_speed, 0.0, 6.0)
        changed, self.show_collision = imgui.checkbox(
            "Show collision prims",
            self.show_collision,
        )
        if changed:
            self._set_collision_visible(self.show_collision)
        changed, self.show_contact_forces = imgui.checkbox(
            "Show contact forces",
            self.show_contact_forces,
        )
        if changed:
            self._update_contact_force_arrows()
        _, self.contact_force_scale = imgui.slider_float(
            "contact force scale",
            self.contact_force_scale,
            0.0,
            0.02,
        )
        imgui.separator()
        changed, self.drag_force_enabled = imgui.checkbox(
            "Enable drag force",
            self.drag_force_enabled,
        )
        if changed and not self.drag_force_enabled:
            self._clear_drag_force()
        changed, self.show_drag_force_arrow = imgui.checkbox(
            "Show drag force arrow",
            self.show_drag_force_arrow,
        )
        if changed and not self.show_drag_force_arrow:
            self._clear_drag_force_arrow()
        _, self.drag_force_stiffness = imgui.slider_float(
            "drag force stiffness",
            self.drag_force_stiffness,
            0.0,
            1000.0,
        )
        _, self.drag_force_damping = imgui.slider_float(
            "drag force damping",
            self.drag_force_damping,
            0.0,
            80.0,
        )
        _, self.drag_force_max = imgui.slider_float(
            "drag force max",
            self.drag_force_max,
            0.0,
            2000.0,
        )
        _, self.drag_force_arrow_scale = imgui.slider_float(
            "drag force arrow scale",
            self.drag_force_arrow_scale,
            0.0005,
            0.02,
        )
        if self._drag_force_body_id is not None:
            imgui.text(f"Dragging body: {self._drag_force_body_id}")
        imgui.separator()

        for i, name in enumerate(self.dof_names):
            lo, hi = self.slider_limits(i)
            changed, value = imgui.slider_float(name, float(self.targets[i]), lo, hi)
            if changed:
                self.targets[i] = value
                self.animate = False

        pos = self.world.state.get_dof_pos(self.obj_id)[0]
        imgui.separator()
        imgui.text("Current DOF positions")
        for name, value in zip(self.dof_names, pos):
            imgui.text(f"{name}: {float(value): .3f}")
        imgui.end()

    def cleanup(self):
        if hasattr(self, "visual"):
            self.visual.release()
        if hasattr(self, "world"):
            self.world.release()


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "mjcf_path",
        nargs="?",
        default=str(default_mjcf_path()),
        help="Path to an MJCF XML file",
    )
    parser.add_argument(
        "--fixed-base",
        action="store_true",
        help="Use a fixed root instead of the default free root.",
    )
    parser.add_argument("--order", default="DFS", choices=("DFS", "BFS"))
    parser.add_argument("--width", type=int, default=1920)
    parser.add_argument("--height", type=int, default=1080)
    args = parser.parse_args()

    class CliMjcfDofControlApp(MjcfDofControlApp):
        fixed_base = args.fixed_base
        order = args.order

    app = CliMjcfDofControlApp(args.mjcf_path)
    app.initialize(args.width, args.height, False, ke.UpAxis.Z)
    app.start()


if __name__ == "__main__":
    main()

MJCF articulation	Collision debug

USD import requirements

Prepare a USD robot with:

• Z-up, metersPerUnit = 1, and kilogramsPerUnit = 1.

• One connected body tree with explicit positive mass and inertia.

• convexHull collision meshes and no joint connecting the root to the world.

Configure initial states, drives, simulation settings, and materials after loading. These scene settings are not fully reproduced by the importer. Unsupported joint or collider configurations raise errors; inspect warnings for omitted properties:

result: ke.asset.USDArticulationImportResult = ke.asset.USDLoader.parse_articulation(
    usd_path="robot.usd", prim_path="/Robot"
)
print(result.diagnostics.warnings)