breezexian/UniPhysGen-1.7B-Structure

UniPhysGen-1.7B-Structure

UniPhysGen-1.7B-Structure is the articulation structure grounding checkpoint from UniPhysGen. Given a full-object point cloud, the point cloud of a movable target part, and the object's candidate part list, it predicts which parts move together with the target part.

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 structure 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 Structure entry point does not automatically run Physics or select movable targets; supply a selected movable part for each inference sample.

The object .npz must contain the regular point-cloud arrays and two additional candidate-part arrays:

point         float32 [N, 3]
color         uint8   [N, 3]
normal        float32 [N, 3]
part_names            [K]
part_centers           [K, 3]

part_names contains candidate part identifiers. part_centers contains their centers in the source coordinate frame and must be aligned with part_names. The movable target part must also be supplied as a separate point cloud.

The movable-part requirement applies only to the target part. Keep the full-object point cloud and complete candidate part list, including the target itself and rigidly attached parts that may move with it. Do not filter part_names and part_centers to only B/C parts.

The structured prediction is:

{"members": [0, 2, 3]}

Every returned member is selected from the supplied candidate identifiers.

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. Keep the full object geometry and candidate-part metadata in --object_pcd:

CUDA_VISIBLE_DEVICES=0 python inference_batch_articulation_structure.py \
  --model_path breezexian/UniPhysGen-1.7B-Structure \
  --object_pcd examples/object_with_parts.npz \
  --part_pcd examples/part.npz \
  --output outputs/articulation_structure.json

For batch inference, pass a JSON list with --input_json, using a selected movable target part in every sample. Retain the complete object candidate list for each sample. The source candidate metadata is retained in each output record for traceability and evaluation.

Evaluation

python -m eval articulation_structure PREDICTIONS \
  --output articulation_structure_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 structure grounding and for proposing motion-coupled part groups in 3D assets. Its result depends on the completeness and correctness of the supplied candidate part decomposition.

Performance may degrade for missing or duplicated parts, inconsistent part identifiers, very fine or very coarse decompositions, nested mechanisms, sparse point clouds, or objects outside the training distribution. Validate the predicted grouping before constructing simulation constraints.

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}
}