# HunyuanWorld-Voyager: one image, a camera path, generated depth

> HunyuanWorld-Voyager generates aligned RGB and depth video along a camera path you define, starting from one image, and rebuilds point clouds from the pair. The repository pins its dependencies exactly, ships ten example cases, and documents no run command for its own inference script.

**Tencent-Hunyuan/HunyuanWorld-Voyager** — Voyager is an interactive RGBD video generation model conditioned on camera input, and supports real-time 3D reconstruction.

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

## One image plus a camera path, out comes RGB and depth

An ordinary video generator gives you motion without geometry: a camera can pan through a scene, but nothing in the output says how far away that wall sits. HunyuanWorld-Voyager was built around that gap. It conditions a video diffusion framework on a single image plus a camera path the user defines, and it generates RGB frames and depth frames in one pass instead of estimating depth from finished pixels afterwards, which keeps the point cloud aligned with the image that produced it.

The demo groupings confirm that this is one mechanism with several consumers. Video reconstruction, image-to-3D generation and video depth estimation all read the same generated pair rather than three separate pipelines. The project description calls the output world-consistent 3D point-cloud sequences, and coherence comes from conditioning every new segment on an existing world observation rather than on the previous frames alone.

So the audience is anyone who needs geometry attached to pixels without hand annotating a single scene: simulation and game asset prototypes, previsualisation, and research on long trajectories around a fixed subject. It does nothing for you if you want coverage of a real location, since no capture of one ever enters the model.

## A world cache, point culling and autoregressive scene extension

The second of the two components handles distance. A world cache holds the scene built so far, point culling drops the parts of it that stop contributing, and auto-regressive inference with smooth video sampling extends the scene one segment at a time. Every extension is conditioned on the world observation accumulated up to that point, which is what context-aware consistency means here, and why a long path does not have to be produced in one forward pass.

Point culling is the load-bearing piece of that loop. Without it an auto-regressive walk over many segments accumulates points without bound; with it, the cache stays tied to how much of the earlier scene is still relevant. What the README never gives you are the numbers that govern it: no cache size, no maximum trajectory length, no culling distance, and no statement about what survives when a path turns back toward the starting view. Those values live in the code under `voyager/`, so anyone planning a fly-through has to read them there.

Smooth video sampling is the other half of the trick, and it arrives as part of the inference procedure rather than as a setting you can pass in.

## The data engine that labelled poses and depth without humans

Geometry supervision is normally where a project like this becomes expensive, because someone has to know where the camera stood and how far each pixel is. Here both steps run automatically. The data engine is a video reconstruction pipeline that estimates camera poses and predicts metric depth for arbitrary videos, which turns ordinary footage into aligned training pairs, and the README states that the curation needed no manual 3D annotation.

On top of that pipeline the team compiled a dataset of over 100,000 video clips, mixing real-world captures with synthetic Unreal Engine renders. Real captures carry appearance and texture under actual imaging conditions, while synthetic renders carry clean geometry and camera tracks for viewpoints nobody would fly through. The split between the two sources is not broken down anywhere, so the two halves cannot be weighted separately in a retraining run.

There is a dependency inside that design worth naming. Metric depth means the depth target carries a scale, and scale comes from the pose estimates, so a pose error propagates straight into supervision. No pose error figure, drift curve or filtering threshold is reported, which leaves a ceiling on reconstruction accuracy that this project does not publish.

## Camera control is the column that separates these baselines

The comparison table is the most informative part of this repository, and reading it carefully changes how the rest should be read. It scores eight columns: WorldScore Average, Camera Control, Object Control, Content Alignment, 3D Consistency, Photometric Consistency, Style Consistency and Subjective Quality. The rows printed run from WonderJourney to CogVideoX-I, and no figure below belongs to Voyager, so open the table before quoting a number for this model.

Camera control is the axis where the approaches separate. WonderWorld scores 92.98 and WonderJourney 84.6, while the general video systems sit far below: Allegro at 24.84, EasyAnimate at 26.72, Gen-3 at 29.47. A spread that wide between models of the same vintage reflects what each one was built to control, not a tuning difference.

One row then contradicts its own average. WonderWorld carries the highest WorldScore Average shown, 72.69, yet its Subjective Quality is 49.81, behind EasyAnimate at 50.31 and far behind Gen-3 at 63.85, while WonderJourney holds the best subjective figure at 66.56 on a lower 63.75 average. Aggregate score and human-facing score are not interchangeable in this table, and the README does not explain how WorldScore combines the two.

## Training libraries sit inside the inference dependency pins

The dependency file does not separate running from training. The inference core is `opencv-python==4.9.0.80`, `diffusers==0.31.0`, `accelerate==1.1.1`, `einops==0.7.0`, `imageio==2.34.0` and `safetensors==0.4.3`:

