cozyclay 1.9.0 → 2.0.0

package/tools/morphgs/assets/gen_truth.py

@@ -0,0 +1,39 @@
+# Ground truth from MorphGS's own Animation.step: writes rot_params.npy + pred_joints.npy exactly like src/render.py:606-618.
+# usage: python gen_truth.py <MorphGS-root> <mesh.obj> <rig.txt> <outdir>
+import sys, os
+morphgs_root, mesh_path, rig_path, out = sys.argv[1:5]
+sys.path.insert(0, os.path.join(morphgs_root, "src"))
+import numpy as np, torch, trimesh
+from model.RigModel import Rig
+from model.AnimationField import Animation, get_embedder
+
+os.makedirs(out, exist_ok=True)
+mesh = trimesh.load_mesh(mesh_path, process=False, maintain_order=True)
+rig = Rig(mesh, rig_path, smooth_w=0, device="cpu", skinning_method="lbs")
+N = rig.joints_name; J = len(N); ix = N.index
+# Emulate MorphGS morphology (ParametricModel.get_joints_pos): legs +8%, arms -5%, same bone directions.
+scale = {n: 1.08 for n in N if "Leg" in n or "Foot" in n or "Toe" in n}
+scale.update({n: 0.95 for n in N if "Arm" in n or "Hand" in n})
+joints = rig.joints_pos.clone()
+for p, c in rig.bones:  # bones are BFS-ordered from the root, parents first
+    joints[c] = joints[p] + (rig.joints_pos[c] - rig.joints_pos[p]) * scale.get(N[c], 1.0)
+# Animation.__init__ hard-codes a CUDA deform net (AnimationField.py:83); step() with explicit rot_params never uses it.
+anim = Animation.__new__(Animation)
+anim.skinning_method, anim.embed_time_fn, anim.joint_num = "lbs", get_embedder(6, 1)[0], J
+fixed = rig.fixed_joint_indices
+torch.manual_seed(0)
+frames = []
+f1 = torch.zeros(J, 3)  # the lead's spec
+f1[ix("LeftForeArm")] = torch.tensor([0, 0, np.pi / 2]); f1[ix("RightLeg")] = torch.tensor([np.pi / 3, 0, 0])
+f1[ix("Hips")] = torch.tensor([0, np.pi / 6, 0])
+frames += [(torch.zeros(J, 3), torch.zeros(3)), (f1, torch.tensor([0.3, 0.0, 0.2]))]
+for _ in range(4):  # random full-body poses, every joint (fixed ones included -- step() must zero them)
+    frames.append((torch.randn(J, 3) * 0.5, torch.randn(3) * 0.3))
+rps, pj = [], []
+for i, (rp, gt) in enumerate(frames):
+    d = anim.step(rig.vertices, joints, rig.skinning_weights, rig, torch.tensor([i / len(frames)]),
+                  rot_params=rp.clone(), global_translation=gt, fixed_joints=fixed)
+    rps.append(d["rot_params"].numpy()); pj.append(d["joints_warped"].numpy())
+np.save(f"{out}/rot_params.npy", np.stack(rps).astype(np.float32))
+np.save(f"{out}/pred_joints.npy", np.stack(pj).astype(np.float32))
+print(f"frames={len(frames)} J={J} fixed={[N[i] for i in fixed]} -> {out}")

package/tools/morphgs/assets/mesh_ori_rig.txt

@@ -0,0 +1,27 @@
+Hips -0.000000 1.042749 0.015543 -1
+Spine -0.000000 1.144565 0.016858 Hips
+Spine1 -0.000000 1.243504 0.002151 Spine
+Spine2 0.000000 1.335712 -0.011555 Spine1
+Neck 0.000000 1.503116 -0.032045 Spine2
+Head 0.000000 1.599295 -0.015195 Neck
+HeadTop_End 0.000000 1.819668 0.059816 Head
+RightShoulder -0.045700 1.445861 -0.033164 Spine2
+RightArm -0.151628 1.440613 -0.055485 RightShoulder
+RightForeArm -0.430043 1.440613 -0.055485 RightArm
+RightHand -0.713332 1.440613 -0.055485 RightForeArm
+RightHandEnd -0.808657 1.440613 -0.055485 RightHand
+LeftShoulder 0.045705 1.445859 -0.033164 Spine2
+LeftArm 0.151628 1.440613 -0.055485 LeftShoulder
+LeftForeArm 0.430043 1.440613 -0.055485 LeftArm
+LeftHand 0.713332 1.440612 -0.055484 LeftForeArm
+LeftHandEnd 0.808666 1.440612 -0.055484 LeftHand
+RightUpLeg -0.082078 0.975232 -0.000452 Hips
+RightLeg -0.082078 0.531531 0.003007 RightUpLeg
+RightFoot -0.082078 0.087294 -0.027429 RightLeg
+RightToeBase -0.082078 0.000007 0.079677 RightFoot
+RightToe_End -0.082079 0.000001 0.172458 RightToeBase
+LeftUpLeg 0.082078 0.975232 -0.000452 Hips
+LeftLeg 0.082078 0.531531 0.003017 LeftUpLeg
+LeftFoot 0.082077 0.087295 -0.027427 LeftLeg
+LeftToeBase 0.082077 0.000008 0.079678 LeftFoot
+LeftToe_End 0.082077 0.000001 0.172460 LeftToeBase

