# tencent-hunyuan/hy-world-2.0 architecture

> Architecture diagram of the GitHub repository tencent-hunyuan/hy-world-2.0, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tencent-hunyuan/hy-world-2.0
- Repository: https://github.com/tencent-hunyuan/hy-world-2.0

## Overview

HY-World 2.0 generates persistent 3D worlds from text or a single image, and reconstructs 3D scenes from multi-view images or video. Generation proceeds through panorama creation, trajectory planning, world expansion, and Gaussian-splat composition; reconstruction runs WorldMirror inference and saves visual and geometric outputs. The README documents the generation stages, while the indexed source references support the shown reconstruction wiring. Several generation links are therefore documented capability-level relationships rather than inspected call sites.

Main entry points: [`hyworld2/worldgen/models/pipelines`](https://github.com/tencent-hunyuan/hy-world-2.0/tree/main/hyworld2/worldgen/models/pipelines) (World Expansion), [`hyworld2/worldrecon/hyworldmirror/models/models/worldmirror.py`](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/models/worldmirror.py) (WorldMirror Core), [`hyworld2/panogen`](https://github.com/tencent-hunyuan/hy-world-2.0/tree/main/hyworld2/panogen) (Panorama Generation), [`hyworld2/worldrecon/pipeline.py`](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/pipeline.py) (Inference Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["World Generation"]
  node_pano_stage["Panorama Generation"]
  node_traj["Trajectory Planning<br/>[traj_generate.py]"]
  node_stereo_stage["World Expansion"]
  node_stereo_model["WorldStereo<br/>[worldstereo.py]"]
  node_stereo_pcd["PCD Keyframes"]
  node_stereo_dmd["DMD Keyframes"]
  node_stereo_ref["Reference Keyframes"]
  node_composition["Gaussian Composition"]
  node_gs_processing["Splat Processing"]
  node_assets["Meshes and 3DGS<br/>[extract_mesh.py]"]
end

subgraph group_panorama["Panorama Models"]
  node_hunyuan_pano["HY-Pano Model"]
  node_qwen_pano["Qwen Panorama"]
end

subgraph group_reconstruction["World Reconstruction"]
  node_recon_ui["Reconstruction App<br/>[gradio_app.py]"]
  node_recon_api["Inference Pipeline<br/>[pipeline.py]"]
  node_recon_outputs["3D and Visual Outputs<br/>[inference_utils.py]"]
end

subgraph group_mirror["WorldMirror Model"]
  node_mirror_core["WorldMirror Core<br/>[worldmirror.py]"]
  node_mirror_layers["Transformer Blocks<br/>[block.py]"]
  node_dense_head["Dense Predictions<br/>[dense_head.py]"]
  node_camera_head["Camera Predictions<br/>[camera_head.py]"]
  node_gs_head["Gaussian Predictions<br/>[gs_head.py]"]
end

node_creator(("Text or Image Creator"))
node_recon_input(("Multi-view or Video"))

node_creator -->|"starts generation"| node_pano_stage
node_pano_stage -.->|"uses panorama model"| node_hunyuan_pano
node_pano_stage -.->|"uses panorama model"| node_qwen_pano
node_pano_stage -->|"plans trajectory"| node_traj
node_traj -->|"guides expansion"| node_stereo_stage
node_stereo_stage -->|"runs WorldStereo"| node_stereo_model
node_stereo_stage -.->|"offers keyframe pipeline"| node_stereo_pcd
node_stereo_stage -.->|"offers keyframe pipeline"| node_stereo_dmd
node_stereo_stage -.->|"offers keyframe pipeline"| node_stereo_ref
node_stereo_stage -->|"composes world"| node_composition
node_composition -.->|"processes splats"| node_gs_processing
node_gs_processing -.->|"exports meshes"| node_assets
node_recon_input -->|"submits views"| node_recon_ui
node_recon_ui -->|"calls inference"| node_recon_api
node_recon_api -->|"runs model"| node_mirror_core
node_mirror_core -->|"uses transformer blocks"| node_mirror_layers
node_mirror_core -->|"predicts dense maps"| node_dense_head
node_mirror_core -->|"predicts cameras"| node_camera_head
node_mirror_core -->|"predicts Gaussians"| node_gs_head
node_recon_api -->|"saves predictions"| node_recon_outputs

click node_pano_stage "https://github.com/tencent-hunyuan/hy-world-2.0/tree/main/hyworld2/panogen"
click node_hunyuan_pano "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/panogen/hunyuan_image_3/modeling_hunyuan_image_3.py"
click node_qwen_pano "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/panogen/qwen_image/pipeline_qwen_pano.py"
click node_traj "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/traj_generate.py"
click node_stereo_stage "https://github.com/tencent-hunyuan/hy-world-2.0/tree/main/hyworld2/worldgen/models/pipelines"
click node_stereo_model "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/models/worldstereo.py"
click node_stereo_pcd "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/models/pipelines/pipeline_pcd_keyframe.py"
click node_stereo_dmd "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/models/pipelines/pipeline_dmd_keyframe.py"
click node_stereo_ref "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/models/pipelines/pipeline_ref_keyframe.py"
click node_composition "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/world_gs_trainer.py"
click node_gs_processing "https://github.com/tencent-hunyuan/hy-world-2.0/tree/main/hyworld2/worldgen/gs"
click node_recon_ui "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/gradio_app.py"
click node_recon_api "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/pipeline.py"
click node_mirror_core "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/models/worldmirror.py"
click node_mirror_layers "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/layers/block.py"
click node_dense_head "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/heads/dense_head.py"
click node_camera_head "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/heads/camera_head.py"
click node_gs_head "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/heads/gs_head.py"
click node_recon_outputs "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/utils/inference_utils.py"
click node_assets "https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/gs/extract_mesh.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pano_stage,node_traj,node_stereo_stage,node_stereo_model,node_stereo_pcd,node_stereo_dmd,node_stereo_ref,node_composition,node_gs_processing,node_assets,node_recon_input toneBlue
class node_hunyuan_pano,node_qwen_pano toneAmber
class node_recon_ui,node_recon_api,node_recon_outputs toneMint
class node_mirror_core,node_mirror_layers,node_dense_head,node_camera_head,node_gs_head toneRose
class node_creator toneIndigo
```

## Components

### World Generation

- [Panorama Generation](https://github.com/tencent-hunyuan/hy-world-2.0/tree/main/hyworld2/panogen): `hyworld2/panogen`
- [Trajectory Planning](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/traj_generate.py): `hyworld2/worldgen/traj_generate.py`
- [World Expansion](https://github.com/tencent-hunyuan/hy-world-2.0/tree/main/hyworld2/worldgen/models/pipelines): `hyworld2/worldgen/models/pipelines`
- [WorldStereo](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/models/worldstereo.py): `hyworld2/worldgen/models/worldstereo.py`
- [PCD Keyframes](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/models/pipelines/pipeline_pcd_keyframe.py): `hyworld2/worldgen/models/pipelines/pipeline_pcd_keyframe.py`
- [DMD Keyframes](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/models/pipelines/pipeline_dmd_keyframe.py): `hyworld2/worldgen/models/pipelines/pipeline_dmd_keyframe.py`
- [Reference Keyframes](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/models/pipelines/pipeline_ref_keyframe.py): `hyworld2/worldgen/models/pipelines/pipeline_ref_keyframe.py`
- [Gaussian Composition](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/world_gs_trainer.py): `hyworld2/worldgen/world_gs_trainer.py`
- [Splat Processing](https://github.com/tencent-hunyuan/hy-world-2.0/tree/main/hyworld2/worldgen/gs): `hyworld2/worldgen/gs`
- [Meshes and 3DGS](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldgen/gs/extract_mesh.py): `hyworld2/worldgen/gs/extract_mesh.py`

### Panorama Models

- [HY-Pano Model](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/panogen/hunyuan_image_3/modeling_hunyuan_image_3.py): `hyworld2/panogen/hunyuan_image_3/modeling_hunyuan_image_3.py`
- [Qwen Panorama](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/panogen/qwen_image/pipeline_qwen_pano.py): `hyworld2/panogen/qwen_image/pipeline_qwen_pano.py`

### World Reconstruction

- [Reconstruction App](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/gradio_app.py): `hyworld2/worldrecon/gradio_app.py`
- [Inference Pipeline](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/pipeline.py): `hyworld2/worldrecon/pipeline.py`
- [3D and Visual Outputs](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/utils/inference_utils.py): `hyworld2/worldrecon/hyworldmirror/utils/inference_utils.py`

### WorldMirror Model

- [WorldMirror Core](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/models/worldmirror.py): `hyworld2/worldrecon/hyworldmirror/models/models/worldmirror.py`
- [Transformer Blocks](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/layers/block.py): `hyworld2/worldrecon/hyworldmirror/models/layers/block.py`
- [Dense Predictions](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/heads/dense_head.py): `hyworld2/worldrecon/hyworldmirror/models/heads/dense_head.py`
- [Camera Predictions](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/heads/camera_head.py): `hyworld2/worldrecon/hyworldmirror/models/heads/camera_head.py`
- [Gaussian Predictions](https://github.com/tencent-hunyuan/hy-world-2.0/blob/main/hyworld2/worldrecon/hyworldmirror/models/heads/gs_head.py): `hyworld2/worldrecon/hyworldmirror/models/heads/gs_head.py`

### Other components

- **Text or Image Creator**
- **Multi-view or Video**

## Connections

- Text or Image Creator → Panorama Generation: starts generation
- Panorama Generation → HY-Pano Model: uses panorama model (evidence: `hyworld2/panogen/hunyuan_image_3/modeling_hunyuan_image_3.py`)
- Panorama Generation → Qwen Panorama: uses panorama model
- Panorama Generation → Trajectory Planning: plans trajectory
- Trajectory Planning → World Expansion: guides expansion
- World Expansion → WorldStereo: runs WorldStereo (evidence: `hyworld2/worldgen/models/pipelines/pipeline_pcd_keyframe.py`)
- World Expansion → PCD Keyframes: offers keyframe pipeline (evidence: `hyworld2/worldgen/models/pipelines/pipeline_pcd_keyframe.py`)
- World Expansion → DMD Keyframes: offers keyframe pipeline (evidence: `hyworld2/worldgen/models/pipelines/pipeline_dmd_keyframe.py`)
- World Expansion → Reference Keyframes: offers keyframe pipeline (evidence: `hyworld2/worldgen/models/pipelines/pipeline_ref_keyframe.py`)
- World Expansion → Gaussian Composition: composes world
- Gaussian Composition → Splat Processing: processes splats (evidence: `hyworld2/worldgen/world_gs_trainer.py`)
- Splat Processing → Meshes and 3DGS: exports meshes (evidence: `hyworld2/worldgen/gs/extract_mesh.py`)
- Multi-view or Video → Reconstruction App: submits views
- Reconstruction App → Inference Pipeline: calls inference (evidence: `hyworld2/worldrecon/gradio_app.py`)
- Inference Pipeline → WorldMirror Core: runs model (evidence: `hyworld2/worldrecon/pipeline.py`)
- WorldMirror Core → Transformer Blocks: uses transformer blocks (evidence: `hyworld2/worldrecon/hyworldmirror/models/models/worldmirror.py`)
- WorldMirror Core → Dense Predictions: predicts dense maps (evidence: `hyworld2/worldrecon/hyworldmirror/models/models/worldmirror.py`)
- WorldMirror Core → Camera Predictions: predicts cameras (evidence: `hyworld2/worldrecon/hyworldmirror/models/models/worldmirror.py`)
- WorldMirror Core → Gaussian Predictions: predicts Gaussians (evidence: `hyworld2/worldrecon/hyworldmirror/models/models/worldmirror.py`)
- Inference Pipeline → 3D and Visual Outputs: saves predictions (evidence: `hyworld2/worldrecon/hyworldmirror/utils/inference_utils.py`)