Skeleton2D

bone hierarchies, rest poses and two-bone IK.

▶ Run in browser

Tags: 2d skeleton bones animation ik procedural

An articulated figure built entirely from Bone2D nodes, with no art assets: each bone carries a tapered Polygon2D limb as a child, so the bone hierarchy alone places the geometry. The spine and neck sway from a pose offset, the right arm waves from an AnimationClip, and the left arm is driven by an analytical two-bone IK solver that keeps the hand on a moving target while the whole torso rotates underneath it.

What it demonstrates

• Building a rig from a declarative table: Bone2D parented to Bone2D, each one offset along its parent by a fraction of the parent’s bone_length.

• set_as_rest() to capture the authored pose, and reset_to_rest() to snap the whole skeleton back to it.

• The two rotation channels a bone has: rotation is the authored local angle, bone_angle is a pose offset layered on top. The sway and the wave both drive bone_angle, so neither one destroys the rest pose.

• Attaching drawables to bones. The limbs and the skull are ordinary Polygon2D children; nothing recomputes their positions, the transform hierarchy does it.

• SkeletonModification2DTwoBoneIK registered with add_modification(), which Skeleton2D.on_update then runs every frame without any calling code.

• bone_tip for the end point of a bone, used both by the IK check and by the gizmo overlay.

Controls: SPACE - Wave the right arm G - Toggle the bone gizmos F - Flip the IK elbow R - Reset the skeleton to its rest pose ESC - Quit

Run: uv run python examples/features/2d/skeleton2d.py Headless self-check: uv run python examples/features/2d/skeleton2d.py –test

Source

"""Skeleton2D: bone hierarchies, rest poses and two-bone IK.

An articulated figure built entirely from Bone2D nodes, with no art assets: each
bone carries a tapered Polygon2D limb as a child, so the bone hierarchy alone
places the geometry. The spine and neck sway from a pose offset, the right arm
waves from an AnimationClip, and the left arm is driven by an analytical
two-bone IK solver that keeps the hand on a moving target while the whole torso
rotates underneath it.

# /// simvx
# tags = ["2d", "skeleton", "bones", "animation", "ik", "procedural"]
# web = { root = "SkeletonDemo", width = 800, height = 600, responsive = true }
# ///

## What it demonstrates
- Building a rig from a declarative table: Bone2D parented to Bone2D, each one
  offset along its parent by a fraction of the parent's `bone_length`.
- `set_as_rest()` to capture the authored pose, and `reset_to_rest()` to snap the
  whole skeleton back to it.
- The two rotation channels a bone has: `rotation` is the authored local angle,
  `bone_angle` is a pose offset layered on top. The sway and the wave both drive
  `bone_angle`, so neither one destroys the rest pose.
- Attaching drawables to bones. The limbs and the skull are ordinary Polygon2D
  children; nothing recomputes their positions, the transform hierarchy does it.
- `SkeletonModification2DTwoBoneIK` registered with `add_modification()`, which
  `Skeleton2D.on_update` then runs every frame without any calling code.
- `bone_tip` for the end point of a bone, used both by the IK check and by the
  gizmo overlay.

Controls:
  SPACE - Wave the right arm
  G     - Toggle the bone gizmos
  F     - Flip the IK elbow
  R     - Reset the skeleton to its rest pose
  ESC   - Quit

Run: uv run python examples/features/2d/skeleton2d.py
Headless self-check: uv run python examples/features/2d/skeleton2d.py --test
"""

import math
from typing import NamedTuple

from simvx.core import (
    AnimationClip,
    AnimationPlayer,
    Bone2D,
    Input,
    InputMap,
    Key,
    Line2D,
    Node2D,
    Polygon2D,
    Skeleton2D,
    SkeletonModification2DTwoBoneIK,
    Vec2,
)
from simvx.graphics import App

WIDTH, HEIGHT = 800, 600
HIP = Vec2(WIDTH * 0.44, HEIGHT * 0.60)  # where the skeleton node itself sits

LIMB = (0.62, 0.68, 0.86, 1.0)
TORSO = (0.42, 0.52, 0.78, 1.0)
SKIN = (0.92, 0.78, 0.62, 1.0)
GIZMO = (0.15, 0.95, 0.75, 1.0)
JOINT = (1.0, 0.85, 0.25, 1.0)
TARGET = (1.0, 0.42, 0.32, 1.0)


