# HunyuanWorld-Mirror packs five 3D representations into one forward pass

> HunyuanWorld-Mirror is a feed-forward model that returns point clouds, multi-view depths, camera parameters, surface normals and 3D Gaussians from a single pass over your images. Its install instructions pin CUDA 12.4 wheels down to the minor version while the Python requirements stay partly open, so the environment you end up with is yours to record.

**Tencent-Hunyuan/HunyuanWorld-Mirror** — [ICML 2026] WorldMirror: Fast and Universal 3D reconstruction model for versatile tasks

- Repository: https://github.com/Tencent-Hunyuan/HunyuanWorld-Mirror
- Website: https://3d-models.hunyuan.tencent.com/world/
- Stars: 1,224 · Forks: 124
- Language: Python
- License: NOASSERTION
- Published: 2026-10-14 · Updated: 2026-10-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/tencent-hunyuan-hunyuanworld-mirror

## One forward pass in place of a chain of 3D models

A pipeline that needs depth, camera poses, normals, a point map and a renderable scene normally bolts separate predictors together, then spends days reconciling the disagreements between them. HunyuanWorld-Mirror collapses that arrangement into one feed-forward model: it reads images, optionally alongside geometric priors, and returns point clouds, multi-view depths, camera parameters, surface normals and 3D Gaussians in a single forward pass. Nothing is fitted per scene at inference time, and that is the difference between this and a reconstruction pipeline assembled from optimisation.

The audience is engineers who already have images and need geometry out of them, rather than a full photogrammetry solve. Two curated example sets at the repository root, `examples/realistic/` and `examples/stylistic/`, split the sample inputs into photographic and stylised cases. The tasks come from the same weights rather than a menu of separate checkpoints, and the evaluation suite spans point map reconstruction, surface normal estimation, novel view synthesis, depth estimation and camera pose estimation. For the first three you are consuming geometry the model measured, and for the last two the geometry is the answer.

## Lightweight encoders turn the priors you have into tokens

The architecture has two named parts, and the split tells you where the engineering went. Multi-Modal Prior Prompting takes calibrated intrinsics, camera poses and depth maps, passes each through several lightweight encoding layers, and emits structured tokens. Universal Geometric Prediction then consumes those tokens and covers the task spectrum from depth and camera estimation through to point map regression and novel view synthesis.

The detail worth planning around is the subset rule: given any subset of the available priors, the encoders still fire, so you are not forced to arrive with a complete calibration set. Priors are therefore an accelerator and not a precondition, which is also why the documentation separates `Inference with Images & Priors` from `Inference with More Functions`. How many priors are worth computing stays a cost question on your side. The encoding path is spelled out in the text, while the per-task comparison between prior configurations sits further down in the project's performance material.

## Install paths split CUDA 12.4 wheels across three pip calls

The README recommends CUDA version 12.4 for a manual install, and the environment it builds is unusually specific for two lines of shell. Start with the clone and the conda environment:

```bash
git clone https://github.com/Tencent-Hunyuan/HunyuanWorld-Mirror
cd HunyuanWorld-Mirror
conda create -n hunyuanworld-mirror python=3.10 cmake=3.14.0 -y
conda activate hunyuanworld-mirror
```

Next come three pip calls: PyTorch from the CUDA 12.4 index, the Python dependencies from the repository file, and gsplat from its own index for 3D Gaussian Splatting rendering.

```bash
pip install torch==2.4.0 torchvision==0.19.0 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
pip install gsplat --index-url https://docs.gsplat.studio/whl/pt24cu124
```

Two details decide whether that works on your machine. The gsplat index path pt24cu124 carries the PyTorch minor version and CUDA build it was compiled against, so a different torch or driver combination means changing that URL as well as the pin. And the root of the tree carries a `submodules/` entry next to `src/`, yet the clone step above never touches it, so whether that directory arrives populated depends on something the published install sequence does not state.

## The local demo adds a second requirements file and Windows wheels

A Gradio demo sits at the repository root as `app.py`, with its own dependency file kept apart from the main list:

```bash
pip install -r requirements_demo.txt
python app.py
```

`onnxruntime` and gsplat are the two packages the README flags for Windows, pointing readers at the Windows wheels noted in comments inside `requirements_demo.txt`. Neither comes through the root `requirements.txt`, which is what keeps the demo environment small enough to start quickly on a workstation. For anyone without a CUDA 12.4 machine, the hosted Hugging Face Space linked from the README runs the same model with no local install at all.

Weights are not in the git tree. They live on the Hugging Face model repository `tencent/HunyuanWorld-Mirror`, and the root requirements file carries `huggingface-hub[torch]>=0.22` as the entry covering that download. It is also the only dependency in that list with a torch extra attached, which tells you the hub client is expected to do the heavy lifting on the fetch.

## One requirements file mixes hard pins with open lower bounds

The root requirements file is split into a training block and an inference block, and the two halves pin in opposite styles. Exact versions sit beside open lower bounds: `numpy<2.0.0`, `open3d==0.18.0`, `pycolmap==3.10.0`, `moviepy==1.0.3` and `rich==13.3.5` are all fixed, while `lightning>=2.5.0` and `huggingface-hub[torch]>=0.22` accept anything above their floor. A fresh resolve has to honour a hard numpy ceiling and a training stack that asks for 2.5.0 or newer at the same time, and no lockfile appears at the repository root to remove that choice.

That mismatch is the quiet contradiction in this repository. The install section is precise down to the CUDA minor version and names a cmake build inside the conda line, while the library list deciding what actually loads into the environment stays open at the top end. There is also no numbered build to roll back to, since the update history is a bullet list of dated entries rather than a version stream. Anyone who needs a reproducible environment has to record the resolved versions after the first successful install and carry them forward themselves.

