Hunyuan3D-2: High-Resolution Text-to-3D, Flow-Matching DiT, and 2K PBR Texture Synthesis

Step 1: Text-to-3D End-to-End Synthesis

from __future__ import annotations

import torch
from hy3d.gen.meshes import Hunyuan3DDiT
from hy3d.gen.paint import Hunyuan3DPaint


def generate_text_to_3d(
    prompt: str,
    output_path: str = "output_asset.glb",
    turbo: bool = True,
    device: str = "cuda",
) -> None:
    # 1. Initialize Decoupled Pipeline Models
    dit_repo = "Tencent-Hunyuan/Hunyuan3D-DiT-v2-0-Turbo" if turbo else "Tencent-Hunyuan/Hunyuan3D-DiT-v2-0"
    paint_repo = "Tencent-Hunyuan/Hunyuan3D-Paint-v2-0-Turbo" if turbo else "Tencent-Hunyuan/Hunyuan3D-Paint-v2-0"

    shape_generator = Hunyuan3DDiT.from_pretrained(dit_repo, torch_dtype=torch.float16).to(device).eval()
    texture_painter = Hunyuan3DPaint.from_pretrained(paint_repo, torch_dtype=torch.float16).to(device).eval()

    with torch.inference_mode():
        # 2. Stage 1: Geometric Shape Synthesis via Rectified Flow
        raw_mesh = shape_generator(
            prompt=prompt,
            num_inference_steps=8 if turbo else 30,
            guidance_scale=5.5,
            octree_resolution=384,
        )

        # 3. Stage 2: View-Conditioned PBR Texture Painting
        pbr_mesh = texture_painter(
            mesh=raw_mesh,
            prompt=prompt,
            num_inference_steps=8 if turbo else 30,
            texture_resolution=2048,
            pbr=True,
        )

        # 4. Export standard glTF 2.0 asset
        pbr_mesh.export(output_path)
        print(f"Asset exported successfully to {output_path}")


if __name__ == "__main__":
    generate_text_to_3d(
        prompt="A heavy industrial robotic arm base, weathered cast steel, brass bolts, precision joints, 4K PBR"
    )

Step 2: Image-to-3D with Automated Foreground Segmentation

from __future__ import annotations

from PIL import Image
import torch
from hy3d.gen.meshes import Hunyuan3DDiT
from hy3d.gen.paint import Hunyuan3DPaint


def generate_image_to_3d(
    image_path: str,
    output_path: str = "image_asset.glb",
    device: str = "cuda",
) -> None:
    shape_generator = Hunyuan3DDiT.from_pretrained(
        "Tencent-Hunyuan/Hunyuan3D-DiT-v2-0", torch_dtype=torch.float16
    ).to(device).eval()
    texture_painter = Hunyuan3DPaint.from_pretrained(
        "Tencent-Hunyuan/Hunyuan3D-Paint-v2-0", torch_dtype=torch.float16
    ).to(device).eval()

    source_image = Image.open(image_path).convert("RGBA")

    with torch.inference_mode():
        # Condition shape DiT on single foreground image
        mesh = shape_generator(
            image=source_image,
            num_inference_steps=50,
            guidance_scale=7.5,
            octree_resolution=512,
            remove_background=True,
        )

        # Apply multi-view texture diffusion
        textured_mesh = texture_painter(
            mesh=mesh,
            image=source_image,
            texture_resolution=2048,
            pbr=True,
        )

        textured_mesh.export(output_path)


if __name__ == "__main__":
    generate_image_to_3d("assets/input_prop.png")

Step 3: Standalone Geometry Re-Painting & PBR Material Tuning

from __future__ import annotations

import trimesh
import torch
from hy3d.gen.paint import Hunyuan3DPaint


def repaint_mesh(
    mesh_path: str,
    style_prompt: str,
    output_path: str,
    metallic_strength: float = 0.8,
    roughness_bias: float = 0.2,
    device: str = "cuda",
) -> None:
    painter = Hunyuan3DPaint.from_pretrained(
        "Tencent-Hunyuan/Hunyuan3D-Paint-v2-0", torch_dtype=torch.float16
    ).to(device).eval()

    base_mesh = trimesh.load(mesh_path)

    with torch.inference_mode():
        retextured = painter(
            mesh=base_mesh,
            prompt=style_prompt,
            texture_resolution=2048,
            pbr=True,
            metallic_strength=metallic_strength,
            roughness_bias=roughness_bias,
        )
        retextured.export(output_path)


if __name__ == "__main__":
    repaint_mesh(
        mesh_path="output_asset.glb",
        style_prompt="Cyberpunk sci-fi variant, matte carbon fiber, illuminated cyan circuits, chrome finish",
        output_path="asset_cyberpunk.glb",
        metallic_strength=0.9,
    )

Empirical Benchmark Evaluation

We benchmarked Hunyuan3D-2 against representative feed-forward and optimization-based 3D generators:

Production Integration & Engine Pipelines

Unreal Engine 5 vs. Unity PBR Channel Mapping

The standard glTF 2.0 specification packs metallic and roughness into green and blue channels. Unreal Engine 5 expects packed Occlusion-Roughness-Metallic (ORM) textures formatted as:

• Red (R): Ambient Occlusion
• Green (G): Roughness
• Blue (B): Metallic

import cv2
import numpy as np


def convert_gltf_to_unreal_orm(gltf_orm_path: str, output_path: str) -> None:
    # glTF standard: G = Roughness, B = Metallic
    img = cv2.imread(gltf_orm_path)
    b_metallic, g_roughness, r_unused = cv2.split(img)

    # Synthetic Ambient Occlusion fallback
    r_ao = np.full_like(g_roughness, 255)

    unreal_orm = cv2.merge([r_ao, g_roughness, b_metallic])
    cv2.imwrite(output_path, unreal_orm)

Troubleshooting Common Generation Artifacts

1. Disconnected Floating Mesh Debris

• Symptom: Spurious tiny triangles float around the main generated object.
• Remedy: Filter connected components using trimesh.split and retain the largest connected mesh volume.

2. Seam Discontinuities Across UV Boundaries

• Symptom: Noticeable visual seams along texture chart borders.
• Remedy: Pre-process the raw mesh with xatlas.parametrize to produce an isometric UV unwrap prior to running Hunyuan3D-Paint.

3. VRAM Out-of-Memory on 12 GB–16 GB GPUs

• Symptom: CUDA OOM during multi-view rendering inside Hunyuan3D-Paint.
• Remedy: Enable sequential CPU offloading via paint.enable_sequential_cpu_offload() and deploy the Turbo checkpoint.