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,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])
|
||||
Reference in New Issue
Block a user