[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons
Python
"""Build the export stage's processed assets (bpy).
``export_asset_glb`` writes ``<export>/rigs/<asset>.glb``: the asset in its
rest pose on the export's pruned skeleton, without animation, textures
embedded and checked (layout and notes: :mod:`data_process.utils.asset_files`).
The exporters call it through :func:`build_asset_glb` / :func:`add_asset_glb`,
which record a failure instead of raising.
"""
import glob
import os
import bpy
import numpy as np
from loguru import logger
from mathutils import Matrix
from data_process.utils.asset_files import (
GLB_ERRORS_DIR,
PROCESSED_GLB_DIR,
TEXTURE_ISSUES_DIR,
check_glb_textures,
log_other_skeletons,
main_skeleton_clips,
processed_glb_path,
write_note,
)
from data_process.utils.blender_rig import (
build_ancestor_map,
export_selected_to_file,
find_skinned_meshes,
rename_truncated_bones,
repair_and_pack_textures,
select_objs,
sync_armature_bones,
update_scene,
)
from data_process.utils.kinematics import clip_global, rest_global
from data_process.utils.skeleton import similarity_fit
# ---------------------------------------------------------------------------
# Materials
# ---------------------------------------------------------------------------
def _node_tree_images(node_tree, seen_groups=None):
"""Images of every Image Texture node in *node_tree*, through node groups."""
seen_groups = set() if seen_groups is None else seen_groups
images = set()
for node in node_tree.nodes:
if node.type == 'TEX_IMAGE' and node.image is not None:
images.add(node.image)
elif node.type == 'GROUP' and node.node_tree is not None \
and node.node_tree.name not in seen_groups:
seen_groups.add(node.node_tree.name)
images |= _node_tree_images(node.node_tree, seen_groups)
return images
def material_images(objs):
"""Images the materials of *objs* use (any node depth)."""
images = set()
for obj in objs:
for slot in getattr(obj, 'material_slots', ()):
mat = slot.material
if mat is not None and mat.use_nodes and mat.node_tree is not None:
images |= _node_tree_images(mat.node_tree)
return images
def _upstream_nodes(socket):
"""Every node feeding *socket*, transitively."""
seen, stack = set(), [link.from_node for link in socket.links]
while stack:
node = stack.pop()
if node in seen:
continue
seen.add(node)
stack.extend(link.from_node for inp in node.inputs for link in inp.links)
return seen
def _material_output(mat):
"""The active Material Output node of *mat*, or None."""
if not mat.use_nodes or mat.node_tree is None:
return None
outputs = [n for n in mat.node_tree.nodes if n.type == 'OUTPUT_MATERIAL']
return next((n for n in outputs if n.is_active_output), outputs[0] if outputs else None)
def _surface_images(mat):
"""Names of the images feeding the surface of *mat*'s active output."""
out = _material_output(mat)
if out is None:
return set()
return {n.image.name for n in _upstream_nodes(out.inputs['Surface'])
if n.type == 'TEX_IMAGE' and n.image is not None}
def principled_from_specgloss(objects):
"""Rebuild glTF spec-gloss materials as a Principled BSDF the exporter reads.
Blender's glTF importer turns a ``KHR_materials_pbrSpecularGlossiness``
material into Diffuse + Glossy (+ Emission, + a Transparent mix), which its
exporter cannot translate, so it would write the material without its
diffuse image. A material whose
output is fed by a Diffuse BSDF and no Principled BSDF gets a Principled
BSDF wired to the output: Base Color from the Diffuse color, Normal from
the Diffuse normal, Emission from the Emission node, Alpha from the
Transparent mix factor, metallic 0, and the Glossy roughness when it is a
value. The old nodes stay, unconnected. The specular-glossiness map has no
slot in a metallic-roughness material (it would have to be baked into a
new image), so it is not carried, and a roughness that came from it falls
back to the Principled default (0.5).
Returns ``(converted material names, names of the images no material
surface uses any more)``.
"""
mats = {slot.material for obj in objects if obj.type == 'MESH'
for slot in obj.material_slots if slot.material is not None}
converted, before = [], set()
for mat in mats:
out = _material_output(mat)
if out is None or not out.inputs['Surface'].is_linked:
continue
upstream = _upstream_nodes(out.inputs['Surface'])
types = {n.type for n in upstream}
if 'BSDF_PRINCIPLED' in types or 'BSDF_DIFFUSE' not in types:
continue
before |= _surface_images(mat)
tree = mat.node_tree
first = lambda kind: next((n for n in upstream if n.type == kind), None) # noqa: E731
diffuse, glossy, emission = first('BSDF_DIFFUSE'), first('BSDF_GLOSSY'), first('EMISSION')
bsdf = tree.nodes.new('ShaderNodeBsdfPrincipled')
bsdf.location = (out.location.x - 300, out.location.y - 300)
def carry(src, dst):
if src.is_linked:
tree.links.new(src.links[0].from_socket, dst)
else:
dst.default_value = src.default_value
carry(diffuse.inputs['Color'], bsdf.inputs['Base Color'])
if diffuse.inputs['Normal'].is_linked:
carry(diffuse.inputs['Normal'], bsdf.inputs['Normal'])
bsdf.inputs['Metallic'].default_value = 0.0
if glossy is not None and not glossy.inputs['Roughness'].is_linked:
bsdf.inputs['Roughness'].default_value = glossy.inputs['Roughness'].default_value
if emission is not None:
carry(emission.inputs['Color'], bsdf.inputs.get('Emission Color') or bsdf.inputs['Emission'])
bsdf.inputs['Emission Strength'].default_value = emission.inputs['Strength'].default_value
for mix in (n for n in upstream if n.type == 'MIX_SHADER'):
# result = (1 - Fac) * Shader_1 + Fac * Shader_2: opacity is Fac
# when the first shader is the Transparent BSDF.
first_shader = mix.inputs[1].links[0].from_node if mix.inputs[1].is_linked else None
if first_shader is not None and first_shader.type == 'BSDF_TRANSPARENT':
carry(mix.inputs['Fac'], bsdf.inputs['Alpha'])
break
tree.links.new(bsdf.outputs['BSDF'], out.inputs['Surface'])
converted.append(mat.name)
# An image is dropped only if no material surface uses it any more.
dropped = before - set().union(*(_surface_images(m) for m in mats)) if converted else set()
if converted:
logger.info(f"Rebuilt {len(converted)} spec-gloss material(s) as Principled BSDF: "
f"{sorted(converted)[:4]}"
+ (f"; spec-gloss map(s) not carried: {sorted(dropped)}" if dropped else ''))
return converted, dropped
# Weights Blender uses to read a colour linked into a float socket.
_LUMINANCE = np.array([0.2126, 0.7152, 0.0722], dtype=np.float32)
def _roughness_from_gloss(gloss):
"""A packed, non-colour image holding ``1 - gloss`` (*gloss* read as
luminance), or None when *gloss* has no pixel data."""
w, h = gloss.size
if not (w and h and gloss.has_data):
logger.warning(f"Gloss map '{gloss.name}' has no pixel data; left as roughness")
return None
px = np.empty(w * h * gloss.channels, dtype=np.float32)
gloss.pixels.foreach_get(px)
px = px.reshape(-1, gloss.channels)
rough = 1.0 - (px[:, :3] @ _LUMINANCE if gloss.channels >= 3 else px[:, 0])
out = np.ones((w * h, 4), dtype=np.float32)
out[:, :3] = np.clip(rough, 0.0, 1.0)[:, None]
# Named after the map's file (FBX image datablocks are often 'file6').
stem = os.path.splitext(bpy.path.basename(gloss.filepath) or gloss.name)[0]
image = bpy.data.images.new(f"{stem}_roughness", w, h)
image.colorspace_settings.name = 'Non-Color'
image.pixels.foreach_set(out.ravel())
image.file_format = 'PNG'
image.pack()
return image
def pbr_from_fbx_phong(objects):
"""Convert the Phong values Blender's FBX importer writes into a Principled
BSDF to the metallic-roughness values they stand for.
- Metallic: the importer copies FBX ``ReflectionFactor`` (or a reflection
map), an environment-reflection strength rather than metalness, which
the glTF exporter would write as metal. It becomes 0.
- Roughness: a ``ShininessExponent`` texture is a gloss map (bright =
shiny) that the importer links to Roughness unchanged. It is replaced by
a packed image of ``1 - gloss``, gloss read as Blender reads a colour in
a float socket (luminance).
Specular keeps the importer's mapping (``SpecularFactor * 2``). Returns ``(materials whose metallic was reset,
{gloss image name: roughness image name})``.
"""
mats = {slot.material for obj in objects if obj.type == 'MESH'
for slot in obj.material_slots if slot.material is not None}
reset, inverted = [], {}
for mat in mats:
if not mat.use_nodes or mat.node_tree is None:
continue
tree = mat.node_tree
for bsdf in [n for n in tree.nodes if n.type == 'BSDF_PRINCIPLED']:
metallic = bsdf.inputs['Metallic']
if metallic.is_linked or metallic.default_value != 0.0:
for link in list(metallic.links):
tree.links.remove(link)
metallic.default_value = 0.0
reset.append(mat.name)
roughness = bsdf.inputs['Roughness']
if not roughness.is_linked:
continue
link = roughness.links[0]
node = link.from_node
if node.type != 'TEX_IMAGE' or node.image is None or link.from_socket.name != 'Color':
continue
if sum(len(out.links) for out in node.outputs) > 1:
logger.warning(f"'{mat.name}': gloss texture node also feeds other inputs; "
f"left as roughness")
continue
gloss = node.image
if gloss.name not in inverted:
inverted[gloss.name] = _roughness_from_gloss(gloss)
if inverted[gloss.name] is not None:
node.image = inverted[gloss.name]
inverted = {k: v.name for k, v in inverted.items() if v is not None}
if reset or inverted:
logger.info(f"FBX materials: metallic reset to 0 on {len(set(reset))}, "
f"gloss map(s) inverted to roughness: {sorted(inverted)[:4]}")
return sorted(set(reset)), inverted
# ---------------------------------------------------------------------------
# Scene preparation
# ---------------------------------------------------------------------------
def _strip_to_rig(armature, kept_bones):
"""Reduce the scene to *armature* and the meshes that belong to it.
Belonging = skinned to it (Armature modifier) or parented under it, the
rule the renderer uses (``blender_render.keep_armature_meshes``); other
meshes and armatures are deleted, among them armatures nested under this
one with everything below them and the meshes they deform, except
ancestors of what is kept (their transforms place the rig; empties are
never deleted). A mesh parented to a bone that is about to be pruned moves
to the bone that takes that bone's weights (:func:`build_ancestor_map`:
the nearest kept ancestor, for a dropped root the kept bone below it),
keeping its rest-pose world transform. Bone constraints and drivers go,
and every bone gets the standard inheritance (rotation, full scale, local
location): an NPZ replayed onto the asset is keyed as ``rest^-1 @ local``
(``compute_bone_keyframes``), which reproduces the exported pose under
exactly those rules, as glTF assumes.
Raises:
ValueError: no mesh belongs to the armature.
"""
def deformed_by_other(obj):
return any(mod.type == 'ARMATURE' and mod.object is not None and mod.object != armature
for mod in getattr(obj, 'modifiers', ()))
def under_other_armature(obj):
node = obj.parent
while node is not None and node != armature:
if node.type == 'ARMATURE':
return True
node = node.parent
return False
# Other armatures under this one, what hangs below them, and meshes they
# deform are another rig: a second armature would confuse character loading.
rig = {armature} | set(find_skinned_meshes(armature)) | {
o for o in armature.children_recursive
if o.type != 'ARMATURE' and not deformed_by_other(o) and not under_other_armature(o)}
keep = set(rig)
for obj in rig:
parent = obj.parent
while parent is not None:
keep.add(parent)
parent = parent.parent
for obj in list(bpy.context.scene.objects):
if obj.type in ('MESH', 'ARMATURE') and obj not in keep:
bpy.data.objects.remove(obj, do_unlink=True)
if not any(o.type == 'MESH' for o in rig):
raise ValueError(f"no mesh is skinned to or parented under armature '{armature.name}'")
# Re-parent in the rest pose, so the result does not depend on the frame
# the scene was left at (last extracted frame vs. freshly imported).
pose_position = armature.data.pose_position
armature.data.pose_position = 'REST'
update_scene()
target_of = build_ancestor_map(armature, kept_bones)
for obj in list(armature.children_recursive):
if obj.parent != armature or obj.parent_type != 'BONE' \
or obj.parent_bone in kept_bones:
continue
target = target_of.get(obj.parent_bone)
world = obj.matrix_world.copy()
if target is None:
obj.parent_type = 'OBJECT'
obj.parent_bone = ''
else:
obj.parent_bone = target
update_scene()
obj.matrix_world = world
logger.info(f"Re-parented '{obj.name}' to "
f"{'the armature' if target is None else repr(target)} (bone pruned)")
armature.data.pose_position = pose_position
for bone in armature.data.bones:
bone.use_inherit_rotation = True
bone.inherit_scale = 'FULL'
bone.use_local_location = True
for pose_bone in armature.pose.bones:
for constraint in list(pose_bone.constraints):
pose_bone.constraints.remove(constraint)
if armature.animation_data is not None:
for driver in list(armature.animation_data.drivers):
armature.animation_data.drivers.remove(driver)
update_scene()
def _set_armature_world(armature, new):
"""Give *armature* the world matrix *new*; meshes outside its hierarchy keep
their armature-relative pose explicitly, its descendants follow it."""
old = np.array(armature.matrix_world)
inside = set(armature.children_recursive)
others = [(o, np.linalg.inv(old) @ np.array(o.matrix_world))
for o in bpy.context.scene.objects
if o.type == 'MESH' and o not in inside]
armature.matrix_world = Matrix(np.asarray(new).tolist())
update_scene()
for obj, rel in others:
obj.matrix_world = Matrix((np.asarray(new) @ rel).tolist())
update_scene()
# Export space is Blender's world turned -90 degrees about X (Y-up).
_EXPORT_FROM_BLENDER = np.array([[1., 0, 0, 0], [0, 0, 1, 0], [0, -1, 0, 0], [0, 0, 0, 1]])
def _rotate_rest(armature, fix, names, rest_pos):
"""Move the whole rig by the rest-orientation fix an export NPZ records
(``rest_orientation_applied``: quat w, x, y, z then an optional offset, export
space; the NPZ's rest is already ``p -> quat * p + offset`` of the original).
The rig's rest joints match the original NPZ rest up to a similarity (scale,
and possibly a constant offset that replay cancels); the fix is applied in that
frame, so the rig ends up related to the fixed NPZ exactly as it was to the
original one. *rest_pos* is the fixed NPZ's rest (export space)."""
fix = np.asarray(fix, dtype=np.float64)
w, x, y, z = fix[:4] / np.linalg.norm(fix[:4])
R = np.array([[1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],
[2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],
[2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)]])
t = fix[4:7] if len(fix) >= 7 else np.zeros(3)
C = _EXPORT_FROM_BLENDER
arm_world = np.array(armature.matrix_world)
bones = armature.data.bones
keep = [j for j, n in enumerate(names) if n in bones]
heads = np.stack([(C @ arm_world @ np.array(bones[names[j]].matrix_local))[:3, 3] for j in keep])
original = (np.asarray(rest_pos)[keep] - t) @ R # R^T (p - t), row vectors
Rf, scale, delta, _ = similarity_fit(original, heads) # heads ~ scale Rf original + delta
A = Rf @ R @ Rf.T
X = np.eye(4)
X[:3, :3] = A
X[:3, 3] = delta - A @ delta + scale * Rf @ t
_set_armature_world(armature, np.linalg.inv(C) @ X @ C @ arm_world)
def _similarity_armature_frame(armature, tol=1e-3):
"""Give *armature* the nearest proper similarity of its world transform.
Export NPZs store the skeleton in armature space, and a rotation-only
skeleton cannot carry a non-uniform or mirroring object scale. When the
armature's world matrix has one (singular values differing by more than
*tol*, or a negative determinant), it is replaced by its polar rotation
(made proper) times the mean scale, keeping its translation; meshes keep
their placement relative to the armature, so the asset becomes its
armature-space shape, the one its clips animate. Returns True when changed.
"""
M = np.array(armature.matrix_world)
U, sv, Vt = np.linalg.svd(M[:3, :3])
det = np.linalg.det(M[:3, :3])
if sv.max() / max(sv.min(), 1e-12) - 1 <= tol and det > 0:
return False
R = U @ np.diag([1.0, 1.0, np.sign(np.linalg.det(U @ Vt))]) @ Vt
new = np.eye(4)
new[:3, :3] = R * np.cbrt(abs(det))
new[:3, 3] = M[:3, 3]
_set_armature_world(armature, new)
logger.info(f"Armature '{armature.name}' had a non-uniform or mirroring scale "
f"(singular values {np.round(sv, 4).tolist()}, det {det:.3g}); "
f"exported in armature space")
return True
def _reset_to_rest(armature):
"""Drop every action and animation binding, and put every bone at rest."""
for action in list(bpy.data.actions):
bpy.data.actions.remove(action)
for obj in bpy.context.scene.objects:
if obj.animation_data is not None:
obj.animation_data_clear()
shape_keys = getattr(getattr(obj, 'data', None), 'shape_keys', None)
if shape_keys is not None and shape_keys.animation_data is not None:
shape_keys.animation_data_clear()
for pose_bone in armature.pose.bones:
pose_bone.location = (0.0, 0.0, 0.0)
pose_bone.rotation_quaternion = (1.0, 0.0, 0.0, 0.0)
pose_bone.rotation_euler = (0.0, 0.0, 0.0)
pose_bone.rotation_axis_angle = (0.0, 0.0, 1.0, 0.0)
pose_bone.scale = (1.0, 1.0, 1.0)
update_scene()
def _check_hierarchy(armature, names, parents):
"""Every NPZ joint the rig has must hang under the bone of its nearest
NPZ ancestor the rig has (ValueError otherwise)."""
bones = armature.data.bones
for j, name in enumerate(names):
if name not in bones:
continue
p = int(parents[j])
while p >= 0 and names[p] not in bones:
p = int(parents[p])
want = names[p] if p >= 0 else None
got = bones[name].parent.name if bones[name].parent is not None else None
if got != want:
raise ValueError(f"bone '{name}' hangs under {got!r}, the NPZ puts it under "
f"{want!r}; wrong asset or rig?")
# Largest difference (relative to its extent) between the rig's rest skeleton
# and the NPZ's that a processed GLB may have; the same tolerance as the
# canonical bake (canonical_rig.FIT_TOL) and skeleton.motion_axis_alignment.
REST_TOL = 5e-3
# Written into export NPZs by tools/patch_annotations.py (apply_rest_orientations);
# keep the name in sync.
REST_ORIENTATION_KEY = 'rest_orientation_applied'
def _check_rest(armature, names, rest_pos, tol):
"""The rig's rest joints must be the NPZ's (*rest_pos*, export space) up
to a similarity, within *tol* of the extent; ValueError otherwise."""
arm_world = np.array(armature.matrix_world)
bones = armature.data.bones
keep = [j for j, n in enumerate(names) if n in bones]
rig = np.stack([(arm_world @ np.array(bones[names[j]].matrix_local))[:3, 3] for j in keep])
resid = similarity_fit(rest_pos[keep], rig)[3]
if resid > tol:
raise ValueError(
f"rest skeleton is {resid:.1e} of its extent from the NPZ's (tolerance {tol:g}); "
f"the clips were extracted from a different reading of this file")
# A rig whose rest skeleton is further from the origin than this many times its
# own extent is moved next to it (:func:`_recentre_far_rig`).
FAR_ORIGIN = 10.0
def _translation(t):
T = np.eye(4)
T[:3, 3] = t
return T
def _map_rig(armature, world_map, arm_translation=None):
"""Apply *world_map* (a 4x4 uniform scale plus translation, world space) to
the whole rig in its rest pose, in the data rather than the object
transforms: the bones in armature space, each mesh's vertices around its own
centre. *arm_translation* moves the armature object too (its rotation and
scale stay); the bones absorb the difference. The asset ends up
``world_map`` of what it was, with no large values left in the node chain
or vertex data for an exporter writing float32 to lose precision on."""
W = np.asarray(world_map, dtype=np.float64)
A = np.array(armature.matrix_world)
A_new = A.copy()
if arm_translation is not None:
A_new[:3, 3] = arm_translation
meshes = [o for o in bpy.context.scene.objects if o.type == 'MESH']
old = {o: np.array(o.matrix_world) for o in meshes}
def depth(obj):
n = 0
while obj.parent is not None:
obj, n = obj.parent, n + 1
return n
X = np.linalg.inv(A_new) @ W @ A # armature space: old -> new
view_layer = bpy.context.view_layer
previous = view_layer.objects.active
view_layer.objects.active = armature
bpy.ops.object.mode_set(mode='EDIT')
# Read everything before writing: moving a bone's tail moves the head of a
# child connected to it.
edit_bones = list(armature.data.edit_bones)
ends = [(np.array(eb.head), np.array(eb.tail), eb.roll) for eb in edit_bones]
for eb, (head, tail, roll) in zip(edit_bones, ends):
eb.head = (X[:3, :3] @ head + X[:3, 3]).tolist()
eb.tail = (X[:3, :3] @ tail + X[:3, 3]).tolist()
eb.roll = roll
bpy.ops.object.mode_set(mode='OBJECT')
view_layer.objects.active = previous
armature.matrix_world = Matrix(A_new.tolist())
update_scene()
for obj in meshes: # each mesh maps its own data
if obj.data.users > 1:
obj.data = obj.data.copy()
for obj in sorted(meshes, key=depth): # parents first: children are placed by world
target = W @ old[obj] # the object's frame, mapped
new = old[obj].copy()
new[:3, 3] = target[:3, 3]
data_map = np.linalg.inv(new) @ target # carries the scale into the data
if len(obj.data.vertices):
co = np.empty(3 * len(obj.data.vertices))
obj.data.vertices.foreach_get('co', co)
co = co.reshape(-1, 3) @ data_map[:3, :3].T + data_map[:3, 3]
centre = (co.min(0) + co.max(0)) / 2
data_map = _translation(-centre) @ data_map
new = new @ _translation(centre)
obj.data.transform(Matrix(data_map.tolist()), shape_keys=True)
obj.matrix_world = Matrix(new.tolist())
update_scene()
def _recentre_far_rig(armature, names, rest_pos, clip_paths, far=FAR_ORIGIN):
"""Move a rig lying more than *far* times its skeleton's extent from the
origin next to it, when its clips then replay closer to the origin too:
skeleton centred over the origin in X/Y, lowest joint at Z = 0 (Blender
world), armature object at the origin. Far away, the float32 node
transforms and inverse bind matrices of the GLB lose the pose's precision.
Replay keys are relative to the NPZ rest pose, so a clip replays where it
was exported, displaced by the move. Some assets were exported with their
rest pose far away but their clips at the origin (the offset is between the
rest pose and the animation in the source); moving those would carry every
replay away, so they stay. *rest_pos* (export space, joints *names*) maps
the clips (*clip_paths*) into the rig's frame. Returns True when moved."""
A = np.array(armature.matrix_world)
bones = armature.data.bones
heads = np.stack([(A @ np.array(b.matrix_local))[:3, 3] for b in bones])
lo, hi = heads.min(0), heads.max(0)
extent = float((hi - lo).max())
centre = (lo + hi) / 2
if extent <= 0 or np.linalg.norm(centre) <= far * extent:
return False
shift = -np.array([centre[0], centre[1], lo[2]])
keep = [j for j, n in enumerate(names) if n in bones]
rig = np.stack([(A @ np.array(bones[names[j]].matrix_local))[:3, 3] for j in keep])
R, s, t, _ = similarity_fit(np.asarray(rest_pos)[keep], rig) # export space -> world
replay = []
for path in clip_paths:
with np.load(path, allow_pickle=True) as npz:
replay.append(s * clip_global(npz).reshape(-1, 3).mean(0) @ R.T + t)
replay = np.array(replay).reshape(-1, 3)
before = float(np.linalg.norm(replay, axis=1).max()) if len(replay) else np.inf
after = float(np.linalg.norm(replay + shift, axis=1).max()) if len(replay) else 0.0
if after >= before:
logger.info(f"Rig '{armature.name}' is {np.linalg.norm(centre) / extent:.0f}x its extent "
f"from the origin but its clips replay {before / extent:.0f}x from it; "
f"not moved")
return False
_map_rig(armature, _translation(shift), arm_translation=np.zeros(3))
logger.info(f"Rig '{armature.name}' was {np.linalg.norm(centre) / extent:.0f}x its extent "
f"from the origin; moved by {np.round(shift, 3).tolist()} (clips replay "
f"{after / extent:.1f}x its extent from it, was {before / extent:.0f}x)")
return True
def _rescale_to_npz(armature, names, rest_pos, tol):
"""Scale a rig whose skeleton stands more than *tol* times taller or shorter
than the NPZ's (*rest_pos*, export space) to the NPZ's size, about the
armature's origin. Heights are taken over the joints both have, the rig's
along world Z in armature units, the NPZ's along Y; a similarity fit or a
bounding box would confuse a character's own proportions (short legs, wide
arms) with a unit error. Returns the factor applied, or None."""
A = np.array(armature.matrix_world)
bones = armature.data.bones
keep = [j for j, n in enumerate(names) if n in bones]
heads = np.stack([(A @ np.array(bones[names[j]].matrix_local))[:3, 3] for j in keep])
arm_scale = np.cbrt(abs(np.linalg.det(A[:3, :3])))
npz_height = float(np.ptp(np.asarray(rest_pos)[keep, 1]))
ratio = float(np.ptp(heads[:, 2]) / arm_scale / npz_height) if npz_height > 0 else np.nan
if not np.isfinite(ratio) or ratio <= 0:
logger.warning(f"Rig '{armature.name}': no height to compare with the export "
f"skeleton's; not rescaled")
return None
if 1 / tol <= ratio <= tol:
return None
S = np.diag([1 / ratio] * 3 + [1.0])
_map_rig(armature, A @ S @ np.linalg.inv(A))
logger.info(f"Rig '{armature.name}' stood {ratio:.3g}x the height of the export skeleton; "
f"scaled by {1 / ratio:.4g}")
return 1 / ratio
# ---------------------------------------------------------------------------
# Building
# ---------------------------------------------------------------------------
def export_asset_glb(armature, npz_path, output_dir, asset, source_path=None, required=None,
rest_tol=REST_TOL, rescale_tol=None):
"""Write ``<output_dir>/rigs/<asset>.glb``: the asset on the export's
pruned skeleton, in its rest pose, without animation.
The skeleton is that of *npz_path* (one of the asset's clips). Bones whose
long names were cut differently than in the NPZ are renamed to it
(``rename_truncated_bones``); bones the export pruned are removed and
their (sub-threshold) weights merged into the bone that takes them (the
nearest kept ancestor; for a dropped root, the kept bone below it), the
reconciliation the mesh-animation entry points apply
(``sync_armature_bones``). Bone names and hierarchy then equal the NPZ's
``names`` / ``parents`` (checked), and so does the rest pose (checked up
to a similarity, *rest_tol*; the root's Z-up -> Y-up turn is cancelled by
keyframing); a Mixamo character keeps its own rest pose and proportions. Any clip NPZ of that skeleton drives the file
directly (``animate_npz``), with no extra bones to reconcile.
With *rescale_tol*, a rig whose skeleton is more than that factor larger
or smaller than the NPZ's is scaled to its size (a character authored in
other units). A rig further than :data:`FAR_ORIGIN` times its extent from
the origin is moved next to it when its clips (``motions/<asset>-*.npz``)
then replay closer to the origin too (:func:`_recentre_far_rig`).
Spec-gloss materials are rebuilt as Principled BSDF
(:func:`principled_from_specgloss`); textures are re-linked next to the
source, packed, embedded and checked (``rigs/texture_issues/<asset>.txt``);
an FBX source's materials get metallic 0 and their gloss maps inverted
into roughness (:func:`pbr_from_fbx_phong`).
The scene is modified in place (objects deleted, bones removed, actions
dropped): call it after the asset's NPZs are extracted, or on a freshly
imported asset. The file is written under a temporary name and renamed,
so an interrupted run never leaves a truncated GLB behind.
Args:
required: NPZ joints the rig must have (default: all of them). Others
may be absent (e.g. the finger bones of a Mixamo character whose
mesh has none); the GLB then lacks them and replay skips them.
rest_tol: largest rest-skeleton difference from the NPZ's, relative to
its extent (default :data:`REST_TOL`); None skips the check (a
Mixamo character, whose proportions are its own).
rescale_tol: size factor beyond which the rig is scaled to the NPZ's
(:func:`_rescale_to_npz`); None (default) never rescales.
Returns:
The GLB path.
"""
with np.load(npz_path, allow_pickle=True) as npz:
names = [str(n) for n in npz['names']]
parents = np.asarray(npz['parents'])
rest_pos = rest_global(npz)
rest_fix = np.asarray(npz[REST_ORIENTATION_KEY]) if REST_ORIENTATION_KEY in npz.files else None
rename_truncated_bones(armature, names)
_strip_to_rig(armature, set(names))
sync_armature_bones(armature, names, extra_bones_strategy='merge')
missing = [n for n in names if n not in armature.data.bones]
must = set(names) if required is None else set(required)
lost = [n for n in missing if n in must]
if lost:
raise ValueError(f"{len(lost)} required NPZ joints are not bones of armature "
f"'{armature.name}' (e.g. {lost[:3]}); wrong asset or rig?")
if missing:
logger.warning(f"'{asset}': {len(missing)} of {len(names)} export joints are not in "
f"the rig (e.g. {missing[:3]}); the GLB has the other "
f"{len(names) - len(missing)}")
_check_hierarchy(armature, names, parents)
# Actions go first: an animated object transform would override the frame.
_reset_to_rest(armature)
_similarity_armature_frame(armature)
if rest_fix is not None:
_rotate_rest(armature, rest_fix, names, rest_pos)
if rest_tol is not None:
_check_rest(armature, names, rest_pos, rest_tol)
if rescale_tol is not None:
_rescale_to_npz(armature, names, rest_pos, rescale_tol)
clip_paths = sorted(glob.glob(os.path.join(
output_dir, 'motions', f'{glob.escape(asset)}-*.npz'))) or [npz_path]
_recentre_far_rig(armature, names, rest_pos, clip_paths)
export_objs = [o for o in bpy.context.scene.objects if o.type in ('MESH', 'ARMATURE')]
_, spec_maps = principled_from_specgloss(export_objs)
unresolved = set()
if source_path is not None:
unresolved = set(repair_and_pack_textures(source_path))
# After the repair: inverting a gloss map needs its pixels.
if os.fspath(source_path).lower().endswith('.fbx'):
pbr_from_fbx_phong(export_objs)
used = [img for img in material_images(export_objs) if img.name not in spec_maps]
unresolved &= {img.name for img in used}
expected = {
img.name: {img.name, os.path.splitext(img.name)[0],
os.path.splitext(bpy.path.basename(img.filepath))[0]} - {''}
for img in used
if img.name not in unresolved
and (img.packed_file is not None or img.source == 'GENERATED')}
final = processed_glb_path(output_dir, asset)
os.makedirs(os.path.dirname(final), exist_ok=True)
partial = os.path.join(os.path.dirname(final), f'.{asset}.partial.glb')
select_objs(export_objs, deselect_first=True)
try:
export_selected_to_file(partial, 'glb')
os.replace(partial, final)
finally:
if os.path.isfile(partial):
os.remove(partial)
try:
problems = check_glb_textures(final, expected, unresolved)
except Exception as exc: # noqa: BLE001 — the GLB is written; keep it
problems = [f"texture check failed: {type(exc).__name__}: {exc}"]
write_note(os.path.join(output_dir, PROCESSED_GLB_DIR), TEXTURE_ISSUES_DIR, asset, problems)
if problems:
logger.warning(f"Textures of '{asset}': " + '; '.join(problems))
logger.info(f"Saved processed GLB {final} ({len(names) - len(missing)} joints, "
f"{len(expected) + len(unresolved)} material image(s)"
+ (f", {len(unresolved)} not found" if unresolved else '') + ")")
return final
def build_asset_glb(asset, npz_path, output_dir, get_armature, source_path=None,
required=None, rest_tol=REST_TOL, rescale_tol=None):
""":func:`export_asset_glb`, with a failure recorded instead of raised.
The GLB comes after the asset's NPZs are complete, so a GLB that cannot be
built must not fail the export (the wrapper would refuse to merge the
shards, on every rerun). The error goes to ``rigs/glb_errors/<asset>.txt``,
removed again once a rerun with ``--save_glb`` / ``--glb_only`` succeeds.
Args:
get_armature: callable returning the asset's armature in the current
scene (importing the asset when needed), called inside the guard.
Returns:
True when the GLB was written.
"""
notes = os.path.join(output_dir, PROCESSED_GLB_DIR)
try:
export_asset_glb(get_armature(), npz_path, output_dir, asset,
source_path=source_path, required=required, rest_tol=rest_tol,
rescale_tol=rescale_tol)
except Exception as exc: # noqa: BLE001 — the NPZs are done; keep the batch going
logger.exception(f"Processed GLB of '{asset}' failed (NPZs unaffected)")
write_note(notes, GLB_ERRORS_DIR, asset, [f'{type(exc).__name__}: {exc}'])
return False
write_note(notes, GLB_ERRORS_DIR, asset, [])
return True
def add_asset_glb(asset, output_dir, get_armature, source_path=None):
"""Build the missing processed GLB of an already exported asset from one of
its main-skeleton clips (``main_skeleton_clips``), guarded like
:func:`build_asset_glb`. Returns True when the GLB was written."""
main, others = main_skeleton_clips(output_dir, asset)
if not main:
return False
log_other_skeletons(asset, others)
return build_asset_glb(asset, main[0], output_dir, get_armature, source_path=source_path)