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:

```bash
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):**
```python
# 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:**
```python
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:

```bash
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:

```bash
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:

```python
# 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`:

```bash
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:

```bash
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:

```python
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:
```python
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:
```csharp
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é:

```csharp
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:

```csharp
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.