"""Forward kinematics: skeleton plus pose, resolved into concrete geometry.
Everything downstream -- camera scaling, actor placement, balloon avoidance, tail
routing, rendering -- consumes the output of this module and nothing else from the
asset layer. That boundary is the whole point: swap the puppet for hand-drawn
artwork exposing the same anchors and hulls, and layout is unchanged.
"""
import math
from dataclasses import dataclass, field
from scenet.assets.contract import BlobPart, BonePart, Feature, Landmark, PuppetSpec
from scenet.geom import BBox, Circle, Point, Vector
[docs]
@dataclass(frozen=True, slots=True)
class ResolvedCapsule:
"""A limb segment: a thick line with rounded ends."""
start: Point
end: Point
width: float
[docs]
@dataclass(frozen=True, slots=True)
class ResolvedBlob:
"""A rounded mass -- head, hand, foot -- after posing.
Attributes:
centre: Where it sits, in panel coordinates.
radius: Radius in panel units, already scaled by the camera.
"""
centre: Point
radius: float
[docs]
@dataclass(frozen=True, slots=True)
class ResolvedFeature:
"""One facial feature point after posing.
Attributes:
centre: Where it sits, in panel coordinates.
size: Its extent in panel units, already scaled. What the number measures
depends on the feature -- see
:class:`FeatureSpec <scenet.assets.contract.FeatureSpec>`.
"""
centre: Point
size: float
[docs]
@dataclass(frozen=True, slots=True)
class ResolvedPuppet:
"""A posed figure in panel coordinates.
Produced once per actor per compile, then treated as read-only by every consumer.
"""
name: str
pose: str
facing_right: bool
scale: float
joints: dict[str, Point]
anchors: dict[str, Point]
landmarks: dict[Landmark, float]
capsules: tuple[ResolvedCapsule, ...]
blobs: tuple[ResolvedBlob, ...]
face: Circle
gaze: Vector
hull: tuple[Point, ...]
expression: str = "neutral"
# Feature points do not contribute to the hull. They sit inside the head, whose
# blob is already in it, so adding them would change nothing except the running
# time -- and a face that pushed balloons further away would be a bug.
features: dict[Feature, ResolvedFeature] = field(default_factory=dict)
@property
def bounds(self) -> BBox:
"""Axis-aligned bounds of the posed silhouette."""
xs = [point.x for point in self.hull]
ys = [point.y for point in self.hull]
return BBox(min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys))
[docs]
def anchor(self, name: str) -> Point:
"""Look up one named attachment point in panel coordinates.
Args:
name: An anchor the puppet declared -- `mouth` and `eyes` are the ones the
compiler itself relies on.
Returns:
Where that anchor ended up after posing, scaling and mirroring.
Raises:
KeyError: This puppet declares no anchor by that name.
"""
if name not in self.anchors:
raise KeyError(
f"puppet '{self.name}' has no anchor '{name}'; has {sorted(self.anchors)}"
)
return self.anchors[name]
def _rotate(dx: float, dy: float, degrees: float) -> tuple[float, float]:
rad = math.radians(degrees)
cos, sin = math.cos(rad), math.sin(rad)
return dx * cos - dy * sin, dx * sin + dy * cos
def _topological_order(spec: PuppetSpec) -> list[str]:
"""Joints ordered parents-first, sorted at each level.
Sorted rather than insertion-ordered so that the traversal -- and therefore any
floating-point accumulation -- is identical on every run, which determinism
requires.
"""
children: dict[str | None, list[str]] = {}
for name, joint in spec.joints.items():
children.setdefault(joint.parent, []).append(name)
for siblings in children.values():
siblings.sort()
order: list[str] = []
stack = [spec.root]
while stack:
node = stack.pop()
order.append(node)
stack.extend(reversed(children.get(node, [])))
return order
[docs]
def solve_pose(spec: PuppetSpec, pose: str) -> tuple[dict[str, Point], dict[str, float]]:
"""Resolve joint positions in the puppet's own units, root at the origin.
Returns the joint positions and the accumulated world angle at each joint, the
latter being what anchors and gaze need in order to ride along with rotation.
"""
angles = spec.pose_angles(pose)
positions: dict[str, Point] = {}
accumulated: dict[str, float] = {}
for name in _topological_order(spec):
joint = spec.joints[name]
local_angle = angles.get(name, 0.0)
if joint.parent is None:
accumulated[name] = local_angle
positions[name] = Point(0.0, 0.0)
continue
accumulated[name] = accumulated[joint.parent] + local_angle
dx, dy = _rotate(joint.offset[0], joint.offset[1], accumulated[name])
positions[name] = positions[joint.parent].translated(dx, dy)
return positions, accumulated
[docs]
def resolve(
spec: PuppetSpec,
*,
pose: str,
facing_right: bool,
scale: float,
origin: Point,
expression: str = "neutral",
) -> ResolvedPuppet:
"""Pose, mirror, scale and place a puppet.
`origin` is where the puppet's root joint lands in panel coordinates. Mirroring
happens in the puppet's own frame before scaling, so a mirrored figure is the
exact reflection of the original rather than being offset by rounding.
`expression` selects which face is drawn. It is validated and carried here, but
the states it names are not applied until the marks are built -- feature *points*
are where the anatomy is, and are the same whatever the face is doing.
"""
if spec.expressions:
spec.expression_states(expression)
local, accumulated = solve_pose(spec, pose)
mirror = 1.0 if facing_right else -1.0
def to_panel(point: Point) -> Point:
return Point(origin.x + mirror * point.x * scale, origin.y + point.y * scale)
def offset_from(joint: str, offset: tuple[float, float]) -> Point:
dx, dy = _rotate(offset[0], offset[1], accumulated[joint])
return to_panel(local[joint].translated(dx, dy))
joints = {name: to_panel(point) for name, point in local.items()}
anchors = {
name: offset_from(anchor.joint, anchor.offset) for name, anchor in spec.anchors.items()
}
capsules: list[ResolvedCapsule] = []
blobs: list[ResolvedBlob] = []
for part in spec.parts:
if isinstance(part, BonePart):
capsules.append(
ResolvedCapsule(
start=joints[part.from_joint],
end=joints[part.to_joint],
width=part.width * scale,
)
)
elif isinstance(part, BlobPart):
blobs.append(
ResolvedBlob(centre=offset_from(part.at, part.offset), radius=part.radius * scale)
)
face_centre = offset_from(spec.face.joint, spec.face.offset)
face = Circle(face_centre.x, face_centre.y, spec.face.radius * scale)
features = {
feature: ResolvedFeature(
centre=offset_from(feature_spec.joint, feature_spec.offset),
size=feature_spec.size * scale,
)
for feature, feature_spec in spec.face.features.items()
}
gaze_origin = anchors[spec.gaze.origin]
forward_dx, forward_dy = _rotate(1.0, 0.0, accumulated[spec.face.joint])
gaze = Vector(mirror * forward_dx, forward_dy).normalised()
return ResolvedPuppet(
name=spec.name,
pose=pose,
facing_right=facing_right,
scale=scale,
joints=joints,
anchors=anchors,
landmarks=_landmarks_in_panel(spec, origin.y, scale),
capsules=tuple(capsules),
blobs=tuple(blobs),
face=face,
gaze=gaze if gaze.length else Vector(mirror, 0.0),
hull=convex_hull(_outline_points(capsules, blobs, [gaze_origin])),
expression=expression,
features=features,
)
def _landmarks_in_panel(spec: PuppetSpec, origin_y: float, scale: float) -> dict[Landmark, float]:
"""Landmark heights as absolute panel y coordinates.
Landmarks are declared downward from the top of the head, while the skeleton is
built outward from the root joint. `root_landmark` says where those two frames
meet, and this converts between them.
"""
root_offset = spec.landmarks[spec.root_landmark]
return {
landmark: origin_y + (value - root_offset) * scale
for landmark, value in spec.landmarks.items()
}
def _outline_points(
capsules: list[ResolvedCapsule], blobs: list[ResolvedBlob], extra: list[Point]
) -> list[Point]:
"""Sample points covering the drawn silhouette.
Capsule ends are expanded to their four corners plus the rounded cap extremes, so
the hull encloses the stroke rather than only its centreline -- otherwise
balloons would be allowed to overlap limbs by half a stroke width.
"""
points: list[Point] = list(extra)
for capsule in capsules:
dx = capsule.end.x - capsule.start.x
dy = capsule.end.y - capsule.start.y
length = math.hypot(dx, dy)
half = capsule.width / 2
if length == 0:
points.extend(
[
capsule.start.translated(half, half),
capsule.start.translated(-half, half),
capsule.start.translated(half, -half),
capsule.start.translated(-half, -half),
]
)
continue
# Unit normal, and the unit direction used to extend past the rounded caps.
nx, ny = -dy / length * half, dx / length * half
ex, ey = dx / length * half, dy / length * half
for end, sign in ((capsule.start, -1.0), (capsule.end, 1.0)):
base = end.translated(sign * ex, sign * ey)
points.append(base.translated(nx, ny))
points.append(base.translated(-nx, -ny))
for blob in blobs:
r = blob.radius
points.extend(
[
blob.centre.translated(r, 0),
blob.centre.translated(-r, 0),
blob.centre.translated(0, r),
blob.centre.translated(0, -r),
blob.centre.translated(r * 0.7071, r * 0.7071),
blob.centre.translated(-r * 0.7071, r * 0.7071),
blob.centre.translated(r * 0.7071, -r * 0.7071),
blob.centre.translated(-r * 0.7071, -r * 0.7071),
]
)
return points
[docs]
def convex_hull(points: list[Point]) -> tuple[Point, ...]:
"""Andrew's monotone chain, returning hull vertices counter-clockwise.
Implemented here rather than delegated to shapely because it runs on a handful of
points per actor and the result must be bit-for-bit reproducible; shapely is
reserved for the genuinely hard polygon work in balloon placement.
"""
unique = sorted({(point.x, point.y) for point in points})
if len(unique) <= 2:
return tuple(Point(x, y) for x, y in unique)
def cross(o: tuple[float, float], a: tuple[float, float], b: tuple[float, float]) -> float:
return (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0])
lower: list[tuple[float, float]] = []
for point in unique:
while len(lower) >= 2 and cross(lower[-2], lower[-1], point) <= 0:
lower.pop()
lower.append(point)
upper: list[tuple[float, float]] = []
for point in reversed(unique):
while len(upper) >= 2 and cross(upper[-2], upper[-1], point) <= 0:
upper.pop()
upper.append(point)
return tuple(Point(x, y) for x, y in lower[:-1] + upper[:-1])