Skip to content

[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons

Python

Decode degenerate 6D rotations to the identity and compute the geodesic loss in float32, require an export digest for reused stage-4 caches, rebuild missing or stale previews without risking cached clips, and read GLB accessors per glTF 2.0

Friedrich-Mb78c7807df7c
diff --git a/data_process/feature_extraction/canonical_assets.py b/data_process/feature_extraction/canonical_assets.py
index fe18fc3..6a0c6d6 100644
--- a/data_process/feature_extraction/canonical_assets.py
+++ b/data_process/feature_extraction/canonical_assets.py
@@ -302,6 +302,12 @@ def bake_canonical_assets(export_dir, features_dir, assets_dir=None, dataset_typ
for fmt, path in extra_files:
os.replace(f'{partial}.{fmt}', path)
os.replace(partial + '.glb', final)
+ # Another format of the asset that this run did not write was
+ # baked from the older inputs (the GLB is always written).
+ for fmt in CANONICAL_FORMATS:
+ stale = os.path.join(out_dir, f'{name}.{fmt}')
+ if fmt != 'glb' and fmt not in formats and os.path.isfile(stale):
+ os.remove(stale)
except Exception as exc: # noqa: BLE001 — keep the batch going
if isinstance(exc, UndeterminedRoll): # incl. CollinearSkeleton
logger.info(f"Canonical GLB of '{name}' refused: {exc}")
diff --git a/data_process/feature_extraction/extract_features.py b/data_process/feature_extraction/extract_features.py
index 13ec2f7..7d23fc3 100644
--- a/data_process/feature_extraction/extract_features.py
+++ b/data_process/feature_extraction/extract_features.py
@@ -36,7 +36,12 @@ result under ``<save_dir>/cond_parts/`` and is skipped on rerun. The cache
records the clip / threshold / topology settings and the export files (name,
size, mtime) it was built from and is re-processed automatically when they
change; delete ``cond_parts/`` (or one entry) to force re-processing for any
-other reason.
+other reason. An entry that does not record the export files is re-processed
+too, unless ``--adopt_legacy_cache`` vouches that the export has not changed
+since it was written. With ``--vis``, a cached object whose previews are
+missing, were made with another ``--vis_ground`` or with unrecorded settings
+is processed again into a temporary directory, and its outputs replace the
+cached ones only when every clip got its preview.
Object types that fail are logged to ``<save_dir>/extract_errors.log``,
recorded in ``filtered_clips.json`` and skipped (no cache entry is written,
@@ -54,6 +59,7 @@ import hashlib
import json
import multiprocessing as mp
import os
+import shutil
import zipfile
from os.path import join as pjoin
@@ -228,6 +234,11 @@ def parse_args(argv=None):
"follow camera, contact shadow and root "
"trajectory (default). --no-vis_ground renders "
"the plain cubic view instead.")
+ parser.add_argument("--adopt_legacy_cache", action="store_true",
+ help="Keep cond_parts/ entries that record no export digest "
+ "instead of re-processing their objects, and stamp them with "
+ "the current one. Only for entries known to be built from the "
+ "current export: nothing checks it.")
parser.add_argument("--save_glb", action="store_true",
help="Afterwards bake <data_dir>/rigs/<asset>.glb (the export stage's "
"rest-pose assets, run_export.sh --save_glb / --glb_only) into the "
@@ -522,7 +533,7 @@ def _export_digest(task):
"""Digest of the inputs the settings hash cannot see: each clip NPZ's name,
size and mtime (a re-export under the same clip names) and the object's
``joint_names.json`` entry (its order drives the clean-name realignment).
- Kept beside ``params_hash`` rather than in it (see :func:`_load_cached_result`)."""
+ Kept beside ``params_hash`` rather than in it (see :func:`_load_cached_payload`)."""
files = []
for path in sorted(task['object_npzs']):
st = os.stat(path)
@@ -530,11 +541,15 @@ def _export_digest(task):
return _digest([files, task.get('expected_names')])
-def _load_cached_result(part_path, object_type, params, params_hash, export_digest):
- """Return a cached object result, or None when absent / stale / unreadable.
+def _load_cached_payload(part_path, object_type, params, params_hash, export_digest,
+ adopt_legacy=False):
+ """Return the cache entry of an object (``result`` and what it was built
+ from), or None when absent / stale / unreadable.
- An entry without an ``export_digest`` is taken as built from the current
- export and stamped with its digest."""
+ An entry without an ``export_digest`` cannot show that it was built from
+ the current export, so it is a miss unless *adopt_legacy*
+ (``--adopt_legacy_cache``) vouches for it; it is then stamped with the
+ current digest."""
if not os.path.isfile(part_path):
return None
try:
@@ -544,18 +559,23 @@ def _load_cached_result(part_path, object_type, params, params_hash, export_dige
f're-processing')
return None
- if 'params_hash' not in payload:
+ if 'params_hash' not in payload or 'result' not in payload:
logger.info(f'[{object_type}] cache invalidated (entry predates settings '
- f'tracking); re-processing')
+ f'tracking or holds no result); re-processing')
return None
if payload['params_hash'] == params_hash:
cached_digest = payload.get('export_digest')
if cached_digest is None:
+ if not adopt_legacy:
+ logger.info(f'[{object_type}] cache entry records no export digest; '
+ f're-processing (--adopt_legacy_cache keeps entries known to '
+ f'match the current export)')
+ return None
payload['export_digest'] = export_digest
atomic_np_save(part_path, payload)
- return payload.get('result')
+ return payload
if cached_digest == export_digest:
- return payload.get('result')
+ return payload
logger.info(f'[{object_type}] cache invalidated (export NPZs or joint_names.json '
f'entry changed); re-processing')
return None
@@ -601,6 +621,135 @@ def _prune_object_clips(save_dir, clip_prefix, prune_vis):
return removed
+def _vis_record(save_vis, vis_ground):
+ """The preview settings a cache entry records: None when the run made no
+ previews."""
+ return {'ground': bool(vis_ground)} if save_vis else None
+
+
+def _previews_current(payload, save_dir, clip_prefix, vis_ground):
+ """Whether a cached object's previews are the ones a ``--vis`` run with
+ *vis_ground* makes: the entry records previews made with that ground
+ setting (an entry that records none, or no settings at all, does not
+ qualify), and every clip of the object in ``motions/`` has its
+ ``videos/<clip>.mp4``."""
+ record = payload.get('vis')
+ if not isinstance(record, dict) or record.get('ground') != bool(vis_ground):
+ return False
+ motions_dir, videos_dir = pjoin(save_dir, 'motions'), pjoin(save_dir, 'videos')
+ clips = [name[:-4] for name in (os.listdir(motions_dir) if os.path.isdir(motions_dir) else [])
+ if name.startswith(clip_prefix) and name.endswith('.npz')]
+ return all(os.path.isfile(pjoin(videos_dir, clip + '.mp4')) for clip in clips)
+
+
+def _rebuild_dir(save_dir, object_type):
+ return pjoin(save_dir, f'.rebuild_{object_type}')
+
+
+def _object_files(save_dir, object_type, clip_prefix):
+ """``(subdir, name)`` of every output file of the object: its clips,
+ previews and T-pose image."""
+ files = []
+ for sub, ext in (('motions', '.npz'), ('videos', '.mp4')):
+ d = pjoin(save_dir, sub)
+ files += [(sub, name) for name in (os.listdir(d) if os.path.isdir(d) else [])
+ if name.startswith(clip_prefix) and name.endswith(ext)]
+ if os.path.isfile(pjoin(save_dir, 'tpose', f'{object_type}.png')):
+ files.append(('tpose', f'{object_type}.png'))
+ return files
+
+
+def _rebuild_with_previews(object_type, task, clip_prefix, part_path, payload, vis):
+ """Process a cached object again, with previews, into a temporary
+ directory beside the outputs; when every clip got its preview, swap its
+ files in and write its new cache entry.
+
+ The swap removes the cache entry first and moves the object's current
+ files into the temporary directory before the new ones go in, so an
+ error midway is undone (old files and entry restored) and a crash
+ midway leaves a miss, never an entry beside half-replaced files.
+
+ Returns ``('rebuilt', result)``; ``('kept', None)`` when the rebuild
+ failed and the cached files and entry are as before; or ``('lost',
+ error)`` when an undo failed too: the entry is then gone, so the next
+ run re-processes the object.
+ """
+ save_dir = task['save_dir']
+ tmp = _rebuild_dir(save_dir, object_type)
+ shutil.rmtree(tmp, ignore_errors=True)
+ try:
+ obj_cond, n_clips, n_frames, n_joints, filtered = process_object(
+ object_type, **dict(task, save_dir=tmp))
+ made = [(sub, name) for sub in ('motions', 'videos', 'tpose')
+ for name in (sorted(os.listdir(pjoin(tmp, sub)))
+ if os.path.isdir(pjoin(tmp, sub)) else [])]
+ videos = {name for sub, name in made if sub == 'videos'}
+ missing = [name[:-4] for sub, name in made
+ if sub == 'motions' and name[:-4] + '.mp4' not in videos]
+ if missing:
+ raise RuntimeError(f'{len(missing)} preview(s) not rendered, e.g. {missing[0]}')
+ except Exception as e: # noqa: BLE001 — nothing of the cached object was touched
+ shutil.rmtree(tmp, ignore_errors=True)
+ logger.warning(f'[{object_type}] previews could not be rebuilt '
+ f'({type(e).__name__}: {e}); kept the cached clips')
+ return 'kept', None
+ result = {'cond': obj_cond, 'n_clips': n_clips, 'n_frames': n_frames,
+ 'n_joints': n_joints, 'filtered': filtered}
+
+ old_dir = pjoin(tmp, 'previous')
+ moved_out, moved_in = [], []
+ try:
+ if os.path.isfile(part_path):
+ os.remove(part_path)
+ for sub, name in _object_files(save_dir, object_type, clip_prefix):
+ os.makedirs(pjoin(old_dir, sub), exist_ok=True)
+ os.replace(pjoin(save_dir, sub, name), pjoin(old_dir, sub, name))
+ moved_out.append((sub, name))
+ for sub, name in made:
+ os.makedirs(pjoin(save_dir, sub), exist_ok=True)
+ os.replace(pjoin(tmp, sub, name), pjoin(save_dir, sub, name))
+ moved_in.append((sub, name))
+ atomic_np_save(part_path, {**payload, 'result': result, 'vis': vis})
+ except Exception as e: # noqa: BLE001 — undo the swap
+ try:
+ for sub, name in moved_in:
+ os.remove(pjoin(save_dir, sub, name))
+ for sub, name in moved_out:
+ os.replace(pjoin(old_dir, sub, name), pjoin(save_dir, sub, name))
+ atomic_np_save(part_path, payload)
+ except Exception as undo: # noqa: BLE001 — leave a miss behind
+ if os.path.isfile(part_path):
+ os.remove(part_path)
+ logger.error(f'[{object_type}] previews could not be swapped in '
+ f'({type(e).__name__}: {e}) nor the swap undone '
+ f'({type(undo).__name__}: {undo}); the object will be re-processed '
+ f'(its earlier files are in {old_dir} until then)')
+ return 'lost', f'swap failed ({type(e).__name__}: {e}), undo failed ({undo})'
+ shutil.rmtree(tmp, ignore_errors=True)
+ logger.warning(f'[{object_type}] previews could not be swapped in '
+ f'({type(e).__name__}: {e}); restored the cached clips')
+ return 'kept', None
+ shutil.rmtree(tmp, ignore_errors=True)
+ return 'rebuilt', result
+
+
+def _failed(object_type, save_dir, error):
+ """The result of an object that failed, its error appended to
+ ``extract_errors.log``."""
+ try:
+ os.makedirs(save_dir, exist_ok=True)
+ with open(_error_log_path(save_dir), 'a') as log_file:
+ log_file.write(f'{object_type}\t{error}\n')
+ except OSError as log_err:
+ logger.warning(f'[{object_type}] could not write error log: {log_err}')
+ return {
+ 'cond': None, 'n_clips': 0, 'n_frames': 0, 'n_joints': 0,
+ 'filtered': [{'name': f'{object_type} (all clips)',
+ 'reason': f'processing failed: {error}'}],
+ 'error': error,
+ }
+
+
def process_object_task(task):
"""Process one object type, caching its result for resume.
@@ -608,6 +757,11 @@ def process_object_task(task):
path. The cached result is reused only when it was produced with the same
clip / threshold / topology settings (see ``CACHE_PARAM_KEYS``).
+ With ``save_vis``, a cached object whose previews are not current (see
+ :func:`_previews_current`) is rebuilt with :func:`_rebuild_with_previews`;
+ if that fails, the cached result is used without them, unless its files
+ could not be restored, which fails the object.
+
Failures are contained here: the object is reported as failed (and its
error appended to ``extract_errors.log``) instead of propagating, which
with ``mp.Pool`` would kill the whole run. On a cache miss the old entry
@@ -625,10 +779,22 @@ def process_object_task(task):
export_digest = _export_digest(task)
task.pop('root_offsets', None) # cache key only; process_object reads the NPZs
task.pop('rest_orientations', None)
-
- cached = _load_cached_result(part_path, object_type, params, params_hash, export_digest)
- if cached is not None:
- return object_type, cached, True
+ adopt_legacy = task.pop('adopt_legacy_cache', False)
+ vis = _vis_record(task['save_vis'], task['vis_ground'])
+
+ payload = _load_cached_payload(part_path, object_type, params, params_hash,
+ export_digest, adopt_legacy=adopt_legacy)
+ if payload is not None:
+ if not task['save_vis'] or _previews_current(payload, task['save_dir'],
+ clip_prefix, task['vis_ground']):
+ return object_type, payload['result'], True
+ status, value = _rebuild_with_previews(object_type, task, clip_prefix,
+ part_path, payload, vis)
+ if status == 'rebuilt':
+ return object_type, value, False
+ if status == 'kept':
+ return object_type, payload['result'], True
+ return object_type, _failed(object_type, task['save_dir'], value), False
try:
# The stale entry goes before the clips it describes: a run that
@@ -636,6 +802,7 @@ def process_object_task(task):
# settings would reuse without its clips.
if os.path.isfile(part_path):
os.remove(part_path)
+ shutil.rmtree(_rebuild_dir(task['save_dir'], object_type), ignore_errors=True)
removed = _prune_object_clips(task['save_dir'], clip_prefix, task['save_vis'])
if removed:
logger.info(f'[{object_type}] removed {removed} clip files from a '
@@ -644,18 +811,8 @@ def process_object_task(task):
object_type, **task)
except Exception as e: # noqa: BLE001 — keep the batch going
logger.exception(f'[{object_type}] failed to process')
- try:
- os.makedirs(task['save_dir'], exist_ok=True)
- with open(_error_log_path(task['save_dir']), 'a') as log_file:
- log_file.write(f'{object_type}\t{type(e).__name__}: {e}\n')
- except OSError as log_err:
- logger.warning(f'[{object_type}] could not write error log: {log_err}')
- return object_type, {
- 'cond': None, 'n_clips': 0, 'n_frames': 0, 'n_joints': 0,
- 'filtered': [{'name': f'{object_type} (all clips)',
- 'reason': f'processing failed: {type(e).__name__}: {e}'}],
- 'error': f'{type(e).__name__}: {e}',
- }, False
+ return object_type, _failed(object_type, task['save_dir'],
+ f'{type(e).__name__}: {e}'), False
result = {'cond': obj_cond, 'n_clips': n_clips, 'n_frames': n_frames,
'n_joints': n_joints, 'filtered': filtered}
@@ -663,7 +820,8 @@ def process_object_task(task):
# entry behind (unreadable ones are treated as misses, but this keeps them
# from happening in the first place).
atomic_np_save(part_path, {'params_hash': params_hash, 'params': params,
- 'export_digest': export_digest, 'result': result})
+ 'export_digest': export_digest, 'result': result,
+ 'vis': vis})
return object_type, result, False
@@ -741,6 +899,7 @@ def build_object_tasks(args, clip_stride, motion_dir, metadata):
jump_ratio_threshold=args.jump_ratio_threshold,
min_joints=args.min_joints, max_joints=args.max_joints,
save_vis=args.vis, vis_ground=args.vis_ground,
+ adopt_legacy_cache=args.adopt_legacy_cache,
))
return tasks
diff --git a/data_process/rig_preprocess/glb.py b/data_process/rig_preprocess/glb.py
index b7890ea..73911f1 100644
--- a/data_process/rig_preprocess/glb.py
+++ b/data_process/rig_preprocess/glb.py
@@ -8,6 +8,8 @@ import numpy as np
_COMPONENTS = {5120: np.int8, 5121: np.uint8, 5122: np.int16, 5123: np.uint16,
5125: np.uint32, 5126: np.float32}
_SIZES = {'SCALAR': 1, 'VEC2': 2, 'VEC3': 3, 'VEC4': 4, 'MAT4': 16}
+# Component types a sparse accessor's indices may have.
+_INDEX_COMPONENTS = {5121: np.uint8, 5123: np.uint16, 5125: np.uint32}
_JSON_CHUNK, _BIN_CHUNK = 0x4E4F534A, 0x004E4942
@@ -29,22 +31,68 @@ class Glb:
offset += 8 + length
self.nodes = self.json.get('nodes', [])
+ def _view_start(self, view_index, byte_offset, nbytes):
+ """Where in the binary chunk *nbytes* at *byte_offset* into a
+ bufferView start; ValueError for a view of another buffer than the
+ GLB's own, or a read past the view or the chunk."""
+ view = self.json['bufferViews'][view_index]
+ if view.get('buffer', 0) != 0:
+ raise ValueError(f"bufferView {view_index} reads buffer {view['buffer']}: only "
+ f"the GLB's binary chunk (buffer 0) is supported")
+ start = view.get('byteOffset', 0) + byte_offset
+ length = view.get('byteLength', len(self.bin) - view.get('byteOffset', 0))
+ if byte_offset + nbytes > length or start + nbytes > len(self.bin):
+ raise ValueError(f"bufferView {view_index}: {nbytes} bytes at offset {byte_offset} "
+ f"read past the view ({length} bytes) or the binary chunk")
+ return view, start
+
def accessor(self, index):
- """Accessor *index* as a float64 ``(count, components)`` array."""
+ """Accessor *index* as a float64 ``(count, components)`` array (glTF
+ 2.0 accessors: interleaved or not, no ``bufferView`` meaning zeros,
+ ``sparse`` replacements, ``normalized`` integers); ValueError for an
+ unsupported or malformed one."""
acc = self.json['accessors'][index]
- view = self.json['bufferViews'][acc['bufferView']]
+ if acc['componentType'] not in _COMPONENTS or acc['type'] not in _SIZES:
+ raise ValueError(f"accessor {index}: unsupported componentType "
+ f"{acc['componentType']} / type {acc['type']!r}")
dtype = np.dtype(_COMPONENTS[acc['componentType']])
- width = _SIZES[acc['type']]
- start = view.get('byteOffset', 0) + acc.get('byteOffset', 0)
- stride = view.get('byteStride', 0) or dtype.itemsize * width
- raw = np.frombuffer(self.bin, dtype=np.uint8, offset=start,
- count=stride * (acc['count'] - 1) + dtype.itemsize * width)
- rows = np.lib.stride_tricks.as_strided(raw, (acc['count'], dtype.itemsize * width),
- (stride, 1))
- arr = np.ascontiguousarray(rows).view(dtype).reshape(acc['count'], width)
+ width, count = _SIZES[acc['type']], acc['count']
+ if 'bufferView' in acc:
+ stride = (self.json['bufferViews'][acc['bufferView']].get('byteStride', 0)
+ or dtype.itemsize * width)
+ nbytes = stride * (count - 1) + dtype.itemsize * width if count else 0
+ _, start = self._view_start(acc['bufferView'], acc.get('byteOffset', 0), nbytes)
+ raw = np.frombuffer(self.bin, dtype=np.uint8, offset=start, count=nbytes)
+ rows = np.lib.stride_tricks.as_strided(raw, (count, dtype.itemsize * width),
+ (stride, 1))
+ arr = np.ascontiguousarray(rows).view(dtype).reshape(count, width)
+ else:
+ arr = np.zeros((count, width), dtype=dtype)
+ sparse = acc.get('sparse')
+ if sparse:
+ arr = arr.copy()
+ n = sparse['count']
+ ind = sparse['indices']
+ if ind['componentType'] not in _INDEX_COMPONENTS:
+ raise ValueError(f"accessor {index}: sparse index componentType "
+ f"{ind['componentType']} is not an unsigned integer type")
+ itype = np.dtype(_INDEX_COMPONENTS[ind['componentType']])
+ _, istart = self._view_start(ind['bufferView'], ind.get('byteOffset', 0),
+ n * itype.itemsize)
+ indices = np.frombuffer(self.bin, dtype=itype, count=n, offset=istart).astype(np.int64)
+ if n and (indices[-1] >= count or np.any(np.diff(indices) <= 0)):
+ raise ValueError(f"accessor {index}: sparse indices must strictly increase "
+ f"and stay below count {count}")
+ vals = sparse['values']
+ _, vstart = self._view_start(vals['bufferView'], vals.get('byteOffset', 0),
+ n * width * dtype.itemsize)
+ arr[indices] = np.frombuffer(self.bin, dtype=dtype, count=n * width,
+ offset=vstart).reshape(n, width)
arr = arr.astype(np.float64)
- if acc.get('normalized'):
+ if acc.get('normalized') and dtype.kind in 'iu':
arr /= np.iinfo(dtype).max
+ if dtype.kind == 'i':
+ np.maximum(arr, -1.0, out=arr)
return arr
@staticmethod
diff --git a/data_process/utils/blender_rig.py b/data_process/utils/blender_rig.py
index 67b107f..755a4b5 100644
--- a/data_process/utils/blender_rig.py
+++ b/data_process/utils/blender_rig.py
@@ -138,11 +138,15 @@ def repair_and_pack_textures(source_path):
def _file_holds(path, data):
- """Whether the file at *path* holds exactly the bytes *data*."""
- if os.path.getsize(path) != len(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
- with open(path, 'rb') as fh:
- return fh.read() == bytes(data)
def write_sidecar(texture_dir, name, ext, data):
diff --git a/unimate/utils/geo_utils.py b/unimate/utils/geo_utils.py
index f927172..6997f79 100644
--- a/unimate/utils/geo_utils.py
+++ b/unimate/utils/geo_utils.py
@@ -12,11 +12,20 @@ def geodesic_distance(R_pred, R_gt):
Returns:
Geodesic angle in radians (..., 1).
+
+ Half-precision inputs are computed in float32, and always outside
+ autocast: in half precision the clamp bound ``1 - 1e-6`` rounds to 1,
+ where arccos has an infinite gradient (e.g. two identity rotations).
"""
- R_rel = th.matmul(R_pred.transpose(-1, -2), R_gt)
- trace = th.diagonal(R_rel, dim1=-2, dim2=-1).sum(-1)
+ with th.autocast(device_type=R_pred.device.type, enabled=False):
+ if R_pred.dtype in (th.float16, th.bfloat16):
+ R_pred = R_pred.float()
+ if R_gt.dtype in (th.float16, th.bfloat16):
+ R_gt = R_gt.float()
+ R_rel = th.matmul(R_pred.transpose(-1, -2), R_gt)
+ trace = th.diagonal(R_rel, dim1=-2, dim2=-1).sum(-1)
- epsilon = 1e-6
- theta = th.arccos(th.clamp((trace - 1) / 2, -1 + epsilon, 1 - epsilon))
+ epsilon = 1e-6
+ theta = th.arccos(th.clamp((trace - 1) / 2, -1 + epsilon, 1 - epsilon))
return theta[..., None]
diff --git a/unimate/utils/rotation_conversions.py b/unimate/utils/rotation_conversions.py
index 2b98492..17c1256 100644
--- a/unimate/utils/rotation_conversions.py
+++ b/unimate/utils/rotation_conversions.py
@@ -13,18 +13,16 @@ import numpy as np
import torch
-def rotation_6d_to_matrix_safe(cont6d: torch.Tensor) -> torch.Tensor:
- """Convert 6D rotation to matrix with NaN protection and epsilon offset.
+# The 6D vector of the identity rotation: what a degenerate 6D vector decodes to.
+IDENTITY_6D = (1.0, 0.0, 0.0, 0.0, 1.0, 0.0)
+# A 6D vector with an axis shorter than this (a zero axis, after the decoder's
+# +1e-8), or whose two axes are closer than PARALLEL_TOL (sine of their angle),
+# is degenerate.
+AXIS_TOL = 1e-6
+PARALLEL_TOL = 1e-6
- Args:
- cont6d: 6D rotation representation (*, 6).
- Returns:
- Rotation matrices (*, 3, 3).
- """
- assert cont6d.shape[-1] == 6, "The last dimension must be 6"
- epsilon = 1e-8
- cont6d = torch.nan_to_num(cont6d) + epsilon
+def _gram_schmidt(cont6d: torch.Tensor) -> torch.Tensor:
x_raw = cont6d[..., 0:3]
y_raw = cont6d[..., 3:6]
x = x_raw / torch.linalg.norm(x_raw, dim=-1, keepdims=True)
@@ -34,8 +32,32 @@ def rotation_6d_to_matrix_safe(cont6d: torch.Tensor) -> torch.Tensor:
return torch.cat([x[..., None], y[..., None], z[..., None]], dim=-1)
-def rotation_6d_to_matrix_np(cont6d: np.ndarray) -> np.ndarray:
- """Convert 6D rotation to matrix (numpy version).
+def _degenerate(cont6d: torch.Tensor) -> torch.Tensor:
+ """Rows that do not define a rotation: an axis shorter than ``AXIS_TOL``,
+ axes less than ``PARALLEL_TOL`` apart (parallel or antiparallel), or any
+ other input whose decode is not finite."""
+ x_raw = cont6d[..., 0:3]
+ y_raw = cont6d[..., 3:6]
+ nx = torch.linalg.norm(x_raw, dim=-1, keepdims=True)
+ ny = torch.linalg.norm(y_raw, dim=-1, keepdims=True)
+ sine = torch.linalg.norm(torch.cross(x_raw / nx, y_raw / ny, dim=-1), dim=-1)
+ finite = torch.isfinite(_gram_schmidt(cont6d)).flatten(-2).all(-1)
+ return ~(finite & (nx[..., 0] > AXIS_TOL) & (ny[..., 0] > AXIS_TOL) & (sine > PARALLEL_TOL))
+
+
+def rotation_6d_to_matrix_safe(cont6d: torch.Tensor) -> torch.Tensor:
+ """Convert 6D rotation to matrix with NaN protection and epsilon offset.
+
+ Every component gets +1e-8. A vector with a non-finite component, or one
+ that is degenerate (see :func:`_degenerate`) before or after the epsilon
+ (zero padding; parallel axes the epsilon would tilt apart), decodes to the
+ identity: it is replaced by ``IDENTITY_6D`` before the decode that
+ gradients flow through, so a degenerate vector yields no NaN, in the
+ result or in its gradient. Every other vector is decoded exactly as
+ without the check. Runs outside autocast; half-precision input is decoded
+ in float32 and the result cast back (the gradient of a nearly degenerate
+ vector, an axis just longer than ``AXIS_TOL``, can still exceed the
+ half-precision range).
Args:
cont6d: 6D rotation representation (*, 6).
@@ -44,6 +66,22 @@ def rotation_6d_to_matrix_np(cont6d: np.ndarray) -> np.ndarray:
Rotation matrices (*, 3, 3).
"""
assert cont6d.shape[-1] == 6, "The last dimension must be 6"
+ dtype = cont6d.dtype
+ with torch.autocast(device_type=cont6d.device.type, enabled=False):
+ if dtype in (torch.float16, torch.bfloat16):
+ cont6d = cont6d.float()
+ epsilon = 1e-8
+ with torch.no_grad():
+ degenerate = ~torch.isfinite(cont6d).all(-1) | _degenerate(torch.nan_to_num(cont6d))
+ cont6d = torch.nan_to_num(cont6d) + epsilon
+ with torch.no_grad():
+ degenerate |= _degenerate(cont6d)
+ identity = torch.tensor(IDENTITY_6D, dtype=cont6d.dtype, device=cont6d.device)
+ cont6d = torch.where(degenerate[..., None], identity, cont6d)
+ return _gram_schmidt(cont6d).to(dtype)
+
+
+def _gram_schmidt_np(cont6d: np.ndarray) -> np.ndarray:
x_raw = cont6d[..., 0:3]
y_raw = cont6d[..., 3:6]
x = x_raw / np.linalg.norm(x_raw, axis=-1, keepdims=True)
@@ -53,6 +91,33 @@ def rotation_6d_to_matrix_np(cont6d: np.ndarray) -> np.ndarray:
return np.concatenate([x[..., None], y[..., None], z[..., None]], axis=-1)
+def rotation_6d_to_matrix_np(cont6d: np.ndarray) -> np.ndarray:
+ """Convert 6D rotation to matrix (numpy version).
+
+ A vector with a non-finite component, an axis shorter than ``AXIS_TOL``,
+ or axes less than ``PARALLEL_TOL`` apart decodes to the identity; every
+ other vector is decoded as is, with no epsilon.
+
+ Args:
+ cont6d: 6D rotation representation (*, 6).
+
+ Returns:
+ Rotation matrices (*, 3, 3).
+ """
+ assert cont6d.shape[-1] == 6, "The last dimension must be 6"
+ with np.errstate(divide='ignore', invalid='ignore', over='ignore'):
+ mats = _gram_schmidt_np(cont6d)
+ nx = np.linalg.norm(cont6d[..., 0:3], axis=-1, keepdims=True)
+ ny = np.linalg.norm(cont6d[..., 3:6], axis=-1, keepdims=True)
+ sine = np.linalg.norm(np.cross(cont6d[..., 0:3] / nx, cont6d[..., 3:6] / ny, axis=-1), axis=-1)
+ valid = (np.isfinite(cont6d).all(-1) & np.isfinite(mats).reshape(*mats.shape[:-2], 9).all(-1)
+ & (nx[..., 0] > AXIS_TOL) & (ny[..., 0] > AXIS_TOL) & (sine > PARALLEL_TOL))
+ if valid.all():
+ return mats
+ identity = np.asarray(IDENTITY_6D, dtype=mats.dtype)
+ return _gram_schmidt_np(np.where(valid[..., None], cont6d, identity))
+
+
def matrix_to_quaternion_np(mats: np.ndarray) -> np.ndarray:
"""Convert rotation matrices to unit quaternions (numpy version).