Files
umamo-reference-layer/sketch/runtime/reference/Mannequin.kt
T
litruv 4eb583b5f3 Design doc and reference implementation sketch for the reference layer
Design for a poseable mannequin plus glTF/GLB import overlay in Umamo:
world axes, orbit camera, draw path, UMA persistence, UI, risks.

docs/seams.md lists the RenderDevice additions the feature needs:
PrimitiveTopology, DepthState, depthAttachment, WorldToClip,
ReferenceMeshSpec.

sketch/ mirrors the algorithms in Kotlin. verify/verify.py proves them:
30 checks, all passing. Two findings: accessor byteOffset must be a
multiple of the component size, and the screen-right basis collapses to a
zero vector at pitch +/-90 degrees, so pitch is clamped to an open
interval.
2026-11-03 18:14:07 +11:00

130 lines
4.9 KiB
Kotlin

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<Bone>) {
/**
* 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<Joint, Euler> pose Per-joint rotation; an absent joint is at rest.
* @return Map<Joint, FloatArray> World matrices, 16 floats row-major.
*/
fun forwardKinematics(pose: Map<Joint, Euler>): Map<Joint, FloatArray> {
val world = HashMap<Joint, FloatArray>()
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<Joint> joints The influencing joints.
* @param FloatArray weights Per-joint weight, same order as [joints].
* @param Map<Joint, FloatArray> world The FK result.
* @return FloatArray The posed position, x y z.
*/
fun skin(vertex: FloatArray, joints: List<Joint>, weights: FloatArray, world: Map<Joint, FloatArray>): 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
}
}
}