package/tools/morphgs/assets/playback-check.mjs

@@ -0,0 +1,30 @@
+// Real-surface check: CozyClay's own decodeMotionNpz + applyMotionFrame (src/ardy/playback.js) drive the x-bot FBX loaded with
+// three FBXLoader; compare each driven bone's world position with MorphGS joints_warped. usage: node playback-check.mjs <take.npz> <pred_joints.npy> <rig.txt>
+import { readFileSync } from "node:fs";
+import * as THREE from "three";
+import { FBXLoader } from "three/examples/jsm/loaders/FBXLoader.js";
+globalThis.window ??= { innerWidth: 1920, innerHeight: 1080, URL };
+const COZY = process.env.COZYCLAY ?? `${process.env.HOME}/CozyClay`;
+const { decodeMotionNpz } = await import(`${COZY}/src/ardy/npz.js`);
+const { applyMotionFrame } = await import(`${COZY}/src/ardy/playback.js`);
+const [npzPath, pjPath, rigPath] = process.argv.slice(2);
+const motion = await decodeMotionNpz(new Uint8Array(readFileSync(npzPath)));
+const b = readFileSync(pjPath), hl = b.readUInt16LE(8), pj = new Float32Array(b.buffer.slice(b.byteOffset + 10 + hl, b.byteOffset + b.length));
+const names = readFileSync(rigPath, "utf8").split("\n").map((l) => l.trim().split(/\s+/)).filter((t) => t.length === 5 && t[0] !== "fixed_joint").map((t) => t[0]);
+const J = names.length, X = (f, n) => [0, 1, 2].map((a) => pj[(f * J + names.indexOf(n)) * 3 + a] * 100); // cm, x-bot frame
+const fbx = readFileSync(`${COZY}/public/models/x-bot-tpose.fbx`);
+const rig = new FBXLoader().parse(fbx.buffer.slice(fbx.byteOffset, fbx.byteOffset + fbx.byteLength), "");
+rig.updateMatrixWorld(true);
+const bone = (n) => { let hit = null; rig.traverse((o) => { if (!hit && o.isBone && o.name === `mixamorig${n}`) hit = o; }); return hit; };
+const CHECK = ["Hips", "Spine", "Spine1", "Spine2", "Neck", "Head", "HeadTop_End", ...["Left", "Right"].flatMap((s) =>
+	["Shoulder", "Arm", "ForeArm", "Hand", "HandMiddle1", "UpLeg", "Leg", "Foot", "ToeBase", "Toe_End"].map((b) => s + b))];
+const err = Object.fromEntries(CHECK.map((n) => [n, 0])); let off = null;
+for (let f = 0; f < motion.frames; f++) {
+	applyMotionFrame(rig, motion, f);
+	const W = (n) => new THREE.Vector3().setFromMatrixPosition(bone(n).matrixWorld).toArray();
+	if (f === 0) off = W("Hips").map((v, a) => (a === 1 ? 0 : v - X(0, "Hips")[a])); // playback anchors frame-0 root XZ at the origin
+	for (const n of CHECK) { const x = X(f, n.replace("HandMiddle1", "HandEnd")), w = W(n);
+		err[n] = Math.max(err[n], Math.hypot(...w.map((v, a) => v - off[a] - x[a]))); }
+}
+for (const n of CHECK) console.log(`${n.padEnd(18)} ${err[n].toFixed(3).padStart(8)} cm`);
+console.log(`frames=${motion.frames} boneScale=${motion.boneScale ? "yes" : "no"} MAX=${Math.max(...Object.values(err)).toFixed(3)} cm`);

package/tools/morphgs/demo-gate.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Run the cached MorphGS tennis→Ninja demo and require motion render outputs.
+set -euo pipefail
+MORPHGS_ROOT="${MORPHGS_ROOT:-/data2/${USER:?USER must be set}/MorphGS}"
+DEMO_ID="${MORPHGS_DEMO_ID:-1oMkA02aJYhoBSNPZX9tMPknvVvX50i-z}"
+LOG_DIR="${MORPHGS_LOG_DIR:-$MORPHGS_ROOT/logs}"
+mkdir -p "$LOG_DIR"
+cd "$MORPHGS_ROOT"
+
+if [[ "${MORPHGS_SKIP_DOWNLOAD:-0}" != 1 ]]; then
+  uv run --with gdown python -m gdown "$DEMO_ID" 2>&1 | tee "$LOG_DIR/demo-download.log"
+fi
+# gdown leaves the archive intact; MorphGS expects demo/processed_videos and demo/characters.
+[[ -d demo/processed_videos/tennis ]] || unzip -q -o demo.zip
+VENV_DIR="${MORPHGS_VENV:-.venv}"
+[[ -x "$VENV_DIR/bin/python" ]] || VENV_DIR="venv"
+source "$VENV_DIR/bin/activate"
+export TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD="${TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD:-1}"
+python src/main.py --config demo/tennis_to_Ninja.yaml 2>&1 | tee "$LOG_DIR/demo-main.log"
+python src/render.py --config demo/tennis_to_Ninja.yaml 2>&1 | tee "$LOG_DIR/demo-render.log"
+
+OUTPUT_ROOT="${MORPHGS_OUTPUT_ROOT:-$MORPHGS_ROOT/output}"
+for artifact in "$OUTPUT_ROOT/rot_params.npy" "$OUTPUT_ROOT/pred_joints.npy"; do
+  [[ -s "$artifact" ]] || { echo "missing demo artifact: $artifact" >&2; exit 1; }
+done
+printf 'PASS MorphGS demo gate: %s\n' "$OUTPUT_ROOT"

