The depth row maps the slab to the full clip range, not half of it, so the CPU sort and the GPU depth test agree on which fragment is nearer. The screen-right axis is the unit horizontal: built as forward x worldUp it carries a factor of cos(pitch) and compresses screen X as the camera tilts, so the pitch clamp is the edge-on guard rather than a fix for a zero vector. MAT4 is an accessor type and count is the number of elements, not floats, which is the shape a skin's inverse bind matrices actually have. node.matrix is column-major while Mat4 is row-major. A skin's joints must be resolved by node index, because CesiumMan.glb keeps its skeleton outside the scene root.
331 lines
13 KiB
Python
331 lines
13 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))
|
|
# The unit horizontal, not forward x worldUp. That cross product carries a factor of cos(pitch)
|
|
# and shrinks to a zero vector at pitch 90, which would scale screen X by cos(pitch) as the camera
|
|
# tilts - a silent compression, not an error.
|
|
right = (math.cos(y), 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])
|
|
|
|
# At pitch == +/-90 the camera looks along the world up axis, which is the drawing plane's normal,
|
|
# so the puppet is seen edge-on and the reference layer collapses to a line. Nothing reports it -
|
|
# the projection still returns a number - so the clamp belongs in the model, not in the drag handler.
|
|
# The right axis is the unit horizontal, so it does not collapse here; building it as
|
|
# forward x worldUp would have made it cos(pitch), exactly zero at 90.
|
|
f, r, u = basis(0, 90)
|
|
check('right stays unit length at pitch 90', round(math.sqrt(sum(v * v for v in r)), 9), 1.0)
|
|
check('pitch 90 puts the view along the world up axis', [round(v, 9) for v in f], [0.0, 0.0, -1.0])
|
|
check('and the drawing plane is edge-on: up projects to nothing', round(u[2], 9), 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
|
|
# near and far are distances from the target, so the slab runs from -near (toward the viewer) to
|
|
# +far. The depth row maps that slab to the full clip range [-1, 1]; mapping it to [0, 1] would
|
|
# throw away half the precision for nothing.
|
|
dz = 2.0 / (near + far)
|
|
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[2 * 4 + 3] += near * dz - 1.0
|
|
m[15] = 1.0
|
|
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))
|
|
|
|
|
|
def window_depth(clip_z):
|
|
return (clip_z + 1.0) / 2.0
|
|
|
|
|
|
NEAR, FAR = 10.0, 30.0
|
|
|
|
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, NEAR, FAR)
|
|
via_matrix = apply_matrix(m, point)
|
|
depth_ok = abs(window_depth(via_matrix[2]) - (direct[2] + NEAR) / (NEAR + FAR)) < 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('the near end of the slab maps to window depth 0', round(window_depth(apply_matrix(ortho_matrix((0, 0, 0), 0, 0, 1, 400, 400, NEAR, FAR), (0, -NEAR, 0))[2]), 6), 0.0)
|
|
check('the far end of the slab maps to window depth 1', round(window_depth(apply_matrix(ortho_matrix((0, 0, 0), 0, 0, 1, 400, 400, NEAR, FAR), (0, FAR, 0))[2]), 6), 1.0)
|
|
|
|
# Applying the columns instead of the rows is the transpose. It is invisible at zero angles, where the
|
|
# matrix is diagonal, so the check has to run at a rotated camera.
|
|
m = ortho_matrix((0, 0, 0), 37, 21, 1, 400, 400, NEAR, FAR)
|
|
check('the matrix is applied by rows, not columns', round(m[1], 9) != round(m[4], 9), True)
|