WorldSculpt README

The project's README from github.com/AlayaLab/WorldSculpt. As one markdown file: README.md.

WorldSculpt: Generating Compositional Worlds from Grounded Videos

Muyao Niu1,2   Jixuan He1   Ruihan Yu1   Lian Fu1   Yonghao Yu1   Zheng-Hui Huang1   Yifan Zhan1   Fengbo Lan1  
Yongtao Ge1   Yinqiang Zheng2   Kaipeng Zhang1,✉   Zhixiang Wang1,✉  
1 Alaya Lab   2 The University of Tokyo   ✉ Corresponding Authors  
Teaser image of WorldSculpt
Given RGB images with instance masks and 3D boxes, WorldSculpt produces a compositional mesh representation for very complex scenes consisting of hundreds of individual objects.

TL;DR

🧭 Pipeline

WorldSculpt pipeline

✨ News

🚀 Getting Started

Installation

Step 1: Following TRELLIS.2 Installation

Please first follow the installation guide of TRELLIS.2 to set up the base environment.

Step 2: Installing Additional Dependencies

NATTEN_CUDA_ARCH is the compute capability of your GPU. Print yours with

python -c "import torch; print('%d.%d' % torch.cuda.get_device_capability())"
# H100; replace 9.0 with your own compute capability
NATTEN_CUDA_ARCH="9.0" NATTEN_N_WORKERS=8 pip install natten==0.21.0 --no-build-isolation
pip install https://github.com/LDYang694/Storages/releases/download/20260430/utils3d-0.0.2-py3-none-any.whl
pip install peft pillow imageio imageio-ffmpeg tqdm easydict opencv-python-headless trimesh transformers==4.57.1 zstandard kornia timm diffusers accelerate gradio plyfile matplotlib scikit-image scikit-learn fpsample iopath pycocotools ftfy
pip install "setuptools<81"

Step 3: Downloading Pretrained Checkpoints

hf download AlayaLab/WorldSculpt --local-dir ./pretrained
hf download TencentARC/Pixal3D --local-dir ./pretrained/Pixal3D

Step 4: Downloading Data

# UE-MeshyScene
hf download AlayaLab/WorldSculpt_data --include "UE-MeshyScene/*" --local-dir ./input --repo-type=dataset
cd ./input/UE-MeshyScene
tar xvf scene*.tar
cd ../..

# Marble DEMO data
hf download AlayaLab/WorldSculpt_data --include "Marble/*" --local-dir ./input --repo-type=dataset
cd ./input/Marble
tar xvf Marble.tar.gz
cd ../..

Step 5 🚀🚀: Running Inference

Every option is passed explicitly — the script has no defaults, so a run is fully described by its own command line. Step 4 extracts each dataset into its own subdirectory, so INPUT_ROOT points at that subdirectory, not at ./input (the script reads $INPUT_ROOT/<scene>/transforms.json).

# UE-MeshyScene, scene_00001
INPUT_ROOT=./input/UE-MeshyScene OUTPUT_ROOT=./output CKPT_ROOT=./pretrained \
SAMPLER=official SS_STEP=15000 SHAPE_STEP=15000 \
RENDER=1 FACE_BUDGET=1000000 GPU=0 \
./inference.sh scene_00001

# Marble demo data, marble_serene_living_room_countryside_view
INPUT_ROOT=./input/Marble OUTPUT_ROOT=./output CKPT_ROOT=./pretrained \
SAMPLER=official SS_STEP=15000 SHAPE_STEP=15000 \
RENDER=1 FACE_BUDGET=1000000 GPU=0 \
./inference.sh marble_serene_living_room_countryside_view

🙏 Acknowledgements

We thank Pixal3D, TRELLIS.2, and DINOv3 for their wonderful work and open-source repositories.

📖 Citation

If you find this work useful, please cite:


@misc{niu2026worldsculptgeneratingcompositionalworlds,
      title={WorldSculpt: Generating Compositional Worlds from Grounded Videos}, 
      author={Muyao Niu and Jixuan He and Ruihan Yu and Lian Fu and Yonghao Yu and Zheng-Hui Huang and Yifan Zhan and Fengbo Lan and Yongtao Ge and Yinqiang Zheng and Kaipeng Zhang and Zhixiang Wang},
      year={2026},
      eprint={2609.05416},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2609.05416}, 
}

WorldSculpt (AlayaLab/WorldSculpt)

Searching Database…

What is this?WorldSculpt is the official implementation of a research method that turns grounded video into 3D scenes: from RGB images with instance masks and 3D boxes it builds a compositional mesh of very complex scenes with hundreds of individual objects.
Is this an app I can just run, or research code?Research code, not an app: the official implementation of a paper. The Sep 2026 release includes Python inference scripts, a pretrained checkpoint on HuggingFace, the arXiv paper and a project page — everything runs from the command line.
How do I get it up and running?Five steps: install the TRELLIS.2 base environment, add the extra dependencies with NATTENCUDAARCH set to your GPU's compute capability, download the pretrained checkpoints and the data, then run the inference script.
What do I need before installing?An NVIDIA GPU with CUDA — you set NATTENCUDAARCH to your card's compute capability — plus the TRELLIS.2 environment installed first as the base, along with additional dependencies like NATTEN.
Anything tricky about running the inference?The inference script has no defaults: every option must be passed explicitly on the command line. Also, INPUTROOT must point at the extracted dataset subdirectory holding transforms.json, not at ./input.
How does it handle scenes with hundreds of objects?The core idea is reusing a generative prior trained for single objects on whole scenes: the authors finetuned Pixal3D to accept occluded multi-view input, then use it for compositional meshification of very complex scenes.
Can I feed it a Marble world?Yes — one demonstrated application runs the same pipeline on a Marble 3DGS world and turns it into object-level compositional meshes.
What is the UE-MeshyScene benchmark?A dataset released with the paper, providing per-frame, per-instance annotations for evaluating compositional mesh reconstruction on complex scenes.
Can I train or finetune the model myself?The README only covers inference: the Sep 2026 release ships inference code and a pretrained checkpoint, with no training pipeline described.
Creator
AlayaLab
Size
8.8 MB
Stars
342
Updated
CommitSep 16
Age
1mo
Commits · 90 Days