[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons
Python
"""Blender utilities for driving a rigged character with an NPZ animation.
Organized as five sections:
1. Scene / object helpers — import meshes, select objects, pack textures.
2. Keyframe computation — per-bone loc/rot keyframes from 4x4 local
transforms.
3. Action reconstruction — turn per-bone keyframe arrays into a Blender
Action bound to the armature.
4. Armature reconciliation — handle armature bones that are absent from
the driving animation (keep them, merge their weights, or delete them).
5. Character export — export the animated mesh + armature to GLB/FBX.
The counterpart for the *export* direction (Blender scene → NPZ) lives in
:mod:`data_process.utils.blender_export`; the export stage's rest-pose GLB per
asset in :mod:`data_process.utils.processed_assets` (bpy) and
:mod:`data_process.utils.asset_files` (paths and notes, bpy-free).
"""
import os
import re
import bpy
import bmesh # registered by ``import bpy`` when running on the pip bpy module
import numpy as np
from loguru import logger
from mathutils import Matrix, Quaternion
from data_process.utils.blender_export import (
bind_action,
clear_animation_state,
)
RECONSTRUCTED_ACTION_NAME = "Reconstructed_Action"
# ─────────────────────────────────────────────────────────────────────────────
# 1. Scene / object helpers
# ─────────────────────────────────────────────────────────────────────────────
def update_scene():
"""Force a full scene dependency-graph update."""
bpy.context.view_layer.update()
bpy.context.scene.update_tag()
for obj in bpy.context.scene.objects:
obj.update_tag()
def deselect():
"""Deselect every object in the scene."""
bpy.ops.object.select_all(action="DESELECT")
def select_objs(obj_list=None, deselect_first=False):
"""Select Blender objects, optionally deselecting everything first."""
if not obj_list:
obj_list = bpy.context.scene.objects
if deselect_first:
deselect()
for obj in obj_list:
obj.select_set(True)
def load_file(filepath, *args, **kwargs):
"""Import a 3D file and return the list of newly-added scene objects."""
old_objs = set(bpy.context.scene.objects)
ext = os.path.splitext(filepath)[1].lower()
if ext in (".glb", ".gltf"):
bpy.ops.import_scene.gltf(filepath=filepath, *args, **kwargs)
elif ext == ".fbx":
bpy.ops.import_scene.fbx(filepath=filepath, *args, **kwargs)
elif ext == ".obj":
bpy.ops.wm.obj_import(filepath=filepath, *args, **kwargs)
elif ext == ".ply":
bpy.ops.wm.ply_import(filepath=filepath, *args, **kwargs)
else:
raise RuntimeError(f"Invalid input file: {filepath}")
imported = sorted(set(bpy.context.scene.objects) - old_objs, key=lambda x: x.name)
logger.info(f"Imported: {[obj.name for obj in imported]}")
return imported
_IMAGE_FORMAT_EXTENSIONS = {
'PNG': '.png', 'JPEG': '.jpg', 'JPEG2000': '.jp2', 'TARGA': '.tga',
'TARGA_RAW': '.tga', 'BMP': '.bmp', 'TIFF': '.tif', 'OPEN_EXR': '.exr',
'HDR': '.hdr', 'WEBP': '.webp',
}
def repair_and_pack_textures(source_path):
"""Re-link missing texture files and pack every image into memory.
Imported assets frequently reference textures by paths from the
original author's machine (absolute Windows paths are common in
Truebones FBX). When the importer can't locate a file, the image
datablock has no pixel data, and both the GLB and FBX exporters
silently drop it. This helper:
1. searches for missing image files next to *source_path*, and
2. packs every loadable image into the .blend so exports no
longer depend on external files.
Returns the list of image names that still have no usable data
(their texture files could not be found on disk).
"""
src_dir = os.path.dirname(os.path.abspath(source_path))
# A symlinked asset keeps its textures beside the link target.
search_dirs = [src_dir]
real_dir = os.path.dirname(os.path.realpath(source_path))
if real_dir != src_dir:
search_dirs.append(real_dir)
for directory in search_dirs:
try:
bpy.ops.file.find_missing_files(directory=directory)
except RuntimeError as exc:
logger.warning(f"find_missing_files failed in {directory}: {exc}")
broken = []
for img in bpy.data.images:
if img.source not in ('FILE', 'SEQUENCE', 'TILED'):
continue
if img.packed_file is None:
try:
img.pack()
except RuntimeError as exc:
logger.warning(f"Could not pack image '{img.name}': {exc}")
if img.packed_file is None:
filepath = bpy.path.abspath(img.filepath) if img.filepath else ''
if not (filepath and os.path.isfile(filepath)):
broken.append(img.name)
if broken:
logger.warning(
f"{len(broken)} image(s) have no pixel data and will be missing "
f"from exports (texture files not found near {src_dir}): {broken}"
)
return broken
def _file_holds(path, data):
"""Whether the file at *path* holds exactly the bytes *data* (False when
it cannot be read, e.g. removed meanwhile by another process)."""
try:
if os.path.getsize(path) != len(data):
return False
with open(path, 'rb') as fh:
return fh.read() == bytes(data)
except OSError:
return False
def write_sidecar(texture_dir, name, ext, data):
"""``<texture_dir>/<name><ext>`` holding *data*, or the first free
``<name>_<n><ext>``; the path, or None when nothing could be written.
A file holding other bytes keeps its name: sanitizing maps ``A B`` and
``A+B`` to one name, and every asset exported into a directory shares its
``textures/``. A name is claimed by creating the file exclusively, so
processes exporting into one directory at once never replace each
other's files; a file that already holds *data* is reused."""
os.makedirs(texture_dir, exist_ok=True)
path, n = os.path.join(texture_dir, name + ext), 1
while True:
try:
with open(path, 'xb') as fh:
try:
fh.write(data)
except OSError:
os.remove(path)
raise
return path
except FileExistsError:
if _file_holds(path, data):
return path
except OSError as exc:
logger.warning(f"Could not write texture sidecar {path}: {exc}")
return None
path = os.path.join(texture_dir, f'{name}_{n}{ext}')
n += 1
def write_packed_images_to_dir(texture_dir):
"""Write packed images that have no on-disk file out to *texture_dir*.
The FBX exporter's COPY/embed path reads texture bytes from the
image's file path on disk; images that exist only as packed data
(typical after a GLB import) are silently skipped, losing textures.
Writing them out right before FBX export makes embedding work.
Returns the sidecar paths the images now point at (written here, or
already holding their bytes).
"""
written = []
for idx, img in enumerate(bpy.data.images):
if img.packed_file is None:
continue
filepath = bpy.path.abspath(img.filepath) if img.filepath else ''
if filepath and os.path.isfile(filepath):
continue
ext = _IMAGE_FORMAT_EXTENSIONS.get(img.file_format, '.png')
safe_name = re.sub(r'[^A-Za-z0-9_.-]+', '_', img.name).strip('_') or f'image_{idx}'
if not safe_name.lower().endswith(ext):
safe_name += ext
# The packed bytes verbatim (no re-encode), where filepath_raw then
# points, so the exporter's embed path finds them. (img.unpack()
# writes to the image's *original* path instead.)
out_path = write_sidecar(texture_dir, safe_name[:-len(ext)], ext,
bytes(img.packed_file.data))
if out_path is None:
continue
img.filepath_raw = out_path
written.append(out_path)
if written:
logger.info(f"Put {len(written)} packed image(s) in {texture_dir} for FBX embedding")
return written
def _find_upstream_image_node(socket, max_depth=8):
"""BFS upstream from *socket* to the first Image Texture node with an image."""
queue = [(socket, 0)]
visited = set()
while queue:
sock, depth = queue.pop(0)
if depth > max_depth:
continue
for link in sock.links:
node = link.from_node
if node in visited:
continue
visited.add(node)
if node.type == 'TEX_IMAGE' and node.image is not None:
return node
queue.extend((inp, depth + 1) for inp in node.inputs)
return None
def simplify_materials_for_fbx(objs):
"""Rewire each material's base-color texture directly into a Principled BSDF.
The FBX exporter only recognizes a texture when its Image Texture node
feeds a Principled BSDF input directly. glTF-imported materials often
interpose extra nodes — a Mix/Multiply for baseColorFactor or vertex
colors, or (for KHR_materials_unlit) an Emission chain with no
Principled node at all — which makes the FBX exporter silently drop
the texture. This flattens those graphs: find the first image texture
upstream and connect it straight to Base Color, creating a Principled
BSDF if the material lacks one.
"""
mats = {slot.material for obj in objs if obj.type == 'MESH'
for slot in obj.material_slots if slot.material}
for mat in mats:
if not mat.use_nodes:
continue
tree = mat.node_tree
principled = next((n for n in tree.nodes if n.type == 'BSDF_PRINCIPLED'), None)
if principled is not None:
base = principled.inputs['Base Color']
if any(l.from_node.type == 'TEX_IMAGE' and l.from_node.image
for l in base.links):
continue # already directly wired; FBX export handles it
img_node = _find_upstream_image_node(base)
if img_node is None:
continue
for l in list(base.links):
tree.links.remove(l)
tree.links.new(img_node.outputs['Color'], base)
logger.info(f"Material '{mat.name}': rewired image "
f"'{img_node.image.name}' directly to Base Color for FBX")
continue
# No Principled BSDF (e.g. unlit glTF material): build one from the
# image feeding the output surface, so FBX gets a textured material.
output = next((n for n in tree.nodes
if n.type == 'OUTPUT_MATERIAL' and n.is_active_output),
None) or next((n for n in tree.nodes
if n.type == 'OUTPUT_MATERIAL'), None)
if output is None:
continue
img_node = _find_upstream_image_node(output.inputs['Surface'])
if img_node is None:
continue
principled = tree.nodes.new('ShaderNodeBsdfPrincipled')
tree.links.new(img_node.outputs['Color'], principled.inputs['Base Color'])
for l in list(output.inputs['Surface'].links):
tree.links.remove(l)
tree.links.new(principled.outputs['BSDF'], output.inputs['Surface'])
logger.info(f"Material '{mat.name}': no Principled BSDF; created one "
f"with image '{img_node.image.name}' for FBX")
def get_armature_obj(obj_list=None):
"""Return the first ARMATURE object from a list (or the scene), else None."""
if not obj_list:
obj_list = bpy.context.scene.objects
for obj in obj_list:
if obj.type == "ARMATURE":
return obj
return None
def set_scene_timing(nframes, fps):
"""Set the scene frame rate and frame range ``[0, nframes - 1]``."""
bpy.context.scene.render.fps = int(fps)
bpy.context.scene.frame_start = 0
bpy.context.scene.frame_end = nframes - 1
# ─────────────────────────────────────────────────────────────────────────────
# 2. Keyframe computation
# ─────────────────────────────────────────────────────────────────────────────
def compute_bone_keyframes(rest_local_mat, anim_local_mat, bone_names,
tpos_global_rot=None):
"""Compute per-bone location/rotation keyframes from local 4x4 transforms.
The relative transform ``rest_inv @ anim`` is computed in NumPy for all
frames at once; per-keyframe loc/rot are then extracted via ``mathutils``
so they match Blender's conventions exactly.
Args:
rest_local_mat: ``(nbones, 4, 4)`` rest-pose local transforms.
anim_local_mat: ``(nframes, nbones, 4, 4)`` animated local transforms.
bone_names: Bone names, length ``nbones``.
tpos_global_rot: Optional ``(nbones, 4)`` T-pose global rotations.
When given, each keyframe is conjugated by the bone's T-pose
global rotation.
Returns:
``{bone_name: {'location': [(frame, Vector), ...],
'rotation': [(frame, Quaternion), ...]}}``
"""
nframes, nbones = anim_local_mat.shape[:2]
rest_inv = np.linalg.inv(rest_local_mat) # (nbones, 4, 4)
rel_mats = rest_inv[None] @ anim_local_mat # (nframes, nbones, 4, 4)
tpos_quats = tpos_quats_inv = None
if tpos_global_rot is not None:
tpos_quats = [Quaternion(tpos_global_rot[b]) for b in range(nbones)]
tpos_quats_inv = [q.inverted() for q in tpos_quats]
anim_data_dict = {}
for idxb in range(nbones):
locs, rots = [], []
for idxf in range(nframes):
m = Matrix(rel_mats[idxf, idxb].tolist())
loc = m.to_translation()
rot = m.to_quaternion()
if tpos_quats is not None:
rot = tpos_quats_inv[idxb] @ rot @ tpos_quats[idxb]
loc = tpos_quats_inv[idxb] @ loc
locs.append((idxf, loc))
rots.append((idxf, rot))
anim_data_dict[str(bone_names[idxb])] = {'location': locs, 'rotation': rots}
return anim_data_dict
# ─────────────────────────────────────────────────────────────────────────────
# 3. Action reconstruction
# ─────────────────────────────────────────────────────────────────────────────
def _add_fcurves(action, bone_name, attr, n_components, keyframes):
"""Create per-channel fcurves for one pose-bone attribute."""
data_path = f'pose.bones["{bone_name}"].{attr}'
for i in range(n_components):
fc = action.fcurves.new(data_path=data_path, index=i)
fc.keyframe_points.add(len(keyframes))
for idx, (frame, val) in enumerate(keyframes):
kp = fc.keyframe_points[idx]
kp.co = (frame, val[i])
kp.interpolation = 'LINEAR'
def rebuild_action_from_data(armature, anim_data_dict):
"""Replace the armature's animation with a new Action built from keyframes.
``anim_data_dict`` has the format returned by
:func:`compute_bone_keyframes`. Any existing action / NLA tracks on the
armature are cleared first; bones missing from the armature are skipped
with a warning.
"""
clear_animation_state(armature)
new_action = bpy.data.actions.new(name=RECONSTRUCTED_ACTION_NAME)
bind_action(armature, new_action)
valid_bones = {bone.name for bone in armature.data.bones}
for bone_name, data in anim_data_dict.items():
if bone_name not in valid_bones:
logger.warning(f"Skipping keyframes for '{bone_name}': not in armature")
continue
_add_fcurves(new_action, bone_name, 'location', 3, data['location'])
_add_fcurves(new_action, bone_name, 'rotation_quaternion', 4, data['rotation'])
# ─────────────────────────────────────────────────────────────────────────────
# 4. Armature reconciliation: handle bones not present in the animation
# ─────────────────────────────────────────────────────────────────────────────
EXTRA_BONES_STRATEGIES = ('keep', 'merge', 'remove')
def skin_rigid_parts(armature):
"""Bind the meshes hanging under *armature* without an Armature modifier
(rigid parts parented to a bone or to the armature object) to one bone
each, weight 1, keeping their rest-pose world transform: the bone they (or
their nearest ancestor) are parented to, else the main root bone (the one
with the most bones below it). They then move with that bone like before,
and count as skinned for code that keeps only skinned meshes. Every part's
bone is chosen before any part is re-parented (a part under another part
would lose its bone otherwise), the armature is put in its rest pose
meanwhile, and a mesh shared with other objects is copied first (vertex
groups belong to the mesh). Returns the names of the meshes converted."""
bones = armature.data.bones
roots = [b for b in bones if b.parent is None]
if not roots:
return []
main_root = max(roots, key=lambda b: len(b.children_recursive)).name
plan = []
for obj in armature.children_recursive:
if obj.type != 'MESH' or any(m.type == 'ARMATURE' for m in obj.modifiers):
continue
bone, node = None, obj
while node is not None and node != armature:
if node.parent == armature and node.parent_type == 'BONE' \
and node.parent_bone in bones:
bone = node.parent_bone
break
node = node.parent
plan.append((obj, bone or main_root))
if not plan:
return []
pose_position = armature.data.pose_position
armature.data.pose_position = 'REST'
update_scene()
worlds = [obj.matrix_world.copy() for obj, _ in plan]
for obj, bone in plan:
if obj.data.users > 1:
obj.data = obj.data.copy()
for group in list(obj.vertex_groups): # unbound groups named like
if group.name in bones and group.name != bone: # bones would deform now
obj.vertex_groups.remove(group)
group = obj.vertex_groups.get(bone) or obj.vertex_groups.new(name=bone)
group.add(list(range(len(obj.data.vertices))), 1.0, 'REPLACE')
modifier = obj.modifiers.new(name='Armature', type='ARMATURE')
modifier.object = armature
for obj, _ in plan:
obj.parent = armature
obj.parent_type = 'OBJECT'
update_scene()
for (obj, _), world in zip(plan, worlds):
obj.matrix_world = world
update_scene()
armature.data.pose_position = pose_position
update_scene()
logger.info(f"Bound {len(plan)} rigid part(s) to their bones: "
f"{[(o.name, b) for o, b in plan][:5]}")
return [obj.name for obj, _ in plan]
def find_skinned_meshes(armature):
"""Return all mesh objects whose Armature modifier targets *armature*."""
meshes = []
for obj in bpy.context.scene.objects:
if obj.type != 'MESH':
continue
for mod in obj.modifiers:
if mod.type == 'ARMATURE' and mod.object == armature:
meshes.append(obj)
break
return meshes
def _topmost_kept(bone, kept_bone_set):
"""The kept bone nearest *bone* in its own subtree (breadth first), or None."""
queue = list(bone.children)
while queue:
b = queue.pop(0)
if b.name in kept_bone_set:
return b
queue.extend(b.children)
return None
def build_ancestor_map(armature, kept_bone_set):
"""Map each armature bone NOT in *kept_bone_set* to the kept bone that
takes its weights: its nearest kept ancestor. A bone with none (a dropped
root, such as the pass-through root the export promotes away, or a separate
root) maps to the topmost kept bone of its own subtree, else to the main
kept root (the one with the most kept bones below it), so its vertices
follow the body instead of losing their weights.
Returns ``{dropped_name: kept_name_or_None}``; ``None`` only when no
bone is kept.
"""
bones = armature.data.bones
kept_roots = [b for b in bones if b.name in kept_bone_set
and not any(a.name in kept_bone_set for a in b.parent_recursive)]
main_root = max(kept_roots, key=lambda b: sum(c.name in kept_bone_set
for c in b.children_recursive),
default=None)
mapping = {}
for bone in bones:
if bone.name in kept_bone_set:
continue
parent = bone.parent
while parent is not None and parent.name not in kept_bone_set:
parent = parent.parent
target = parent or _topmost_kept(bone, kept_bone_set) or main_root
mapping[bone.name] = target.name if target is not None else None
return mapping
def transfer_vertex_group(mesh_obj, src_name, dst_name):
"""Merge weights of vertex group *src_name* into *dst_name* and delete src.
If *dst_name* is ``None``, the src group is just removed. Existing dst
weights are preserved and incremented (ADD semantics).
"""
vgs = mesh_obj.vertex_groups
src = vgs.get(src_name)
if src is None:
return
if dst_name is None:
vgs.remove(src)
return
dst = vgs.get(dst_name) or vgs.new(name=dst_name)
src_idx = src.index
# Snapshot (vert_idx, weight) pairs before mutating the groups.
transfers = []
for vert in mesh_obj.data.vertices:
for grp in vert.groups:
if grp.group == src_idx:
if grp.weight > 0.0:
transfers.append((vert.index, grp.weight))
break # a vertex appears at most once per group
for v_idx, weight in transfers:
dst.add([v_idx], weight, 'ADD')
vgs.remove(src)
def merge_extra_bone_weights(armature, kept_bone_set):
"""Transfer weights of dropped bones to the kept bone that takes them
(:func:`build_ancestor_map`: the nearest kept ancestor; for a dropped
root, the kept bone below it).
Returns the ancestor map used (for logging).
"""
ancestor_map = build_ancestor_map(armature, kept_bone_set)
if not ancestor_map:
return ancestor_map
meshes = find_skinned_meshes(armature)
if not meshes:
logger.warning("No skinned meshes found targeting this armature; "
"weight transfer is a no-op")
for src_name, dst_name in ancestor_map.items():
for mesh_obj in meshes:
transfer_vertex_group(mesh_obj, src_name, dst_name)
return ancestor_map
def delete_dominant_weighted_vertices(mesh_obj, dropped_bone_names):
"""Delete vertices whose dominant (max-weight) group is in *dropped_bone_names*.
Vertices with mixed influences whose primary bone survives are kept,
so we don't punch holes near boundary regions (e.g. wrist verts that
have minor finger-bone influences but are mostly weighted to the
forearm).
Returns the number of vertices deleted from *mesh_obj*.
"""
vgs = mesh_obj.vertex_groups
dropped_idxs = {vgs[name].index for name in dropped_bone_names if name in vgs}
if not dropped_idxs:
return 0
verts_to_delete = []
for vert in mesh_obj.data.vertices:
if not vert.groups:
continue
max_weight = -1.0
max_group = -1
for g in vert.groups:
if g.weight > max_weight:
max_weight = g.weight
max_group = g.group
if max_group in dropped_idxs:
verts_to_delete.append(vert.index)
if not verts_to_delete:
return 0
bm = bmesh.new()
bm.from_mesh(mesh_obj.data)
bm.verts.ensure_lookup_table()
bmesh.ops.delete(
bm,
geom=[bm.verts[i] for i in verts_to_delete],
context='VERTS',
)
bm.to_mesh(mesh_obj.data)
bm.free()
mesh_obj.data.update()
return len(verts_to_delete)
def delete_skin_vertices_for_bones(armature, dropped_bone_names):
"""Delete dominantly-weighted vertices for *dropped_bone_names* across all meshes.
Returns ``{mesh_name: n_deleted}`` for logging.
"""
if not dropped_bone_names:
return {}
meshes = find_skinned_meshes(armature)
if not meshes:
logger.warning("No skinned meshes found targeting this armature; "
"vertex deletion is a no-op")
return {}
deleted = {}
for mesh_obj in meshes:
n = delete_dominant_weighted_vertices(mesh_obj, dropped_bone_names)
if n:
deleted[mesh_obj.name] = n
return deleted
def remove_armature_bones(armature, bone_names):
"""Delete *bone_names* from *armature* in EDIT mode, keeping the
hierarchy connected.
Blender does NOT re-parent children when an edit bone is removed —
they silently become parentless roots. So before deleting, every
surviving bone whose parent chain passes through a dropped bone is
re-parented to its nearest surviving ancestor (the same bone its
vertex weights are merged into under the 'merge' strategy). Edit-bone
head/tail are stored in armature space, so re-parenting with
``use_connect=False`` preserves each bone's rest transform exactly.
"""
bpy.context.view_layer.objects.active = armature
bpy.ops.object.mode_set(mode='EDIT')
edit_bones = armature.data.edit_bones
dropped = {name for name in bone_names if name in edit_bones}
for bone in edit_bones:
if bone.name in dropped:
continue
if bone.parent is None or bone.parent.name not in dropped:
continue
ancestor = bone.parent
while ancestor is not None and ancestor.name in dropped:
ancestor = ancestor.parent
bone.use_connect = False
bone.parent = ancestor
if ancestor is None:
logger.warning(
f"Bone '{bone.name}': entire parent chain was dropped; "
f"it becomes a root bone"
)
else:
logger.info(f"Re-parented '{bone.name}' to surviving ancestor "
f"'{ancestor.name}'")
for bone_name in dropped:
edit_bones.remove(edit_bones[bone_name])
bpy.ops.object.mode_set(mode='OBJECT')
_DEDUP_SUFFIX = re.compile(r'^(.*)\.(\d{3})$')
def rename_truncated_bones(armature, motion_names):
"""Give bones the motion's name where the two differ only in how a long
name was cut. Blender caps bone names at 63 bytes and de-duplicates with
``.NNN``, and Blender versions differ in how many characters they keep
before the suffix (``<base>.001`` in one, ``<base>h.001`` in another). A
motion name absent from
the armature matches the one bone, itself not a motion name and cut at the
limit (63 bytes), with the same ``.NNN`` suffix whose base starts with the
motion name's base (itself cut: at least 59 bytes); renaming the bone
renames its vertex groups too. Returns ``{old: new}``."""
wanted = [str(n) for n in motion_names]
wanted_set = set(wanted)
bone_names = set(armature.data.bones.keys())
free = [b for b in bone_names if b not in wanted_set and len(b.encode()) == 63]
renames = {}
for name in wanted:
m = _DEDUP_SUFFIX.match(name)
if name in bone_names or m is None or len(name.encode()) < 59:
continue
cands = [b for b in free if b not in renames
and (mb := _DEDUP_SUFFIX.match(b)) is not None
and mb.group(2) == m.group(2) and mb.group(1).startswith(m.group(1))]
if len(cands) == 1:
renames[cands[0]] = name
for old, new in renames.items():
armature.data.bones[old].name = new
if renames:
logger.info(f"Renamed {len(renames)} bone(s) cut differently from the motion's "
f"names: {list(renames.items())[:3]}")
return renames
def sync_armature_bones(armature, anim_bone_names, extra_bones_strategy='merge'):
"""Reconcile armature bones with the animation bone list.
*extra_bones_strategy* controls what happens to armature bones that are
NOT present in *anim_bone_names*:
- ``'merge'`` (default): transfer each extra bone's vertex weights to
its nearest kept ancestor on every skinned mesh (a dropped root's to
the kept bone below it, see :func:`build_ancestor_map`), then delete
the bone. Mesh stays attached; articulation in the merged region is lost.
- ``'remove'``: delete the bones AND every mesh vertex whose dominant
(max-weight) bone is one of them. Vertices with mixed influences
whose primary bone survives are kept, so we don't punch holes near
boundary regions.
- ``'keep'``: leave the bones in place with no keyframes. They sit at
identity local pose and inherit their parent's animated transform
through Blender's hierarchical pose evaluation.
Animation bones absent from the armature are always logged and skipped
by :func:`rebuild_action_from_data`.
"""
if extra_bones_strategy not in EXTRA_BONES_STRATEGIES:
raise ValueError(
f"extra_bones_strategy must be one of {EXTRA_BONES_STRATEGIES}, "
f"got {extra_bones_strategy!r}"
)
rename_truncated_bones(armature, anim_bone_names)
armature_bone_set = {bone.name for bone in armature.data.bones}
anim_bone_set = {str(name) for name in anim_bone_names}
extra = armature_bone_set - anim_bone_set
if extra:
if extra_bones_strategy == 'keep':
logger.info(
f"Keeping {len(extra)} armature bones not in animation "
f"(no keyframes; will follow parent pose): {sorted(extra)}"
)
elif extra_bones_strategy == 'merge':
ancestor_map = merge_extra_bone_weights(armature, anim_bone_set)
summary = ', '.join(
f"{src}->{dst or '<orphan>'}"
for src, dst in sorted(ancestor_map.items())
)
logger.warning(
f"Merged {len(extra)} extra armature bones into the kept bone that "
f"takes their weights and removed them: {summary}"
)
remove_armature_bones(armature, extra)
else: # 'remove'
deleted = delete_skin_vertices_for_bones(armature, extra)
if deleted:
total = sum(deleted.values())
summary = ', '.join(f"{name}: {n}" for name, n in sorted(deleted.items()))
logger.warning(
f"Deleted {total} mesh vertices dominantly weighted to "
f"dropped bones ({summary})"
)
logger.warning(f"Removing armature bones not in animation: {sorted(extra)}")
remove_armature_bones(armature, extra)
missing = anim_bone_set - armature_bone_set
if missing:
logger.warning(f"Animation bones not in armature (will be skipped): {missing}")
update_scene()
# ─────────────────────────────────────────────────────────────────────────────
# 5. Character export
# ─────────────────────────────────────────────────────────────────────────────
def export_animated_character(output_path_no_ext, formats=('glb',)):
"""Export every MESH + ARMATURE object to ``<output_path_no_ext>.<fmt>``.
Stale actions other than the reconstructed one are removed first so the
exporters only bake the driving animation.
"""
export_objs = [obj for obj in bpy.context.scene.objects
if obj.type in ('MESH', 'ARMATURE')]
select_objs(export_objs, deselect_first=True)
for action in list(bpy.data.actions):
if action.name != RECONSTRUCTED_ACTION_NAME:
bpy.data.actions.remove(action)
# Imported characters can carry object-level animation data (static
# transform keys); the glTF exporter samples it into a stray extra
# animation, so drop everything but the reconstructed armature action.
for obj in export_objs:
anim_data = obj.animation_data
if anim_data is not None and (
anim_data.action is None
or anim_data.action.name != RECONSTRUCTED_ACTION_NAME):
obj.animation_data_clear()
for fmt in formats:
export_selected_to_file(f"{output_path_no_ext}.{fmt}", fmt)
def export_selected_to_file(filepath, char_anim_type='glb', custom_props=False):
"""Export currently-selected scene objects to GLB or FBX.
``custom_props`` also exports object-level custom properties (glTF
extras / FBX user properties) — used by the canonical bake to carry
the canonical joint order inside the asset.
"""
if char_anim_type == 'glb':
bpy.ops.export_scene.gltf(
filepath=filepath,
check_existing=False,
use_selection=True,
export_format='GLB',
export_extras=custom_props,
# Export the action's own F-curves rather than resampling every
# object: sampling also bakes the armature *object's* static
# transform into a stray second glTF animation.
export_force_sampling=False,
)
elif char_anim_type == 'fbx':
# The FBX exporter drops textures that aren't wired directly into a
# Principled BSDF (Mix nodes, unlit materials); flatten those first.
simplify_materials_for_fbx(bpy.context.selected_objects)
# Sidecar copies for FBX consumers that ignore embedded media;
# embedding itself reads packed data or these files.
write_packed_images_to_dir(
os.path.join(os.path.dirname(os.path.abspath(filepath)), 'textures'))
bpy.ops.export_scene.fbx(
filepath=filepath,
check_existing=False,
use_selection=True,
use_triangles=True,
add_leaf_bones=False,
bake_anim=True,
path_mode="COPY",
embed_textures=True,
use_custom_props=custom_props,
)
else:
raise RuntimeError(f"Invalid char_anim_type: {char_anim_type}")
logger.info(f"Saved animated character: {filepath}")