cozyclay 2.1.0 → 3.0.0

package/tools/kimodo/setup-on-box.sh

@@ -1,339 +0,0 @@
-#!/usr/bin/env bash
-# Provision the best-supported Kimodo runtime for the host this script runs on.
-# Run directly on the host, or through setup-local.mjs (which pipes it over ssh).
-#
-# The installer is a router: it detects OS / architecture / RAM / CUDA and
-# installs one of four backends, best first:
-#
-#   kimodo-mlx        macOS arm64 with > 32 GB RAM — MLX/Metal port with the
-#                     15 GB LLM2Vec encoder resident in unified memory
-#                     (measured 0.93 s warm E2E vs 37 s kimodo.cpp Metal on an
-#                     M4 Max 64 GB; see NomaDamas/kimodo-mlx README benchmarks).
-#   kimodo.cpp-metal  macOS arm64 with <= 32 GB RAM — GGML build streaming
-#                     transformer layers from disk; residency is the wrong
-#                     trade when the encoder cannot stay in memory.
-#   nvidia-cuda       Linux with a working NVIDIA GPU — the upstream PyTorch
-#                     Kimodo stack (nv-tlabs/kimodo), fully CUDA accelerated.
-#   kimodo.cpp-cpu    any other Unix — GGML CPU build, Vulkan when available.
-#
-# Detection can be overridden for tests and dry-runs:
-#   CCLAY_KIMODO_DETECT_OS, CCLAY_KIMODO_DETECT_ARCH,
-#   CCLAY_KIMODO_DETECT_RAM_GB, CCLAY_KIMODO_DETECT_CUDA (0|1)
-# The route itself is overridden with --backend or CCLAY_KIMODO_BACKEND.
-set -euo pipefail
-
-KIMODO_DIR="${CCLAY_KIMODO_REMOTE_DIR:-$HOME/.cozyclay/kimodo}"
-VENV_DIR="${CCLAY_KIMODO_VENV_DIR:-$HOME/.cozyclay/kimodo-venv}"
-MLX_DIR="${CCLAY_KIMODO_MLX_DIR:-$HOME/.cozyclay/kimodo-mlx}"
-MLX_VENV_DIR="${CCLAY_KIMODO_MLX_VENV_DIR:-$HOME/.cozyclay/kimodo-mlx-venv}"
-CPP_DIR="${CCLAY_KIMODO_CPP_DIR:-$HOME/.cozyclay/kimodo.cpp}"
-CPP_VENV_DIR="${CCLAY_KIMODO_CPP_VENV_DIR:-$HOME/.cozyclay/kimodo-cpp-venv}"
-# kimodo.cpp ref the Metal patch in NomaDamas/kimodo-mlx is known to apply to.
-CPP_METAL_REF="${CCLAY_KIMODO_CPP_METAL_REF:-568b0253}"
-MLX_MIN_RAM_GB="${CCLAY_KIMODO_MLX_MIN_RAM_GB:-32}"
-CPP_VULKAN="${CCLAY_KIMODO_CPP_VULKAN:-auto}"
-MODEL="${CCLAY_KIMODO_MODEL:-Kimodo-SOMA-RP-v1.1}"
-BACKEND="${CCLAY_KIMODO_BACKEND:-auto}"
-DRY_RUN=0
-
-usage() {
-  cat <<'EOF'
-Usage: setup-on-box.sh [--backend NAME] [--kimodo-dir DIR] [--venv DIR]
-                       [--model NAME] [--dry-run]
-
-Detects the host and installs the best-supported Kimodo backend:
-kimodo-mlx, kimodo.cpp-metal, nvidia-cuda, or kimodo.cpp-cpu.
---backend (or CCLAY_KIMODO_BACKEND) forces a route; --dry-run prints the
-detected route and every command without changing the host.
-HF_TOKEN may be present in the environment for Hugging Face access; it is never
-printed by this script.
-EOF
-}
-log() { printf 'setup-kimodo: %s\n' "$*"; }
-die() { printf 'setup-kimodo: error: %s\n' "$*" >&2; exit 1; }
-run() {
-  if [ "$DRY_RUN" -eq 1 ]; then printf '+ '; printf '%q ' "$@"; printf '\n'; return 0; fi
-  "$@"
-}
-
-while [ "$#" -gt 0 ]; do
-  case "$1" in
-    --backend) [ "$#" -ge 2 ] || die "--backend needs a value"; BACKEND="$2"; shift 2 ;;
-    --kimodo-dir) [ "$#" -ge 2 ] || die "--kimodo-dir needs a value"; KIMODO_DIR="$2"; shift 2 ;;
-    --venv) [ "$#" -ge 2 ] || die "--venv needs a value"; VENV_DIR="$2"; shift 2 ;;
-    --model) [ "$#" -ge 2 ] || die "--model needs a value"; MODEL="$2"; shift 2 ;;
-    --dry-run) DRY_RUN=1; shift ;;
-    --help|-h) usage; exit 0 ;;
-    *) die "unknown option: $1" ;;
-  esac
-done
-
-# --- host detection -------------------------------------------------------
-
-detect_os() {
-  if [ -n "${CCLAY_KIMODO_DETECT_OS:-}" ]; then printf '%s' "$CCLAY_KIMODO_DETECT_OS"; else uname -s; fi
-}
-detect_arch() {
-  if [ -n "${CCLAY_KIMODO_DETECT_ARCH:-}" ]; then printf '%s' "$CCLAY_KIMODO_DETECT_ARCH"; else uname -m; fi
-}
-detect_ram_gb() {
-  if [ -n "${CCLAY_KIMODO_DETECT_RAM_GB:-}" ]; then printf '%s' "$CCLAY_KIMODO_DETECT_RAM_GB"; return; fi
-  local bytes=""
-  case "$(detect_os)" in
-    Darwin) bytes=$(sysctl -n hw.memsize 2>/dev/null || true) ;;
-    Linux) bytes=$(awk '/^MemTotal:/ {print $2 * 1024}' /proc/meminfo 2>/dev/null || true) ;;
-  esac
-  [ -n "$bytes" ] || { printf '0'; return; }
-  printf '%s' $(( bytes / 1073741824 ))
-}
-detect_cuda() {
-  if [ -n "${CCLAY_KIMODO_DETECT_CUDA:-}" ]; then printf '%s' "$CCLAY_KIMODO_DETECT_CUDA"; return; fi
-  if command -v nvidia-smi >/dev/null 2>&1 && nvidia-smi >/dev/null 2>&1; then printf '1'; else printf '0'; fi
-}
-
-route_backend() {
-  case "$BACKEND" in
-    auto) ;;
-    kimodo-mlx|kimodo.cpp-metal|nvidia-cuda|kimodo.cpp-cpu) printf '%s' "$BACKEND"; return ;;
-    *) die "unknown backend: $BACKEND (expected kimodo-mlx, kimodo.cpp-metal, nvidia-cuda, kimodo.cpp-cpu, or auto)" ;;
-  esac
-  local os arch ram cuda
-  os=$(detect_os); arch=$(detect_arch); ram=$(detect_ram_gb); cuda=$(detect_cuda)
-  case "$os" in
-    Darwin)
-      case "$arch" in
-        arm64)
-          # > 32 GB keeps the 15 GB encoder resident; at or below it, stream.
-          if [ "$ram" -gt "$MLX_MIN_RAM_GB" ]; then printf 'kimodo-mlx'; else printf 'kimodo.cpp-metal'; fi
-          ;;
-        *) printf 'kimodo.cpp-cpu' ;;
-      esac
-      ;;
-    Linux)
-      if [ "$cuda" = "1" ]; then printf 'nvidia-cuda'; else printf 'kimodo.cpp-cpu'; fi
-      ;;
-    *) die "unsupported OS: $os (use --backend to force a route, or run inside WSL on Windows)" ;;
-  esac
-}
-
-OS=$(detect_os); ARCH=$(detect_arch); RAM_GB=$(detect_ram_gb); CUDA=$(detect_cuda)
-BACKEND=$(route_backend)
-
-if [ "$DRY_RUN" -eq 1 ]; then
-  log "dry run; no files, packages, or models will be changed"
-fi
-log "detected: os=$OS arch=$ARCH ram=${RAM_GB}GB cuda=$CUDA"
-log "backend=$BACKEND"
-
-# --- backends ---------------------------------------------------------------
-
-install_nvidia_cuda() {
-  if [ "$DRY_RUN" -ne 1 ]; then
-    command -v git >/dev/null 2>&1 || die "git is required"
-    command -v python3 >/dev/null 2>&1 || die "python3 is required"
-    command -v nvidia-smi >/dev/null 2>&1 || die "an NVIDIA CUDA host is required (nvidia-smi not found)"
-    nvidia-smi >/dev/null 2>&1 || die "nvidia-smi cannot access the GPU"
-  fi
-
-  if [ ! -e "$KIMODO_DIR/.git" ]; then
-    mkdir -p "$(dirname "$KIMODO_DIR")"
-    run git clone --depth 1 https://github.com/nv-tlabs/kimodo.git "$KIMODO_DIR"
-  else
-    log "Kimodo checkout already exists at $KIMODO_DIR"
-  fi
-
-  if [ ! -x "$VENV_DIR/bin/python" ]; then
-    run python3 -m venv "$VENV_DIR"
-  else
-    log "Python environment already exists at $VENV_DIR"
-  fi
-
-  PY="$VENV_DIR/bin/python"
-  run "$PY" -m pip install --upgrade pip
-  run "$PY" -m pip install torch
-  run "$PY" -m pip install -e "$KIMODO_DIR" llm2vec
-
-  if [ "$DRY_RUN" -eq 1 ]; then
-    log "would prefetch model $MODEL and LLM2Vec encoder assets"
-  else
-    "$PY" - "$MODEL" <<'PY'
-import sys
-from huggingface_hub import snapshot_download
-model = sys.argv[1]
-snapshot_download(repo_id=f"nvidia/{model}")
-snapshot_download(repo_id="meta-llama/Meta-Llama-3-8B-Instruct")
-snapshot_download(repo_id="McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp")
-snapshot_download(repo_id="McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised")
-print("model and encoder assets ready")
-PY
-  fi
-
-  if [ "$VENV_DIR" != "$KIMODO_DIR/.venv" ]; then
-    if [ "$DRY_RUN" -eq 1 ]; then
-      log "would link $KIMODO_DIR/.venv -> $VENV_DIR"
-    else
-      ln -sfn "$VENV_DIR" "$KIMODO_DIR/.venv"
-    fi
-  fi
-
-  log "export CCLAY_MOTION_BACKEND=kimodo"
-  log "export CCLAY_KIMODO_HOST=<this host>"
-  log "export CCLAY_KIMODO_REPO=$KIMODO_DIR (venv available at $KIMODO_DIR/.venv)"
-  log "Kimodo model: $MODEL"
-}
-
-install_kimodo_mlx() {
-  if [ "$DRY_RUN" -ne 1 ]; then
-    command -v git >/dev/null 2>&1 || die "git is required"
-    command -v python3 >/dev/null 2>&1 || die "python3 is required"
-  fi
-
-  if [ ! -e "$MLX_DIR/.git" ]; then
-    mkdir -p "$(dirname "$MLX_DIR")"
-    run git clone --depth 1 https://github.com/NomaDamas/kimodo-mlx.git "$MLX_DIR"
-  else
-    log "kimodo-mlx checkout already exists at $MLX_DIR"
-  fi
-
-  if [ ! -x "$MLX_VENV_DIR/bin/python" ]; then
-    if command -v uv >/dev/null 2>&1; then
-      run uv venv --python 3.12 "$MLX_VENV_DIR"
-    else
-      run python3 -m venv "$MLX_VENV_DIR"
-    fi
-  else
-    log "Python environment already exists at $MLX_VENV_DIR"
-  fi
-
-  PY="$MLX_VENV_DIR/bin/python"
-  HF="$MLX_VENV_DIR/bin/hf"
-  run "$PY" -m pip install --upgrade pip
-  run "$PY" -m pip install -e "$MLX_DIR" huggingface_hub
-
-  run "$HF" download "nvidia/$MODEL" --local-dir "$MLX_DIR/models/$(printf '%s' "$MODEL" | sed 's/^Kimodo-/nvidia-/' | tr 'A-Z' 'a-z')"
-  run "$HF" download LocalAI-io/Llama-3-Kimodo-GGML --local-dir "$MLX_DIR/models/llm2vec-text-bundle"
-
-  if [ "$DRY_RUN" -eq 1 ]; then
-    log "would run: $PY -m kimodo_mlx diagnose (expect mlx-metal)"
-    log "would verify: $PY -m kimodo_mlx --help"
-  else
-    "$PY" -m kimodo_mlx diagnose || die "kimodo-mlx diagnose failed; see $MLX_DIR/README.md"
-    "$PY" -m kimodo_mlx --help >/dev/null || die "kimodo-mlx CLI verification failed; see $MLX_DIR/README.md"
-  fi
-
-  log "kimodo-mlx ready: $PY -m kimodo_mlx generate --prompt \"walk forward\" --frames 30 --steps 10"
-}
-
-install_kimodo_cpp() {
-  local accel="$1" # metal | cpu
-  if [ "$DRY_RUN" -ne 1 ]; then
-    command -v git >/dev/null 2>&1 || die "git is required"
-    command -v cmake >/dev/null 2>&1 || die "cmake is required (CMake 3.25+)"
-    command -v python3 >/dev/null 2>&1 || die "python3 is required"
-  fi
-
-  if [ ! -e "$CPP_DIR/.git" ]; then
-    mkdir -p "$(dirname "$CPP_DIR")"
-    run git clone --depth 1 https://github.com/localai-org/kimodo.cpp.git "$CPP_DIR"
-  else
-    log "kimodo.cpp checkout already exists at $CPP_DIR"
-  fi
-  run git -C "$CPP_DIR" submodule update --init --recursive
-
-  local build_dir="$CPP_DIR/build-$accel"
-  if [ "$accel" = "metal" ]; then
-    # The GGML Metal wiring lives in a patch maintained with the kimodo-mlx
-    # port; apply it onto the ref it was written against.
-    if [ ! -e "$MLX_DIR/.git" ]; then
-      mkdir -p "$(dirname "$MLX_DIR")"
-      run git clone --depth 1 https://github.com/NomaDamas/kimodo-mlx.git "$MLX_DIR"
-    fi
-    run git -C "$CPP_DIR" fetch --depth 1 origin "$CPP_METAL_REF"
-    run git -C "$CPP_DIR" checkout FETCH_HEAD
-    if [ "$DRY_RUN" -eq 1 ]; then
-      printf '+ '; printf '%q ' git -C "$CPP_DIR" apply "$MLX_DIR/patches/0001-kimodo-ggml-metal.patch"; printf '\n'
-    else
-      if git -C "$CPP_DIR" apply --check "$MLX_DIR/patches/0001-kimodo-ggml-metal.patch" 2>/dev/null; then
-        git -C "$CPP_DIR" apply "$MLX_DIR/patches/0001-kimodo-ggml-metal.patch"
-      elif git -C "$CPP_DIR" apply --check -R "$MLX_DIR/patches/0001-kimodo-ggml-metal.patch" 2>/dev/null; then
-        log "Metal patch already applied; continuing"
-      else
-        die "Metal patch cannot be applied cleanly; see $CPP_DIR and $MLX_DIR/patches/0001-kimodo-ggml-metal.patch"
-      fi
-    fi
-    run cmake -S "$CPP_DIR" -B "$build_dir" \
-      -DKIMODO_ENABLE_VULKAN=OFF -DKIMODO_ENABLE_METAL=ON -DKIMODO_BUILD_TESTS=OFF
-  else
-    local vulkan="$CPP_VULKAN"
-    if [ "$vulkan" = "auto" ]; then
-      if pkg-config --exists vulkan 2>/dev/null || [ -f /usr/include/vulkan/vulkan.h ]; then
-        vulkan=ON
-      else
-        vulkan=OFF
-      fi
-    fi
-    log "kimodo.cpp CPU build: vulkan=$vulkan"
-    run cmake -S "$CPP_DIR" -B "$build_dir" \
-      -DKIMODO_ENABLE_VULKAN="$vulkan" -DKIMODO_BUILD_TESTS=OFF
-  fi
-  run cmake --build "$build_dir" --parallel
-
-  local binary="$build_dir/kmd-generate"
-  if [ "$DRY_RUN" -eq 1 ]; then
-    log "would verify executable $binary"
-  else
-    [ -x "$binary" ] || die "kimodo.cpp build did not produce executable: $binary"
-    log "verified kimodo.cpp executable: $binary"
-  fi
-
-  if [ "$accel" = "metal" ] && [ "$DRY_RUN" -ne 1 ]; then
-    local metal_enabled=0
-    if [ -f "$build_dir/CMakeCache.txt" ] && grep -Eq '^KIMODO_ENABLE_METAL(:BOOL)?=ON$' "$build_dir/CMakeCache.txt"; then
-      metal_enabled=1
-    else
-      while IFS= read -r -d '' binary; do
-        if command -v nm >/dev/null 2>&1 && nm "$binary" 2>/dev/null | grep -Eiq 'metal|ggml_metal'; then
-          metal_enabled=1
-          break
-        fi
-      done < <(find "$build_dir" -type f -perm -111 -print0 2>/dev/null)
-    fi
-    [ "$metal_enabled" -eq 1 ] || die "Metal build verification failed; KIMODO_ENABLE_METAL is not enabled"
-    log "verified Metal build: KIMODO_ENABLE_METAL=ON"
-  fi
-
-  # GGUF weights come from the LocalAI-io org through the upstream script,
-  # which needs the hf CLI; keep it in a small dedicated venv.
-  if [ ! -x "$CPP_VENV_DIR/bin/hf" ]; then
-    run python3 -m venv "$CPP_VENV_DIR"
-    run "$CPP_VENV_DIR/bin/python" -m pip install --upgrade pip huggingface_hub
-  fi
-  local cpp_model
-  cpp_model=$(printf '%s' "$MODEL" | sed 's/^Kimodo-//' | tr 'A-Z' 'a-z')
-  run env "PATH=$CPP_VENV_DIR/bin:$PATH" bash "$CPP_DIR/scripts/download_gguf_weights.sh" \
-    --output "$CPP_DIR" --model "$cpp_model"
-
-  log "kimodo.cpp ($accel) ready: build at $build_dir, GGUF weights under $CPP_DIR"
-}
-
-case "$BACKEND" in
-  nvidia-cuda) install_nvidia_cuda ;;
-  kimodo-mlx) install_kimodo_mlx ;;
-  kimodo.cpp-metal) install_kimodo_cpp metal ;;
-  kimodo.cpp-cpu) install_kimodo_cpp cpu ;;
-esac
-
-# Tell the Studio runner exactly which installed route to use.
-if [ "$DRY_RUN" -eq 1 ]; then
-  log "would write $HOME/.cozyclay/kimodo-backend.json"
-else
-  mkdir -p "$HOME/.cozyclay"
-  if [ "$BACKEND" = "kimodo-mlx" ]; then
-    printf '{"backend":"%s","model":"%s","motion":"%s/models/nvidia-soma-rp-v1.1","text":"%s/models/llm2vec-text-bundle"}\n' "$BACKEND" "$MODEL" "$MLX_DIR" "$MLX_DIR" > "$HOME/.cozyclay/kimodo-backend.json"
-  elif [ "$BACKEND" = "kimodo.cpp-metal" ] || [ "$BACKEND" = "kimodo.cpp-cpu" ]; then
-    printf '{"backend":"%s","model":"%s","motion":"%s/models/kimodo-%s-f32.gguf","text":"%s/generated/llm2vec-text-bundle"}\n' "$BACKEND" "$MODEL" "$CPP_DIR" "$(printf '%s' "$MODEL" | sed 's/^Kimodo-//' | tr 'A-Z' 'a-z')" "$CPP_DIR" > "$HOME/.cozyclay/kimodo-backend.json"
-  else
-    printf '{"backend":"%s","model":"%s"}\n' "$BACKEND" "$MODEL" > "$HOME/.cozyclay/kimodo-backend.json"
-  fi
-fi
-log "ready"

