suvadityamuk/Hunyuan3D-2.1-Paint-diffusers-3d

Hunyuan3D-2.1 Paint for diffusers-3d

tencent/Hunyuan3D-2.1 converted into a diffusers-3d pipeline: ordinary Diffusers and Transformers component folders plus the object3d_model_index.json sidecar that the package's auto-loader validates before downloading anything. Nothing here requires remote code.

Install

pip install git+https://github.com/suvadityamuk/diffusers-3d.git
pip install "git+https://github.com/suvadityamuk/diffusers-3d.git#subdirectory=packages/diffusers-3d"

diffusers-3d runs every network in plain PyTorch on CPU or GPU. Rendering Gaussian splats needs the optional gsplat backend; the PBR-textured mesh for TRELLIS.2 needs CuMesh (see the package docs).

Usage

import torch
from diffusers_3d import AutoPipelineFor3D, AutoPipelineForImageTo3D, ImageCondition

shape = AutoPipelineForImageTo3D.from_pretrained("suvadityamuk/Hunyuan3D-2.1-diffusers-3d", dtype=torch.float16).to("cuda")
mesh = shape(ImageCondition(image=rgba), generator=torch.Generator("cuda").manual_seed(0)).objects[0]

paint = AutoPipelineFor3D.from_pretrained("suvadityamuk/Hunyuan3D-2.1-Paint-diffusers-3d", dtype=torch.float16).to("cuda")
textured = paint(mesh, ImageCondition(image=rgba), generator=torch.Generator("cuda").manual_seed(0)).objects[0]

mesh is any MeshAsset, for example a shape pipeline's output, and rgba a (4, H, W) tensor in [0, 1] whose alpha masks the object. The result is a UV-textured MeshAsset; export it with TrimeshBackend().export_mesh(textured.to("cpu"), "textured.glb") (needs the portable extra). Paint simplifies the mesh to 40k faces (max_faces=None keeps it; simplifying needs fast-simplification), unwraps it with xatlas, generates albedo and metallic-roughness views, upscales them with Real-ESRGAN, and bakes a base-colour plus metallic-roughness PBRMaterial in plain PyTorch.

Components

Folder	Class
feature_extractor	transformers.BitImageProcessorPil
image_encoder	transformers.Dinov2Model
scheduler	diffusers.UniPCMultistepScheduler
unet	diffusers_3d.families.hunyuan3d.paint_models.Hunyuan3DPaintUNet
upscaler	diffusers_3d.families.hunyuan3d.paint_models.Hunyuan3DPaintRRDBNet
vae	diffusers.AutoencoderKL

Provenance

Converted with diffusers-3d-convert-hunyuan3d-paint from diffusers-3d 0.1.0.dev0; the package's family README lists the pinned upstream revisions and how the conversion maps each tensor. Parity tests against the pinned upstream code are part of the package test suite.

License and attribution

Tencent Hunyuan 3D 2.1 is licensed under the Tencent Hunyuan 3D 2.1 Community License Agreement, Copyright © 2025 Tencent. All Rights Reserved. The trademark rights of "Tencent Hunyuan" are owned by Tencent or its affiliate.

This repository redistributes modified Tencent Hunyuan 3D 2.1 works: diffusers-3d converted the released hunyuan3d-paintpbr-v2-1 weights into Diffusers component folders (parameters renamed into stock modules, the unused CLIP encoders dropped; weight values unchanged). The license, including its Acceptable Use Policy and the use restrictions of its Sections 5(a) and 5(b), applies to everyone who uses these files; read LICENSE-TENCENT-HUNYUAN-3D-2.1 and NOTICE before use. The license does not apply in the European Union, the United Kingdom, or South Korea, and products above 1 million monthly active users need a separate license from Tencent.

The Paint UNets and VAE derive from Stable Diffusion 2.1-base and are also subject to the CreativeML Open RAIL++-M License and its use-based restrictions; LICENSE-OPENRAIL-PLUSPLUS-M.md is that license's text as published with SDXL, since Stability AI no longer hosts Stable Diffusion 2.x. The image encoder is facebook/dinov2-giant (Apache-2.0). The upscaler holds the RealESRGAN_x4plus weights of Real-ESRGAN, BSD-3-Clause, Copyright (c) 2021 Xintao Wang (LICENSE-REAL-ESRGAN). This repository and diffusers-3d are not affiliated with, sponsored, or endorsed by Tencent, Stability AI, Meta, or the Real-ESRGAN authors.