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:
litruv
2026-11-03 18:14:07 +11:00
parent e95d7795ae
commit 4eb583b5f3
10 changed files with 1913 additions and 2 deletions
+311
View File
@@ -0,0 +1,311 @@
#!/usr/bin/env python3
"""Proof harness for the three pure parts of the reference-layer design.
Mirrors the Kotlin sketch in sketch/. Nothing here touches a GPU, so every
assertion is a fact the sketch can state as a test expectation.
1. GLB container + accessor resolution
2. Forward kinematics of the mannequin joint chain
3. Orbit orthographic camera (world -> NDC), and its agreement with
ViewportCamera at yaw = pitch = 0
Convention used throughout, matching Umamo's world space:
X right, Y depth (into the screen), Z up. Row-major 4x4 matrices.
Euler applied as R = Rz * Ry * Rx.
"""
import json
import math
import struct
FAILURES = []
def check(name, got, want):
ok = got == want
if not ok:
FAILURES.append((name, got, want))
print(f"[{'ok ' if ok else 'FAIL'}] {name}: {got}")
def approx(name, got, want, eps=1e-6):
ok = all(abs(a - b) < eps for a, b in zip(got, want))
if not ok:
FAILURES.append((name, got, want))
print(f"[{'ok ' if ok else 'FAIL'}] {name}: {[round(v, 6) for v in got]}")
# ---------------------------------------------------------------- 1. GLB
GLB_MAGIC = 0x46546C67
CHUNK_JSON = 0x4E4F4A42
CHUNK_BIN = 0x004E4942
COMPONENT_BYTES = {5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4}
COMPONENT_ELEMENTS = {5120: 'b', 5121: 'B', 5122: 'h', 5123: 'H', 5125: 'I', 5126: 'f'}
TYPE_COMPONENTS = {'SCALAR': 1, 'VEC2': 2, 'VEC3': 3, 'VEC4': 4}
def build_glb(json_obj, bin_chunk):
body = json.dumps(json_obj, separators=(',', ':')).encode('utf-8')
body += b' ' * ((4 - len(body) % 4) % 4)
padded_bin = bin_chunk + b'\x00' * ((4 - len(bin_chunk) % 4) % 4)
out = struct.pack('<III', GLB_MAGIC, 2, 12 + 8 + len(body) + 8 + len(padded_bin))
out += struct.pack('<II', len(body), CHUNK_JSON) + body
out += struct.pack('<II', len(padded_bin), CHUNK_BIN) + padded_bin
return out
def read_glb(data):
magic, version, total = struct.unpack_from('<III', data, 0)
if magic != GLB_MAGIC or version != 2:
raise ValueError('not a glTF 2.0 binary')
if total != len(data):
raise ValueError(f'declared length {total} != actual {len(data)}')
pos = 12
json_obj = None
bin_chunk = None
while pos < len(data):
length, kind = struct.unpack_from('<II', data, pos)
payload = data[pos + 8:pos + 8 + length]
if len(payload) != length:
raise ValueError('chunk truncated')
if kind == CHUNK_JSON:
if json_obj is not None:
raise ValueError('more than one JSON chunk')
json_obj = json.loads(payload.decode('utf-8'))
elif kind == CHUNK_BIN:
if bin_chunk is not None:
raise ValueError('more than one BIN chunk')
bin_chunk = payload
pos += 8 + length
if json_obj is None:
raise ValueError('no JSON chunk')
return json_obj, bin_chunk
def read_accessor(doc, bin_chunk, index):
acc = doc['accessors'][index]
comp = acc['componentType']
size = COMPONENT_BYTES[comp]
n = TYPE_COMPONENTS[acc['type']]
view = doc['bufferViews'][acc['bufferView']]
stride = acc.get('stride') or view.get('stride') or size * n
start = view['byteOffset'] + acc.get('byteOffset', 0)
if start % size:
raise ValueError(f'accessor {index}: byteOffset {start} not a multiple of {size}')
fmt = '<' + COMPONENT_ELEMENTS[comp] * n
out = []
for i in range(acc['count']):
out.extend(struct.unpack_from(fmt, bin_chunk, start + i * stride))
return out
BIN = struct.pack('<3f', 0.0, 0.0, 0.0) + struct.pack('<3f', 1.0, 0.0, 0.0) + struct.pack('<3f', 0.0, 1.0, 0.0)
BIN += struct.pack('<3H', 0, 1, 2)
DOC = {
'asset': {'version': '2.0'},
'buffers': [{'byteLength': len(BIN)}],
'bufferViews': [
{'buffer': 0, 'byteOffset': 0, 'byteLength': 36, 'target': 34962},
{'buffer': 0, 'byteOffset': 36, 'byteLength': 6, 'target': 34963},
],
'accessors': [
{'bufferView': 0, 'componentType': 5126, 'count': 3, 'type': 'VEC3'},
{'bufferView': 1, 'componentType': 5123, 'count': 3, 'type': 'SCALAR'},
],
}
glb = build_glb(DOC, BIN)
parsed, parsed_bin = read_glb(glb)
check('glb round-trip json', parsed, DOC)
check('glb bin chunk padded to 4 bytes', len(parsed_bin), 44)
check('glb positions', read_accessor(parsed, parsed_bin, 0), [0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0])
check('glb indices', read_accessor(parsed, parsed_bin, 1), [0, 1, 2])
json_len = len(json.dumps(DOC, separators=(',', ':')).encode())
pad = (4 - json_len % 4) % 4
check('json chunk padded with spaces to a 4-byte boundary',
((json_len + pad) % 4, glb[12 + 8 + json_len:12 + 8 + json_len + pad]), (0, b' ' * pad))
try:
bad = dict(DOC)
bad['accessors'] = [{'bufferView': 1, 'byteOffset': 1, 'componentType': 5123, 'count': 1, 'type': 'SCALAR'}]
read_accessor(bad, parsed_bin, 0)
check('misaligned accessor rejected', 'accepted', 'rejected')
except ValueError:
check('misaligned accessor rejected', 'rejected', 'rejected')
try:
read_glb(glb[:len(glb) - 4])
check('truncated chunk rejected', 'accepted', 'rejected')
except ValueError:
check('truncated chunk rejected', 'rejected', 'rejected')
# ---------------------------------------------------------------- 2. FK
def mat_mul(a, b):
return [sum(a[r * 4 + k] * b[k * 4 + c] for k in range(4)) for r in range(4) for c in range(4)]
def identity():
return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
def translate(t):
m = identity()
m[3], m[7], m[11] = t
return m
def euler(x, y, z):
rx, ry, rz = (math.radians(v) for v in (x, y, z))
mx = [1, 0, 0, 0, 0, math.cos(rx), -math.sin(rx), 0, 0, math.sin(rx), math.cos(rx), 0, 0, 0, 0, 1]
my = [math.cos(ry), 0, math.sin(ry), 0, 0, 1, 0, 0, -math.sin(ry), 0, math.cos(ry), 0, 0, 0, 0, 1]
mz = [math.cos(rz), -math.sin(rz), 0, 0, math.sin(rz), math.cos(rz), 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
return mat_mul(mat_mul(mz, my), mx)
JOINTS = [
('pelvis', None, (0.00, 0.00, 0.48)),
('chest', 'pelvis', (0.00, 0.00, 0.16)),
('shoulder_l', 'chest', (0.08, 0.00, 0.14)),
('elbow_l', 'shoulder_l', (0.18, 0.00, 0.00)),
('wrist_l', 'elbow_l', (0.16, 0.00, 0.00)),
]
def fk(pose):
world = {}
for name, parent, offset in JOINTS:
local = mat_mul(translate(offset), euler(*pose.get(name, (0, 0, 0))))
world[name] = local if parent is None else mat_mul(world[parent], local)
return world
def origin(m):
return (m[3], m[7], m[11])
def apply(m, p):
return (m[0] * p[0] + m[1] * p[1] + m[2] * p[2] + m[3],
m[4] * p[0] + m[5] * p[1] + m[6] * p[2] + m[7],
m[8] * p[0] + m[9] * p[1] + m[10] * p[2] + m[11])
rest = fk({})
approx('rest arm hangs along +X', origin(rest['wrist_l']), (0.42, 0.00, 0.78))
bent = fk({'elbow_l': (0, 90, 0)})
approx('elbow yawed 90 deg about Y swings the bone toward -Z', origin(bent['wrist_l']), (0.26, 0.00, 0.62))
# Pose-invariant facts the skinning path depends on.
bone = math.dist(origin(bent['elbow_l']), origin(bent['wrist_l']))
check('bone length is pose-invariant', round(bone, 6), 0.16)
check('a joint rotation does not move its own origin', origin(bent['elbow_l']), origin(rest['elbow_l']))
m = bent['elbow_l']
approx('rotation block orthonormal', [round(math.sqrt(sum(m[r * 4 + c] ** 2 for c in range(3))), 6) for r in range(3)], [1.0, 1.0, 1.0])
approx('no shear, no scale', [round(m[0], 6), round(m[1], 6), round(m[2], 6)], [0.0, 0.0, 1.0])
# Skinning: a weighted vertex follows its joint.
weights = [0.7, 0.3]
joints = [rest['elbow_l'], bent['elbow_l']]
vertex = (0.10, 0.0, 0.0)
skinned = tuple(sum(weights[j] * apply(joints[j], vertex)[i] for j in range(2)) for i in range(3))
check('70/30 blend lands between the two poses', [round(v, 6) for v in skinned], [0.33, 0.0, 0.75])
# ---------------------------------------------------------------- 3. Camera
def basis(yaw_deg, pitch_deg):
y, p = math.radians(yaw_deg), math.radians(pitch_deg)
forward = (-math.cos(p) * math.sin(y), math.cos(p) * math.cos(y), -math.sin(p))
right = (math.cos(p) * math.cos(y), math.cos(p) * math.sin(y), 0.0)
up = (-math.sin(p) * math.sin(y), math.sin(p) * math.cos(y), math.cos(p))
return forward, right, up
def project(p, target, yaw, pitch, zoom, w, h):
forward, right, up = basis(yaw, pitch)
d = (p[0] - target[0], p[1] - target[1], p[2] - target[2])
x = right[0] * d[0] + right[1] * d[1] + right[2] * d[2]
y = up[0] * d[0] + up[1] * d[1] + up[2] * d[2]
z = forward[0] * d[0] + forward[1] * d[1] + forward[2] * d[2]
return (x * 2 * zoom / w, y * 2 * zoom / h, z), (w / 2 + x * zoom, h / 2 - y * zoom)
f, r, u = basis(0, 0)
approx('yaw 0 pitch 0 basis matches Umamo axes (forward +Y, right +X, up +Z)',
list(f) + list(r) + list(u), [0, 1, 0, 1, 0, 0, 0, 0, 1])
ndc, px = project((1, 0, 0), (0, 0, 0), 0, 0, 1, 400, 400)
approx('one world unit right at zoom 1 -> one pixel right', px, (201.0, 200.0))
approx('and NDC matches ViewportCamera.worldToNdc', ndc[:2], (2 / 400, 0.0))
ndc, px = project((0, 0, 1), (0, 0, 0), 0, 0, 1, 400, 400)
approx('one world unit up -> one pixel UP (screen y measures down)', px, (200.0, 199.0))
ndc, px = project((0, 1, 0), (0, 0, 0), 90, 0, 1, 400, 400)
approx('yaw 90: the depth axis becomes screen right', px, (201.0, 200.0))
ndc, px = project((0, 0, 1), (0, 0, 0), 0, 90, 1, 400, 400)
approx('pitch 90 (looking straight down): the up axis projects to nothing', px, (200.0, 200.0))
ndc, _ = project((0, 5, 0), (0, 0, 0), 0, 0, 1, 400, 400)
check('depth increases away from the camera', ndc[2], 5.0)
ndc, _ = project((0, -5, 0), (0, 0, 0), 0, 0, 1, 400, 400)
check('a point in front of the camera has negative depth', ndc[2], -5.0)
f, r, u = basis(37, 21)
approx('basis stays orthonormal at yaw 37 pitch 21',
[round(f[0] * r[0] + f[1] * r[1] + f[2] * r[2], 9),
round(f[0] * u[0] + f[1] * u[1] + f[2] * u[2], 9),
round(r[0] * u[0] + r[1] * u[1] + r[2] * u[2], 9)], [0.0, 0.0, 0.0])
# Real degeneracy: at pitch == +/-90 the camera looks along the world up axis, so the
# screen-right axis is undefined. The camera must clamp pitch to the open interval and
# the UI must not allow a drag that reaches it.
f, r, u = basis(0, 90)
check('pitch 90 collapses the right axis (must be clamped)', round(math.sqrt(sum(v * v for v in r)), 9), 0.0)
f, r, u = basis(0, 89.9)
approx('pitch 89.9 still gives a usable right axis', [round(v, 6) for v in r], (0.001745, 0.0, 0.0))
print()
if FAILURES:
print(f'{len(FAILURES)} FAILURES')
for name, got, want in FAILURES:
print(f' {name}: got {got} want {want}')
raise SystemExit(1)
print('all checks pass')
# ---------------------------------------------------------------- 4. Matrix form
def ortho_matrix(target, yaw, pitch, zoom, w, h, near, far):
forward, right, up = basis(yaw, pitch)
sx, sy = 2 * zoom / w, 2 * zoom / h
dz = 1.0 / (far - near)
def dot(a, b):
return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
m = [0.0] * 16
for r, axis, scale in ((0, right, sx), (1, up, sy), (2, forward, dz)):
for c in range(3):
m[r * 4 + c] = axis[c] * scale
m[r * 4 + 3] = -dot(axis, target) * scale
m[15] = 1.0
m[2 * 4 + 3] -= near * dz
return m
def apply_matrix(m, p):
return tuple(m[r * 4 + 0] * p[0] + m[r * 4 + 1] * p[1] + m[r * 4 + 2] * p[2] + m[r * 4 + 3] for r in range(3))
for point, yaw, pitch in (((1, 0, 0), 0, 0), ((0, 0, 1), 0, 0), ((0, 1, 0), 90, 0), ((0.3, 0.4, 0.5), 37, 21)):
direct, _ = project(point, (0, 0, 0), yaw, pitch, 1, 400, 400)
m = ortho_matrix((0, 0, 0), yaw, pitch, 1, 400, 400, -10.0, 10.0)
via_matrix = apply_matrix(m, point)
depth_ok = abs(via_matrix[2] - (direct[2] + 10) / 20) < 1e-9
xy_ok = all(abs(a - b) < 1e-9 for a, b in zip(via_matrix[:2], direct[:2]))
check(f'matrix form agrees with the direct form at yaw {yaw} pitch {pitch}', (round(xy_ok), round(depth_ok)), (1, 1))
check('depth maps near to 0 and far to 1', [round(v, 6) for v in apply_matrix(ortho_matrix((0, 0, 0), 0, 0, 1, 400, 400, -10.0, 10.0), (0, -10, 0))], [0.0, 0.0, 0.0])