Cepheid

Paper (arXiv 2610.18871) · Project page · Code

Weights for Cepheid: Decoupling Scale from Structure for Cross-Family Motion Completion. Given a 3D mesh and the 3D displacements of a sparse subset of its vertices, Cepheid completes the dense motion of every vertex as F̂ = H + ŝ·R̄: H is the harmonic extension of the observed displacements, ŝ the predicted amplitude from amplitude recovery, and R̄ the mean of k samples of a flow-matching network's dimensionless residual.

The model

unified/ is the unified prior, the "ours (unified)" row of Table 2 of the paper: one network trained on DeformingThings4D, AMASS and a Franka robot arm, scored on those three families and zero-shot on cloth and legged robots. Table 2 (completion error divided by each column's mean motion magnitude; harmonic is the no-learning base):

	DT4D	AMASS	Franka	cloth	legged
harmonic	0.2685	0.0693	0.1011	0.4377	0.2474
ours (unified)	0.1243	0.0214	0.0201	0.3692	0.2225

Loading

pip install "git+https://github.com/Su-Terry/cepheid.git"   # install PyTorch for your CUDA first

from cepheid import Cepheid
model = Cepheid.from_pretrained("ohinic/cepheid")             # downloads unified/, checks sha256
out = model.complete(vertices, faces=faces, observed_idx=idx, observed_disp=disp)

from_pretrained downloads unified/ and SHA256SUMS, checks every file's sha256 against SHA256SUMS, and loads the state dict strictly. out.F is the completed motion, out.H the harmonic extension and out.s_hat the predicted amplitude.

Files

path	contents
unified/model.safetensors	the unified model's weights
unified/config.json	the architecture, base and normalisation settings, generated from configs/xm2_unified.yaml
unified/amplitude_rule.json	the frozen amplitude rule the model was trained and scored with (sha256 f4d1bc5d…9a7f)
unified/checkpoint_meta.json	the training metadata stored in the checkpoint
paper_checkpoints/*.pt	the eleven checkpoints the paper's tables were scored with, byte for byte, for reproduction with the code repository
SHA256SUMS	sha256 of every file above

The unified/ files are for the API. The paper_checkpoints/ files are for reproducing the paper's tables (see REPRODUCE.md in the code repository); which checkpoint gives which row:

checkpoint	table and row
xm2_unified_model.pt	Table 1 "ours (unified)"; Table 2 "ours (unified)"; Table 3 (the network predictions every row rescales); Table 4 last row and the "mean of k samples" dash row (the same weights read at k = 1); Table 8 last row; Table 15 "zero-shot"
xm2_dt4d_model.pt	Table 2 "ours (DT4D)"
xm2_amass_model.pt	Table 2 "ours (AMASS)"
xm2_franka_model.pt	Table 2 "ours (Franka)"
xm2_unified_zero_model.pt	Table 4 / Table 8, the row without harmonic extension
xm2_unified_reg_model.pt	Table 4 / Table 8, the row without flow matching
xm2_unified_nobc_model.pt	Table 4 / Table 8, the row not conditioned on harmonic extension
xmatrix_unified_nonorm500k_model.pt	Table 4 / Table 8, the row without amplitude recovery (ŝ = 1)
crossmesh_knn.pt	Table 14 "Laplacian + GNN (ours)"
dt4d_crossmesh_knn_tps.pt	Table 14 "TPS + kNN (ours)"
xm2_franka_anchork_ft_model.pt	Table 15 "fine-tuned"

Limitations

• Resolution lock. The network's message graph is a kNN graph on vertex positions, and the models are locked to the graph density they were trained at (about 3,000 vertices on DT4D, 6,890 on AMASS). Running far from it, or raising k, makes results measurably worse. complete() warns outside 1,000–7,000 vertices.
• DT4D's stored graph. DT4D meshes carry explicit edges, not faces. The preprocessing builds them once per identity, from the largest clip's first frame and faces, and copies that edge set into every clip of the identity. The harmonic extension and the amplitude features use these stored edges; the network's messages do not. Some edges are long in poses other than the reference one. The released numbers use this graph unchanged.
• GPU nondeterminism. The flow-matching sampler is not bit-deterministic on a GPU. Re-running identical code moves sampled sums by up to about 5e-5 relative; the harmonic extension and ground-truth sums do not move. Expect agreement to about four decimals, not bit-identity. On CPU, runs are bit-identical.
• Third-party code is not shipped. The DOMA and NSDP baselines (Table 1) and the GenBot1K rollouts need code from $MC_EXTERNAL that the code repository does not include. Configurations for backbones that need it are kept, but those models are not registered.

License

Non-commercial research use only, subject to the terms of the datasets the weights were trained on (DeformingThings4D, AMASS/SMPL-H, the Franka Panda description).

Citation

@article{su2026cepheid,
  title         = {Cepheid: Decoupling Scale from Structure for Cross-Family Motion Completion},
  author        = {Su, Chih-Hai and Ke, Tsung-Wei and Liu, Yu-Lun},
  journal       = {arXiv preprint arXiv:2610.18871},
  eprint        = {2610.18871},
  archivePrefix = {arXiv},
  year          = {2026}
}