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.
This commit is contained in:
@@ -0,0 +1,94 @@
|
||||
package org.umamo.format.gltf
|
||||
|
||||
// Reference sketch for PR 1. Container rules only - the JSON half is
|
||||
// kotlinx-serialization-json, already a :format dependency. Everything here is
|
||||
// commonMain-safe: no java.nio, no platform math, no assumption about byte order
|
||||
// beyond the one the format states.
|
||||
|
||||
/** GLB magic, "glTF" read as a little-endian uint32. */
|
||||
public const val GLB_MAGIC: Int = 0x46546C67
|
||||
|
||||
/** The only container version this reader accepts. */
|
||||
public const val GLB_VERSION: Int = 2
|
||||
|
||||
private const val CHUNK_JSON: Int = 0x4E4F4A42
|
||||
private const val CHUNK_BIN: Int = 0x004E4942
|
||||
|
||||
/** The two chunks a GLB carries, in the order they were read. */
|
||||
public class GlbChunks(
|
||||
public val jsonBytes: ByteArray,
|
||||
public val binBytes: ByteArray,
|
||||
)
|
||||
|
||||
public class GlbException(message: String) : Exception(message)
|
||||
|
||||
/**
|
||||
* Reads the GLB container.
|
||||
*
|
||||
* Three rules that are easy to get wrong and are enforced here rather than assumed:
|
||||
*
|
||||
* 1. The declared total length must equal the actual length. A file that declares more than it
|
||||
* holds reads as a truncated chunk, and a truncated chunk is an error, not a short read.
|
||||
* 2. Chunk data is padded to a 4-byte boundary - spaces for JSON, zeros for BIN. The padding is
|
||||
* part of the chunk length, so the JSON bytes handed back include it. The JSON parser must
|
||||
* not be given the padding as content; trim before parsing.
|
||||
* 3. An unknown chunk type is skipped, not rejected. A GLB with an extra chunk is still a valid
|
||||
* GLB. More than one chunk of a known type is not.
|
||||
*
|
||||
* @param ByteArray data The whole file.
|
||||
* @return GlbChunks The JSON and BIN chunks.
|
||||
*/
|
||||
public fun readGlb(data: ByteArray): GlbChunks {
|
||||
if (data.size < 12) {
|
||||
throw GlbException("shorter than the 12-byte header")
|
||||
}
|
||||
if (readUint32(data, 0) != GLB_MAGIC) {
|
||||
throw GlbException("magic is not 'glTF'")
|
||||
}
|
||||
val version = readUint32(data, 4)
|
||||
if (version != GLB_VERSION) {
|
||||
throw GlbException("container version $version, this reader accepts 2")
|
||||
}
|
||||
val declared = readUint32(data, 8)
|
||||
if (declared != data.size) {
|
||||
throw GlbException("declared length $declared, actual ${data.size}")
|
||||
}
|
||||
|
||||
var json: ByteArray? = null
|
||||
var bin: ByteArray? = null
|
||||
var pos = 12
|
||||
while (pos + 8 <= data.size) {
|
||||
val length = readUint32(data, pos)
|
||||
val type = readUint32(data, pos + 4)
|
||||
val start = pos + 8
|
||||
if (start + length > data.size) {
|
||||
throw GlbException("chunk at $pos declares $length bytes, only ${data.size - start} remain")
|
||||
}
|
||||
val payload = data.copyOfRange(start, start + length)
|
||||
if (type == CHUNK_JSON) {
|
||||
if (json != null) {
|
||||
throw GlbException("more than one JSON chunk")
|
||||
}
|
||||
json = payload
|
||||
} else if (type == CHUNK_BIN) {
|
||||
if (bin != null) {
|
||||
throw GlbException("more than one BIN chunk")
|
||||
}
|
||||
bin = payload
|
||||
}
|
||||
// An unknown type is skipped.
|
||||
pos = start + length
|
||||
}
|
||||
|
||||
if (json == null) {
|
||||
throw GlbException("no JSON chunk")
|
||||
}
|
||||
return GlbChunks(json, bin ?: ByteArray(0))
|
||||
}
|
||||
|
||||
/** Little-endian uint32. glTF is little-endian everywhere; there is no host-order reading here. */
|
||||
private fun readUint32(data: ByteArray, offset: Int): Int =
|
||||
(data[offset].toInt() and 0xFF) or
|
||||
((data[offset + 1].toInt() and 0xFF) shl 8) or
|
||||
((data[offset + 2].toInt() and 0xFF) shl 16) or
|
||||
((data[offset + 3].toInt() and 0xFF) shl 24)
|
||||
@@ -0,0 +1,115 @@
|
||||
package org.umamo.format.gltf
|
||||
|
||||
// Reference sketch for PR 1: accessor resolution. This is the part of the reader with rules
|
||||
// that produce wrong numbers silently rather than failing, so it is written as its own seam.
|
||||
|
||||
public class GltfException(message: String) : Exception(message)
|
||||
|
||||
/** glTF component types. The codes are the format's constants, not Umamo's. */
|
||||
public enum class ComponentType(val code: Int, val byteSize: Int) {
|
||||
Int8(5120, 1),
|
||||
Uint8(5121, 1),
|
||||
Int16(5122, 2),
|
||||
Uint16(5123, 2),
|
||||
Uint32(5125, 4),
|
||||
Float32(5126, 4);
|
||||
|
||||
public companion object {
|
||||
/** An unknown code is a hard failure, not a fallback: a wrong component size shifts every value after it. */
|
||||
public fun fromCode(code: Int): ComponentType =
|
||||
entries.firstOrNull { it.code == code } ?: throw GltfException("unknown componentType $code")
|
||||
}
|
||||
}
|
||||
|
||||
/** Number of components per element. */
|
||||
public enum class ComponentCount(val code: String, val components: Int) {
|
||||
Scalar("SCALAR", 1),
|
||||
Vec2("VEC2", 2),
|
||||
Vec3("VEC3", 3),
|
||||
Vec4("VEC4", 4);
|
||||
|
||||
public companion object {
|
||||
public fun fromCode(code: String): ComponentCount =
|
||||
entries.firstOrNull { it.code == code } ?: throw GltfException("unknown accessor type $code")
|
||||
}
|
||||
}
|
||||
|
||||
public data class BufferView(
|
||||
val bufferIndex: Int,
|
||||
val byteOffset: Int,
|
||||
val byteLength: Int,
|
||||
val byteStride: Int?,
|
||||
)
|
||||
|
||||
public data class Accessor(
|
||||
val bufferViewIndex: Int,
|
||||
val byteOffset: Int,
|
||||
val componentType: ComponentType,
|
||||
val componentCount: ComponentCount,
|
||||
val count: Int,
|
||||
val byteStride: Int?,
|
||||
)
|
||||
|
||||
/**
|
||||
* Reads one accessor as floats.
|
||||
*
|
||||
* Two rules enforced here:
|
||||
*
|
||||
* 1. The resolved byte offset must be a multiple of the component size. glTF states this as a
|
||||
* validity requirement; a reader that ignores it reads a shifted value and gets a plausible
|
||||
* wrong number rather than an error. This is the single most common glTF corruption.
|
||||
* 2. The read must stay inside the buffer view's byteLength. Reading past it is an error, not a
|
||||
* zero fill - a zero-filled vertex collapses a mesh quietly.
|
||||
*
|
||||
* `normalized` is deliberately not applied. A reference layer needs raw positions and indices;
|
||||
* normalizing a position would scale it by 65535. If a material factor ever needs it, that is a
|
||||
* separate read, not this one.
|
||||
*
|
||||
* @param ByteArray bin The BIN chunk.
|
||||
* @param List<BufferView> views The document's buffer views.
|
||||
* @param Accessor accessor The accessor to read.
|
||||
* @return FloatArray The values, element-major.
|
||||
*/
|
||||
public fun readFloats(bin: ByteArray, views: List<BufferView>, accessor: Accessor): FloatArray {
|
||||
val view = views[accessor.bufferViewIndex]
|
||||
val size = accessor.componentType.byteSize
|
||||
val n = accessor.componentCount.components
|
||||
val stride = accessor.byteStride ?: view.byteStride ?: size * n
|
||||
val start = view.byteOffset + accessor.byteOffset
|
||||
|
||||
if (start % size != 0) {
|
||||
throw GltfException("accessor byte offset $start is not a multiple of component size $size")
|
||||
}
|
||||
val needed = (accessor.count - 1) * stride + size * n
|
||||
if (start + needed > view.byteLength) {
|
||||
throw GltfException("accessor reads $needed bytes, buffer view holds ${view.byteLength}")
|
||||
}
|
||||
|
||||
val out = FloatArray(accessor.count * n)
|
||||
for (i in 0 until accessor.count) {
|
||||
for (c in 0 until n) {
|
||||
out[i * n + c] = readComponent(bin, start + i * stride + c * size, accessor.componentType)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
private fun readComponent(bin: ByteArray, offset: Int, type: ComponentType): Float {
|
||||
val b = (bin[offset].toInt() and 0xFF) or
|
||||
((bin[offset + 1].toInt() and 0xFF) shl 8) or
|
||||
((bin[offset + 2].toInt() and 0xFF) shl 16) or
|
||||
((bin[offset + 3].toInt() and 0xFF) shl 24)
|
||||
return when (type) {
|
||||
ComponentType.Float32 -> Float.fromBits(b)
|
||||
ComponentType.Uint32 -> b.toLong().and(0xFFFFFFFFL).toFloat()
|
||||
ComponentType.Int8 -> bin[offset].toInt().toFloat()
|
||||
ComponentType.Uint8 -> (bin[offset].toInt() and 0xFF).toFloat()
|
||||
ComponentType.Int16 -> shortAt(bin, offset).toInt().toFloat()
|
||||
ComponentType.Uint16 -> (shortAt(bin, offset).toInt() and 0xFFFF).toFloat()
|
||||
}
|
||||
}
|
||||
|
||||
private fun shortAt(bin: ByteArray, offset: Int): Short {
|
||||
val v = (bin[offset].toInt() and 0xFF) or ((bin[offset + 1].toInt() and 0xFF) shl 8)
|
||||
return v.toShort()
|
||||
}
|
||||
@@ -0,0 +1,119 @@
|
||||
package org.umamo.render
|
||||
|
||||
import kotlin.math.cos
|
||||
import kotlin.math.sin
|
||||
|
||||
/**
|
||||
* An orbit orthographic camera over the reference layer.
|
||||
*
|
||||
* World axes: X right, Y depth, Z up - Umamo's existing convention, the one
|
||||
* `PuppetModel.worldOriginX` / `worldOriginZ` and the world axis lines already use. At
|
||||
* yaw == pitch == 0 the basis is forward +Y, right +X, up +Z, and the projection agrees
|
||||
* exactly with `ViewportCamera.worldToNdc`. That agreement is the anchor of the design: an
|
||||
* unrotated reference layer sits in the drawing plane, and rotation is the only thing that
|
||||
* separates it from the puppet.
|
||||
*
|
||||
* Pure, like `ViewportCamera`: every helper returns a new camera and touches no GL, so the
|
||||
* maths unit-tests without a context.
|
||||
*
|
||||
* The pitch clamp is not cosmetic. At pitch == ±90 the camera looks along the world up axis,
|
||||
* the screen-right basis vector becomes a zero vector, and the projection still returns a
|
||||
* number - the model collapses to a line and nothing reports it. The clamp therefore belongs
|
||||
* in the pure model, not in the drag handler. Verified in verify/verify.py.
|
||||
*
|
||||
* @property Float targetX World X the camera looks at.
|
||||
* @property Float targetY World Y (depth) the camera looks at.
|
||||
* @property Float targetZ World Z (up) the camera looks at.
|
||||
* @property Float yaw Rotation about the world up axis, degrees.
|
||||
* @property Float pitch Elevation above the target, degrees, clamped to ±MAX_PITCH_DEG.
|
||||
* @property Float zoom Screen pixels per world unit, shared with the viewport camera.
|
||||
*/
|
||||
data class ReferenceCamera(
|
||||
val targetX: Float,
|
||||
val targetY: Float,
|
||||
val targetZ: Float,
|
||||
val yaw: Float,
|
||||
val pitch: Float,
|
||||
val zoom: Float,
|
||||
) {
|
||||
/** The camera's orthonormal basis: forward is the view direction, right is screen right, up is screen up. */
|
||||
data class Basis(val forwardX: Float, val forwardY: Float, val forwardZ: Float, val rightX: Float, val rightY: Float, val rightZ: Float, val upX: Float, val upY: Float, val upZ: Float)
|
||||
|
||||
/**
|
||||
* The basis at the camera's current angles, with pitch clamped.
|
||||
*
|
||||
* @return Basis The basis.
|
||||
*/
|
||||
fun basis(): Basis {
|
||||
val y = yaw * DEG
|
||||
val p = clampedPitch() * DEG
|
||||
return Basis(
|
||||
-cos(p) * sin(y), cos(p) * cos(y), -sin(p),
|
||||
cos(p) * cos(y), cos(p) * sin(y), 0f,
|
||||
-sin(p) * sin(y), sin(p) * cos(y), cos(p),
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* The row-major 4x4 world-to-clip matrix the vertex shader applies.
|
||||
*
|
||||
* x and y are the orthographic NDC scales, the same scales `ViewportCamera.worldToNdc`
|
||||
* produces. z is the depth, mapped from [near, far] to [0, 1] so a nearer fragment has the
|
||||
* smaller value and `DepthFunc.Less` picks it.
|
||||
*
|
||||
* @param Int viewportWidth Viewport width in pixels.
|
||||
* @param Int viewportHeight Viewport height in pixels.
|
||||
* @param Float near Near depth, relative to the target.
|
||||
* @param Float far Far depth, relative to the target.
|
||||
* @return FloatArray 16 floats, row-major.
|
||||
*/
|
||||
fun worldToClip(viewportWidth: Int, viewportHeight: Int, near: Float, far: Float): FloatArray {
|
||||
val b = basis()
|
||||
val scaleX = 2f * zoom / viewportWidth
|
||||
val scaleY = 2f * zoom / viewportHeight
|
||||
val scaleZ = 1f / (far - near)
|
||||
val out = FloatArray(16)
|
||||
|
||||
// One row per basis axis. The translation term is -(axis · target) * scale, which is what
|
||||
// puts the target at the NDC origin; the depth row additionally shifts by -near so the near
|
||||
// plane lands on 0 rather than on a negative value the depth test cannot represent.
|
||||
val axes = arrayOf(
|
||||
floatArrayOf(b.rightX, b.rightY, b.rightZ, scaleX),
|
||||
floatArrayOf(b.upX, b.upY, b.upZ, scaleY),
|
||||
floatArrayOf(b.forwardX, b.forwardY, b.forwardZ, scaleZ),
|
||||
)
|
||||
for (r in 0 until 3) {
|
||||
val axis = axes[r]
|
||||
val scale = axis[3]
|
||||
val dot = axis[0] * targetX + axis[1] * targetY + axis[2] * targetZ
|
||||
out[r * 4] = axis[0] * scale
|
||||
out[r * 4 + 1] = axis[1] * scale
|
||||
out[r * 4 + 2] = axis[2] * scale
|
||||
out[r * 4 + 3] = -dot * scale
|
||||
}
|
||||
out[2 * 4 + 3] -= near * scaleZ
|
||||
out[15] = 1f
|
||||
return out
|
||||
}
|
||||
|
||||
/** Pans by a screen-pixel drag delta, grab style, Y carrying the screen-down sign flip. */
|
||||
fun panByScreen(deltaXpx: Float, deltaYpx: Float): ReferenceCamera =
|
||||
copy(targetX = targetX - deltaXpx / zoom, targetZ = targetZ + deltaYpx / zoom)
|
||||
|
||||
/** Orbits by a drag delta. Pitch is clamped here, at the model, not in the caller. */
|
||||
fun orbitBy(deltaYawDeg: Float, deltaPitchDeg: Float): ReferenceCamera =
|
||||
copy(yaw = yaw + deltaYawDeg, pitch = clampedPitch() + deltaPitchDeg)
|
||||
|
||||
private fun clampedPitch(): Float = pitch.coerceIn(-MAX_PITCH_DEG, MAX_PITCH_DEG)
|
||||
|
||||
companion object {
|
||||
/** Pitch is clamped to the open interval; ±90 collapses the screen-right axis. */
|
||||
const val MAX_PITCH_DEG: Float = 89.9f
|
||||
|
||||
/** Shared with ViewportCamera so a linked camera cannot disagree about the limits. */
|
||||
const val MIN_ZOOM: Float = 0.02f
|
||||
const val MAX_ZOOM: Float = 64f
|
||||
|
||||
private const val DEG = 0.017453292519943295f
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,130 @@
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user