```bash
opencv-python==4.9.0.80
diffusers==0.31.0
accelerate==1.1.1
einops==0.7.0
imageio==2.34.0
safetensors==0.4.3
```

The same `requirements.txt` also carries `peft==0.13.2`, `deepspeed==0.15.1`, `tensorboard==2.19.0` and `pyarrow==14.0.1` for the training and data engine side, plus `pandas==2.0.3`, `numpy==1.24.4` and `tqdm==4.66.2` for data handling:

```bash
peft==0.13.2
deepspeed==0.15.1
tensorboard==2.19.0
pyarrow==14.0.1
git+https://github.com/openai/CLIP.git
```

Two pins will shape whatever environment you build around this. `diffusers==0.31.0` and `numpy==1.24.4` are old enough that anything newer in your own project will collide with them, so keep this repository in a dedicated environment.

The sharp edge is that last line. CLIP is installed straight from git with no tag and no commit hash, so two people running the same setup on different days can end up with different model code and no record of which one.

## Finding weights and a command line that was never written down

The code and the model weights were published together on Sep 2, 2025, and the README sends readers to `ckpts/README.md` for the download itself. A model card also sits at `huggingface.co/tencent/HunyuanWorld-Voyager`, so there are two places to look, and only one of them belongs to this repository.

The top level shows how the pieces split. `sample_image2video.py` is the single-image entry point, `app.py` is a separate front end, `voyager/` holds the model, `data_engine/` holds the training data pipeline, and `examples/` ships ten cases running from `examples/case1/` to `examples/case10/`. Those ten directories are the closest thing to a test set on offer, and none of their contents is named.

What is missing is a run command. No invocation of `sample_image2video.py` appears in the README text, so there is no documented flag for device, resolution, frame count or camera path format, and nothing states what the script writes or prints. The other copy of the instructions is `README_zh.md`, and past that the argument parser at the top of the script is the first place worth reading.

The repository has also moved past its own headline. The last push to this repository is dated 2026-04-15, yet the News section dates the HY-World-2.0 announcement April 16, 2026, one day later, so the newest line of this README points somewhere else.

## A single frame sets the boundary of what the path can show

Everything the model knows about your scene arrives in one frame. That is where its usefulness comes from and also the shape of its failure: regions outside the initial view carry no evidence in the input, and the depth channel covering them is generated rather than recovered.

The phrase real time is where the short description outruns the evidence. The project description calls this real-time 3D reconstruction, and no frame rate, latency, resolution or GPU model appears anywhere in the README text. The one timing figure nearby belongs to a different project: the News entry on FlashWorld claims 3DGS world generation in `5~10 seconds on a single GPU`, and FlashWorld is a separate repository by another author rather than a mode of Voyager. Taking that line for this model is the easiest mistake available here.

Then check the geometry itself. The data engine derives metric depth from predicted camera poses rather than from scans, and nothing in the README reports pose error, drift across long trajectories, or what happens when an extended path returns to its starting view. Extension is described as iterative and forward, and the loop-back case is left unaddressed.

## Conclusion

HunyuanWorld-Voyager earns its place when you need RGB and depth that share one frame, and you can afford to read sample_image2video.py yourself, because no invocation for it is written down anywhere. Leave it out if the geometry already exists or if you need vendor-friendly terms, since the LICENSE file holds a custom licence that GitHub cannot classify. Before adopting, check what ckpts/README.md points at today, pin the CLIP git line yourself, and run the script in a clean environment before trusting any WorldScore figure in the table.

## FAQ

### What does HunyuanWorld-Voyager take as input and what does it output?

A single image plus a camera path defined by the user. It generates aligned RGB and depth video, from which world-consistent 3D point-cloud sequences are produced.

### How large is the HunyuanWorld-Voyager training set and how was it labelled?

Over 100,000 video clips, mixing real-world captures with synthetic Unreal Engine renders. A video reconstruction pipeline automates camera pose estimation and metric depth prediction, so no manual 3D annotation is required.

### Does HunyuanWorld-Voyager reconstruct in real time?

The project description calls it real-time 3D reconstruction, but the README text gives no frame rate, latency, resolution or GPU requirement. The 5~10 second figure printed in the News list belongs to FlashWorld, a separate repository.

### Which GPU and CUDA setup does HunyuanWorld-Voyager need?

No hardware requirement is stated in the README text. requirements.txt pins diffusers==0.31.0, accelerate==1.1.1 and numpy==1.24.4, which fix the software side and say nothing about the card.

### Where do I download the HunyuanWorld-Voyager weights from?

The code and weights were published together on Sep 2, 2025, and ckpts/README.md inside the repository carries the download instructions. A model card also sits at huggingface.co/tencent/HunyuanWorld-Voyager.

## Sources

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

---

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