class BoneSpec(NamedTuple):
    """One bone in the rig, authored relative to its parent."""

    name: str
    parent: str | None
    angle: float  # local rotation in degrees, relative to the parent bone
    length: float
    root_w: float  # limb width at the joint
    tip_w: float  # limb width at the far end
    attach: float = 1.0  # fraction along the parent bone where this bone starts
    colour: tuple = LIMB


#: Angles are screen-space: 0 points right, +90 points down. The spine at -90
#: therefore points up, and every child angle is read relative to that.
RIG = (
    BoneSpec("spine", None, -90, 130, 48, 34, colour=TORSO),
    BoneSpec("neck", "spine", 0, 30, 18, 16, colour=SKIN),
    BoneSpec("arm_r", "spine", 118, 78, 18, 14, attach=0.84),
    BoneSpec("forearm_r", "arm_r", 34, 70, 14, 10),
    BoneSpec("arm_l", "spine", -118, 78, 18, 14, attach=0.84),
    # The two-bone IK solver measures the upper segment to wherever the lower
    # bone actually sits, so an IK pair may attach anywhere along its parent.
    # This elbow is at the tip only because that is where an elbow goes.
    BoneSpec("forearm_l", "arm_l", -34, 70, 14, 10),
    BoneSpec("thigh_r", None, 72, 92, 24, 18),
    BoneSpec("shin_r", "thigh_r", 20, 86, 18, 12),
    BoneSpec("thigh_l", None, 108, 92, 24, 18),
    BoneSpec("shin_l", "thigh_l", -20, 86, 18, 12),
)

SKULL_R = 27.0
GIZMO_Z = 10  # gizmo overlay sorts above the limbs

WAVE_CLIP = 1.6  # seconds
SWAY_SPEED = 1.7

#: The IK target orbits here, in skeleton-local pixels. The left shoulder sits
#: about 109px above the hip and the arm reaches 148px, so this orbit (centre 92px
#: from the shoulder, radius 42) stays inside the reachable ring. A target outside
#: it does not fail: the solver clamps to the ring and the hand stops visibly short.
TARGET_CENTRE = Vec2(-84, -72)
TARGET_RADIUS = 42.0
TARGET_ORBIT = 3.0  # seconds per revolution


def _disc(centre: Vec2, radius: float, segments: int = 24) -> list[tuple[float, float]]:
    """Polygon vertices approximating a circle, in a bone's local space."""
    step = math.tau / segments
    return [(centre.x + math.cos(i * step) * radius, centre.y + math.sin(i * step) * radius) for i in range(segments)]


def _limb(spec: BoneSpec) -> list[tuple[float, float]]:
    """A tapered quad running from the bone's origin to its tip."""
    return [
        (0.0, -spec.root_w / 2),
        (spec.length, -spec.tip_w / 2),
        (spec.length, spec.tip_w / 2),
        (0.0, spec.root_w / 2),
    ]


