package org.umamo.runtime.reference import kotlin.math.cos import kotlin.math.sin /** * The mannequin's joint set. Fixed, and a pose addresses joints by these names rather than by * list ordinal - an ordinal is not stable across a proportions edit, the same reason * `KeyformOwner.Glue` addresses a glue by its pair instead of by index. */ public enum class Joint { Pelvis, Spine, Chest, Neck, Head, ShoulderL, ElbowL, WristL, HipL, KneeL, AnkleL, ShoulderR, ElbowR, WristR, HipR, KneeR, AnkleR, } /** One joint's rotation, degrees, applied as R = Rz * Ry * Rx. */ public data class Euler(val x: Float, val y: Float, val z: Float) /** Per-axis anatomical limits. A pose outside these is not a pose a body can hold. */ public data class JointLimits(val minX: Float, val maxX: Float, val minY: Float, val maxY: Float, val minZ: Float, val maxZ: Float) /** One bone: its parent, its rest offset from that parent, and its limits. */ public data class Bone(val joint: Joint, val parent: Joint?, val offsetX: Float, val offsetY: Float, val offsetZ: Float, val limits: JointLimits) /** * The mannequin as data: bones in tree order, proportions as fractions of standing height. * * Procedural on purpose. A bundled asset would raise a licensing question and make the output * non-deterministic across asset revisions; this produces the same triangles from the same * proportions every time, which is what lets a test pin a pose. */ public class Mannequin(private val bones: List) { /** * Forward kinematics: one world matrix per joint, row-major 4x4. * * local = T(offset) * R(euler), world = parentWorld * local. Three consequences follow from * that order and are asserted in verify/verify.py: * * 1. A joint's rotation does not move its own origin - the rotation is applied after the * translation, so the joint sits where its bone says it sits. * 2. Bone length is pose-invariant. * 3. At scale 1 the rotation block stays orthonormal, which is what skinning depends on. * * @param Map pose Per-joint rotation; an absent joint is at rest. * @return Map World matrices, 16 floats row-major. */ fun forwardKinematics(pose: Map): Map { val world = HashMap() for (bone in bones) { val clamped = clamp(pose[bone.joint] ?: Euler(0f, 0f, 0f), bone.limits) val local = matMul(translate(bone.offsetX, bone.offsetY, bone.offsetZ), euler(clamped)) world[bone.joint] = if (bone.parent == null) local else matMul(world.getValue(bone.parent), local) } return world } /** * CPU skinning: a weighted vertex follows its joints. * * CPU first, matching the codebase's existing shape - the CPU path is the oracle, the GPU path * is the fast one. Weights are expected to sum to 1; they are not renormalized here, because * a glTF that ships weights summing to 0.9 is a data problem the caller should see rather than * one this function quietly repairs. * * @param FloatArray vertex The rest position, x y z. * @param List joints The influencing joints. * @param FloatArray weights Per-joint weight, same order as [joints]. * @param Map world The FK result. * @return FloatArray The posed position, x y z. */ fun skin(vertex: FloatArray, joints: List, weights: FloatArray, world: Map): FloatArray { val out = FloatArray(3) for (i in joints.indices) { val m = world.getValue(joints[i]) for (r in 0 until 3) { out[r] += weights[i] * (m[r * 4] * vertex[0] + m[r * 4 + 1] * vertex[1] + m[r * 4 + 2] * vertex[2] + m[r * 4 + 3]) } } return out } private fun clamp(e: Euler, l: JointLimits): Euler = Euler(e.x.coerceIn(l.minX, l.maxX), e.y.coerceIn(l.minY, l.maxY), e.z.coerceIn(l.minZ, l.maxZ)) private companion object { private const val DEG = 0.017453292519943295f private fun matMul(a: FloatArray, b: FloatArray): FloatArray { val out = FloatArray(16) for (r in 0 until 4) { for (c in 0 until 4) { var sum = 0f for (k in 0 until 4) { sum += a[r * 4 + k] * b[k * 4 + c] } out[r * 4 + c] = sum } } return out } private fun translate(x: Float, y: Float, z: Float): FloatArray { val m = identity() m[3] = x m[7] = y m[11] = z return m } private fun euler(e: Euler): FloatArray { val rx = e.x * DEG val ry = e.y * DEG val rz = e.z * DEG val mx = floatArrayOf(1f, 0f, 0f, 0f, 0f, cos(rx), -sin(rx), 0f, 0f, sin(rx), cos(rx), 0f, 0f, 0f, 0f, 1f) val my = floatArrayOf(cos(ry), 0f, sin(ry), 0f, 0f, 1f, 0f, 0f, -sin(ry), 0f, cos(ry), 0f, 0f, 0f, 0f, 1f) val mz = floatArrayOf(cos(rz), -sin(rz), 0f, 0f, sin(rz), cos(rz), 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f) return matMul(matMul(mz, my), mx) } private fun identity(): FloatArray { val m = FloatArray(16) m[0] = 1f m[5] = 1f m[10] = 1f m[15] = 1f return m } } }