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.
312 lines
12 KiB
Python
312 lines
12 KiB
Python
#!/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])
|