class SkeletonDemo(Node2D):
    """A Bone2D rig posed by a sway, an animation clip and an IK solver."""

    dynamic = True  # every bone moves every frame

    def on_ready(self):
        InputMap.add_action("wave", [Key.SPACE])
        InputMap.add_action("gizmos", [Key.G])
        InputMap.add_action("flip", [Key.F])
        InputMap.add_action("reset", [Key.R])
        InputMap.add_action("quit", [Key.ESCAPE])

        self._t = 0.0
        self._show_gizmos = True

        self._skeleton = Skeleton2D(name="Figure", position=HIP)
        self.add_child(self._skeleton)
        self._bones = self._build_rig()

        # A moving IK target, drawn as a disc. It lives on the scene root rather
        # than on the skeleton, because the solver reads it in world space.
        self._target = Polygon2D(name="Target", polygon=_disc(Vec2(0, 0), 9), colour=TARGET, z_index=GIZMO_Z)
        self.add_child(self._target)

        # Two-bone IK on the left arm. Registering it with the skeleton is all
        # that is needed: Skeleton2D.on_update executes it every frame.
        self._ik = SkeletonModification2DTwoBoneIK(
            upper_bone_index=self._skeleton.find_bone_index("arm_l"),
            lower_bone_index=self._skeleton.find_bone_index("forearm_l"),
        )
        self._skeleton.add_modification(self._ik)

        # The wave drives bone_angle, a pose offset, so the arm's authored rest
        # rotation survives it and the clip keys stay small and readable.
        self._wave_upper = self._add_wave_player(self._bones["arm_r"], [0.0, -1.35, -0.95, -1.35, 0.0])
        self._wave_lower = self._add_wave_player(self._bones["forearm_r"], [0.0, -0.75, -0.15, -0.75, 0.0])

    # -- Rig construction ----------------------------------------------------

    def _build_rig(self) -> dict[str, Bone2D]:
        """Instantiate RIG, attaching a limb polygon and a gizmo to every bone."""
        bones: dict[str, Bone2D] = {}
        for spec in RIG:
            parent = bones[spec.parent] if spec.parent else self._skeleton
            offset = Vec2(bones[spec.parent].bone_length * spec.attach, 0) if spec.parent else Vec2(0, 0)
            bone = Bone2D(
                name=spec.name,
                bone_length=spec.length,
                position=offset,
                rotation=math.radians(spec.angle),
            )
            # The authored pose becomes the rest pose, so reset_to_rest() returns
            # here rather than to an unposed heap at the origin.
            bone.set_as_rest()
            parent.add_child(bone)

            bone.add_child(Polygon2D(name=f"{spec.name}_limb", polygon=_limb(spec), colour=spec.colour))
            bone.add_child(
                Line2D(
                    name=f"{spec.name}_gizmo",
                    points=[(0, 0), (spec.length, 0)],
                    colour=GIZMO,
                    z_index=GIZMO_Z,
                )
            )
            bone.add_child(
                Polygon2D(
                    name=f"{spec.name}_joint",
                    polygon=_disc(Vec2(0, 0), 4, segments=8),
                    colour=JOINT,
                    z_index=GIZMO_Z,
                )
            )
            bones[spec.name] = bone

        # The skull rides the neck bone, offset to sit on its tip. Because the
        # offset is the node's position rather than baked into the vertices, the
        # skull's world position stays exactly neck.bone_tip for free.
        neck = bones["neck"]
        neck.add_child(
            Polygon2D(
                name="skull",
                position=Vec2(neck.bone_length, 0),
                polygon=_disc(Vec2(0, 0), SKULL_R),
                colour=SKIN,
            )
        )
        return bones

    def _add_wave_player(self, bone: Bone2D, keys: list[float]) -> AnimationPlayer:
        """An AnimationPlayer that sweeps one bone's pose offset and returns to rest."""
        clip = AnimationClip(f"wave_{bone.name}", duration=WAVE_CLIP)
        clip.add_track("bone_angle", [(WAVE_CLIP * i / (len(keys) - 1), v) for i, v in enumerate(keys)])
        player = AnimationPlayer(target=bone, name=f"player_{bone.name}")
        player.add_clip(clip)
        bone.add_child(player)
        return player

    # -- Per-frame -----------------------------------------------------------

    @property
    def _waving(self) -> bool:
        return self._wave_upper.playing

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
        if Input.is_action_just_pressed("wave") and not self._waving:
            self._wave_upper.play(f"wave_{self._bones['arm_r'].name}")
            self._wave_lower.play(f"wave_{self._bones['forearm_r'].name}")
        if Input.is_action_just_pressed("gizmos"):
            self.set_gizmos(not self._show_gizmos)
        if Input.is_action_just_pressed("flip"):
            self._ik.flip = not self._ik.flip
        if Input.is_action_just_pressed("reset"):
            self.reset()

        self._t += dt
        self._sway()
        self._move_target()

    def _sway(self) -> None:
        """Layer an idle sway onto the rest pose via bone_angle."""
        s = math.sin(self._t * SWAY_SPEED)
        self._bones["spine"].bone_angle = s * 0.055
        self._bones["neck"].bone_angle = -s * 0.09
        # The right arm yields its pose channel to the wave clip while it plays.
        if not self._waving:
            self._bones["arm_r"].bone_angle = s * 0.12
            self._bones["forearm_r"].bone_angle = s * 0.16
        # The left arm is IK-driven and takes no pose offset: the solver owns
        # both joints, so an animated bone_angle here would fight it for the
        # same channel every frame.

    def _move_target(self) -> None:
        """Orbit the IK target and hand its world position to the solver."""
        a = self._t * math.tau / TARGET_ORBIT
        self._target.position = HIP + TARGET_CENTRE + Vec2(math.cos(a), math.sin(a)) * TARGET_RADIUS
        self._ik.target = Vec2(self._target.world_position)

    # -- Actions -------------------------------------------------------------

    def set_gizmos(self, on: bool) -> None:
        """Show or hide the bone overlay by toggling the gizmo nodes' visibility."""
        self._show_gizmos = on
        for bone in self._skeleton.bones:
            for child in bone.children:
                if child.name.endswith(("_gizmo", "_joint")):
                    child.visible = on

    def reset(self) -> None:
        """Stop the wave and put every bone back on its rest transform."""
        self._wave_upper.stop()
        self._wave_lower.stop()
        self._skeleton.reset_to_rest()
        self._t = 0.0

    # -- HUD -----------------------------------------------------------------

    def on_draw(self, renderer):
        hand = self._bones["forearm_l"].bone_tip
        reach = float(math.dist(tuple(hand), tuple(self._ik.target)))
        renderer.draw_text("Skeleton2D", (10, 10), colour=(1.0, 1.0, 1.0), scale=2)
        renderer.draw_text(
            f"{self._skeleton.bone_count} bones   IK error: {reach:5.1f}px   elbow: "
            f"{'flipped' if self._ik.flip else 'normal'}   gizmos: {'on' if self._show_gizmos else 'off'}",
            (10, 44),
            colour=(0.75, 0.78, 0.85),
        )
        renderer.draw_text(
            "waving" if self._waving else "idle sway",
            (10, 68),
            colour=(1.0, 0.85, 0.35) if self._waving else (0.6, 0.62, 0.68),
        )
        renderer.draw_text(
            "SPACE: wave   G: gizmos   F: flip elbow   R: rest pose   ESC: quit",
            (10, HEIGHT - 28),
            colour=(0.55, 0.57, 0.62),
        )


