third_party/Puppeteer/skinning/README.md

Skinning Weight Prediction

This folder provides the skinning weight prediction implementation and scripts to evaluate the paper’s metrics on three test sets. You can also run inference on your own 3D objects.

Weights Download

First download checkpoints of PartField and our released weights for skinning weight prediction:

ln -s ../../skeleton/third_partys/Michelangelo third_partys/Michelangelo
python download.py

Evaluation

To reproduce our evaluations, run the following command on Articulation-XL2.0-test, ModelResource-test and Diverse-pose-test. The test sets are available here, we preprocess the released NPZ files and save them as h5 files (check utils/save_h5.py for how we save them). The inference process requires 4.2 GB of VRAM.

bash eval.sh

We save the skinning weights as .npy files by passing --save_skin_npy.

Demo

Given meshes and skeletons, we can predict skinning weights by running:

bash demo.sh

For inputs, place meshes .obj files in the directory specified by --mesh_folder, and place rig .txt files in --input_skel_folder. Each mesh and rig pair must share same filenames. The rig files should follow the RigNet format containing:

joints [joint_name] [x] [y] [z]
root [root_joint_name]
hier [parent_joint_name] [child_joint_name]

If you are using GLB files, refer to skeleton/data_utils/read_rig_mesh_from_glb.py for reading the mesh and rig. After predict skinning weights, we will save the final rig files by adding skinning lines:

skin [vertex_index] [joints_name1] [skinning_weight1] [joints_name2] [skinning_weight2] ...

⚠️ Note that meshes with complex topology may require more data processing time.

Visualization

The skinning visualizations shown in the paper can be reproduced using utils/visualize.py. This script generates two types of visualizations: (1) objects with skinning weights represented as colors, and (2) objects with L1 error maps that highlight differences between predicted and ground truth skinning weights.