package/tools/morphgs/fbx2morphgs.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// x-bot FBX -> MorphGS target: <out>/mesh.obj + <out>/rigging/mesh_ori_rig.txt (compact format, no skin -> heat skinning)
+// usage: node fbx2morphgs.mjs <in.fbx> <outDir> [--all-bones]
+import * as THREE from "three";
+import { FBXLoader } from "three/examples/jsm/loaders/FBXLoader.js";
+import { mergeVertices } from "three/examples/jsm/utils/BufferGeometryUtils.js";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+globalThis.window ??= { innerWidth: 1920, innerHeight: 1080, URL };
+
+const [inPath, outDir] = process.argv.slice(2);
+const allBones = process.argv.includes("--all-bones");
+const FIXED_JOINTS = ["Spine", "LeftUpLeg", "RightUpLeg", "Neck", "LeftShoulder", "RightShoulder", "LeftHandEnd", "RightHandEnd"];
+const SCALE = 0.01; // FBX is centimetres -> metres; Y-up, faces +Z already (pytorch3d look_at defaults)
+const buf = readFileSync(inPath);
+const root = new FBXLoader().parse(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength), "");
+root.updateMatrixWorld(true);
+
+// Control skeleton = skinned skeleton whose root bone hangs off a non-bone (same rule as tools/ardy/extract-rest.mjs);
+// FBXLoader also nests same-name zero-length copies of every bone, which must not reach the rig (zero-length bone -> NaN).
+const meshes = [];
+root.traverse((o) => o.isSkinnedMesh && meshes.push(o));
+const skel = meshes.find((m) => m.skeleton.bones.some((b) => !b.parent?.isBone)).skeleton;
+const bones = skel.bones.filter((b, i, a) => a.findIndex((c) => c.name === b.name) === i);
+const strip = (n) => n.replace(/^mixamorig:?/, "");
+const KEEP = new Set(["Hips", "Spine", "Spine1", "Spine2", "Neck", "Head", "HeadTop_End",
+	...["Left", "Right"].flatMap((s) => [`${s}Shoulder`, `${s}Arm`, `${s}ForeArm`, `${s}Hand`, `${s}HandMiddle1`,
+		`${s}UpLeg`, `${s}Leg`, `${s}Foot`, `${s}ToeBase`, `${s}Toe_End`])]);
+const kept = bones.filter((b) => allBones || KEEP.has(strip(b.name)));
+const keptSet = new Set(kept);
+const pos = (o) => new THREE.Vector3().setFromMatrixPosition(o.matrixWorld).multiplyScalar(SCALE);
+const lines = kept.map((b) => {
+	let p = b.parent;
+	while (p?.isBone && !keptSet.has(p)) p = p.parent; // skip dropped joints (fingers) up to nearest kept ancestor
+	const name = allBones ? strip(b.name) : strip(b.name).replace(/HandMiddle1$/, "HandEnd");
+	const v = pos(b);
+	return { b, name, line: `${name} ${v.x.toFixed(6)} ${v.y.toFixed(6)} ${v.z.toFixed(6)} ` };
+});
+const nameOf = new Map(lines.map((l) => [l.b, l.name]));
+const rig = lines.map(({ b, line }) => {
+	let p = b.parent;
+	while (p?.isBone && !keptSet.has(p)) p = p.parent;
+	return line + (p?.isBone ? nameOf.get(p) : "-1");
+});
+
+// Mesh: skin every vertex at the loaded (T-)pose into world space, weld the triangle soup FBXLoader emits.
+const soup = [];
+const v = new THREE.Vector3();
+for (const m of meshes) {
+	const g = m.geometry;
+	const idx = g.index ? g.index.array : null;
+	const n = idx ? idx.length : g.attributes.position.count;
+	for (let k = 0; k < n; k++) {
+		m.getVertexPosition(idx ? idx[k] : k, v);
+		v.applyMatrix4(m.matrixWorld).multiplyScalar(SCALE);
+		soup.push(v.x, v.y, v.z);
+	}
+}
+const geo = new THREE.BufferGeometry();
+geo.setAttribute("position", new THREE.Float32BufferAttribute(soup, 3));
+const welded = mergeVertices(geo, 1e-5);
+const P = welded.attributes.position.array, I = welded.index.array;
+let obj = "";
+for (let k = 0; k < P.length; k += 3) obj += `v ${P[k].toFixed(6)} ${P[k + 1].toFixed(6)} ${P[k + 2].toFixed(6)}\n`;
+for (let k = 0; k < I.length; k += 3) obj += `f ${I[k] + 1} ${I[k + 1] + 1} ${I[k + 2] + 1}\n`;
+mkdirSync(`${outDir}/rigging`, { recursive: true });
+writeFileSync(`${outDir}/mesh.obj`, obj);
+writeFileSync(`${outDir}/rigging/mesh_ori_rig.txt`, rig.join("\n") + `\nfixed_joint ${FIXED_JOINTS.join(" ")}\n`);
+console.log(`meshes=${meshes.map((m) => m.name)} verts=${P.length / 3} faces=${I.length / 3} joints=${rig.length}`);