def _selftest() -> bool:
    """Headless: check the rig, the pose channels, the IK and the rendered result."""
    from simvx.core.testing import InputSimulator
    from simvx.graphics.testing import assert_not_blank, save_png

    FRAMES = 240
    app = App(title="Skeleton2D", width=WIDTH, height=HEIGHT, visible=False)
    scene = SkeletonDemo(name="SkeletonDemo")
    sim = InputSimulator()

    skull_track: list[Vec2] = []
    ik_error: list[float] = []
    spine_world: list[float] = []
    arm_r_angle: list[float] = []
    after_reset: list[tuple[float, float]] = []

    def on_frame(idx: int, _t: float) -> bool:
        bones = scene._bones
        skull_track.append(Vec2(bones["neck"].bone_tip))
        hand = bones["forearm_l"].bone_tip
        ik_error.append(float(math.dist(tuple(hand), tuple(scene._ik.target))))
        spine_world.append(float(bones["spine"].world_rotation))
        arm_r_angle.append(float(bones["arm_r"].bone_angle))

        if idx == 60:
            sim.press_key(Key.SPACE)
        elif idx == 61:
            sim.release_key(Key.SPACE)
        elif idx == 200:
            sim.press_key(Key.R)
        elif idx == 201:
            sim.release_key(Key.R)
        elif idx in (202, 203):
            after_reset.append((float(bones["spine"].bone_angle), float(bones["arm_r"].bone_angle)))
        return True

    frames = app.run_headless(scene, frames=FRAMES, on_frame=on_frame, capture_frames=[0, 90])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/skeleton2d_test.png")

    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    bones = scene._bones
    skel = scene._skeleton

    check(
        "the rig built every bone in RIG", skel.bone_count == len(RIG), f"{skel.bone_count} bones for {len(RIG)} specs"
    )
    check(
        "bones are reachable by name and in depth-first order",
        skel.bones[0] is bones["spine"] and skel.find_bone("forearm_l") is bones["forearm_l"],
        f"first bone is {skel.bones[0].name}",
    )
    rest_ok = all(abs(bones[s.name].rest_transform.rotation - math.radians(s.angle)) < 1e-5 for s in RIG)
    check("set_as_rest captured the authored angles", rest_ok, "every rest_transform matches its BoneSpec")

    # The skull is a plain Polygon2D child of the neck bone, centred on the tip.
    skull = next(c for c in bones["neck"].children if c.name == "skull")
    tip_gap = float(math.dist(tuple(skull.world_position), tuple(bones["neck"].bone_tip)))
    check(
        "an attached drawable rides the bone with no per-frame code",
        tip_gap < 1e-3,
        f"skull sits {tip_gap:.2e}px from neck.bone_tip",
    )

    travel = max(float(math.dist(tuple(skull_track[0]), tuple(p))) for p in skull_track)
    check("the sway actually moves the rig", travel > 3.0, f"the head travelled {travel:.1f}px")

    swing = max(spine_world) - min(spine_world)
    check("bone_angle rotates the spine without touching its rotation", swing > 0.08, f"{swing:.3f} rad of world swing")
    check(
        "the sway left the authored rotation alone",
        abs(bones["spine"].rotation - math.radians(-90)) < 1e-5,
        f"spine.rotation is still {math.degrees(bones['spine'].rotation):.1f} deg",
    )

    # SPACE at frame 60 starts the clip; it is 1.6s long, so it is over well
    # before the reset at frame 200.
    wave_peak = min(arm_r_angle[60:190])
    check("SPACE drove the wave clip", wave_peak < -1.0, f"arm_r.bone_angle reached {wave_peak:.2f} rad")
    check("the wave finished and released the arm", not scene._wave_upper.playing, "the player stopped on its own")

    # The IK runs from Skeleton2D.on_update alone, while the spine sways beneath it.
    worst = max(ik_error[5:])
    check(
        "two-bone IK held the hand on the moving target",
        worst < 2.0,
        f"worst hand-to-target error {worst:.2f}px over {len(ik_error) - 5} frames",
    )

    check(
        "R put every pose offset back to rest",
        bool(after_reset) and all(abs(a) < 0.02 and abs(b) < 0.02 for a, b in after_reset),
        f"bone_angles just after the reset: {[(round(a, 3), round(b, 3)) for a, b in after_reset]}",
    )

    # Gizmo toggle: the overlay nodes go invisible and the picture changes.
    gizmo_scene = SkeletonDemo(name="SkeletonDemo")
    gsim = InputSimulator()

    def gizmo_frame(idx: int, _t: float) -> bool:
        if idx == 20:
            gsim.press_key(Key.G)
        elif idx == 21:
            gsim.release_key(Key.G)
        return True

    gframes = App(title="Skeleton2D gizmos", width=WIDTH, height=HEIGHT, visible=False).run_headless(
        gizmo_scene, frames=40, on_frame=gizmo_frame, capture_frames=[10, 39]
    )
    gizmo_nodes = [c for b in gizmo_scene._skeleton.bones for c in b.children if c.name.endswith("_gizmo")]
    check(
        "G hid the gizmo nodes",
        not gizmo_scene._show_gizmos and all(not n.visible for n in gizmo_nodes),
        f"{len(gizmo_nodes)} gizmo nodes, all hidden: {all(not n.visible for n in gizmo_nodes)}",
    )
    changed = int((abs(gframes[0].astype(int) - gframes[1].astype(int)).sum(axis=-1) > 20).sum())
    check("hiding the gizmos changed the picture", changed > 500, f"{changed} pixels differ")

    # And the figure is really on screen and really moving.
    moved = int((abs(frames[0].astype(int) - frames[1].astype(int)).sum(axis=-1) > 20).sum())
    check("the rendered figure moves", moved > 500, f"{moved} pixels changed between frame 0 and 90")

    quit_scene = SkeletonDemo(name="SkeletonDemo")
    qsim = InputSimulator()
    last = [-1]

    def quit_frame(idx: int, _t: float) -> bool:
        last[0] = idx
        if idx == 30:
            qsim.press_key(Key.ESCAPE)
        elif idx == 31:
            qsim.release_key(Key.ESCAPE)
        return True

    App(title="Skeleton2D quit", width=WIDTH, height=HEIGHT, visible=False).run_headless(
        quit_scene, frames=200, on_frame=quit_frame
    )
    check("ESC ends the run", last[0] < 60, f"the loop stopped at frame {last[0]} of 200")

    print("screenshot: /tmp/skeleton2d_test.png")
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(title="Skeleton2D Rig", width=WIDTH, height=HEIGHT).run(SkeletonDemo())