UniPhysGen-1.7B-Kinematics

UniPhysGen-1.7B-Kinematics is the kinematic parameter grounding checkpoint of UniPhysGen, fine-tuned from the physical semantic alignment checkpoint UniPhysGen-1.7B-Physics. Given a full-object point cloud and the point cloud of a movable target part, it predicts the prismatic or revolute joint type, motion axis, pivot, and motion range.

Its geometry-robust articulation grounding combines SO(3) rotation augmentation, spherical axis parameterization, and a shared global voxel origin to reduce orientation shortcuts and preserve object-to-part spatial correspondence for pivot localization under heterogeneous part decompositions. See the paper for details.

Model details

Inputs and outputs

[!IMPORTANT] The target part must be a movable part, with prismatic (B) or revolute (C) motion. Select the target part before running kinematic inference. Movable parts can be identified using:

• First-stage Physics predictions: run UniPhysGen-1.7B-Physics and select parts whose result.part_identity.motion_type is B or C.
• Other sources: ground-truth or manual annotations, existing asset metadata, or another movable-part identification method.

Running Physics is optional when movable parts are already known. The Kinematics entry point does not automatically run Physics or filter parts; pass only the selected movable parts. Contact-only (A) and rigid/fixed (D) parts are outside this task's target set.

The recommended point-cloud format is .npz with aligned arrays:

point   float32 [N, 3]
color   uint8   [N, 3]
normal  float32 [N, 3]

Object and part point clouds are normalized together. The model generates motion_type as B (prismatic) or C (revolute). An example in the normalized model frame is:

{
  "motion_type": "C",
  "axis": {"theta": 90, "phi": 0},
  "pivot": [1.0, 1.0, 1.0],
  "range": [0.0, 0.25]
}

The inference entry point converts the spherical axis to a Cartesian unit vector. In the saved result, pivots and prismatic limits are restored to the source coordinate system; revolute limits are returned in radians.

Installation

The model has been tested on Linux with Python 3.11, PyTorch 2.4.1, CUDA 12.4, and transformers==4.51.0.

[!IMPORTANT] Use transformers==4.51.0. This is the tested version and is pinned by the UniPhysGen project metadata.

git clone https://github.com/breezexian/UniPhysGen.git
cd UniPhysGen/uniphysgen

conda create -n uniphysgen python=3.11 -y
conda activate uniphysgen
conda install -y -c nvidia/label/cuda-12.4.0 cuda-toolkit

python -m pip install torch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 --index-url https://download.pytorch.org/whl/cu124
python -m pip install -e ".[train]"
bash scripts/install_cuda_extensions.sh

For inference only, replace python -m pip install -e ".[train]" with python -m pip install -e ..

The model uses a custom Transformers architecture. Install UniPhysGen before loading the checkpoint; a generic transformers.pipeline is not supported.

Inference

Set --part_pcd to the selected movable part's point cloud and use --spherical_axis with this released checkpoint:

CUDA_VISIBLE_DEVICES=0 python inference_batch_kinematic_parameters.py \
  --model_path breezexian/UniPhysGen-1.7B-Kinematics \
  --object_pcd examples/object.npz \
  --part_pcd examples/part.npz \
  --spherical_axis \
  --output outputs/kinematic_parameters.json

For batch inference, pass a JSON list containing only the selected movable parts with --input_json. The saved coordinate_frame records the reversible mapping used to restore predictions to source units.

Evaluation

The paper evaluates kinematic parameters on ground-truth movable parts, separating parameter estimation from movable-part identification. Use the annotated movable-part set to reproduce this protocol. Results using Physics-selected parts also depend on the accuracy of movable-part identification.

python -m eval kinematic_parameters PREDICTIONS \
  --output kinematic_parameters_metrics.json

See Table 2 of the paper for the UniPhys-Bench results and the main project README for the complete evaluation protocol.

Intended use and limitations

This checkpoint is intended for research on articulation grounding and for generating candidate joint parameters for downstream simulation. Predicted axes, pivots, and limits are estimates rather than calibrated measurements.

Performance may degrade for symmetrical geometry, occluded joints, sparse or noisy point clouds, ambiguous part decompositions, multi-axis mechanisms, or mechanisms outside the training distribution. Validate predictions before using them in robotics, safety-critical control, or real-world engineering.

License

The model weights are released under the Creative Commons Attribution-NonCommercial 4.0 International license. Commercial use is not permitted under this license. The UniPhysGen source code is licensed separately under Apache-2.0. See the included license for Qwen3 and Sonata attribution.

Citation

@article{li2026uniphysgen,
  title   = {UniPhysGen: Unified Physical Grounding for Simulation-Ready 3D Assets},
  author  = {Li, Xian and Wei, Rong and Yang, Lujie and Huang, Haolin and Fang, Junyuan and Tang, Siliang and Xiao, Jun and Tang, Rui and Li, Juncheng},
  journal = {arXiv preprint arXiv:2607.13586},
  year    = {2026}
}