docs/troubleshooting.md

Troubleshooting — EDou 3D Pipeline

Erros comuns + soluções. Este doc foi atualizado em 2026-04-29 após o primeiro run real bem-sucedido — todos os 8 patches abaixo estão consolidados em setup/install_hunyuan3d.sh. Se rodar fresh e bater algum desses erros, script provavelmente precisa update porque upstream mudou.

⚠️ Os 8 patches obrigatórios

Sem eles, paint v2.1 falha silenciosamente ou trava no install. Detalhes:

1. Repo errado (HF vs GitHub)

huggingface.co/tencent/Hunyuan3D-2.1 tem só weights (não código). Código está no GitHub:

git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1 hunyuan21

Repos legados (Tencent/Hunyuan3D-2) têm só código v2.0 — não funciona com weights v2.1 PBR.

2. import bpy no mesh_utils.py quebra Python 3.12

hy3dpaint/DifferentiableRenderer/mesh_utils.py faz import bpy no top. bpy não tem wheel pra Python 3.12 (pip install bpy → "No matching distribution").

Patch (já no install script):

# Wrap em try/except
try:
    import bpy
except ImportError:
    bpy = None

# Reescreve convert_obj_to_glb pra usar trimesh
def convert_obj_to_glb(obj_path, glb_path, **kw):
    import trimesh
    trimesh.load(obj_path).export(glb_path)
    return True

3. fast_simplification 0.1.13 mudou API

hy3dpaint/utils/simplify_mesh_utils.py chama courent.simplify_quadric_decimation(target_count) que internamente vai pra fast_simplification.simplify(target_count=N) — quebra com:

ValueError: target_reduction must be between 0 and 1

API nova só aceita target_reduction. Patch:

target_reduction = max(0.0, min(0.999, 1.0 - (target_count / face_num)))
new_v, new_f = simplify(courent.vertices, courent.faces, target_reduction=target_reduction)
courent = trimesh.Trimesh(vertices=new_v, faces=new_f, process=False)

4. mesh_inpaint_processor não compilado

NameError: name 'meshVerticeInpaint' is not defined

C++ pybind11 extension. Compilar manualmente:

cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh

Resultado: mesh_inpaint_processor.cpython-312-x86_64-linux-gnu.so.

5. custom_rasterizer não compilado

AttributeError: module 'custom_rasterizer' has no attribute 'rasterize'

CUDA extension. --no-build-isolation é essencial — pip's isolated env não tem torch:

cd hy3dpaint/custom_rasterizer
pip install --no-build-isolation .

6. CUDA version mismatch (toolkit 13 vs torch 12.4)

RuntimeError: The detected CUDA version (13.0) mismatches the version that was
used to compile PyTorch (12.4).

Vast.ai instances vêm com CUDA 13 toolkit (/usr/local/cuda/bin/nvcc). Torch 2.6.0 vem CUDA 12.4. Bypass via patch:

# Em torch/utils/cpp_extension.py
# raise RuntimeError(CUDA_MISMATCH_MESSAGE.format(...))
import warnings; warnings.warn(CUDA_MISMATCH_MESSAGE.format(...)); return

Funciona perfeitamente — major version compatible.

7. setuptools >= 81 removeu pkg_resources

ModuleNotFoundError: No module named 'pkg_resources'

pytorch-lightning 1.9.5 chama pkg_resources.declare_namespace. Pip-instalar setuptools<81:

pip install "setuptools<81"

8. RealESRGAN ckpt não vem com pesos HF

Hunyuan paint v2.1 usa RealESRGAN pra image super-resolution. Ckpt não é auto-baixado. Manual:

mkdir -p hy3dpaint/ckpt
wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth \
    -O hy3dpaint/ckpt/RealESRGAN_x4plus.pth

⚠️ Bug do pipeline antigo (silently broken)

setup/run_estante_pipeline.sh (legado) chama:

from hy3dgen.texgen import Hunyuan3DPaintPipeline
texgen = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2.1",
    subfolder="hunyuan3d-paintpbr-v2-1",  # ← KeyError swallowed
)

hy3dgen.texgen.Hunyuan3DPaintPipeline é a API v2.0 que tem:

self.pipe_dict = {
    'hunyuan3d-paint-v2-0': 'hunyuanpaint',
    'hunyuan3d-paint-v2-0-turbo': 'hunyuanpaint-turbo'
}
self.pipe_name = self.pipe_dict[subfolder_name]  # KeyError aqui

Mas o script tinha try/except amplo que engolia o KeyError e printava "Mesh sem textura em shape_only.glb. Continuando." — Anderson nunca percebia que o paint NUNCA rodava.

Solução: usar textureGenPipeline.py PBR diretamente (em hy3dpaint/), não hy3dgen.texgen. Ver workflows/run_paint_pbr.py.

Unity integration

GLB importado mas mesh aparece cinza/sem textura

✅ Causa NUNCA é o GLB se a fonte é Hunyuan-Paint v2.1 — sempre o caminho de import.

Se vinha por Blender → FBX → Unity: abandona FBX. Blender FBX exporter não traduz Mix nodes do Principled BSDF que o Hunyuan-Paint v2.1 cria. Importar GLB direto via com.unity.cloud.gltfast resolve.

Verificar:

var prefab = AssetDatabase.LoadAssetAtPath<GameObject>("Assets/.../foo.glb");
// Se prefab != null, tem material e textura wired automaticamente.

GLB importou mas estante "enterrada" no chão

Hunyuan output tem origem no centro da bbox [-1, +1]. Pra ficar em pé:

var renderers = go.GetComponentsInChildren<MeshRenderer>();
float minY = renderers
    .SelectMany(r => Get8WorldCorners(r.GetComponent<MeshFilter>().sharedMesh.bounds, r.transform))
    .Min(c => c.y);
go.transform.position += Vector3.up * -minY;  // base em y=0

Renderer.bounds só atualiza no próximo frame em Editor — usar MeshFilter.sharedMesh.bounds (local) + transform.TransformPoint(corner).

Implementação completa: EstanteAIPreviewScene.SpawnFBX no projeto EDou Unity.

Estante muito pequena/grande

Hunyuan output normalizado em ~2m. Pra altura customizada:

float scale = TARGET_HEIGHT_METERS / renderers[0].bounds.size.y;
go.transform.localScale = Vector3.one * scale;

Cost overruns

Esqueci instance ligado

Vast.ai cobra por hora. Sempre destruir pós-uso:

• vast.ai/console → Instances → Destroy
• Cobrança continua até confirmar destroy

Custo > $1 sem output útil

Provavelmente install falhou meio do caminho. Diagnóstico:

1. SSH no instance, cat ~/install.log ou ~/paint_AB.log
2. Se setup parado em algum patch, executar manualmente o passo
3. Se completo mas paint não rodou, checar tmux session (tmux ls)

Pra cortar perdas: snapshot disk + destroy. Resume noutra instance recarregando snapshot.