Nicholas ButzkeandClaude Opus 5
27c4117c25
Fixes the two root causes behind four of the seven reported breakages, and rejects the source that cannot be fixed. STAND UP FIRST. flatten_and_scale() now derives the up axis from the skeleton and rotates the model upright before measuring anything. Aria and Momo are correct: 1.75 m tall, 1.43 x 0.41 and 1.52 x 0.39 across, verified by render. The up vector is measured from the FEET to the HIPS, not from the hips to the head. The head is not a reliable landmark — the spine walk ends on the last non-cosmetic bone in the chain, which on a rig with a facial skeleton can sit BELOW the hips. Momo's did, so the first cut of this fix stood her neatly on her head: right size, right proportions, upside down. Feet cannot be mistaken. REACH BONES BY ROLE. SkinnedPlayerModel gained _role_bone(), and set_weapon uses it. Four characters could not hold a gun because one hardcoded lookup knew three spellings and their hands are called "Right wrist" and "J_Bip_R_Hand" — both resolved perfectly in the sidecar the whole time. HIKARI IS REJECTED. She now fails the gate: her feet and spine disagree about which way is up, so the stand-up correction cannot resolve her either, on top of zero-length cosmetic bones and a second armature that was smuggling its own clips into the export. That is not a tuning problem, it is a file that has been through two toolchains. De-registered and removed rather than shipped broken — which is what the gate is for. Six GLB skins remain, all passing. Smoke 0 failures, 11/11 movement tests. Still open, recorded in the skill: kiyoko faces backwards, miku's grown hair stretches under animation, the mannequin's rifle hold does not convince, and taila's front skirt clipping. Co-Authored-By: Claude Opus 5 <[email protected]>
1441 lines
60 KiB
Python
1441 lines
60 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
Put the animation library onto a character WITHOUT touching how it deforms.
|
|
|
|
This replaces the old strip_rig -> autorig -> merge_animations route, which
|
|
solved a naming problem by destroying the asset. That route threw away the
|
|
character's skeleton, joined every mesh into one blob, and rebound the result
|
|
with nearest-four-bones Euclidean weights. Measured on the shipped taila.glb it
|
|
produced 2817 vertices pulled by BOTH legs (worst a dead 50/50 split) and 86%
|
|
of all vertices carrying the full four influences — while the ORIGINAL file it
|
|
was built from had zero cross-leg bleed, one mesh per material, and dedicated
|
|
bone chains for the skirt and the hair. Every runtime "repair" in
|
|
characters/skin_leg_repair.gd exists to undo damage done right here.
|
|
|
|
So: keep the character's own rig, weights, per-part meshes and cloth chains,
|
|
and move the ANIMATION onto it instead.
|
|
|
|
1. Rebuild parenting. A Rigify DEF-rig exports its chain roots parented
|
|
straight to the armature root, because Rigify drives them by constraint
|
|
rather than hierarchy. Left that way, rotating the hips would leave the
|
|
legs, skirt and hair floating in place. Orphans are re-attached by
|
|
anatomy where it is known and by rest geometry otherwise — and cloth may
|
|
only ever attach to the trunk, never to a limb, or a skirt would ride one
|
|
thigh.
|
|
2. Retarget by ROLE, not by name (see tools/rig_map.py).
|
|
3. Bake each clip as a rest-relative delta:
|
|
|
|
R_world = src_pose_rot * src_rest_rot^-1 (what the clip does)
|
|
tgt_rot = R_world * tgt_rest_rot (done to THIS rig)
|
|
|
|
Copying absolute world orientation instead — which is what the old
|
|
constraint bake did — forces the library's bone roll onto a mesh that was
|
|
bound with a different one, and twists every limb by a constant offset.
|
|
4. Drive ONLY the body. Skirt, hair, twist and face bones are left with no
|
|
keys at all, so they rest relative to their parents and are free for the
|
|
spring solver at runtime. That split — clips animate the body, physics
|
|
animates the cloth — is the whole point.
|
|
|
|
Usage:
|
|
blender --background --python tools/retarget.py -- \
|
|
<character.glb> <animations_dir> <output.glb> [--height 1.75] [--keep-root-motion]
|
|
|
|
Writes <output>.rig.json beside the GLB: resolved bone roles, cloth chains and
|
|
twist pairs, so the runtime never has to re-guess the skeleton's anatomy.
|
|
"""
|
|
import bpy
|
|
import math
|
|
import json
|
|
import os
|
|
import sys
|
|
import tempfile
|
|
from collections import defaultdict
|
|
from mathutils import Matrix, Quaternion, Vector
|
|
|
|
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
|
import gltf_fix
|
|
import rig_map
|
|
from rig_map import RigRoles, build_map, is_cosmetic, is_segment_of, tokens
|
|
|
|
argv = sys.argv
|
|
argv = argv[argv.index("--") + 1:] if "--" in argv else []
|
|
if len(argv) < 3:
|
|
print(__doc__)
|
|
sys.exit(1)
|
|
|
|
CHARACTER, ANIM_DIR, OUTPUT = argv[0], argv[1], argv[2]
|
|
STRIP_ROOT_MOTION = "--keep-root-motion" not in argv
|
|
TARGET_HEIGHT = 1.75
|
|
if "--height" in argv:
|
|
TARGET_HEIGHT = float(argv[argv.index("--height") + 1])
|
|
OVERRIDES = {}
|
|
if "--bone-map" in argv:
|
|
with open(argv[argv.index("--bone-map") + 1], "r", encoding="utf-8") as f:
|
|
OVERRIDES = json.load(f)
|
|
|
|
# Library clip -> the game's canonical clip name. Unmapped clips are skipped so
|
|
# character GLBs stay small.
|
|
LIBRARY_CLIP_MAP = {
|
|
"Idle_Loop": "Idle",
|
|
"Walk_Loop": "Walk",
|
|
"Jog_Fwd_Loop": "Run",
|
|
"Sprint_Loop": "Sprint",
|
|
"Jump_Start": "Jump",
|
|
"Jump_Loop": "Fall",
|
|
"Jump_Land": "Land",
|
|
"Crouch_Idle_Loop": "CrouchIdle",
|
|
"Crouch_Fwd_Loop": "CrouchWalk",
|
|
"Roll": "Dash",
|
|
"Death01": "Death",
|
|
"Hit_Chest": "Hit",
|
|
"Dance_Loop": "Dance",
|
|
"Swim_Fwd_Loop": "Grapple",
|
|
"Pistol_Idle_Loop": "PistolIdle",
|
|
"Pistol_Shoot": "PistolShoot",
|
|
"Pistol_Reload": "PistolReload",
|
|
"Sword_Attack": "Throw",
|
|
}
|
|
|
|
UP = Vector((0.0, 0.0, 1.0))
|
|
|
|
# Which cosmetic chains get secondary motion. A face-shape or eye chain is
|
|
# cosmetic but must never swing, so this is deliberately narrower than
|
|
# rig_map.COSMETIC.
|
|
SPRING_CLASSES = {"hair", "skirt", "cloth", "ribbon", "tail", "cape", "coat",
|
|
"scarf", "sleeve", "breast", "bust", "feather", "strap",
|
|
"antenna", "wing"}
|
|
|
|
|
|
def spring_class(name):
|
|
"""Which secondary-motion class this bone belongs to, or None.
|
|
|
|
Whole token first, then a SHORT positional suffix — the same rule as
|
|
rig_map.is_cosmetic, and it must be the same rule, because a bone that reads
|
|
as cosmetic there and as nothing here is left out of every chain and its
|
|
geometry never moves. DANDADAN's hair is HairFL / HairFR / HairF_Top, which
|
|
tokenise to "hairfl" and matched no class at all: she imported with six
|
|
chains, all of them her bust, and not one strand of hair.
|
|
"""
|
|
for t in tokens(name):
|
|
if t in SPRING_CLASSES:
|
|
return t
|
|
for c in SPRING_CLASSES:
|
|
if len(t) - len(c) <= 2 and t.startswith(c) and len(t) > len(c):
|
|
return c
|
|
return None
|
|
|
|
|
|
# --------------------------------------------------------------------- import
|
|
|
|
|
|
def clear_scene():
|
|
bpy.ops.object.select_all(action="SELECT")
|
|
bpy.ops.object.delete()
|
|
for blocks in (bpy.data.meshes, bpy.data.armatures, bpy.data.actions):
|
|
for b in list(blocks):
|
|
if b.users == 0:
|
|
blocks.remove(b)
|
|
|
|
|
|
def import_any(path):
|
|
ext = os.path.splitext(path)[1].lower()
|
|
if ext in (".glb", ".gltf"):
|
|
bpy.ops.import_scene.gltf(filepath=path)
|
|
elif ext == ".fbx":
|
|
bpy.ops.import_scene.fbx(filepath=path)
|
|
else:
|
|
print(f"ERROR: unsupported character format {ext}")
|
|
sys.exit(1)
|
|
|
|
|
|
def skinned_meshes(arm):
|
|
"""Meshes actually driven by this armature.
|
|
|
|
Anything else in the file is scene dressing — Sketchfab models routinely
|
|
ship a display base or a diorama, and those must not become part of the
|
|
player.
|
|
"""
|
|
out = []
|
|
for o in [o for o in bpy.data.objects if o.type == "MESH"]:
|
|
driven = any(m.type == "ARMATURE" and m.object is arm for m in o.modifiers)
|
|
if driven or (o.parent is arm and o.vertex_groups):
|
|
out.append(o)
|
|
return out
|
|
|
|
|
|
def strip_import_suffixes(arm, meshes):
|
|
"""`DEF-thigh.L_16` -> `DEF-thigh.L`.
|
|
|
|
The glTF importer appends the node index to every bone name. Those names
|
|
ship in the exported GLB and are what the game code matches on, so clean
|
|
them up here rather than teaching every consumer about the suffix.
|
|
"""
|
|
renames = {}
|
|
taken = set(b.name for b in arm.data.bones)
|
|
for bone in arm.data.bones:
|
|
clean = rig_map.strip_gltf_suffix(bone.name)
|
|
if clean != bone.name and clean not in taken:
|
|
renames[bone.name] = clean
|
|
taken.discard(bone.name)
|
|
taken.add(clean)
|
|
for old, new in renames.items():
|
|
arm.data.bones[old].name = new
|
|
# Vertex groups are matched to bones by NAME and are not renamed for us.
|
|
for m in meshes:
|
|
for vg in m.vertex_groups:
|
|
new = renames.get(vg.name)
|
|
if new and new not in m.vertex_groups:
|
|
vg.name = new
|
|
print(f"Cleaned {len(renames)} bone names")
|
|
|
|
|
|
# ----------------------------------------------------------------- hierarchy
|
|
|
|
|
|
def _seg_distance(p, a, b):
|
|
ab = b - a
|
|
d2 = ab.dot(ab)
|
|
t = 0.0 if d2 < 1e-12 else max(0.0, min(1.0, (p - a).dot(ab) / d2))
|
|
return (p - (a + ab * t)).length
|
|
|
|
|
|
def rebuild_hierarchy(arm, roles):
|
|
"""Re-attach chain roots that exported parented to the armature root.
|
|
|
|
Anatomy first (a thigh belongs to the hips, a forearm to the upper arm),
|
|
rest geometry second. Cloth and hair are only ever allowed to attach to the
|
|
TRUNK: pick anchors by raw proximity and a skirt panel hanging beside a leg
|
|
attaches to that thigh and rides it like a trouser leg.
|
|
"""
|
|
trunk = [roles.hips] + list(roles.spine)
|
|
trunk = [n for n in trunk if n]
|
|
limb = roles.limb
|
|
|
|
def anat(role, side):
|
|
return limb.get((role, side))
|
|
|
|
fixed = {}
|
|
for side in ("L", "R"):
|
|
chest = trunk[-3] if len(trunk) >= 3 else (trunk[-1] if trunk else None)
|
|
pairs = [
|
|
(("thigh", side), roles.hips),
|
|
(("shin", side), anat("thigh", side)),
|
|
(("foot", side), anat("shin", side)),
|
|
(("toe", side), anat("foot", side)),
|
|
(("shoulder", side), chest),
|
|
(("upper_arm", side), anat("shoulder", side) or chest),
|
|
(("forearm", side), anat("upper_arm", side)),
|
|
(("hand", side), anat("forearm", side)),
|
|
]
|
|
for key, parent in pairs:
|
|
name = limb.get(key)
|
|
if name and parent:
|
|
fixed[name] = parent
|
|
|
|
bpy.context.view_layer.objects.active = arm
|
|
bpy.ops.object.mode_set(mode="EDIT")
|
|
eb = arm.data.edit_bones
|
|
|
|
# Where each anchor bone actually EXTENDS TO, from authored data only.
|
|
#
|
|
# glTF stores joints as nodes with no tail, so the tails Blender reports are
|
|
# invented — every one of Taila's skirt bones comes back 0.78 m long. Using
|
|
# them, DEF-spine's phantom tail runs straight down through the whole skirt
|
|
# and every panel measures ~0.05 m from "the hips", which beat each panel's
|
|
# real 0.15 m link to its own chain root and flattened all 7 chains.
|
|
# A bone's true extent is the head of the next bone along.
|
|
span = {}
|
|
for i, name in enumerate(trunk):
|
|
nxt = trunk[i + 1] if i + 1 < len(trunk) else None
|
|
span[name] = (eb[name].head,
|
|
eb[nxt].head if nxt and nxt in eb else eb[name].tail)
|
|
for name in limb.values():
|
|
if name not in eb:
|
|
continue
|
|
kids = [c for c in eb[name].children if not is_cosmetic(c.name)]
|
|
span[name] = (eb[name].head, kids[0].head if kids else eb[name].tail)
|
|
|
|
def anchor_distance(point, name):
|
|
a, b = span.get(name, (eb[name].head, eb[name].tail))
|
|
return _seg_distance(point, a, b)
|
|
|
|
def is_root_like(bone):
|
|
return bone is None or any(
|
|
t in ("root", "master", "armature", "scene", "rootjoint")
|
|
for t in tokens(bone.name))
|
|
|
|
def descendants(bone):
|
|
out = {bone.name}
|
|
stack = list(bone.children)
|
|
while stack:
|
|
b = stack.pop()
|
|
out.add(b.name)
|
|
stack.extend(b.children)
|
|
return out
|
|
|
|
trunk_set = set(trunk)
|
|
core = trunk_set | set(limb.values())
|
|
orphans = [b for b in eb
|
|
if b.name != roles.hips and b.name not in trunk_set
|
|
and is_root_like(b.parent)]
|
|
|
|
reparented = 0
|
|
cosmetic_left = []
|
|
for bone in orphans:
|
|
if is_cosmetic(bone.name):
|
|
cosmetic_left.append(bone)
|
|
continue
|
|
target = fixed.get(bone.name)
|
|
if target is None:
|
|
banned = descendants(bone)
|
|
cands = [n for n in core if n in eb and n not in banned]
|
|
if not cands:
|
|
continue
|
|
target = min(cands, key=lambda n: anchor_distance(bone.head, n))
|
|
if target in eb and target != bone.name:
|
|
bone.parent = eb[target]
|
|
bone.use_connect = False
|
|
reparented += 1
|
|
|
|
# Cloth and hair hang from the TRUNK — never from a limb, and never from
|
|
# each other.
|
|
#
|
|
# Attaching cloth to whatever bone is nearest puts 16 of Taila's 21 skirt
|
|
# bones on a thigh, where the panel rides one leg like a trouser leg. The
|
|
# trunk restriction fixes that.
|
|
#
|
|
# Reconstructing multi-bone chains is deliberately NOT attempted. The
|
|
# temptation is obvious — Taila's skirt is really 7 panels of 3 — but the
|
|
# information is not in the file. glTF stores no bone tails, the panel
|
|
# numbering is not sequential (`skirt` -> `skirt.011` -> `skirt.002`), and
|
|
# neighbouring panel roots ring the waist 0.04 m apart, far closer than any
|
|
# of them is to the trunk. Successive attempts at distance, chain-direction
|
|
# and grow-outward rules each produced a topology that was still wrong
|
|
# somewhere — stitching panels together sideways, or hanging hair off an
|
|
# eye bone. A wrong chain is worse than no chain: the solver then swings
|
|
# bones along axes the mesh was never weighted for, and tears it.
|
|
#
|
|
# So each orphan becomes its own pendulum from the body. Chains the ARTIST
|
|
# authored survive untouched, because only chain ROOTS are orphans — which
|
|
# is why Taila's hair keeps its real 4-7 bone strands while her
|
|
# flat-exported skirt becomes per-panel pendulums. Both look like cloth;
|
|
# only the authored one gets true multi-segment drape.
|
|
for bone in cosmetic_left:
|
|
cands = [n for n in trunk_set if n in eb]
|
|
if not cands:
|
|
break
|
|
bone.parent = eb[min(cands, key=lambda n: anchor_distance(bone.head, n))]
|
|
bone.use_connect = False
|
|
reparented += 1
|
|
|
|
bpy.ops.object.mode_set(mode="OBJECT")
|
|
print(f"Re-attached {reparented} orphaned bones")
|
|
|
|
|
|
# ----------------------------------------------------------------- normalize
|
|
|
|
|
|
def flatten_and_scale(arm, meshes, target_height, roles=None):
|
|
"""Bake the import hierarchy away and set the character's real-world size.
|
|
|
|
Sketchfab wraps everything in scaled/rotated empties. Left in place they
|
|
turn up as a scale on the exported Skeleton3D, and every measurement the
|
|
game makes off bone rests reads in the wrong units.
|
|
"""
|
|
if arm.animation_data:
|
|
arm.animation_data_clear()
|
|
for pb in arm.pose.bones:
|
|
pb.matrix_basis = Matrix()
|
|
|
|
for obj in [arm] + meshes:
|
|
world = obj.matrix_world.copy()
|
|
obj.parent = None
|
|
obj.matrix_world = world
|
|
for o in [o for o in bpy.data.objects if o.type == "EMPTY"]:
|
|
bpy.data.objects.remove(o, do_unlink=True)
|
|
|
|
def apply_all():
|
|
bpy.ops.object.select_all(action="DESELECT")
|
|
for obj in [arm] + meshes:
|
|
obj.select_set(True)
|
|
bpy.context.view_layer.objects.active = arm
|
|
bpy.ops.object.transform_apply(location=True, rotation=True, scale=True)
|
|
|
|
apply_all()
|
|
|
|
# STAND THE CHARACTER UP before measuring anything.
|
|
#
|
|
# The scale below normalises the bounding box along Z because Z is up in
|
|
# Blender. For a model that arrives lying along another axis that measures
|
|
# the character's THICKNESS — about 0.25 m — so it gets scaled by ~7 and left
|
|
# on its back. One assumption, both symptoms, and invisible afterwards
|
|
# because the exporter maps Blender Z to glTF Y: "is the height 1.75" comes
|
|
# out true on a character who is 7.5 m tall lying down.
|
|
#
|
|
# Which way is up is not a convention to assume, it is a property of the
|
|
# skeleton: the head is above the hips. Snapped to the nearest axis rather
|
|
# than aligned exactly, so a character with a slight lean in their rest pose
|
|
# is stood up, not straightened.
|
|
# Measured from the FEET to the HIPS, not from the hips to the head.
|
|
#
|
|
# The head is not a reliable landmark. The spine walk ends on whatever the
|
|
# last non-cosmetic bone in the chain is, and on a rig with a facial skeleton
|
|
# that can be a bone sitting BELOW the hips — which points this vector
|
|
# downwards and stands the character neatly on her head. Momo did exactly
|
|
# that. Feet cannot be mistaken: they are the bottom of a standing character
|
|
# on every rig, and foot.L/R resolve on every source met so far.
|
|
if roles is not None and roles.hips:
|
|
hips_b = arm.data.bones.get(roles.hips)
|
|
feet = [arm.data.bones.get(roles.limb.get(("foot", s), ""))
|
|
for s in ("L", "R")]
|
|
feet = [f for f in feet if f]
|
|
ref = None
|
|
if feet:
|
|
ref = sum((f.head_local for f in feet), Vector()) / len(feet)
|
|
elif roles.head and arm.data.bones.get(roles.head):
|
|
# No feet — fall back to the head, and accept the risk above.
|
|
ref = hips_b.head_local - (
|
|
arm.data.bones[roles.head].head_local - hips_b.head_local)
|
|
if hips_b and ref is not None:
|
|
d = hips_b.head_local - ref
|
|
k = max(range(3), key=lambda i: abs(d[i]))
|
|
src = Vector((0.0, 0.0, 0.0))
|
|
src[k] = 1.0 if d[k] > 0 else -1.0
|
|
up = Vector((0.0, 0.0, 1.0))
|
|
if src.dot(up) < 0.999:
|
|
axis = src.cross(up)
|
|
if axis.length < 1e-6:
|
|
axis = Vector((1.0, 0.0, 0.0)) # upside down
|
|
R = Matrix.Rotation(src.angle(up), 4, axis.normalized())
|
|
for obj in [arm] + meshes:
|
|
obj.matrix_world = R @ obj.matrix_world
|
|
apply_all()
|
|
print(f"Stood the character up: feet->hips ran along "
|
|
f"{'XYZ'[k]}{'+' if d[k] > 0 else '-'}, rotated to Z+")
|
|
|
|
lo = Vector((1e9, 1e9, 1e9))
|
|
hi = -lo.copy()
|
|
for m in meshes:
|
|
for corner in m.bound_box:
|
|
p = m.matrix_world @ Vector(corner)
|
|
lo = Vector((min(lo.x, p.x), min(lo.y, p.y), min(lo.z, p.z)))
|
|
hi = Vector((max(hi.x, p.x), max(hi.y, p.y), max(hi.z, p.z)))
|
|
height = hi.z - lo.z
|
|
if height > 1e-4:
|
|
s = target_height / height
|
|
for obj in [arm] + meshes:
|
|
obj.scale = (s, s, s)
|
|
apply_all()
|
|
lo *= s
|
|
hi *= s
|
|
print(f"Scaled by {s:.4f} to {target_height:.2f} m")
|
|
|
|
offset = Vector((-(lo.x + hi.x) * 0.5, -(lo.y + hi.y) * 0.5, -lo.z))
|
|
for obj in [arm] + meshes:
|
|
obj.location = offset
|
|
apply_all()
|
|
|
|
# Re-parent meshes under the armature so the export writes one clean skin.
|
|
for m in meshes:
|
|
m.parent = arm
|
|
m.matrix_parent_inverse = Matrix()
|
|
if not any(mod.type == "ARMATURE" and mod.object is arm for mod in m.modifiers):
|
|
mod = m.modifiers.new("Armature", "ARMATURE")
|
|
mod.object = arm
|
|
|
|
|
|
def fix_unlit_materials(meshes):
|
|
"""Route each material's texture into Base Color.
|
|
|
|
Anime models are commonly authored UNLIT: black base colour with the albedo
|
|
wired to emission. Our toon shader reads ALBEDO, so left alone the
|
|
character renders pitch black.
|
|
"""
|
|
seen = set()
|
|
for m in meshes:
|
|
for mat in m.data.materials:
|
|
if not mat or not mat.use_nodes or mat.name in seen:
|
|
continue
|
|
seen.add(mat.name)
|
|
nt = mat.node_tree
|
|
tex = next((n for n in nt.nodes if n.type == "TEX_IMAGE" and n.image), None)
|
|
bsdf = next((n for n in nt.nodes if n.type == "BSDF_PRINCIPLED"), None)
|
|
if not bsdf or not tex:
|
|
continue
|
|
base = bsdf.inputs["Base Color"]
|
|
if not base.links:
|
|
nt.links.new(tex.outputs["Color"], base)
|
|
print(f"Material '{mat.name}': routed '{tex.image.name}' to base colour")
|
|
if "Emission Strength" in bsdf.inputs:
|
|
bsdf.inputs["Emission Strength"].default_value = 0.0
|
|
|
|
|
|
# ------------------------------------------------------------------ retarget
|
|
|
|
|
|
def world_rest(arm):
|
|
mw = arm.matrix_world
|
|
return {b.name: mw @ b.matrix_local for b in arm.data.bones}
|
|
|
|
|
|
def rig_forward(arm, roles):
|
|
"""Which way the rest pose faces, on the ground plane, from the feet."""
|
|
mw = arm.matrix_world
|
|
acc = Vector((0.0, 0.0, 0.0))
|
|
for side in ("L", "R"):
|
|
for role in ("toe", "foot"):
|
|
name = roles.limb.get((role, side))
|
|
if not name:
|
|
continue
|
|
b = arm.data.bones[name]
|
|
v = (mw @ b.tail_local) - (mw @ b.matrix_local.translation)
|
|
v.z = 0.0
|
|
if v.length > 1e-5:
|
|
acc += v.normalized()
|
|
break
|
|
return acc.normalized() if acc.length > 1e-5 else None
|
|
|
|
|
|
def facing_correction(src_arm, src_roles, tgt_arm, tgt_roles):
|
|
"""Yaw that carries the source rig's forward onto the target's.
|
|
|
|
Without it a library that rests facing -Y drives a character that rests
|
|
facing +Y and every clip plays backwards.
|
|
"""
|
|
a = rig_forward(src_arm, src_roles)
|
|
b = rig_forward(tgt_arm, tgt_roles)
|
|
if a is None or b is None:
|
|
return Quaternion()
|
|
# angle_signed is 2D-only in mathutils, which is what we want anyway: the
|
|
# correction is a yaw about world up, never a tilt.
|
|
angle = Vector((a.x, a.y)).angle_signed(Vector((b.x, b.y)), 0.0)
|
|
if abs(angle) < 1e-4:
|
|
return Quaternion()
|
|
print(f"Facing correction: {angle * 57.2958:.1f} deg")
|
|
return Quaternion(UP, angle)
|
|
|
|
|
|
def bone_order(arm):
|
|
"""Every bone, parents before children."""
|
|
out = []
|
|
|
|
def walk(b):
|
|
out.append(b.name)
|
|
for c in b.children:
|
|
walk(c)
|
|
|
|
for b in arm.data.bones:
|
|
if b.parent is None:
|
|
walk(b)
|
|
return out
|
|
|
|
|
|
def solve_pose(arm, order, rest_w, desired_rot, hips, hips_head):
|
|
"""Turn desired WORLD orientations into per-bone local basis transforms.
|
|
|
|
Done arithmetically rather than by setting `pose_bone.matrix` and letting
|
|
Blender solve, because that needs a depsgraph update per bone — 150 bones
|
|
across 18 clips is tens of thousands of scene evaluations.
|
|
|
|
Blender relates pose to rest as
|
|
pose = parent_pose * parent_rest^-1 * rest * basis
|
|
so with M standing for everything left of `basis`, a rotation-only basis of
|
|
M.rot^-1 * desired lands the bone on `desired` exactly.
|
|
"""
|
|
pose_w = {}
|
|
basis = {}
|
|
bones = arm.data.bones
|
|
for name in order:
|
|
b = bones[name]
|
|
rest = rest_w[name]
|
|
if b.parent is not None:
|
|
M = pose_w[b.parent.name] @ rest_w[b.parent.name].inverted() @ rest
|
|
else:
|
|
M = rest
|
|
q = Quaternion()
|
|
if name in desired_rot:
|
|
q = M.to_quaternion().inverted() @ desired_rot[name]
|
|
loc = Vector((0.0, 0.0, 0.0))
|
|
if name == hips and hips_head is not None:
|
|
loc = M.inverted() @ hips_head
|
|
basis[name] = (loc, q)
|
|
pose_w[name] = M @ Matrix.Translation(loc) @ q.to_matrix().to_4x4()
|
|
return basis
|
|
|
|
|
|
def retarget_clip(src_arm, src_roles, tgt_arm, tgt_roles, mapping, action,
|
|
clip_name, yaw, scale):
|
|
src_rest = world_rest(src_arm)
|
|
tgt_rest = world_rest(tgt_arm)
|
|
order = bone_order(tgt_arm)
|
|
src_rest_rot = {n: m.to_quaternion() for n, m in src_rest.items()}
|
|
tgt_rest_rot = {n: m.to_quaternion() for n, m in tgt_rest.items()}
|
|
yaw_inv = yaw.inverted()
|
|
|
|
src_hips = src_roles.hips
|
|
tgt_hips = tgt_roles.hips
|
|
src_hips_rest = src_rest[src_hips].translation.copy()
|
|
tgt_hips_rest = tgt_rest[tgt_hips].translation.copy()
|
|
|
|
assign_action(src_arm, action)
|
|
f0, f1 = (int(round(v)) for v in action.frame_range)
|
|
|
|
baked = bpy.data.actions.new(clip_name)
|
|
assign_action(tgt_arm, baked)
|
|
for pb in tgt_arm.pose.bones:
|
|
pb.rotation_mode = "QUATERNION"
|
|
|
|
scene = bpy.context.scene
|
|
for frame in range(f0, f1 + 1):
|
|
scene.frame_set(frame)
|
|
dg = bpy.context.evaluated_depsgraph_get()
|
|
src_eval = src_arm.evaluated_get(dg)
|
|
smw = src_eval.matrix_world
|
|
|
|
desired = {}
|
|
for tgt_name, src_name in mapping.items():
|
|
if src_name not in src_eval.pose.bones or tgt_name not in tgt_rest_rot:
|
|
continue
|
|
pose_rot = (smw @ src_eval.pose.bones[src_name].matrix).to_quaternion()
|
|
delta = pose_rot @ src_rest_rot[src_name].inverted()
|
|
desired[tgt_name] = (yaw @ delta @ yaw_inv) @ tgt_rest_rot[tgt_name]
|
|
|
|
hips_head = None
|
|
if src_hips in src_eval.pose.bones:
|
|
moved = (smw @ src_eval.pose.bones[src_hips].matrix).translation
|
|
d = yaw @ ((moved - src_hips_rest) * scale)
|
|
if STRIP_ROOT_MOTION:
|
|
d.x = 0.0
|
|
d.y = 0.0 # gameplay code moves the body; keep the vertical bob
|
|
hips_head = tgt_hips_rest + d
|
|
|
|
basis = solve_pose(tgt_arm, order, tgt_rest, desired, tgt_hips, hips_head)
|
|
for name in mapping:
|
|
if name not in basis:
|
|
continue
|
|
pb = tgt_arm.pose.bones[name]
|
|
pb.rotation_quaternion = basis[name][1]
|
|
pb.keyframe_insert("rotation_quaternion", frame=frame)
|
|
if hips_head is not None:
|
|
pb = tgt_arm.pose.bones[tgt_hips]
|
|
pb.location = basis[tgt_hips][0]
|
|
pb.keyframe_insert("location", frame=frame)
|
|
|
|
assign_action(tgt_arm, None)
|
|
return baked
|
|
|
|
|
|
def assign_action(obj, action):
|
|
if not obj.animation_data:
|
|
obj.animation_data_create()
|
|
obj.animation_data.action = action
|
|
if action is None:
|
|
return
|
|
try: # Blender 4.4+ slotted actions
|
|
if not obj.animation_data.action_slot and len(action.slots):
|
|
obj.animation_data.action_slot = action.slots[0]
|
|
except (AttributeError, TypeError):
|
|
pass
|
|
|
|
|
|
def add_nla_clip(arm, action, name):
|
|
action.name = name
|
|
track = arm.animation_data.nla_tracks.new()
|
|
track.name = name
|
|
strip = track.strips.new(name, 0, action)
|
|
strip.name = name
|
|
track.mute = True
|
|
action.use_fake_user = True
|
|
|
|
|
|
# -------------------------------------------------------------------- sidecar
|
|
|
|
|
|
def _dominant_vertices(meshes, arm, min_weight=0.25):
|
|
"""bone name -> world positions of the vertices it mostly owns.
|
|
|
|
"Mostly" as in holds the largest share — a vertex belongs to one bone for
|
|
the purpose of measuring what that bone covers, even though it is skinned
|
|
to several.
|
|
|
|
`min_weight` is how strongly a vertex must belong to its bone to count.
|
|
The collider pass raises it: a vertex split 0.3/0.3/0.4 across hip, thigh
|
|
and glute is a BLEND, and letting those in put the hip flare back into the
|
|
thigh's band samples — the fitted capsule came out 0.18 m at the head.
|
|
"""
|
|
out = defaultdict(list)
|
|
for m in meshes:
|
|
gname = {g.index: g.name for g in m.vertex_groups}
|
|
mw = m.matrix_world
|
|
for v in m.data.vertices:
|
|
best = None
|
|
for g in v.groups:
|
|
if best is None or g.weight > best.weight:
|
|
best = g
|
|
if best is not None and best.weight > min_weight:
|
|
out[gname.get(best.group, "")].append(mw @ v.co)
|
|
return out
|
|
|
|
|
|
def _bone_tip(arm, bone, chain, index, owned, fallback):
|
|
"""Where a bone effectively points, in its own rest space.
|
|
|
|
The next bone along when there is one. Otherwise the centroid of the
|
|
geometry this bone actually drives — which is the only real answer for
|
|
Taila's skirt, whose 21 panel bones export with no children and no usable
|
|
tail, so there is nothing in the skeleton to say which way a panel hangs.
|
|
"""
|
|
rest_world = arm.matrix_world @ arm.data.bones[bone].matrix_local
|
|
if index + 1 < len(chain):
|
|
nxt = arm.matrix_world @ arm.data.bones[chain[index + 1]].matrix_local
|
|
return rest_world.inverted() @ nxt.translation
|
|
pts = owned.get(bone, [])
|
|
if pts:
|
|
centroid = sum(pts, Vector((0.0, 0.0, 0.0))) / len(pts)
|
|
local = rest_world.inverted() @ centroid
|
|
# The centroid sits mid-panel, so the far edge is roughly twice out.
|
|
if local.length > 1e-4:
|
|
return local * 2.0
|
|
return fallback
|
|
|
|
|
|
def _hull_samples(arm, bone, owned, limit=10):
|
|
"""A few points spread across the geometry a cloth bone actually drives,
|
|
in that bone's own rest space.
|
|
|
|
The runtime collides THESE, not points along the bone. A skirt panel is a
|
|
wide sheet hanging off a single stick from the waist, so keeping the stick
|
|
out of the thigh is nearly meaningless: measured over a movement sweep, the
|
|
bones were clear by ~1 mm while the leg was 85 mm inside the skirt MESH with
|
|
190 vertices swallowed.
|
|
|
|
Chosen by farthest-point sampling so the handful of points spans the panel
|
|
(edges, hem, middle) instead of clustering wherever the mesh is dense.
|
|
"""
|
|
pts = owned.get(bone, [])
|
|
if len(pts) < 4:
|
|
return []
|
|
inv = (arm.matrix_world @ arm.data.bones[bone].matrix_local).inverted()
|
|
local = [inv @ p for p in pts]
|
|
picked = [max(local, key=lambda v: v.length)]
|
|
while len(picked) < min(limit, len(local)):
|
|
far = max(local, key=lambda v: min((v - q).length for q in picked))
|
|
if min((far - q).length for q in picked) < 1e-4:
|
|
break
|
|
picked.append(far)
|
|
return [[round(v.x, 5), round(v.y, 5), round(v.z, 5)] for v in picked]
|
|
|
|
|
|
# How far off the skin a garment sits — its own thickness, plus the fact that
|
|
# cloth drapes over a limb rather than being painted onto it.
|
|
CLOTH_CLEARANCE = 0.008
|
|
|
|
|
|
def _pct(sorted_values, p):
|
|
"""Value at percentile `p` of an already-sorted list."""
|
|
i = int(round(p * (len(sorted_values) - 1)))
|
|
return sorted_values[max(0, min(len(sorted_values) - 1, i))]
|
|
|
|
|
|
def _body_points(meshes):
|
|
"""Every skinned vertex that is NOT cloth, in world space.
|
|
|
|
The waist lid is sized from these. Including the garment measured the skirt
|
|
itself — a 0.24 m radius that would have held it out in a bell.
|
|
"""
|
|
out = []
|
|
for m in meshes:
|
|
gname = {g.index: g.name for g in m.vertex_groups}
|
|
mw = m.matrix_world
|
|
for v in m.data.vertices:
|
|
cloth_w = sum(g.weight for g in v.groups
|
|
if spring_class(gname.get(g.group, "")))
|
|
if cloth_w < 0.35:
|
|
out.append(mw @ v.co)
|
|
return out
|
|
|
|
|
|
def _leg_colliders(arm, roles, owned, body_pts=None):
|
|
"""TAPERED capsules for the legs, sized from the body geometry itself.
|
|
|
|
The skirt has to be kept off the thighs, and a guessed radius either lets it
|
|
clip through or holds it out in a bell. Three things the obvious version got
|
|
wrong, all measured on Taila:
|
|
|
|
* A limb is not a cylinder. Her thigh is ~0.10 m across at the hip and
|
|
~0.055 m just above the knee, so one radius is either too fat at the knee
|
|
or too thin at the hip. Head and tail radii are stored separately and
|
|
interpolated at runtime.
|
|
* A leg's own vertices are not the leg. Most of the thigh belongs to the
|
|
TWIST bone (`DEF-thigh.L.001`); what is left dominated by `DEF-thigh.L`
|
|
is mostly the hip flare, which measured a 0.154 m radius — a 30 cm thigh.
|
|
Twist children are folded in.
|
|
* Neither a low percentile nor a high one works on a POOLED bucket. The
|
|
70th tracked that flare; the median then left half the limb's surface
|
|
outside its own collider, so cloth pushed out to it was clear of the
|
|
capsule while the thigh was visibly through it in the render; and the
|
|
88th over-measured the shaft by 30% because the top bucket still holds
|
|
the hip. Measured per band along the bone instead and fitted as the line
|
|
it actually is, dropping the contaminated end bands.
|
|
* Garments have thickness and hang OFF a leg rather than painted onto it,
|
|
so a small clearance is added on top. Without it the cloth's rest state
|
|
is exactly tangent to the limb and every frame is a contact.
|
|
"""
|
|
names = set(b.name for b in arm.data.bones)
|
|
out = []
|
|
# A LID across the waist first.
|
|
#
|
|
# Magica Cloth 2's skirt guide is blunt about this: put "one big sphere
|
|
# collider on your waist", because it "acts as a lid that prevents particles
|
|
# in the skirt from slipping into the body". Leg capsules alone only stop
|
|
# cloth going through a thigh — nothing stops a panel being swung INWARD
|
|
# between the legs and ending up inside the pelvis, which is where several
|
|
# of the worst contacts here were sitting.
|
|
trunk = [roles.hips] + [n for n in roles.spine if n != roles.hips]
|
|
if len(trunk) >= 2 and trunk[0] in names and trunk[1] in names:
|
|
a = (arm.matrix_world @ arm.data.bones[trunk[0]].matrix_local).translation
|
|
b = (arm.matrix_world @ arm.data.bones[trunk[1]].matrix_local).translation
|
|
# Sized from the geometry that actually surrounds the pelvis, not from
|
|
# the hip bone's own vertices: on a Rigify rig the hips own almost
|
|
# nothing (2 vertices here, and spine.001 none) because the torso
|
|
# belongs to spine.002, so there is nothing there to measure.
|
|
ab = b - a
|
|
d2 = ab.dot(ab)
|
|
pts = []
|
|
if d2 > 1e-9:
|
|
for p in (body_pts or []):
|
|
t = (p - a).dot(ab) / d2
|
|
if 0.0 <= t <= 1.0:
|
|
pts.append(p)
|
|
if len(pts) >= 12:
|
|
rr = sorted(_seg_distance(p, a, b) for p in pts)
|
|
# 60th percentile, not the 90th used for limbs: the lid only has to
|
|
# stop cloth being swung INTO the body. Sized to the widest thing
|
|
# near the hips it would hold the whole skirt out in a bell.
|
|
r = _pct(rr, 0.60) + CLOTH_CLEARANCE
|
|
out.append({
|
|
"bone": trunk[0], "child": trunk[1],
|
|
"from": 0.0,
|
|
"radius_head": round(r, 4),
|
|
"radius_tail": round(r, 4),
|
|
"radius": round(r, 4),
|
|
# A lid is something to stay OUT of, not a limb to be carried by.
|
|
"lid": True,
|
|
})
|
|
|
|
for role, child_role in (("thigh", "shin"), ("shin", "foot")):
|
|
for side in ("L", "R"):
|
|
name = roles.limb.get((role, side))
|
|
child = roles.limb.get((child_role, side))
|
|
if not name or not child:
|
|
continue
|
|
a = (arm.matrix_world @ arm.data.bones[name].matrix_local).translation
|
|
b = (arm.matrix_world @ arm.data.bones[child].matrix_local).translation
|
|
ab = b - a
|
|
d2 = ab.dot(ab)
|
|
if d2 < 1e-9:
|
|
continue
|
|
# This bone plus any twist segment hanging off it — together they
|
|
# are the limb.
|
|
pts = list(owned.get(name, []))
|
|
for other in names:
|
|
if other != name and other.startswith(name + ".") \
|
|
and is_segment_of(other, names):
|
|
pts.extend(owned.get(other, []))
|
|
if len(pts) < 12:
|
|
continue
|
|
|
|
# A limb is a TAPER, so measure it as one. Ten bands along the
|
|
# bone, the 90th percentile radius in each, and a least-squares
|
|
# line through them. Two pooled buckets could not do this: the top
|
|
# bucket is contaminated by the hip flare and the bottom one by the
|
|
# knee and boot, so whatever percentile was chosen came out wrong
|
|
# at one end or the other — a median under-measured the limb by
|
|
# half its surface, and a high percentile over-measured it by 30%
|
|
# along the whole shaft. The two end bands are dropped for exactly
|
|
# that reason; the fit extrapolates back through them.
|
|
bands = [[] for _ in range(10)]
|
|
for p in pts:
|
|
t = max(0.0, min(1.0, (p - a).dot(ab) / d2))
|
|
bands[min(int(t * 10.0), 9)].append(_seg_distance(p, a, b))
|
|
samples = []
|
|
for k in range(1, 9):
|
|
if len(bands[k]) < 3:
|
|
continue
|
|
bands[k].sort()
|
|
samples.append(((k + 0.5) / 10.0, _pct(bands[k], 0.90)))
|
|
if len(samples) < 3:
|
|
continue
|
|
n = len(samples)
|
|
mt = sum(t for t, _ in samples) / n
|
|
mr = sum(r for _, r in samples) / n
|
|
den = sum((t - mt) ** 2 for t, _ in samples)
|
|
slope = sum((t - mt) * (r - mr) for t, r in samples) / den if den > 1e-9 else 0.0
|
|
head = mr + slope * (0.0 - mt) + CLOTH_CLEARANCE
|
|
tail = mr + slope * (1.0 - mt) + CLOTH_CLEARANCE
|
|
# A limb never widens toward the joint below it, and a fit through
|
|
# noisy bands occasionally says otherwise.
|
|
tail = max(0.01, min(tail, head))
|
|
head = max(head, tail)
|
|
# The capsule starts BELOW the hip joint.
|
|
#
|
|
# The top of a thigh is not a free limb, it is the hip, and it is
|
|
# buried inside the body the skirt hangs from. Colliding against it
|
|
# asks the solver for something it cannot do: those cloth points sit
|
|
# 20-30 mm from their own bone's head, and rotating a bone moves a
|
|
# point near its pivot by almost nothing — measured, 24 mm of lever
|
|
# against 86 mm of overlap, where the most any rotation can achieve
|
|
# is twice the lever. The solver spent all six passes saturated at
|
|
# its per-pass cap and still left 60-90 mm.
|
|
#
|
|
# Only the sphere cap buried in the pelvis is cut. The upper thigh
|
|
# itself stays covered, because the runtime can also SHIFT a chain
|
|
# bodily (SpringBones.PUSH_MAX) and a shift does not care how much
|
|
# lever the bone has: rotation handles the contacts with leverage,
|
|
# translation handles the ones without. Trimming 30% instead of 10%
|
|
# stopped the solver even trying across the top of the thigh, and
|
|
# that band is exactly what then showed through the skirt.
|
|
head_t = 0.10
|
|
out.append({
|
|
"bone": name, "child": child,
|
|
"from": head_t,
|
|
"radius_head": round(head + (tail - head) * head_t, 4),
|
|
"radius_tail": round(tail, 4),
|
|
# Kept so an older runtime still gets a usable single radius.
|
|
"radius": round(tail, 4),
|
|
})
|
|
return out
|
|
|
|
|
|
def _cloth_neighbours(meshes, cloth_names):
|
|
"""bone -> {neighbouring bone: how strongly they share the same mesh}.
|
|
|
|
Two cloth bones are neighbours when the SAME VERTICES are weighted to both.
|
|
That is the only definition that matters here: a vertex driven half by one
|
|
skirt panel and half by the next is the piece of mesh that has to absorb any
|
|
difference between them, and linear-blend skinning absorbs it by pulling
|
|
itself apart. Measured with debug/cloth_stretch_check.gd, adjacent panels
|
|
taking drape shares of 0.85 and 0.48 stretched the edge between them to 3.3x
|
|
its rest length — an 80 mm hole in the front of the skirt, which is the
|
|
skirt "breaking" around the thigh rather than deforming over it.
|
|
|
|
Adjacency by NAME or by rest distance would both be guesses; the artist
|
|
already answered the question in the weights.
|
|
"""
|
|
shared = defaultdict(lambda: defaultdict(float))
|
|
for m in meshes:
|
|
gname = {g.index: g.name for g in m.vertex_groups}
|
|
for v in m.data.vertices:
|
|
here = [(gname.get(g.group, ""), g.weight) for g in v.groups
|
|
if gname.get(g.group, "") in cloth_names and g.weight > 0.05]
|
|
for a_name, aw in here:
|
|
for b_name, bw in here:
|
|
if a_name != b_name:
|
|
shared[a_name][b_name] += aw * bw
|
|
return {a: dict(d) for a, d in shared.items()}
|
|
|
|
|
|
def describe_rig(arm, roles, mapping, meshes):
|
|
"""Record what we worked out, so the runtime never re-guesses anatomy."""
|
|
names = set(b.name for b in arm.data.bones)
|
|
owned = _dominant_vertices(meshes, arm)
|
|
roles_out = {"hips": roles.hips, "head": roles.head, "neck": roles.neck,
|
|
"spine": list(roles.spine)}
|
|
for (role, side), name in roles.limb.items():
|
|
roles_out[f"{role}.{side}"] = name
|
|
|
|
driven = set(mapping)
|
|
chains = []
|
|
springy = {b.name: b for b in arm.data.bones
|
|
if b.name not in driven
|
|
and spring_class(b.name)}
|
|
neighbours = _cloth_neighbours(meshes, set(springy))
|
|
|
|
for name, bone in springy.items():
|
|
if bone.parent is not None and bone.parent.name in springy:
|
|
continue # not the root of a chain
|
|
# One chain per leaf path, so each strand solves independently.
|
|
stack = [[name]]
|
|
while stack:
|
|
path = stack.pop()
|
|
kids = [c.name for c in arm.data.bones[path[-1]].children
|
|
if c.name in springy]
|
|
if not kids:
|
|
tips = []
|
|
hulls = []
|
|
fallback = Vector((0.0, 0.0, -0.06))
|
|
for i in range(len(path)):
|
|
t = _bone_tip(arm, path[i], path, i, owned, fallback)
|
|
tips.append([round(t.x, 5), round(t.y, 5), round(t.z, 5)])
|
|
hulls.append(_hull_samples(arm, path[i], owned))
|
|
fallback = t
|
|
chains.append({
|
|
"class": spring_class(path[0]) or "cloth",
|
|
"root_parent": bone.parent.name if bone.parent else None,
|
|
"bones": path,
|
|
"tips": tips,
|
|
"hulls": hulls,
|
|
# Which other cloth bones share mesh with each of these,
|
|
# so the runtime can stop neighbours drifting apart. See
|
|
# _cloth_neighbours.
|
|
"neighbours": [neighbours.get(n, {}) for n in path],
|
|
})
|
|
continue
|
|
for k in kids:
|
|
stack.append(path + [k])
|
|
|
|
# Twist bones only — a hair link is also `X.001`, but it is cloth, and
|
|
# listing it here would have the twist distributor and the spring solver
|
|
# both writing the same bone.
|
|
twist = []
|
|
for b in arm.data.bones:
|
|
if b.name in driven or is_cosmetic(b.name) or not is_segment_of(b.name, names):
|
|
continue
|
|
if b.parent is not None:
|
|
twist.append({"bone": b.name, "parent": b.parent.name,
|
|
"child": b.children[0].name if b.children else None})
|
|
return {"roles": roles_out, "chains": chains, "twist": twist,
|
|
"colliders": _leg_colliders(
|
|
arm, roles, _dominant_vertices(meshes, arm, min_weight=0.6),
|
|
_body_points(meshes)),
|
|
"weights_authored": _weights_look_authored(meshes, roles),
|
|
"driven_bones": sorted(driven)}
|
|
|
|
|
|
def _weights_look_authored(meshes, roles):
|
|
"""Were these weights painted, or solved by a nearest-bone fit?
|
|
|
|
The runtime decides from this whether to run its destructive load-time
|
|
weight repair, so it is MEASURED rather than inferred from which pipeline
|
|
branch ran — a model that arrives unrigged still goes through autorig and
|
|
out through this same tool, and must not be handed a sidecar that says its
|
|
weights are fine when they are not.
|
|
|
|
Two signatures, both taken from the shipped-vs-source comparison that
|
|
started this rework: the nearest-four-bones fit left 16% of vertices pulled
|
|
by BOTH legs and gave 86% of them the full four influences, where the
|
|
artist's own weights had 0.1% and 26%.
|
|
"""
|
|
legs = {}
|
|
for (role, side), name in roles.limb.items():
|
|
if role in ("thigh", "shin", "foot", "toe"):
|
|
legs[name] = -1 if side == "L" else 1
|
|
|
|
def side_of(group_name):
|
|
for name, s in legs.items():
|
|
if group_name == name or group_name.startswith(name + "."):
|
|
return s
|
|
return 0
|
|
|
|
total = 0
|
|
bleeding = 0
|
|
four = 0
|
|
for m in meshes:
|
|
gside = {g.index: side_of(g.name) for g in m.vertex_groups}
|
|
for v in m.data.vertices:
|
|
wl = wr = 0.0
|
|
n = 0
|
|
for g in v.groups:
|
|
if g.weight <= 0.005:
|
|
continue
|
|
n += 1
|
|
s = gside.get(g.group, 0)
|
|
if s == -1:
|
|
wl += g.weight
|
|
elif s == 1:
|
|
wr += g.weight
|
|
total += 1
|
|
if n >= 4:
|
|
four += 1
|
|
if wl > 0.005 and wr > 0.005:
|
|
bleeding += 1
|
|
if total == 0:
|
|
return False
|
|
authored = bleeding / total < 0.02 and four / total < 0.5
|
|
print(f"Weights: {bleeding} cross-leg ({bleeding / total * 100:.1f}%), "
|
|
f"{four / total * 100:.0f}% at four influences — "
|
|
f"{'authored' if authored else 'solved, runtime repair stays on'}")
|
|
return authored
|
|
|
|
|
|
# ------------------------------------------------------------------------ main
|
|
|
|
|
|
def main():
|
|
clear_scene()
|
|
print(f"Importing character {CHARACTER}")
|
|
# Normalise emissive-albedo materials FIRST. Blender honours
|
|
# KHR_materials_unlit and reads only base colour, so an unlit model with its
|
|
# texture in the emissive slot imports with no images at all and exports a
|
|
# black silhouette — there is no node graph left to repair afterwards.
|
|
import_any(gltf_fix.prepare(CHARACTER, tempfile.gettempdir()))
|
|
arms = [o for o in bpy.data.objects if o.type == "ARMATURE"]
|
|
if not arms:
|
|
print("ERROR: character has no armature. Rig it first (see docs/3D_ASSET_PIPELINE.md).")
|
|
sys.exit(1)
|
|
arm = max(arms, key=lambda a: len(a.data.bones))
|
|
meshes = skinned_meshes(arm)
|
|
if not meshes:
|
|
print("ERROR: no skinned meshes bound to the armature")
|
|
sys.exit(1)
|
|
for o in [o for o in bpy.data.objects if o.type == "MESH" and o not in meshes]:
|
|
print(f"Dropping unskinned prop mesh: {o.name}")
|
|
bpy.data.objects.remove(o, do_unlink=True)
|
|
print(f"Character: {len(arm.data.bones)} bones, {len(meshes)} meshes "
|
|
f"({sum(len(m.data.vertices) for m in meshes)} verts) — weights kept as authored")
|
|
|
|
strip_import_suffixes(arm, meshes)
|
|
for a in list(bpy.data.actions):
|
|
bpy.data.actions.remove(a) # the character's own clip is not ours
|
|
|
|
roles = RigRoles(arm)
|
|
missing = roles.missing_core()
|
|
if missing:
|
|
print(f"ERROR: could not identify these bones on the character rig: {missing}")
|
|
print("Resolved so far:\n" + roles.describe())
|
|
sys.exit(1)
|
|
rebuild_hierarchy(arm, roles)
|
|
subdivide_cloth_panels(arm, meshes, roles)
|
|
unbind_cloth_from_legs(arm, meshes, roles)
|
|
flatten_and_scale(arm, meshes, TARGET_HEIGHT, roles)
|
|
fix_unlit_materials(meshes)
|
|
roles = RigRoles(arm) # rest positions moved; re-read
|
|
|
|
library = os.path.join(ANIM_DIR, "_library.glb")
|
|
if not os.path.exists(library):
|
|
print(f"ERROR: animation library not found: {library}")
|
|
sys.exit(1)
|
|
before = set(bpy.data.objects)
|
|
before_actions = set(bpy.data.actions)
|
|
bpy.ops.import_scene.gltf(filepath=library)
|
|
new_objects = [o for o in bpy.data.objects if o not in before]
|
|
src_arm = next((o for o in new_objects if o.type == "ARMATURE"), None)
|
|
if not src_arm:
|
|
print("ERROR: no armature in the animation library")
|
|
sys.exit(1)
|
|
src_roles = RigRoles(src_arm)
|
|
|
|
mapping = build_map(src_roles, roles, OVERRIDES)
|
|
print("\nLibrary rig:\n" + src_roles.describe())
|
|
print("\nCharacter rig:\n" + roles.describe())
|
|
print(f"\nDriving {len(mapping)} of {len(arm.data.bones)} bones from the library; "
|
|
f"{len(arm.data.bones) - len(mapping)} left free for secondary motion.")
|
|
|
|
yaw = facing_correction(src_arm, src_roles, arm, roles)
|
|
src_h = (src_arm.matrix_world @ src_arm.data.bones[src_roles.hips].matrix_local).translation.z
|
|
tgt_h = (arm.matrix_world @ arm.data.bones[roles.hips].matrix_local).translation.z
|
|
scale = tgt_h / src_h if src_h > 1e-5 else 1.0
|
|
print(f"Hips height: library {src_h:.3f} m, character {tgt_h:.3f} m (scale {scale:.3f})")
|
|
|
|
if not arm.animation_data:
|
|
arm.animation_data_create()
|
|
for track in list(arm.animation_data.nla_tracks):
|
|
arm.animation_data.nla_tracks.remove(track)
|
|
|
|
merged = 0
|
|
kept_clips = set()
|
|
for action in [a for a in bpy.data.actions if a not in before_actions]:
|
|
clip = LIBRARY_CLIP_MAP.get(action.name.split(".")[0])
|
|
if not clip:
|
|
continue
|
|
print(f" {action.name} -> {clip}")
|
|
baked = retarget_clip(src_arm, src_roles, arm, roles, mapping, action,
|
|
clip, yaw, scale)
|
|
add_nla_clip(arm, baked, clip)
|
|
kept_clips.add(clip)
|
|
merged += 1
|
|
if merged == 0:
|
|
print("ERROR: no clips retargeted")
|
|
sys.exit(1)
|
|
|
|
# Drop anything animated that we did not put here.
|
|
#
|
|
# Clearing bpy.data.actions before the library import is not enough: a
|
|
# character can carry its own clip in an NLA track that survives, and it is
|
|
# then exported alongside ours. `hikari` shipped two — " Girl|Loli Anime
|
|
# GirlAction" — which are keyed for a rig that no longer exists after the
|
|
# retarget, so they export as frozen rest-pose statues and the build fails a
|
|
# check that is right to fail it.
|
|
# Across EVERY object, not just the armature we retargeted onto. The export
|
|
# runs in NLA_TRACKS mode, so anything sitting in an NLA track anywhere in
|
|
# the file ships — including a second armature the model happened to carry,
|
|
# which is where hikari's two were hiding.
|
|
def _strip_foreign(ad):
|
|
if ad is None:
|
|
return
|
|
for track in list(ad.nla_tracks):
|
|
if not any(st.action and st.action.name in kept_clips
|
|
for st in track.strips):
|
|
ad.nla_tracks.remove(track)
|
|
if ad.action is not None and ad.action.name not in kept_clips:
|
|
ad.action = None
|
|
|
|
for obj in list(bpy.data.objects):
|
|
_strip_foreign(obj.animation_data)
|
|
if obj.type == "MESH" and obj.data.shape_keys:
|
|
_strip_foreign(obj.data.shape_keys.animation_data)
|
|
for a in list(bpy.data.actions):
|
|
if a.name not in kept_clips:
|
|
a.use_fake_user = False
|
|
bpy.data.actions.remove(a)
|
|
print(f"Kept {len(kept_clips)} clips; dropped everything else")
|
|
|
|
for o in new_objects:
|
|
bpy.data.objects.remove(o, do_unlink=True)
|
|
|
|
os.makedirs(os.path.dirname(os.path.abspath(OUTPUT)), exist_ok=True)
|
|
sidecar = os.path.splitext(OUTPUT)[0] + ".rig.json"
|
|
info = describe_rig(arm, roles, mapping, meshes)
|
|
with open(sidecar, "w", encoding="utf-8") as f:
|
|
json.dump(info, f, indent=2)
|
|
print(f"Wrote {os.path.basename(sidecar)}: {len(info['chains'])} cloth chains, "
|
|
f"{len(info['twist'])} twist bones, {len(info['colliders'])} leg colliders")
|
|
|
|
print(f"Merged {merged} clips. Exporting {OUTPUT}")
|
|
bpy.ops.export_scene.gltf(
|
|
filepath=OUTPUT,
|
|
export_format="GLB",
|
|
export_yup=True,
|
|
export_apply=False,
|
|
export_skins=True,
|
|
export_animations=True,
|
|
export_animation_mode="NLA_TRACKS",
|
|
# Export ONLY the bones the clips actually key. Baking every bone
|
|
# writes rest-pose tracks for the skirt and hair too, which triples the
|
|
# clip data and — worse — has the AnimationPlayer overwrite exactly the
|
|
# bones the spring solver is meant to own.
|
|
export_bake_animation=False,
|
|
export_optimize_animation_size=True,
|
|
# "keep_anim_armature" is what forces a track onto every bone whether
|
|
# or not the clip touches it. Off, so the skirt and hair export with no
|
|
# tracks at all and belong entirely to the spring solver.
|
|
export_optimize_animation_keep_anim_armature=False,
|
|
)
|
|
print("Done.")
|
|
|
|
|
|
|
|
|
|
def subdivide_cloth_panels(arm, meshes, roles, segments=4):
|
|
"""Split single-bone cloth panels into a CHAIN so they can bend.
|
|
|
|
A skirt panel modelled as one rigid bone off the waist cannot ride up over a
|
|
thigh, because riding up is a FOLD: the top of the panel stays at the waist
|
|
while the lower part lifts. One bone can only rotate the whole sheet about
|
|
the waist, so the hem swings forward while the middle stays put and the
|
|
thigh comes straight through it. No amount of collision or drape strength
|
|
fixes that — the degree of freedom does not exist.
|
|
|
|
Taila's skirt is 21 such bones (see rebuild_hierarchy: the panels export
|
|
flat, and their real 3-segment chains are not recoverable from the file).
|
|
So the segments are BUILT here: each panel bone gains `segments - 1`
|
|
children strung along the direction it actually covers, and the vertices it
|
|
drives are handed to whichever segment spans them. The runtime spring
|
|
solver already treats chains properly, so the lower segment can lift over
|
|
the leg while the top stays anchored.
|
|
|
|
SIX segments, not three. Magica Cloth 2's skirt guide: "if the bone position
|
|
deviates from the shape of the skirt, or if the bones are spaced too far
|
|
apart, the accuracy of collision detection will be significantly reduced."
|
|
That is measurable here — a collision is resolved by ROTATING a bone, which
|
|
moves a point at most twice its distance from that bone's head, and with
|
|
three segments the front panels had contacts sitting 10-48 mm from their own
|
|
pivot against a thigh 100 mm inside them. No amount of tuning can clear that;
|
|
the pivot has to be closer to the contact.
|
|
|
|
Runs before flatten_and_scale, in the source's own units.
|
|
"""
|
|
owned = _dominant_vertices(meshes, arm)
|
|
panels = []
|
|
for bone in arm.data.bones:
|
|
if not is_cosmetic(bone.name):
|
|
continue
|
|
cls = spring_class(bone.name)
|
|
if cls is None or cls == "hair":
|
|
continue
|
|
if bone.children:
|
|
continue # already a chain — the artist's own topology wins
|
|
pts = owned.get(bone.name, [])
|
|
if len(pts) < 12:
|
|
continue
|
|
rest = arm.matrix_world @ bone.matrix_local
|
|
tip = _bone_tip(arm, bone.name, [bone.name], 0, owned,
|
|
Vector((0.0, 0.0, -0.06)))
|
|
if tip.length < 1e-4:
|
|
continue
|
|
panels.append((bone.name, rest, tip))
|
|
if not panels:
|
|
return 0
|
|
|
|
bpy.context.view_layer.objects.active = arm
|
|
bpy.ops.object.mode_set(mode="EDIT")
|
|
eb = arm.data.edit_bones
|
|
made = {}
|
|
for name, rest, tip_local in panels:
|
|
parent = eb[name]
|
|
head = parent.head.copy()
|
|
step = (rest.to_3x3() @ tip_local) / segments
|
|
chain = [name]
|
|
prev = parent
|
|
for s in range(1, segments):
|
|
seg = eb.new("%s.seg%d" % (name, s))
|
|
seg.head = head + step * s
|
|
seg.tail = head + step * (s + 1)
|
|
seg.parent = prev
|
|
seg.use_connect = False
|
|
prev = seg
|
|
chain.append(seg.name)
|
|
parent.tail = head + step
|
|
made[name] = chain
|
|
bpy.ops.object.mode_set(mode="OBJECT")
|
|
|
|
# Spread each vertex across the TWO nearest segments, so the panel bends
|
|
# where the geometry is and the mesh stays continuous while it does.
|
|
#
|
|
# Handing every vertex to exactly one segment puts a hard cut through the
|
|
# sheet: the vertices either side of a segment boundary are then driven
|
|
# 100% by different bones, and the moment those bones rotate apart the mesh
|
|
# opens along that line. Measured with debug/cloth_stretch_check.gd over a
|
|
# movement sweep, an edge inside DEF-skirt.L.003 grew 270 mm — 11.7x its own
|
|
# rest length. That is the skirt visibly BREAKING around a thigh instead of
|
|
# stretching over it, and it looks nothing like a collision bug.
|
|
#
|
|
# Weighting to the two nearest segment CENTRES instead makes the transition
|
|
# linear, which is the same trick that stops a limb tearing at an elbow.
|
|
for m in meshes:
|
|
for name, chain in made.items():
|
|
vg = m.vertex_groups.get(name)
|
|
if vg is None:
|
|
continue
|
|
groups = [vg] + [m.vertex_groups.new(name=n) for n in chain[1:]]
|
|
rest = arm.matrix_world @ arm.data.bones[name].matrix_local
|
|
origin = rest.translation
|
|
axis = (rest.to_3x3() @ _bone_tip(
|
|
arm, name, [name], 0, owned, Vector((0.0, 0.0, -0.06))))
|
|
span = axis.length
|
|
if span < 1e-5:
|
|
continue
|
|
axis = axis / span
|
|
mw = m.matrix_world
|
|
for v in m.data.vertices:
|
|
w = 0.0
|
|
for g in v.groups:
|
|
if g.group == vg.index:
|
|
w = g.weight
|
|
if w <= 0.0:
|
|
continue
|
|
t = max(0.0, min(1.0, (mw @ v.co - origin).dot(axis) / span))
|
|
# Position measured in segment-CENTRE space: the ends of the
|
|
# panel sit on one segment outright, everything between is a
|
|
# blend of the two it lies between.
|
|
u = t * segments - 0.5
|
|
lo = int(math.floor(u))
|
|
f = u - lo
|
|
if lo < 0:
|
|
lo, f = 0, 0.0
|
|
elif lo >= segments - 1:
|
|
lo, f = segments - 1, 0.0
|
|
groups[0].remove([v.index])
|
|
if w * (1.0 - f) > 1e-5:
|
|
groups[lo].add([v.index], w * (1.0 - f), "REPLACE")
|
|
if f > 1e-5:
|
|
groups[lo + 1].add([v.index], w * f, "REPLACE")
|
|
print(f"Subdivided {len(made)} cloth panels into {segments} segments each")
|
|
return len(made)
|
|
|
|
|
|
def unbind_cloth_from_legs(arm, meshes, roles):
|
|
"""Take the LIMBS out of any vertex the cloth chains own.
|
|
|
|
A source model auto-weighted in Rigify leaves a band of skirt vertices
|
|
partly weighted to the thigh, and the vertices immediately next to them not
|
|
at all. Nothing about that is smooth: when the thigh swings, one vertex
|
|
follows it and its neighbour does not, and the mesh splits along the join.
|
|
Measured with debug/cloth_stretch_check.gd during a slide, two adjacent
|
|
front-panel vertices — identical weights except that one carried
|
|
DEF-thigh.L at 0.24 — pulled 80 mm apart, 3.3x their rest length. 0.24 of
|
|
the thigh's ~0.35 m of travel is 84 mm, so that is the whole of it. On
|
|
screen it is the skirt "breaking" around the thigh instead of stretching
|
|
over it.
|
|
|
|
Smoothing the field instead of deleting it does NOT work, and the arithmetic
|
|
says why: differential motion is the weight GRADIENT times how far the limb
|
|
travels. Holding an edge to under 10 mm against a thigh that moves 350 mm
|
|
needs less than 0.03 of weight difference across it, and this skirt's edges
|
|
are ~48 mm long, so the falloff would have to span most of the character.
|
|
Tried it — a 1.7-radius falloff put 0.24 on one vertex and 0.00 on its
|
|
neighbour and tore by 95 mm. Any leg weighting on this cloth tears.
|
|
|
|
Which is the project's own rule anyway: cloth moves by spring bones, never
|
|
by weights. Keeping the leg out of the weights is also what leaves the
|
|
spring solver able to move these vertices at all — see the note below on
|
|
bind_cloth_to_legs, which was this same mistake made deliberately.
|
|
"""
|
|
limbs = set()
|
|
for (role, side), name in roles.limb.items():
|
|
if role not in ("thigh", "shin", "foot"):
|
|
continue
|
|
limbs.add(name)
|
|
# ...and the twist segments hanging off them, which are the same limb.
|
|
for b in arm.data.bones:
|
|
if b.name != name and b.name.startswith(name + "."):
|
|
limbs.add(b.name)
|
|
cloth = set(b.name for b in arm.data.bones
|
|
if any(t in SPRING_CLASSES for t in tokens(b.name)))
|
|
if not limbs or not cloth:
|
|
return 0
|
|
|
|
freed = 0
|
|
for m in meshes:
|
|
gname = {g.index: g.name for g in m.vertex_groups}
|
|
for v in m.data.vertices:
|
|
cloth_w = 0.0
|
|
limb_w = 0.0
|
|
for g in v.groups:
|
|
n = gname.get(g.group, "")
|
|
if n in cloth:
|
|
cloth_w += g.weight
|
|
elif n in limbs:
|
|
limb_w += g.weight
|
|
# The cloth has to actually own the vertex. A thigh vertex with a
|
|
# little skirt on it is a LEG and must keep following the leg.
|
|
if limb_w <= 0.0 or cloth_w < 0.5 or cloth_w <= limb_w:
|
|
continue
|
|
scale = (cloth_w + limb_w) / cloth_w
|
|
for g in list(v.groups):
|
|
n = gname.get(g.group, "")
|
|
if n in limbs:
|
|
m.vertex_groups[g.group].remove([v.index])
|
|
elif n in cloth:
|
|
m.vertex_groups[g.group].add(
|
|
[v.index], min(1.0, g.weight * scale), "REPLACE")
|
|
freed += 1
|
|
print(f"Freed {freed} cloth vertices from the legs they were skinned to")
|
|
return freed
|
|
|
|
|
|
# Cloth is NOT skinned to the legs.
|
|
#
|
|
# There was a bind_cloth_to_legs() here that gave every cloth vertex near a
|
|
# thigh a share of that thigh, so the skirt would ride the leg the way a real
|
|
# one does. It was written because the drape and collision in
|
|
# characters/spring_bones.gd appeared to do nothing however hard they were
|
|
# driven — and they did nothing because of two bugs since fixed there (the
|
|
# drape rotated the spring's target but not the bone, so it cancelled out at
|
|
# equilibrium; and the collision's answer was read back off the bone tip, which
|
|
# discards the twist that is most of what lifts a sheet off a leg).
|
|
#
|
|
# With those fixed the binding is actively harmful. A vertex weighted 0.9 to a
|
|
# thigh cannot be moved by its own cloth bone, so the solver loses the authority
|
|
# to push it out of the leg — and the leg still overtakes it, because 0.9 of a
|
|
# rotation always lags the surface doing 1.0 of it. It also poisoned the
|
|
# collider measurement below: 2258 skirt vertices counted as thigh geometry and
|
|
# fitted a 0.28 m thigh.
|
|
#
|
|
# Measured on the run cycle with debug/skirt_clip_view.gd, which paints cloth
|
|
# magenta so leg-in-front-of-cloth is unambiguous: removing it made the frames
|
|
# it was supposed to fix cleaner, not worse.
|
|
|
|
|
|
main()
|