Tencent-Hunyuan/HunyuanWorld-Mirror

Tencent-Hunyuan/HunyuanWorld-Mirror

Description: [ICML 2026] WorldMirror: Fast and Universal 3D reconstruction model for versatile tasks

Language: Python

License: NOASSERTION

Stars: 1138

Forks: 114

Open issues: 9

Created: 2025-10-16T13:47:15Z

Pushed: 2026-05-27T03:22:57Z

Default branch: main

Fork: no

Archived: no

README: [中文阅读](README_zh.md)

HunyuanWorld-Mirror [ICML 2026]

HunyuanWorld-Mirror is a versatile feed-forward model for comprehensive 3D geometric prediction. It integrates diverse geometric priors (camera poses, calibrated intrinsics, depth maps) and simultaneously generates various 3D representations (point clouds, multi-view depths, camera parameters, surface normals, 3D Gaussians) in a single forward pass.

https://github.com/user-attachments/assets/146a9a25-5eb7-4400-aa09-5b58e1d10a5e

🔥🔥🔥 Updates

• [May 20, 2026]: 🚀🚀🚀 WorldMirror is accepted to ICML 2026!
• [Apr 16, 2026]: 🤗 We release HY-World-2.0 with WorldMirror-2.0, state-of-the-art 3D world model!
• [Dec 17, 2025]: 🤗 We release HunyuanWorld-1.5, enabling real-time world creation and play!
• [Nov 7, 2025]: 🚀🚀🚀 We release the training and evaluation code. See [Training Instructions](#🤖-training) and [Evaluation Instructions](#📊-evaluation).
• [Oct 22, 2025]: We release the inference code and model weights. Download Pretrained Model.

> Join our [Wechat](#) and [Discord](https://discord.gg/dNBrdrGGMa) group to discuss and find help from us.

| Wechat Group | Xiaohongshu | X | Discord | |--------------------------------------------------|-------------------------------------------------------|---------------------------------------------|---------------------------------------------------| | | | | |

Table of Contents

• [Introduction](#☯️-hunyuanworld-mirror-introduction)
• [Architecture](#architecture)
• [Installation](#🛠️-dependencies-and-installation)
• [Quick Start](#🎮-quick-start)
• [Online Demo](#online-demo)
• [Local Demo](#local-demo)
• [Download Pretrained Models](#📦-download-pretrained-models)
• [Inference with Images & Priors](#🚀-inference-with-images--priors)
• [Example Code Snippet](#example-code-snippet)
• [Output Format](#output-format)
• [Inference with More Functions](#inference-with-more-functions)
• [Post 3DGS Optimization (Optional)](#🎯-post-3dgs-optimization-optional)
• [Install Dependencies](#install-dependencies)
• [Optimization](#optimization)
• [Performance](#🔮-performance)
• [Point Cloud Reconstruction](#point-cloud-reconstruction)
• [Novel View Synthesis](#novel-view-synthesis)
• [Boost of Geometric Priors](#boost-of-geometric-priors)
• [Training](#🤖-training)
• [Training Data Preparation](#training-data-preparation)
• [Install Dependencies](#install-dependencies)
• [Training Commands](#training-commands)
• [Fine-tuning Commands](#fine-tuning-commands)
• [Evaluation](#📊-evaluation)
• [Evaluation Data Preparation](#evaluation-data-preparation)
• [Install Dependencies](#install-dependencies)
• [Evaluation Commands](#evaluation-commands)
• [1. Point Map Reconstruction](#1-point-map-reconstruction)
• [2. Surface Normal Estimation](#2-surface-normal-estimation)
• [3. Novel View Synthesis](#3-novel-view-synthesis)
• [4. Depth Estimation](#4-depth-estimation)
• [5. Camera Pose Estimation](#5-camera-pose-estimation)
• [Open-Source Plan](#📑-open-source-plan)
• [BibTeX](#🔗-bibtex)
• [Contact](#📧-contact)
• [Acknowledgments](#acknowledgements)

☯️ HunyuanWorld-Mirror Introduction

Architecture

HunyuanWorld-Mirror consists of two key components:

(1) Multi-Modal Prior Prompting: A mechanism that embeds diverse prior modalities, including calibrated intrinsics, camera pose, and depth, into the feed-forward model. Given any subset of the available priors, we utilize several lightweight encoding layers to convert each modality into structured tokens.

(2) Universal Geometric Prediction: A unified architecture capable of handling the full spectrum of 3D reconstruction tasks from camera and depth estimation to point map regression, surface normal estimation, and novel view synthesis.

🛠️ Dependencies and Installation

We recommend using CUDA version 12.4 for the manual installation.

# 1. Clone the repository
git clone https://github.com/Tencent-Hunyuan/HunyuanWorld-Mirror
cd HunyuanWorld-Mirror

# 2. Create conda environment
conda create -n hunyuanworld-mirror python=3.10 cmake=3.14.0 -y
conda activate hunyuanworld-mirror

# 3. Install PyTorch and other dependencies using pip
# For CUDA 12.4
pip install torch==2.4.0 torchvision==0.19.0 --index-url https://download.pytorch.org/whl/cu124

# 4. Install pip dependencies
pip install -r requirements.txt

# 5. Install gsplat for 3D Gaussian Splatting rendering
# For CUDA 12.4
pip install gsplat --index-url https://docs.gsplat.studio/whl/pt24cu124

🎮 Quick Start

We provide a Gradio demo for the HunyuanWorld-Mirror model for quick start.

Online Demo

Try our online demo without installation: 🤗 Hugging Face Demo

Local Demo

# 1. Install requirements for gradio demo
pip install -r requirements_demo.txt
# For Windows, please replace onnxruntime and gsplat with Windows wheels (comments in requirements_demo.txt)
# 2. Launch gradio demo locally
python app.py

📦 Download Pretrained Models

To download the HunyuanWorld-Mirror model, first install the huggingface-cli:

python -m pip install "huggingface_hub[cli]"

Then download the model using the following commands:

huggingface-cli download tencent/HunyuanWorld-Mirror --local-dir ./ckpts

> Note: For inference, the model weights will be automatically downloaded from Hugging Face when running the inference scripts, so you can skip this manual download step if preferred.

🚀 Inference with Images & Priors

Example Code Snippet

from pathlib import Path
import torch
from src.models.models.worldmirror import WorldMirror
from src.utils.inference_utils import extract_load_and_preprocess_images

# --- Setup ---
device = 'cuda' if torch.cuda.is_available() else 'cpu'
model =…