suvadityamuk/Hunyuan3D-Omni-diffusers-3d

Hunyuan3D-Omni for diffusers-3d

tencent/Hunyuan3D-Omni converted into a diffusers-3d pipeline: ordinary Diffusers and Transformers component folders that the installed package loads. 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 numpy as np
import torch
from diffusers_3d import AutoPipelineForImageTo3D, ImageCondition

pipeline = AutoPipelineForImageTo3D.from_pretrained("suvadityamuk/Hunyuan3D-Omni-diffusers-3d", dtype=torch.float16).to("cuda")
bones = torch.from_numpy(np.loadtxt("a_pose_bone.txt")).float()  # (bones, 6)
mesh = pipeline(ImageCondition(image=rgba), skeleton=bones, generator=torch.Generator("cuda").manual_seed(1234)).objects[0]

rgba is a (4, H, W) tensor in [0, 1] whose alpha channel masks the object; the pipeline crops and pads it as the released code does. Pass exactly one control, in the output mesh's normalized frame: point_cloud (points, 3), voxels (points, 3), bbox (3,), or skeleton (bones, 6). The result is an untextured MeshAsset. Defaults follow upstream's inference.py (50 steps, guidance 4.5, octree_resolution=512). Its pymeshlab clean-up needs the GPL meshlab extra; postprocess=False skips it. The DINOv2 image encoder is not included: it loads from facebook/dinov2-large (Apache-2.0) at a pinned revision, as upstream does. Weights are stored in float32 (the DiT is 12.2 GB); load with dtype=torch.float16 to run like upstream.

Components

Folder	Class
control_encoder	diffusers_3d.families.hunyuan3d_omni.models.Hunyuan3DOmniControlEncoder
image_encoder	transformers.Dinov2Model (not included; loads from facebook/dinov2-large)
scheduler	diffusers_3d.families.hunyuan3d.scheduler.Hunyuan3DFlowMatchEulerDiscreteScheduler
transformer	diffusers_3d.families.hunyuan3d.models.Hunyuan3DDiTModel
vae	diffusers_3d.families.hunyuan3d.vae.Hunyuan3DShapeVAE

Provenance

Converted with diffusers-3d-convert-hunyuan3d-omni 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 Omni is licensed under the Tencent Hunyuan 3D Omni 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 Omni works: diffusers-3d converted the released weights into Diffusers component folders (parameters renamed; 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-OMNI and NOTICE before use. The license does not apply in the European Union, the United Kingdom, or South Korea, products above 1 million monthly active users need a separate license from Tencent, and outputs may not be used to improve other AI models. This repository and diffusers-3d are not affiliated with, sponsored, or endorsed by Tencent.