## Training and evaluation live behind separate command sets

Inference sits at the root in `infer.py` and training sits beside it in a `training/` directory, so the two halves of the project can be taken separately. The training block of the requirements file pulls in `lightning>=2.5.0`, `hydra-core`, `tensorboardX`, `rootutils` and `h5py`. The inference block adds `torchmetrics` and `pytest` next to the geometry libraries, including `pycolmap==3.10.0` for the COLMAP bindings and `roma` for rotation maths, plus `lpips` and `colorspacious` for image comparison metrics and `moviepy==1.0.3` for writing out video.

Separate entries exist for training commands and fine-tuning commands, and evaluation is broken into five numbered tasks: point map reconstruction, surface normal estimation, novel view synthesis, depth estimation and camera pose estimation. Pushing all five through one model is the project's central claim, and that numbered list is where you would check it rather than take it on trust. Three of the five are estimation problems, so the geometry the model emits as output becomes the target it is scored against when the same quantities arrive as priors.

## Upgrading means re-reading two root files and the update log

Two facts set the upgrade cost. GitHub lists the licence as Other, a custom one it cannot classify, and the terms live in `License.txt` and `Notice.txt` at the repository root, so both files belong in any review of what you intend to build from the output. The last push was on 2026-05-27, one week after the update entry recording acceptance to ICML 2026 on May 20, 2026.

What arrived before that date defines the current shape of the tree: inference code and model weights in October 2025, training and evaluation code in November 2025, then an April 2026 entry pointing at a successor model, and finally the conference note. The root has stayed close to that shape ever since, holding `infer.py`, `app.py`, `src/`, `training/`, `submodules/` and the two example directories, which means a fresh clone gets the same surface a first-time user saw.

## WorldMirror-2.0 sits in a different repository

Here is the naming trap worth checking before you plan an adoption. The update entry dated Apr 16, 2026 calls WorldMirror-2.0 a state-of-the-art 3D world model and links to it inside HY-World-2.0, while the Dec 17, 2025 entry points at HunyuanWorld-1.5 in HY-WorldPlay for real-time world creation and play. Neither of those lives in this repository. The code here is the feed-forward reconstructor that came first, so anyone arriving for the world model will not find it under this name.

The two approaches differ in kind rather than in a score. WorldMirror takes images, optionally with priors, and emits a fixed set of geometric representations in one pass, which suits batch asset work and anything that needs a camera, a point map or normals from a fixed input set. A world model is built to carry a scene forward instead of describing a static one, and the HunyuanWorld-1.5 entry frames it around real-time creation and play. If you need reproducible representations from known frames, that difference costs you nothing. If you need a scene that keeps generating, the repository you want is not this one.

## Conclusion

Adopt this when you hold images and need several geometric outputs from one pass, since the prior encoders let you start from partial calibration and the demo requirements stay separate from the training stack. Leave it aside when your job needs a scene that keeps generating rather than a fixed reconstruction, because WorldMirror-2.0 and HunyuanWorld-1.5 both sit in other repositories. Before anything else, confirm the gsplat index pt24cu124 matches your torch and CUDA pairing and that the numpy<2.0.0 ceiling survives your resolve.

## FAQ

### What does HunyuanWorld-Mirror output from a single forward pass?

Point clouds, multi-view depths, camera parameters, surface normals and 3D Gaussians, produced together from the same input images in one pass. Priors such as camera poses, calibrated intrinsics and depth maps can be supplied when your data already contains them.

### How do I install HunyuanWorld-Mirror locally?

The documented path is a conda environment on python=3.10, then torch 2.4.0 and torchvision 0.19.0 from the cu124 wheel index, `requirements.txt`, and gsplat from the pt24cu124 index. CUDA version 12.4 is the recommended manual setup, and Windows users of the demo are told to swap onnxruntime and gsplat for Windows wheels.

### Do I need camera poses and intrinsics to run HunyuanWorld-Mirror?

No, the prior prompting path is documented as working from any subset of the available priors, so images alone are the starting point. Each prior you can supply, calibrated intrinsics, camera pose or depth, gets its own lightweight encoding layer that turns it into structured tokens.

### Where do I download the HunyuanWorld-Mirror model weights?

From the Hugging Face model repository `tencent/HunyuanWorld-Mirror`, not from the git tree, and the root `requirements.txt` includes `huggingface-hub[torch]>=0.22` for that step. A hosted Hugging Face Space is also linked for trying the model with no local install.

### Can HunyuanWorld-Mirror be fine-tuned on my own data?

The documentation lists training commands and fine-tuning commands as separate entries, with the training code under `training/` at the repository root. Training dependencies such as `lightning>=2.5.0`, `hydra-core` and `h5py` sit in the same `requirements.txt` as the inference ones, so one file covers both halves.

### What licence does HunyuanWorld-Mirror use?

GitHub classifies it as Other, a custom licence it cannot categorise, and the repository root carries `License.txt` and `Notice.txt`. Those two files hold the terms that apply to the weights and to the output you generate from them.

## Sources

- [Issues](https://github.com/Tencent-Hunyuan/HunyuanWorld-Mirror/issues)
- [Project website](https://3d-models.hunyuan.tencent.com/world/)
- [README](https://github.com/Tencent-Hunyuan/HunyuanWorld-Mirror/blob/main/README.md)
- [Tencent-Hunyuan/HunyuanWorld-Mirror on GitHub](https://github.com/Tencent-Hunyuan/HunyuanWorld-Mirror)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tencent-hunyuan-hunyuanworld-mirror