package/tools/morphgs/morphgs-to-cskel27.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// MorphGS render outputs (rot_params.npy [T,J,3], pred_joints.npy [T,J,3]; src/render.py:606-618) + x-bot rig txt -> cskel27 take npz.
+// usage: node morphgs-to-cskel27.mjs <mesh_ori_rig.txt> <rot_params.npy> <pred_joints.npy> <out.npz> [--fps 30] [--check]
+import { readFileSync } from "node:fs";
+const COZY = process.env.COZYCLAY ?? new URL("../..", import.meta.url).pathname;
+const { CSKEL27_JOINTS: CJ, CSKEL27_PARENTS: CP } = await import(`${COZY}/src/ardy/cskel27.js`);
+const { CSKEL27_NEUTRAL: NEU } = await import(`${COZY}/src/ardy/cskel27-neutral.js`);
+const { deriveBoneOffsets, forwardKinematics, matMul, matTranspose } = await import(`${COZY}/src/ardy/convert.js`);
+const { canonicalCskel27Reference } = await import(`${COZY}/src/ardy/to-cskel27.js`);
+const { motionArraysToNpzMembers, writeNpz } = await import(`${COZY}/tools/ardy/npz.mjs`);
+
+const [rigPath, rotPath, jointsPath, outPath] = process.argv.slice(2);
+const fps = Number(process.argv[process.argv.indexOf("--fps") + 1]) || 30;
+const npy = (p) => { // float32 little-endian C-order .npy
+	const b = readFileSync(p), hl = b.readUInt16LE(8), h = b.toString("latin1", 10, 10 + hl);
+	if (!h.includes("'<f4'") || h.includes("True")) throw new Error(`${p}: need <f4 C-order`);
+	return { shape: h.match(/\(([^)]*)\)/)[1].split(",").filter(Boolean).map(Number), d: new Float32Array(b.buffer.slice(b.byteOffset + 10 + hl, b.byteOffset + b.length)) };
+};
+// Rig: compact "<name> x y z <parent|-1>" (file order == MorphGS joint index, root first) + fixed_joint lines.
+const names = [], parent = [], rest = [], fixed = new Set();
+for (const t of readFileSync(rigPath, "utf8").split("\n").map((l) => l.trim().split(/\s+/))) {
+	if (t[0] === "fixed_joint") t.slice(1).forEach((n) => fixed.add(n));
+	else if (t.length === 5) { names.push(t[0]); rest.push(t.slice(1, 4).map(Number)); parent.push(t[4] === "-1" ? -1 : names.indexOf(t[4])); }
+}
+const J = names.length, ix = (n) => names.indexOf(n), kids = names.map((_, j) => parent.flatMap((p, k) => (p === j ? [k] : [])));
+// cskel27 joint -> x-bot bone it drives: playback.js SKINNING_MAP / cskel27.js (Mixamo Spine,Spine1,Spine2 -> Spine1,Spine2,Spine3).
+const SRC = { Hips: "Hips", Spine1: "Spine", Spine2: "Spine1", Spine3: "Spine2", Neck: "Neck", Head: "Head" };
+for (const s of ["Left", "Right"]) for (const b of ["Shoulder", "Arm", "ForeArm", "Hand", "UpLeg", "Leg", "Foot", "ToeBase"]) SRC[s + b] = s + b;
+const ARM = /Shoulder|Arm|Hand/; // playback: arm chain = bind translation + rotation; wrist undriven; rest positional
+for (const x of Object.values(SRC)) {
+	const free = kids[ix(x)].filter((k) => !fixed.has(names[k]));
+	if (kids[ix(x)].length > 1 && free.length && !process.env.ALLOW_FREE) throw new Error(`${x} has ${kids[ix(x)].length} children; add fixed_joint ${free.map((k) => names[k]).join(" ")}`);
+}
+const I3 = [[1, 0, 0], [0, 1, 0], [0, 0, 1]], mv = (m, v) => m.map((r) => r[0] * v[0] + r[1] * v[1] + r[2] * v[2]);
+const rod = (v) => {
+	const a = Math.hypot(...v); if (a < 1e-12) return I3;
+	const [x, y, z] = v.map((u) => u / a), s = Math.sin(a), c = Math.cos(a), t = 1 - c;
+	return [[t * x * x + c, t * x * y - s * z, t * x * z + s * y], [t * x * y + s * z, t * y * y + c, t * y * z - s * x], [t * x * z - s * y, t * y * z + s * x, t * z * z + c]];
+};
+const rot = npy(rotPath), pj = npy(jointsPath), T = rot.shape[0];
+if (rot.shape[1] !== J || pj.shape[1] !== J) throw new Error(`rig has ${J} joints, npy has ${rot.shape[1]}/${pj.shape[1]}`);
+const P = (f, j) => [0, 1, 2].map((a) => pj.d[(f * J + j) * 3 + a]);
+const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+const len = (a, b) => dist(P(0, ix(a)), P(0, ix(b))); // MorphGS (morphed) bone length; rigid motion keeps it
+// Playback constants for the x-bot (playback.js prepOf): bind = FBX world cm; s = leg height / 0.9544128.
+const bind = (x) => rest[ix(x)].map((v) => v * 100), MINY = -0.9544128;
+const s = (bind("Hips")[1] - Math.min(...Object.values(SRC).filter((x) => !/Hand$/.test(x)).map((x) => bind(x)[1]))) / -MINY;
+const nf = (c) => { const n = NEU[CJ.indexOf(c)]; return [n[0], n[1] - MINY, n[2]]; };
+// bone_scale only on the arm chain (playback boneStretch): girdle joints take morphed/bind, ForeArm/Hand morphed/(s*canonical).
+const boneScale = new Float32Array(27).fill(1);
+for (const c of CJ) {
+	if (!ARM.test(c) || !SRC[c] || /Thumb|End/.test(c)) continue;
+	const x = SRC[c], px = names[parent[ix(x)]], i = CJ.indexOf(c), m = len(x, px) * 100;
+	boneScale[i] = /Shoulder|^(Left|Right)Arm$/.test(c) ? m / dist(bind(x), bind(px)) : m / (s * dist(NEU[i], NEU[CP[i]]));
+}
+const canon = deriveBoneOffsets(canonicalCskel27Reference().posed_joints, canonicalCskel27Reference().local_rot_mats);
+const rotMats = new Float32Array(T * 243), rootPos = new Float32Array(T * 3), posed = new Float32Array(T * 81), frames = [];
+for (let f = 0; f < T; f++) {
+	const Gm = []; // MorphGS parent-pivot: R_j swings segment parent(j)->j; its world rotation is the chain product
+	for (let j = 0; j < J; j++) {
+		const R = fixed.has(names[j]) ? I3 : rod([0, 1, 2].map((a) => rot.d[(f * J + j) * 3 + a]));
+		Gm[j] = parent[j] < 0 ? R : matMul(Gm[parent[j]], R);
+	}
+	const G = [], pos = [];
+	CJ.forEach((c, i) => { G[i] = SRC[c] ? Gm[kids[ix(SRC[c])][0]] : G[CP[i]]; }); // outgoing segment of the driven bone
+	const L = CJ.map((_, i) => (CP[i] === null ? G[i] : matMul(matTranspose(G[CP[i]]), G[i])));
+	CJ.forEach((c, i) => { // posed_joints = inverse of playback's positional skinning; unskinned joints hang off their parent
+		if (SRC[c] && !ARM.test(c)) { const b = bind(SRC[c]), g = mv(G[i], b.map((v, a) => v - s * nf(c)[a])); pos[i] = P(f, ix(SRC[c])).map((v, a) => (v * 100 - g[a]) / s); }
+		else { const o = mv(G[CP[i]], canon[i]); pos[i] = pos[CP[i]].map((v, a) => v + o[a]); }
+	});
+	L.forEach((m, i) => rotMats.set(m.flat(), (f * 27 + i) * 9));
+	pos.forEach((p, i) => posed.set(p, (f * 27 + i) * 3));
+	rootPos.set(pos[0], f * 3);
+	frames.push({ G, L, pos });
+}
+writeNpz(outPath, motionArraysToNpzMembers({ frames: T, fps, rotMats, rootPos, posedJoints: posed, boneScale }));
+console.log(`wrote ${outPath}: ${T} frames, fixed=[${[...fixed]}], s=${s.toFixed(3)}`);
+
+// ---- --check: compare against MorphGS joints_warped (truth), per mapped x-bot joint, max over frames, in cm ----
+if (process.argv.includes("--check")) {
+	// (a) CozyClay convert.js forwardKinematics over the exported local_rot_mats with the x-bot's own morphed offsets
+	const xr = CJ.map((c) => (SRC[c] ? rest[ix(SRC[c])] : null));
+	xr[CJ.indexOf("Spine")] = rest[0].map((v, a) => (v + rest[ix("Spine")][a]) / 2);
+	CJ.forEach((c, i) => { if (!xr[i]) xr[i] = c.endsWith("HandEnd") ? rest[ix(c)] : xr[CP[i]]; });
+	const xOff = xr.map((p, i) => { if (CP[i] === null) return [0, 0, 0]; const d = p.map((v, a) => v - xr[CP[i]][a]), n = Math.hypot(...d);
+		const x = SRC[CJ[i]] ?? (CJ[i].endsWith("HandEnd") ? CJ[i] : null), px = SRC[CJ[CP[i]]];
+		const l = CJ[i] === "Spine" || CJ[i] === "Spine1" ? len("Spine", "Hips") / 2 : x && px ? len(x, px) : n; return n > 0 ? d.map((v) => (v / n) * l) : d; });
+	// (b) previous iteration: canonical cskel27 FK (what posed_joints would be if written as plain FK)
+	// (c) playback.js simulated on the x-bot with the written npz arrays (positional skinning + arm chain), /100 -> m
+	const stretch = (i) => /Shoulder|^(Left|Right)Arm$/.test(CJ[i]) ? boneScale[i] : boneScale[i] * s * dist(NEU[i], NEU[CP[i]]) / dist(bind(SRC[CJ[i]]), bind(names[parent[ix(SRC[CJ[i]])]]));
+	const rows = Object.entries(SRC).map(([c, x]) => ({ c, x, i: CJ.indexOf(c), a: 0, b: 0, cc: 0 }));
+	frames.forEach(({ G, L, pos }, f) => {
+		const fa = forwardKinematics(L, xOff, P(f, 0)), fb = forwardKinematics(L, canon, P(f, 0)), W = [];
+		CJ.forEach((c, i) => {
+			if (!SRC[c]) return;
+			if (!ARM.test(c)) { const g = mv(G[i], bind(SRC[c]).map((v, a) => v - s * nf(c)[a])); W[i] = pos[i].map((v, a) => (s * v + g[a]) / 100); return; }
+			const pi = /Shoulder/.test(c) ? CJ.indexOf("Spine3") : CP[i], o = mv(G[pi], bind(SRC[c]).map((v, a) => (v - bind(SRC[CJ[pi]])[a]) * stretch(i)));
+			W[i] = W[pi].map((v, a) => v + o[a] / 100);
+		});
+		for (const r of rows) { const t = P(f, ix(r.x)); r.a = Math.max(r.a, dist(fa[r.i], t) * 100); r.b = Math.max(r.b, dist(fb[r.i], t) * 100); r.cc = Math.max(r.cc, dist(W[r.i], t) * 100); }
+	});
+	console.log("cskel27 <- x-bot        (a)FK x-bot offs  (b)canonical FK  (c)playback sim   bone_scale");
+	for (const r of rows) console.log(`${r.c.padEnd(14)}<- ${r.x.padEnd(14)} ${r.a.toFixed(4).padStart(8)} ${r.b.toFixed(3).padStart(15)} ${r.cc.toFixed(4).padStart(15)} ${boneScale[r.i].toFixed(3).padStart(10)}`);
+	for (const k of ["a", "b", "cc"]) console.log(`MAX ${k} = ${Math.max(...rows.map((r) => r[k])).toFixed(4)} cm`);
+}

