OzzyGT/hi3d_v1_custom_blocks

Hi3D v1.0 Modular Diffusers

Top: the coarse mesh from Hunyuan3D-2mini turbo. Bottom: refined with the code below (seed 42, 25 steps, resolution 1024).

Modular Diffusers blocks for hi3d-official/Hi3Dv1.0: refine a coarse, untextured 3D shape guided by an image of the object. The model code and weights are in OzzyGT/hi3d_v1.

Requires PyTorch, diffusers>=0.41.0, transformers>=5.3.0, numpy, pillow and pyfqmr. The example also uses trimesh to load and save the meshes.

Licensing

The blocks are Apache-2.0, including the FlexiCubes surface extraction adapted from NVIDIA FlexiCubes. This repository contains no model weights. The weights are under the Hi3D Open License Agreement Version 1.0; see the LICENSE and NOTICE in the model repository. Powered by Hi3D 1.0.

Usage

The example uses trust_remote_code=True, which loads these blocks, and trust_components_code=True, which allows the model repository's custom classes.

Note: both flags run Python code downloaded from the Hub: trust_remote_code=True runs the code of the blocks repository, and trust_components_code=True runs the code shipped in the components_repo. Only use them with repositories you trust, and review their code before passing different ones.

import torch
import trimesh
from diffusers import ModularPipelineBlocks
from diffusers.utils import load_image
from huggingface_hub import hf_hub_download


blocks = ModularPipelineBlocks.from_pretrained(
    "OzzyGT/hi3d_v1_custom_blocks",
    trust_remote_code=True,
    components_repo="OzzyGT/hi3d_v1",
    trust_components_code=True,
)
pipe = blocks.init_pipeline()
pipe.load_components(dtype=torch.float16)
pipe.to("cuda")

image = load_image(
    "https://huggingface.co/datasets/OzzyGT/diffusers-examples/resolve/main/hunyuan3d_2mini/20261016231355.png",
    convert_method=lambda image: image.convert("RGBA"),
)
coarse_mesh = trimesh.load(
    hf_hub_download("OzzyGT/diffusers-examples", "hi3d_v1/20261016231355_coarse.glb", repo_type="dataset"),
    force="mesh",
)
mesh = pipe(
    image=image,
    mesh=coarse_mesh,
    generator=torch.Generator().manual_seed(42),
    output="meshes",
)[0]
trimesh.Trimesh(mesh["vertices"], mesh["faces"]).export("refined.glb")

The image should show the object on a transparent background. The coarse mesh is the shape of that object, such as the output of the Hunyuan3D-2mini blocks.

The default resolution is 1024. Pass resolution=512 to from_pretrained for a faster, less detailed result, or resolution=1536 for more detail.