package/tools/kimodo/soma77-to-cskel27.mjs

@@ -1,305 +0,0 @@
-/**
- * soma77-to-cskel27.mjs — Kimodo's somaskel77 motion npz → the exact motion
- * arrays the cclay npz encoder consumes ({ frames, fps, rotMats, rootPos,
- * posedJoints }), i.e. the same shape tools/ardy/bvh-cskel27.mjs produces.
- *
- * WHY GLOBAL ROTATIONS. cskel27 and somaskel77 do not share a spine
- * segmentation: cskel27 runs Hips→Spine→Spine1→Spine2→Spine3 (four segments
- * before the shoulder carrier) where somaskel77 runs Hips→Spine1→Spine2→Chest
- * (three), and somaskel77 splits the neck in two (Neck1→Neck2) where cskel27
- * has one. Re-deriving each cskel27 LOCAL from a per-joint global — exactly
- * the rule tools/ardy/bvh-cskel27.mjs states for the Mixamo case — makes that
- * mismatch a non-issue in both directions:
- *
- *   - a source segment cskel27 lacks (Neck2) is absorbed into the child's
- *     local, because local = parentGlobalᵀ · global composes whatever sits
- *     between the two mapped joints. No rotation is lost.
- *   - a cskel27 joint the source lacks (Spine2, the Hand ends) borrows its
- *     nearest mapped ancestor's global, so its local comes out identity —
- *     the same "not authored" rule poseToCskel27 and bvhToCskel27Motion use.
- *
- * Both skeletons rest in the same convention (Y-up, metres, standard T-pose:
- * Kimodo writes its NPZ against the canonical SOMA T-pose, and CSKEL27_NEUTRAL
- * is the cskel27 T-pose), so a somaskel77 global IS the cskel27 global for the
- * matching joint and no basis change is needed.
- *
- * POSITIONS ARE RE-GROWN, never copied: the take has to move CozyClay's body,
- * not drag Kimodo's per-model bone lengths into the scene. FK runs over the
- * canonical cskel27 skeleton and the root trajectory is scaled by the
- * leg-length ratio so stride length survives the reproportioning, then
- * floor-shifted so the clip's lowest foot sample touches Y=0.
- */
-
-import { CSKEL27_JOINTS, CSKEL27_PARENTS } from "../../src/ardy/cskel27.js";
-import { deriveBoneOffsets, forwardKinematics, matMul, matTranspose } from "../../src/ardy/convert.js";
-import { canonicalCskel27Reference } from "../../src/ardy/to-cskel27.js";
-
-/**
- * somaskel77 joint order, transcribed from the upstream skeleton definition
- * (`SOMASkeleton77.bone_order_names_with_parents` in ardy/skeleton/definitions.py,
- * identical in the Kimodo tree). Index here == joint index in the Kimodo npz
- * arrays. The standard-T-pose BVH in the Kimodo assets carries an extra `Root`
- * node ABOVE Hips that is a BVH-file artifact only — it is not part of the
- * joint arrays, so this list starts at Hips and is 77 long.
- */
-export const SOMA77_JOINTS = [
-	"Hips", "Spine1", "Spine2", "Chest", "Neck1", "Neck2", "Head", "HeadEnd",
-	"Jaw", "LeftEye", "RightEye",
-	"LeftShoulder", "LeftArm", "LeftForeArm", "LeftHand",
-	"LeftHandThumb1", "LeftHandThumb2", "LeftHandThumb3", "LeftHandThumbEnd",
-	"LeftHandIndex1", "LeftHandIndex2", "LeftHandIndex3", "LeftHandIndex4", "LeftHandIndexEnd",
-	"LeftHandMiddle1", "LeftHandMiddle2", "LeftHandMiddle3", "LeftHandMiddle4", "LeftHandMiddleEnd",
-	"LeftHandRing1", "LeftHandRing2", "LeftHandRing3", "LeftHandRing4", "LeftHandRingEnd",
-	"LeftHandPinky1", "LeftHandPinky2", "LeftHandPinky3", "LeftHandPinky4", "LeftHandPinkyEnd",
-	"RightShoulder", "RightArm", "RightForeArm", "RightHand",
-	"RightHandThumb1", "RightHandThumb2", "RightHandThumb3", "RightHandThumbEnd",
-	"RightHandIndex1", "RightHandIndex2", "RightHandIndex3", "RightHandIndex4", "RightHandIndexEnd",
-	"RightHandMiddle1", "RightHandMiddle2", "RightHandMiddle3", "RightHandMiddle4", "RightHandMiddleEnd",
-	"RightHandRing1", "RightHandRing2", "RightHandRing3", "RightHandRing4", "RightHandRingEnd",
-	"RightHandPinky1", "RightHandPinky2", "RightHandPinky3", "RightHandPinky4", "RightHandPinkyEnd",
-	"LeftLeg", "LeftShin", "LeftFoot", "LeftToeBase", "LeftToeEnd",
-	"RightLeg", "RightShin", "RightFoot", "RightToeBase", "RightToeEnd",
-];
-
-/**
- * cskel27 joint name → the somaskel77 joint whose GLOBAL rotation drives it,
- * or null for "this joint is not authored by the source".
- *
- * The two anchors that fix the torso alignment are structural, not cosmetic:
- * Hips is the root in both, and cskel27's Spine3 carries the shoulders and the
- * neck exactly as somaskel77's Chest does — so Spine3↔Chest is forced. That
- * leaves three cskel27 links (Spine, Spine1, Spine2) spanning the two
- * somaskel77 links (Spine1, Spine2) between those anchors, so exactly one
- * cskel27 spine joint must go unauthored. Spine2 is the one chosen: mapping
- * from the bottom up keeps the lower spine — where the large trunk rotation
- * lives — driven by real data, and pushes the identity link to the top of the
- * chain where the residual Spine2→Chest rotation is absorbed into Spine3's
- * local anyway.
- *
- * NOTE ON THE LEGS: the names shift by one between the two skeletons.
- * somaskel77's LeftLeg is the THIGH (cskel27's LeftUpLeg) and its LeftShin is
- * the shank (cskel27's LeftLeg). Mapping these by identical name would silently
- * put the knee rotation on the hip.
- *
- * The hand ends stay unauthored, matching bvhToCskel27Motion: somaskel77's
- * nearest equivalents are finger roots, and borrowing one would splay the hand.
- */
-export const CSKEL27_FROM_SOMA77 = {
-	Hips: "Hips",
-	Spine: "Spine1",
-	Spine1: "Spine2",
-	Spine2: null,
-	Spine3: "Chest",
-	Neck: "Neck1",
-	Head: "Head",
-
-	RightShoulder: "RightShoulder",
-	RightArm: "RightArm",
-	RightForeArm: "RightForeArm",
-	RightHand: "RightHand",
-	RightHandEnd: null,
-	RightHandThumb1: "RightHandThumb1",
-
-	LeftShoulder: "LeftShoulder",
-	LeftArm: "LeftArm",
-	LeftForeArm: "LeftForeArm",
-	LeftHand: "LeftHand",
-	LeftHandEnd: null,
-	LeftHandThumb1: "LeftHandThumb1",
-
-	RightUpLeg: "RightLeg",
-	RightLeg: "RightShin",
-	RightFoot: "RightFoot",
-	RightToeBase: "RightToeBase",
-
-	LeftUpLeg: "LeftLeg",
-	LeftLeg: "LeftShin",
-	LeftFoot: "LeftFoot",
-	LeftToeBase: "LeftToeBase",
-};
-
-const IDENTITY = [
-	[1, 0, 0],
-	[0, 1, 0],
-	[0, 0, 1],
-];
-
-/** cskel27 joints whose Y decides where the floor is. */
-const GROUND_JOINTS = ["LeftFoot", "LeftToeBase", "RightFoot", "RightToeBase"];
-
-/**
- * Per cskel27 joint, the somaskel77 index whose global rotation it takes.
- * An unmapped joint walks up the cskel27 parent chain to the nearest mapped
- * ancestor, which is what makes its local come out identity.
- */
-export function resolveSourceIndices(jointNames = SOMA77_JOINTS) {
-	const sourceIndex = new Map(jointNames.map((name, index) => [name, index]));
-	const missing = Object.values(CSKEL27_FROM_SOMA77).filter(
-		(name) => name !== null && !sourceIndex.has(name)
-	);
-	if (missing.length) {
-		throw new Error(`soma77ToCskel27Motion: source skeleton is missing ${missing.join(", ")}`);
-	}
-	const resolved = new Array(CSKEL27_JOINTS.length);
-	for (let index = 0; index < CSKEL27_JOINTS.length; index += 1) {
-		let cursor = index;
-		let source = CSKEL27_FROM_SOMA77[CSKEL27_JOINTS[cursor]];
-		while (source == null) {
-			cursor = CSKEL27_PARENTS[cursor];
-			if (cursor === null) {
-				throw new Error(
-					`soma77ToCskel27Motion: ${CSKEL27_JOINTS[index]} has no mapped ancestor`
-				);
-			}
-			source = CSKEL27_FROM_SOMA77[CSKEL27_JOINTS[cursor]];
-		}
-		resolved[index] = sourceIndex.get(source);
-	}
-	return resolved;
-}
-
-function readMat(flat, base) {
-	return [
-		[flat[base], flat[base + 1], flat[base + 2]],
-		[flat[base + 3], flat[base + 4], flat[base + 5]],
-		[flat[base + 6], flat[base + 7], flat[base + 8]],
-	];
-}
-
-function chainLength(positions, indexByName, names) {
-	let total = 0;
-	for (let step = 1; step < names.length; step += 1) {
-		const a = positions[indexByName.get(names[step - 1])];
-		const b = positions[indexByName.get(names[step])];
-		total += Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
-	}
-	return total;
-}
-
-/**
- * @param {object} input
- * @param {number} input.frames
- * @param {number} input.fps
- * @param {Float32Array} input.globalRotMats  Kimodo `global_rot_mats`, frames*J*9
- * @param {Float32Array} input.posedJoints    Kimodo `posed_joints`, frames*J*3
- * @param {string[]} [input.jointNames]       source joint order (default somaskel77)
- * @returns {{frames:number, fps:number, rotMats:Float32Array, rootPos:Float32Array, posedJoints:Float32Array}}
- */
-export function soma77ToCskel27Motion({ frames, fps, globalRotMats, posedJoints, jointNames = SOMA77_JOINTS }) {
-	if (!Number.isInteger(frames) || frames < 1) {
-		throw new Error("soma77ToCskel27Motion: frames must be a positive integer");
-	}
-	if (!Number.isInteger(fps) || fps < 1) {
-		throw new Error("soma77ToCskel27Motion: fps must be a positive integer");
-	}
-	const jointCount = jointNames.length;
-	if (globalRotMats.length !== frames * jointCount * 9) {
-		throw new Error(
-			`soma77ToCskel27Motion: globalRotMats must be ${frames * jointCount * 9} long, got ${globalRotMats.length}`
-		);
-	}
-	if (posedJoints.length !== frames * jointCount * 3) {
-		throw new Error(
-			`soma77ToCskel27Motion: posedJoints must be ${frames * jointCount * 3} long, got ${posedJoints.length}`
-		);
-	}
-
-	const sources = resolveSourceIndices(jointNames);
-	const indexByName = new Map(jointNames.map((name, index) => [name, index]));
-
-	// Canonical cskel27 proportions. The reference rests with identity locals,
-	// so these offsets are the neutral skeleton's own bone vectors.
-	const reference = canonicalCskel27Reference();
-	const boneOffsets = deriveBoneOffsets(reference.posed_joints, reference.local_rot_mats);
-
-	// Leg-length ratio, measured on the source's own first frame against the
-	// canonical body, so a stride generated for Kimodo's proportions covers the
-	// same fraction of a step on CozyClay's.
-	const firstFrame = [];
-	for (let joint = 0; joint < jointCount; joint += 1) {
-		const base = joint * 3;
-		firstFrame.push([posedJoints[base], posedJoints[base + 1], posedJoints[base + 2]]);
-	}
-	const sourceLeg = chainLength(firstFrame, indexByName, ["LeftLeg", "LeftShin", "LeftFoot"]);
-	const canonicalIndex = new Map(CSKEL27_JOINTS.map((name, index) => [name, index]));
-	const canonicalLeg = chainLength(reference.posed_joints, canonicalIndex, [
-		"LeftUpLeg",
-		"LeftLeg",
-		"LeftFoot",
-	]);
-	if (!(sourceLeg > 0)) {
-		throw new Error("soma77ToCskel27Motion: source leg length measured as zero");
-	}
-	const rootScale = canonicalLeg / sourceLeg;
-
-	const rotMats = new Float32Array(frames * 27 * 9);
-	const rootPos = new Float32Array(frames * 3);
-	const outPosed = new Float32Array(frames * 27 * 3);
-
-	const hipsSource = indexByName.get("Hips");
-	let floorY = Infinity;
-
-	for (let frame = 0; frame < frames; frame += 1) {
-		const rotBase = frame * jointCount * 9;
-		const globals = new Array(27);
-		for (let joint = 0; joint < 27; joint += 1) {
-			globals[joint] = readMat(globalRotMats, rotBase + sources[joint] * 9);
-		}
-
-		const locals = new Array(27);
-		for (let joint = 0; joint < 27; joint += 1) {
-			const parent = CSKEL27_PARENTS[joint];
-			locals[joint] =
-				parent === null ? globals[joint].map((row) => row.slice()) : matMul(matTranspose(globals[parent]), globals[joint]);
-		}
-
-		const posBase = frame * jointCount * 3 + hipsSource * 3;
-		const root = [
-			posedJoints[posBase] * rootScale,
-			posedJoints[posBase + 1] * rootScale,
-			posedJoints[posBase + 2] * rootScale,
-		];
-		const positions = forwardKinematics(locals, boneOffsets, root);
-
-		for (const name of GROUND_JOINTS) {
-			const y = positions[canonicalIndex.get(name)][1];
-			if (y < floorY) floorY = y;
-		}
-
-		const outRotBase = frame * 27 * 9;
-		for (let joint = 0; joint < 27; joint += 1) {
-			const m = locals[joint];
-			for (let row = 0; row < 3; row += 1) {
-				for (let col = 0; col < 3; col += 1) {
-					rotMats[outRotBase + joint * 3 * 3 + row * 3 + col] = m[row][col];
-				}
-			}
-		}
-		rootPos[frame * 3] = root[0];
-		rootPos[frame * 3 + 1] = root[1];
-		rootPos[frame * 3 + 2] = root[2];
-		const outPosBase = frame * 27 * 3;
-		for (let joint = 0; joint < 27; joint += 1) {
-			outPosed[outPosBase + joint * 3] = positions[joint][0];
-			outPosed[outPosBase + joint * 3 + 1] = positions[joint][1];
-			outPosed[outPosBase + joint * 3 + 2] = positions[joint][2];
-		}
-	}
-
-	// One rigid floor shift for the whole clip: per-frame grounding would
-	// flatten the arc of a jump, which is exactly the motion this pipeline
-	// exists to stage.
-	if (Number.isFinite(floorY) && floorY !== 0) {
-		for (let frame = 0; frame < frames; frame += 1) {
-			rootPos[frame * 3 + 1] -= floorY;
-			const outPosBase = frame * 27 * 3;
-			for (let joint = 0; joint < 27; joint += 1) {
-				outPosed[outPosBase + joint * 3 + 1] -= floorY;
-			}
-		}
-	}
-
-	return { frames, fps, rotMats, rootPos, posedJoints: outPosed };
-}
-
-export { IDENTITY as CSKEL27_IDENTITY };

package/tools/morphgs/assets/gen_truth.py

@@ -1,39 +0,0 @@
-# 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}")