package/tools/morphgs/patches/preprocess_src-none-mode.patch

@@ -0,0 +1,76 @@
+--- a/src/preprocess/preprocess_src.py	2026-09-23 18:54:26
++++ b/src/preprocess/preprocess_src.py	2026-09-23 22:00:59
+@@ -18,14 +18,6 @@
+
+ # Add generative-models to path
+ sys.path.append(os.path.join(os.path.dirname(__file__), "../extlibs/generative-models"))
+-
+-from scripts.demo.sv4d_helpers import (
+-    load_model,
+-    preprocess_video,
+-    read_video,
+-    run_img2vid,
+-)
+-from sgm.modules.encoders.modules import VideoPredictionEmbedderWithEncoder
+
+ IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".bmp", ".webp", ".PNG", ".JPG", ".JPEG", ".BMP", ".WEBP"}
+ VIDEO_EXTS = {".mp4", ".gif", ".mov", ".avi", ".mkv", ".webm", ".MP4", ".GIF", ".MOV", ".AVI", ".MKV", ".WEBM"}
+@@ -137,6 +129,8 @@
+     verbose=False,
+     remove_bg=False,
+ ):
++    from scripts.demo.sv4d_helpers import load_model, preprocess_video, read_video, run_img2vid
++    from sgm.modules.encoders.modules import VideoPredictionEmbedderWithEncoder
+     sp4d_model = "sp4d"
+     config = sp4d_configs[sp4d_model]
+     T = config["T"]
+@@ -319,6 +313,8 @@
+     Simple script to generate multiple novel-view videos conditioned on a video `input_path` or multiple frames, one for each
+     image file in folder `input_path`. If you run out of VRAM, try decreasing `decoding_t` and `encoding_t`.
+     """
++    from scripts.demo.sv4d_helpers import load_model, preprocess_video, read_video, run_img2vid
++    from sgm.modules.encoders.modules import VideoPredictionEmbedderWithEncoder
+     # Set model config
+     assert os.path.basename(model_path) in [
+         "sv4d2.safetensors",
+@@ -582,6 +578,7 @@
+     "sv4d": [0, 60, 120, 180, 240],
+     "sp4d": [0, 60, 120, 180, 240],
+     "sv4d2_8views": [0, 30, 75, 120, 165, 210, 255, 300, 330],
++    "none": [0],
+ }
+
+
+@@ -630,6 +627,23 @@
+             yield
+         finally:
+             os.chdir(prev_cwd)
++    if mode == "none":
++        # MorphGS can train from the source view alone. Keep the same square,
++        # white-background contract as generated views and avoid importing or
++        # loading the SV4D checkpoints on CPU-only preprocessing nodes.
++        color_dir = os.path.join(out_dir, "view_0", "color")
++        os.makedirs(color_dir, exist_ok=True)
++        frames = _list_image_frames(src_video_path)
++        if not frames:
++            raise RuntimeError(f"no image frames found under {src_video_path}")
++        for index, name in enumerate(frames):
++            image = Image.open(os.path.join(src_video_path, name)).convert("RGB")
++            side = max(image.size)
++            canvas = Image.new("RGB", (side, side), (255, 255, 255))
++            canvas.paste(image, ((side - image.width) // 2, (side - image.height) // 2))
++            canvas.save(os.path.join(color_dir, f"{index:03d}.png"))
++        return out_dir
++
+     model_root = "src/extlibs/generative-models"
+     sparse_input_path, sparse_cleanup_dir, sparse_nf = _build_sparse_input_dir(
+         src_video_path,
+@@ -766,7 +780,7 @@
+
+     parser = argparse.ArgumentParser(description="Preprocess source data for MorphGS.")
+     parser.add_argument("src_video_path", help="Path to source frames folder / mp4 / gif.")
+-    parser.add_argument("--mode", default="sv4d", choices=["sv4d", "sp4d", "sv4d2_8views"])
++    parser.add_argument("--mode", default="sv4d", choices=["sv4d", "sp4d", "sv4d2_8views", "none"])
+     parser.add_argument("--sv4d_num_steps", type=int, default=50)
+     parser.add_argument("--sv4d_img_size", type=int, default=512)
+     parser.add_argument("--sv4d_max_frames", type=int, default=None)

package/tools/morphgs/setup-on-cluster.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Reproduce the verified MorphGS Blackwell environment on the shared cluster.
+# Allocate first (sbatch is unavailable on the full login filesystem):
+#   srun --gres=gpu:1 --cpus-per-task=8 --mem=40G --time=02:00:00 --pty bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: setup-on-cluster.sh [--dry-run]
+
+Run inside an srun allocation on mkseoul2. The default root is
+/data2/$USER/MorphGS; override MORPHGS_ROOT, DATA_ROOT, or CUDA_HOME when needed.
+Set CUDA_RUNFILE to an existing CUDA 12.8.1 runfile (or CUDA_RUNFILE_URL to
+fetch it). --dry-run prints every command without changing the cluster.
+USAGE
+}
+
+DRY_RUN=0
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "unknown argument: $arg" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+DATA_ROOT="${DATA_ROOT:-/data2/${USER:?USER must be set}}"
+MORPHGS_ROOT="${MORPHGS_ROOT:-$DATA_ROOT/MorphGS}"
+CUDA_HOME="${CUDA_HOME:-$DATA_ROOT/cuda-12.8}"
+CUDA_RUNFILE="${CUDA_RUNFILE:-$DATA_ROOT/cuda_12.8.1_*.run}"
+CUDA_RUNFILE_URL="${CUDA_RUNFILE_URL:-https://developer.download.nvidia.com/compute/cuda/12.8.1/local_installers/cuda_12.8.1_570.124.06_linux.run}"
+GEO_ROOT="${GEO_ROOT:-$DATA_ROOT/GeoAware-SC}"
+GEO_VENV="${GEO_VENV:-$DATA_ROOT/venv-geo}"
+
+run() {
+  if (( DRY_RUN )); then
+    printf '+ '
+    printf '%q ' "$@"
+    printf '\n'
+  else
+    "$@"
+  fi
+}
+
+mkdir_p() { run mkdir -p "$1"; }
+mkdir_p "$DATA_ROOT"
+
+if [[ ! -d "$MORPHGS_ROOT/.git" ]]; then
+  run git clone https://github.com/xodus777/MorphGS "$MORPHGS_ROOT"
+fi
+run git -C "$MORPHGS_ROOT" submodule update --init
+
+# GCC 13 needs these standard headers in the two CUDA extensions. Keep the
+# edits idempotent so rerunning setup never adds duplicate includes.
+if (( DRY_RUN )); then
+  echo '+ add #include <cstdint> to src/extlibs/latent-gaussian-rasterization/cuda_rasterizer/rasterizer_impl.h'
+  echo '+ add #include <cfloat> to src/extlibs/simple-knn/simple_knn.cu'
+else
+  grep -q '^#include <cstdint>$' "$MORPHGS_ROOT/src/extlibs/latent-gaussian-rasterization/cuda_rasterizer/rasterizer_impl.h" || \
+    sed -i '1i #include <cstdint>' "$MORPHGS_ROOT/src/extlibs/latent-gaussian-rasterization/cuda_rasterizer/rasterizer_impl.h"
+  grep -q '^#include <cfloat>$' "$MORPHGS_ROOT/src/extlibs/simple-knn/simple_knn.cu" || \
+    sed -i '1i #include <cfloat>' "$MORPHGS_ROOT/src/extlibs/simple-knn/simple_knn.cu"
+fi
+
+# CUDA 12.8 is required for sm_120. The pip nvcc package only supplies ptxas.
+if (( DRY_RUN )); then
+  echo "+ install CUDA runfile at $CUDA_HOME (CUDA_RUNFILE or CUDA_RUNFILE_URL)"
+else
+  shopt -s nullglob
+  runfiles=( $CUDA_RUNFILE )
+  shopt -u nullglob
+  if (( ${#runfiles[@]} == 0 )); then
+    CUDA_RUNFILE="$DATA_ROOT/cuda_12.8.1_linux.run"
+    run curl -L --fail --retry 3 -o "$CUDA_RUNFILE" "$CUDA_RUNFILE_URL"
+  else
+    CUDA_RUNFILE="${runfiles[0]}"
+  fi
+  if [[ ! -x "$CUDA_HOME/bin/nvcc" ]]; then
+    run sh "$CUDA_RUNFILE" --silent --toolkit --installpath="$CUDA_HOME"
+  fi
+fi
+export CUDA_HOME
+export PATH="$CUDA_HOME/bin:$PATH"
+# MorphGS demo caches contain trusted PyTorch3D camera pickles; PyTorch 2.11
+# otherwise defaults torch.load to weights_only=True and rejects them.
+export TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1
+
+run uv venv "$MORPHGS_ROOT/.venv" --python 3.10
+run uv pip install --python "$MORPHGS_ROOT/.venv/bin/python" torch==2.11.0 --index-url https://download.pytorch.org/whl/cu128
+run uv pip install --python "$MORPHGS_ROOT/.venv/bin/python" 'pytorch3d==0.7.9+pt2110cu128' --extra-index-url https://ImageMindAnalytics.github.io/pytorch3d-wheels/simple/
+
+REQ_TMP="${TMPDIR:-/tmp}/morphgs-requirements-${USER}.txt"
+if (( DRY_RUN )); then
+  echo "+ grep -v scikit-sparse $MORPHGS_ROOT/requirements.txt > $REQ_TMP"
+else
+  grep -v '^scikit-sparse' "$MORPHGS_ROOT/requirements.txt" > "$REQ_TMP"
+fi
+run uv pip install --python "$MORPHGS_ROOT/.venv/bin/python" -r "$REQ_TMP"
+
+export TORCH_CUDA_ARCH_LIST=12.0
+run uv pip install --python "$MORPHGS_ROOT/.venv/bin/python" --no-build-isolation -e "$MORPHGS_ROOT/src/extlibs/latent-gaussian-rasterization"
+run uv pip install --python "$MORPHGS_ROOT/.venv/bin/python" --no-build-isolation "$MORPHGS_ROOT/src/extlibs/simple-knn"
+
+# GeoAware's numpy 1.23 / Pillow 9.5 stack is intentionally isolated from the
+# training venv (numpy 2.2). Its MSDeformAttn patch targets torch 2.11 APIs.
+run uv venv "$GEO_VENV" --python 3.10
+run uv pip install --python "$GEO_VENV/bin/python" torch==2.11.0 --index-url https://download.pytorch.org/whl/cu128
+if [[ ! -d "$GEO_ROOT/.git" ]]; then run git clone https://github.com/Junyi42/GeoAware-SC "$GEO_ROOT"; fi
+run git -C "$GEO_ROOT" checkout b20fab9
+if (( DRY_RUN )); then
+  echo '+ patch GeoAware MSDeformAttn value.type() and .type().is_cuda()'
+else
+  grep -rl 'value.type()' --include='ms_deform_attn*' "$GEO_ROOT/third_party" | xargs -r sed -i \
+    -e 's/\.type()\.is_cuda()/\.is_cuda()/g' -e 's/value\.type()/value.scalar_type()/g'
+fi
+OVERRIDE="${TMPDIR:-/tmp}/geo-override-${USER}.txt"
+if (( DRY_RUN )); then echo "+ printf 'faiss-cpu>=1.7.1\\n' > $OVERRIDE"; else printf 'faiss-cpu>=1.7.1\n' > "$OVERRIDE"; fi
+run uv pip install --python "$GEO_VENV/bin/python" 'numpy==1.23.5' 'pillow==9.5.0'
+run uv pip install --python "$GEO_VENV/bin/python" --override "$OVERRIDE" --no-build-isolation -e "$GEO_ROOT"
+if (( DRY_RUN )); then
+  echo "+ ln -s $GEO_ROOT $MORPHGS_ROOT/src/extlibs/GeoAware"
+else
+  ln -sfn "$GEO_ROOT" "$MORPHGS_ROOT/src/extlibs/GeoAware"
+fi
+
+echo "MorphGS cluster setup complete: $MORPHGS_ROOT"