Initial pipeline scaffold: Hunyuan3D-2.1 + ComfyUI on Vast.ai

.gitignore

@@ -0,0 +1,33 @@
+# Outputs (GLBs/FBXs gerados — não commitar; copiar manualmente pra Unity)
+outputs/*.glb
+outputs/*.fbx
+outputs/*.obj
+outputs/*.png
+outputs/*.jpg
+outputs/runs/
+
+# Model weights baixados em setup/download_models.sh — NUNCA commitar (~30GB)
+weights/
+models/
+*.safetensors
+*.ckpt
+*.bin
+
+# ComfyUI / Hunyuan caches
+__pycache__/
+*.pyc
+*.pyo
+.cache/
+.venv/
+venv/
+3d-env/
+
+# IDE / system
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Logs (manter cost_tracking.md, ignorar runtime)
+logs/
+*.log

LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 Anderson Melo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTE: This MIT license covers ONLY the scripts/code in this repository.
+
+Third-party components used by this pipeline have their own licenses:
+- Hunyuan3D-2.1 (Tencent): see https://github.com/Tencent/Hunyuan3D-2/blob/main/LICENSE
+- Stable Diffusion XL: CreativeML Open RAIL-M
+- ComfyUI: GPL-3.0
+- Generated 3D assets: license depends on Hunyuan3D Tencent terms — verify
+  for commercial use before deploying in shipped EDou Unity build.

README.md

@@ -0,0 +1,125 @@
+# EDou 3D Pipeline — Hunyuan3D + ComfyUI on Vast.ai
+
+Pipeline pré-organizada pra geração de assets 3D do projeto e-DOU VR Library
+(Unity 6.4.4f1 / Quest 3) via **Hunyuan3D-2.1** (Tencent, open-source) +
+**ComfyUI/SDXL** rodando em GPU instance Vast.ai.
+
+> **Por que open-source self-hosted?** Anderson optou pelo learning vs APIs
+> blackbox (Tripo/Meshy). Stack inteiro fica no controle: PyTorch + CUDA +
+> ComfyUI + Hunyuan + Blender post-processing → skills transferem pra C5
+> (Voice SDK + busca semântica) e qualquer ML deployment futuro.
+
+## Quick start (após instance Vast.ai pronta)
+
+```bash
+# 1. SSH no Vast.ai instance + clone este repo
+git clone https://huggingface.co/<your-username>/edou-3d.git
+cd edou-3d
+
+# 2. Setup (~30min, ~$0.20 num RTX 3090)
+bash setup/install_hunyuan3d.sh
+bash setup/download_models.sh
+bash setup/verify_install.sh
+
+# 3. Gera estante hero piece
+bash setup/run_estante_pipeline.sh
+
+# 4. Download GLB pra local + post-process
+# (no laptop)
+scp <vastai-ip>:~/work/outputs/estante_v1.glb ./outputs/
+blender --background --python blender/add_estante_anchors.py -- ./outputs/estante_v1.glb
+```
+
+## Estrutura
+
+```
+3d-pipeline/
+├── README.md                       este arquivo
+├── .gitignore                      ignora outputs/, weights/, cache/
+├── setup/
+│   ├── install_hunyuan3d.sh        Hunyuan3D-2.1 + ComfyUI deps em GPU instance
+│   ├── download_models.sh          baixa weights Hunyuan + SDXL (~30GB)
+│   ├── verify_install.sh           smoke test (gera 1 cubo de teste)
+│   └── run_estante_pipeline.sh     pipeline completa: SDXL→imagem→Hunyuan→GLB
+├── prompts/
+│   ├── estante_baroque.txt         SDXL prompt pra imagem de referência da estante
+│   ├── casco_hogwarts.txt          SDXL prompt pro casco (paredes, teto, vitrais)
+│   └── README.md                   guia de prompt engineering (lições + iteração)
+├── workflows/
+│   ├── sdxl_estante.json           ComfyUI workflow JSON (SDXL → 1024×1024)
+│   └── hunyuan_inference.py        script Python: imagem → mesh + textura
+├── blender/
+│   ├── add_estante_anchors.py      Blender headless: importa GLB, adiciona empties
+│   │                               Prateleira_0..3 + Plaqueta_Anchor, exporta FBX
+│   └── README.md                   passo-a-passo Blender post-processing manual
+├── docs/
+│   ├── vastai_runbook.md           SSH + tmux + cost monitoring + destruir instance
+│   ├── troubleshooting.md          erros comuns + soluções
+│   └── cost_tracking.md            log de runs com custo real
+└── outputs/                        gitignored — GLBs/FBXs gerados
+    └── README.md
+```
+
+## Pipeline conceitual
+
+```
+TEXT (Anderson)
+  ↓ prompt engineering em prompts/
+IMAGE (SDXL via ComfyUI, ~30s no instance)
+  ↓ workflows/sdxl_estante.json
+3D SHAPE + TEXTURE (Hunyuan3D-2.1, ~2-5min no instance)
+  ↓ workflows/hunyuan_inference.py
+GLB (download local)
+  ↓ scp
+BLENDER POST-PROCESS (local, gratuito)
+  ↓ blender/add_estante_anchors.py
+FBX com empties anchors
+  ↓ cp pra Unity Assets/_Project/Models/Furniture/
+UNITY EstanteSpawner (existente, sem mudanças)
+  ✓ 12 estantes + 800 livros funcionando
+```
+
+## Custo esperado
+
+| Item | Quanto | Custo |
+|---|---|---|
+| Vast.ai RTX 3090 setup inicial | ~3h primeira vez | ~$1.00 |
+| Vast.ai gen estante (3-5 iter) | ~1.5h | ~$0.50 |
+| Vast.ai gen casco (futuro C2) | ~1h | ~$0.30 |
+| **Total estante completa** | — | **<$2** |
+
+Pré-aprovação Anderson: <$1/instância sem perguntar. Com tmux + sessões
+descartáveis isso bate certinho.
+
+## Requisitos
+
+- Vast.ai conta com saldo
+- GPU mínimo: 24GB VRAM (RTX 3090, 4090, A5000, A40, A100)
+- Storage: ~50GB no instance (15GB Hunyuan + 7GB SDXL + 10GB cache + 18GB working)
+- Local: Blender 5.x + ~5GB livre pros GLB/FBX
+
+## Status
+
+- 🟢 Estrutura local organizada (este repo)
+- 🟡 Aguardando primeiro run real em Vast.ai (smoke test pendente)
+- 🔴 Todos os scripts são **best-effort sem testes em GPU instance** — esperar
+  ajustes na primeira execução. Documentar troubleshooting em `docs/`.
+
+## Workflow de aprendizado sugerido
+
+1. Lê `docs/vastai_runbook.md` pra entender o lifecycle do instance
+2. Spin um RTX 3090 cheap (~$0.20/hr), abre SSH + tmux
+3. Roda `install_hunyuan3d.sh` — observa cada etapa, anota o que falha
+4. Roda `download_models.sh` (vai dormir, ~30min download)
+5. Roda `verify_install.sh` — primeiro mesh teste
+6. Itera o `run_estante_pipeline.sh` 3-5 vezes ajustando prompts em `prompts/estante_baroque.txt`
+7. Quando GLB ficar bom, baixa local + Blender post-process
+8. Atualiza `docs/cost_tracking.md` com $ gasto + resultados
+9. Destrói instance Vast.ai (CRITICAL — esquecer = $$/hr indo)
+
+## Licença
+
+Scripts deste repo: MIT.
+Hunyuan3D-2.1: Tencent license (verificar uso comercial em `LICENSE` do repo deles).
+SDXL: CreativeML Open RAIL-M.
+Geometria gerada pelo Hunyuan: livre conforme licença Tencent (verificar caso a caso).

blender/README.md

@@ -0,0 +1,111 @@
+# Blender Post-Processing — EDou 3D
+
+Após Hunyuan3D gerar o GLB no Vast.ai, baixe localmente e rode esse passo
+no teu Blender (5.x). Adiciona os empties que o Unity precisa pra spawn
+de livros + plaqueta de mês/ano.
+
+## Quick start (headless / batch)
+
+```bash
+# Do diretório 3d-pipeline/
+blender --background --python blender/add_estante_anchors.py -- \
+    --input outputs/estante_v1.glb \
+    --output-fbx outputs/estante_hero_ai.fbx \
+    --scale-target 2.6 \
+    --shelf-count 4
+
+# Verifica abrindo no Blender GUI:
+blender outputs/estante_hero_ai.fbx
+# Outliner deve mostrar: EstanteHeroAI + Prateleira_0..3 + Plaqueta_Anchor
+
+# Copia pro Unity:
+cp outputs/estante_hero_ai.fbx \
+   ../unity-library/EDouLibrary/Assets/_Project/Models/Furniture/
+```
+
+## Quick start (manual UI)
+
+Se preferir Blender GUI pra ajustar antes:
+
+1. **File → Import → glTF 2.0** → selecionar `outputs/estante_v1.glb`
+2. Selecionar mesh → **Object → Set Origin → Origin to Geometry (Median)**
+3. Verificar bounding box no N-panel → escalar pra altura ~2.6m com **S**
+4. Mover mesh pra Z=0 base no chão
+5. **Add → Empty → Plain Axes**, nomear `Prateleira_0`
+6. Posicionar dentro do mesh na altura da prateleira topo
+7. Ctrl+drag pra duplicar 3 vezes, distribuir verticalmente, renomear `Prateleira_1..3`
+8. Add empty `Plaqueta_Anchor` no centro do frontão (face -Y)
+9. Selecionar todos os empties + mesh pai
+10. Parent → Object (Keep Transform) — empties viram filhos do mesh
+11. **File → Export → FBX (.fbx)**:
+    - Selected Objects ✓
+    - Object Types: Mesh + Empty
+    - Apply Scalings: FBX All
+    - Forward: -Z Forward
+    - Up: Y Up
+    - Bake Space Transform ✓
+    - Path Mode: Copy + Embed Textures ✓
+12. Salvar em `Assets/_Project/Models/Furniture/estante_hero_ai.fbx`
+
+## Validação no Unity
+
+Após copiar o FBX pro Unity:
+
+```
+Project view → estante_hero_ai.fbx → Inspector
+  - Materials tab: 1 slot "MadeiraMogno" → External Material assigned (do FBX)
+  - Apply
+
+Menu: EDou → Estante Hero - PolyHaven Materials
+  → Reaplica madeira + bronze nos slots externos
+
+Menu: EDou → Estante Hero - Preview Scene
+  → Cria cena com 1 estante AI rotacionando
+
+Play ▶
+  → Click + WASD pra walkthrough
+```
+
+## Convenções de empties (CRITICAL pro spawn de livros funcionar)
+
+| Empty name | Posição esperada | Função |
+|---|---|---|
+| `Prateleira_0` | mais alta (próxima ao frontão) | EstanteInfo.GetPrateleira(1) → Sec1 |
+| `Prateleira_1` | meio-alto | Sec2 |
+| `Prateleira_2` | meio-baixo | Sec3 |
+| `Prateleira_3` | mais baixa (próxima à base) | Extra |
+| `Plaqueta_Anchor` | centro frontão, face frontal | EstantePrefabBuilder.CriarPlaqueta posiciona texto |
+
+Empties sem mesh, parented ao root mesh do estante, exportados via
+`object_types={"MESH", "EMPTY"}` no FBX export.
+
+## Troubleshooting
+
+**Hunyuan exportou mesh com escala enorme/minúscula** → `--scale-target 2.6`
+normaliza pra altura padrão do EDou (2.60m).
+
+**Mesh tá deitado / rotacionado** → adicionar passo de rotação 90° no
+script. Hunyuan às vezes exporta com Y up mas Z forward (Blender
+convention diferente). Editar `add_estante_anchors.py` linha de import
+gltf, adicionar `bpy.ops.transform.rotate()` apropriado.
+
+**Texturas vazaram no FBX** → `path_mode="COPY"` + `embed_textures=True`
+empacota textures dentro do FBX. Unity ignora — vamos remap pra
+PolyHaven mesmo. Sem problema.
+
+**Verts > 50K** → Hunyuan output é high-poly por default. Decimate
+modifier antes de export pode reduzir pra ~10K mantendo silhueta.
+Adicionar ao script:
+```python
+mod = estante.modifiers.new(name="Decimate", type="DECIMATE")
+mod.ratio = 0.3  # mantém 30% dos polys
+bpy.ops.object.modifier_apply(modifier="Decimate")
+```
+
+**Prateleiras posicionadas erradas** → script distribui uniformemente
+no terço superior-inferior. Se mesh AI tem prateleiras mais densas no
+topo, ajustar margins manualmente:
+```bash
+--shelf-count 4  # padrão
+# OU editar margem em add_estante_anchors.py linhas margin_top/margin_base
+```

blender/add_estante_anchors.py

@@ -0,0 +1,226 @@
+"""
+add_estante_anchors.py — pós-processa GLB do Hunyuan3D pra integrar no
+pipeline do EDou. Importa GLB, calcula bounding box, gera 4 empties
+Prateleira_0..3 distribuídos verticalmente na metade dianteira do mesh,
+adiciona Plaqueta_Anchor no topo do mesh, e exporta FBX pronto pro
+Unity Assets/_Project/Models/Furniture/.
+
+Uso (Blender headless):
+    blender --background --python add_estante_anchors.py -- \\
+        --input ./outputs/estante_v1.glb \\
+        --output-fbx ../unity-library/EDouLibrary/Assets/_Project/Models/Furniture/estante_hero_ai.fbx \\
+        --scale-target 2.6
+
+O '--' separa args do Blender vs args do script.
+
+Args:
+    --input        path do GLB gerado pelo Hunyuan
+    --output-fbx   path destino do FBX (default: ./outputs/estante_hero_ai.fbx)
+    --scale-target altura desejada em metros (default: 2.6)
+    --shelf-count  número de prateleiras (default: 4)
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+# Blender args separator
+if "--" in sys.argv:
+    argv = sys.argv[sys.argv.index("--") + 1:]
+else:
+    argv = []
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Hunyuan GLB → Unity FBX com anchors")
+    parser.add_argument("--input", required=True, type=Path, help="GLB gerado pelo Hunyuan")
+    parser.add_argument("--output-fbx", type=Path,
+                        default=Path("./outputs/estante_hero_ai.fbx"))
+    parser.add_argument("--scale-target", type=float, default=2.6,
+                        help="Altura em metros (estantes do projeto = 2.60m)")
+    parser.add_argument("--shelf-count", type=int, default=4)
+    return parser.parse_args(argv)
+
+
+def main() -> int:
+    args = parse_args()
+
+    if not args.input.exists():
+        print(f"ERRO: input não encontrado: {args.input}", file=sys.stderr)
+        return 1
+
+    args.output_fbx.parent.mkdir(parents=True, exist_ok=True)
+
+    import bpy
+
+    # 1. Cena vazia
+    bpy.ops.object.select_all(action="SELECT")
+    bpy.ops.object.delete(use_global=False)
+
+    # 2. Import GLB
+    print(f"[blender] Importando {args.input}...")
+    bpy.ops.import_scene.gltf(filepath=str(args.input))
+
+    # Pega objeto raiz importado (Hunyuan geralmente exporta 1 mesh top-level)
+    imported = [obj for obj in bpy.data.objects if obj.type == "MESH"]
+    if not imported:
+        print("ERRO: nenhum mesh importado", file=sys.stderr)
+        return 1
+
+    # Joina meshes (caso Hunyuan exporte vários submeshes)
+    if len(imported) > 1:
+        bpy.ops.object.select_all(action="DESELECT")
+        for o in imported:
+            o.select_set(True)
+        bpy.context.view_layer.objects.active = imported[0]
+        bpy.ops.object.join()
+    estante = bpy.context.view_layer.objects.active
+    estante.name = "EstanteHeroAI"
+
+    # 3. Centralizar pivot na origem + apoiar base no chão (Z=0)
+    print("[blender] Centering + grounding pivot...")
+    bpy.ops.object.select_all(action="DESELECT")
+    estante.select_set(True)
+    bpy.context.view_layer.objects.active = estante
+    bpy.ops.object.origin_set(type="ORIGIN_GEOMETRY", center="MEDIAN")
+
+    # Calcular bounding box em world
+    bpy.context.view_layer.update()
+    bbox_corners = [estante.matrix_world @ Mathutils.Vector(corner) if False else None for corner in estante.bound_box]
+    # Workaround: usar bound_box em local space + estante.location
+    bbox_local = [tuple(c) for c in estante.bound_box]
+    min_z_local = min(c[2] for c in bbox_local)
+    max_z_local = max(c[2] for c in bbox_local)
+    height_local = max_z_local - min_z_local
+    print(f"  Local bbox height: {height_local:.3f}")
+
+    # 4. Scale uniformly to target height
+    print(f"[blender] Scaling para altura {args.scale_target}m...")
+    if height_local > 0:
+        scale_factor = args.scale_target / height_local
+        estante.scale = (scale_factor, scale_factor, scale_factor)
+        bpy.ops.object.transform_apply(location=False, rotation=False, scale=True)
+
+    # 5. Mover pra base ficar em Z=0
+    bpy.context.view_layer.update()
+    bbox_after = [tuple(c) for c in estante.bound_box]
+    min_z_after = min(c[2] for c in bbox_after)
+    estante.location.z -= min_z_after
+    bpy.ops.object.transform_apply(location=True, rotation=False, scale=False)
+
+    # 6. Calcular dimensions finais (depois do scale e ground)
+    bpy.context.view_layer.update()
+    bbox = estante.bound_box
+    xs = [c[0] for c in bbox]; ys = [c[1] for c in bbox]; zs = [c[2] for c in bbox]
+    min_x, max_x = min(xs), max(xs)
+    min_y, max_y = min(ys), max(ys)
+    min_z, max_z = min(zs), max(zs)
+    w = max_x - min_x  # width X
+    d = max_y - min_y  # depth Y
+    h = max_z - min_z  # height Z
+    print(f"  Final bbox: W={w:.3f} D={d:.3f} H={h:.3f}m")
+
+    # 7. Adicionar empties Prateleira_0..3 distribuídos verticalmente
+    # Convenção do EDou: índice 0 = mais alta (Sec1), índice N-1 = mais baixa (Extra)
+    # Distribui no terço superior ao terço inferior do mesh, deixando margens
+    # pra base/topo. shelf_z_positions vai do TOPO pra BASE (decreasing Z).
+    print(f"[blender] Adicionando {args.shelf_count} empties Prateleira_*...")
+    margin_top = h * 0.10     # 10% top margin (pediment area)
+    margin_base = h * 0.05    # 5% base margin
+    usable_height = h - margin_top - margin_base
+    if args.shelf_count > 1:
+        spacing = usable_height / args.shelf_count
+        first_z = max_z - margin_top - spacing / 2.0
+    else:
+        spacing = 0
+        first_z = (max_z + min_z) / 2.0
+
+    # Y position: meio do mesh em Y (front-back)
+    shelf_y = (min_y + max_y) / 2.0
+    # X position: centro
+    shelf_x = (min_x + max_x) / 2.0
+
+    for i in range(args.shelf_count):
+        z = first_z - i * spacing
+        empty = bpy.data.objects.new(f"Prateleira_{i}", None)
+        empty.empty_display_type = "PLAIN_AXES"
+        empty.empty_display_size = 0.10
+        bpy.context.collection.objects.link(empty)
+        empty.parent = estante
+        # Posição em coords LOCAL do estante (after parenting, location is local)
+        empty.location = (shelf_x, shelf_y, z)
+        print(f"  Prateleira_{i}: ({shelf_x:.2f}, {shelf_y:.2f}, {z:.2f})")
+
+    # 8. Plaqueta_Anchor — no topo do mesh, na face frontal (Y mais negativo)
+    # Convenção EDou: frontal face em Blender -Y direction.
+    print("[blender] Adicionando Plaqueta_Anchor no topo frontal...")
+    plaqueta_z = max_z - h * 0.13  # ~13% abaixo do topo (área do frontão)
+    plaqueta_y = min_y - 0.005     # 5mm pra fora da face frontal
+    plaqueta_x = (min_x + max_x) / 2.0  # centro
+    anchor = bpy.data.objects.new("Plaqueta_Anchor", None)
+    anchor.empty_display_type = "PLAIN_AXES"
+    anchor.empty_display_size = 0.05
+    bpy.context.collection.objects.link(anchor)
+    anchor.parent = estante
+    anchor.location = (plaqueta_x, plaqueta_y, plaqueta_z)
+    print(f"  Plaqueta_Anchor: ({plaqueta_x:.2f}, {plaqueta_y:.2f}, {plaqueta_z:.2f})")
+
+    # 9. Renomear material do mesh pra "MadeiraMogno" (compatibilidade com
+    # EstantePolyHavenSetup que faz remap por nome). Hunyuan exporta material
+    # com nome arbitrário; renomear pra slot 0.
+    if estante.data.materials:
+        mat = estante.data.materials[0]
+        mat.name = "MadeiraMogno"
+        print(f"  Material slot 0 renomeado pra MadeiraMogno")
+    else:
+        print("  ⚠ Mesh sem material — Unity vai aplicar default URP/Lit")
+
+    # 10. Export FBX
+    print(f"[blender] Export FBX → {args.output_fbx}")
+    bpy.ops.object.select_all(action="DESELECT")
+    estante.select_set(True)
+    for child in estante.children:
+        child.select_set(True)
+    bpy.context.view_layer.objects.active = estante
+
+    bpy.ops.export_scene.fbx(
+        filepath=str(args.output_fbx),
+        use_selection=True,
+        object_types={"MESH", "EMPTY"},
+        bake_space_transform=True,
+        axis_forward="-Z",
+        axis_up="Y",
+        apply_scale_options="FBX_SCALE_NONE",
+        use_mesh_modifiers=True,
+        path_mode="COPY",  # textura empacotada junto
+        embed_textures=True,
+    )
+    print(f"  ✅ FBX salvo: {args.output_fbx}")
+    print(f"     Size: {args.output_fbx.stat().st_size / 1024:.1f} KB")
+
+    print("")
+    print("============================================================")
+    print("✅ Post-processing completo. FBX pronto pro Unity.")
+    print("============================================================")
+    print("Próximos passos:")
+    print(f"  1. Verificar FBX em Blender GUI: blender {args.output_fbx}")
+    print(f"  2. Copiar pro Unity Assets:")
+    print(f"     cp {args.output_fbx} ../unity-library/EDouLibrary/Assets/_Project/Models/Furniture/")
+    print(f"  3. Em Unity: EDou → Estante Hero - PolyHaven Materials (re-aplica wood+bronze)")
+    print(f"  4. EDou → Estante Hero - Preview Scene → Play")
+    return 0
+
+
+# Mathutils import fix (Blender API)
+try:
+    import mathutils as Mathutils
+except ImportError:
+    Mathutils = None
+
+
+if __name__ == "__main__":
+    rc = main()
+    if rc != 0:
+        sys.exit(rc)

docs/cost_tracking.md

@@ -0,0 +1,54 @@
+# Cost Tracking — EDou 3D Pipeline
+
+Log de runs Vast.ai pra controle de gastos + aprendizado sobre o que
+funciona / não funciona em cada iteração.
+
+## Template de entrada
+
+```markdown
+### YYYY-MM-DD — <descrição curta>
+
+- **Instance**: RTX 3090 / 4090 / etc
+- **$/hr**: $0.XX
+- **Duração**: Xh YYmin
+- **Total**: $X.XX
+- **Output**: arquivo gerado (ou "rejeitado" / "failed")
+- **Lições**:
+  - O que funcionou
+  - O que falhou
+  - Próxima iteração: o que mudar
+
+```
+
+## Histórico
+
+### 2026-04-29 — Setup inicial (planejado)
+
+- **Instance**: RTX 3090 (a definir)
+- **$/hr**: ~$0.25 (esperado)
+- **Duração estimada**: 2-3h (install + downloads + smoke + 1ª estante)
+- **Total esperado**: ~$0.60-0.90
+- **Output esperado**: 1 estante GLB + smoke test + runbook validado
+- **Lições**: PRIMEIRA EXECUÇÃO — o que documentar:
+  - Tempo real de cada etapa do install_hunyuan3d.sh
+  - Tamanho real download de weights
+  - GPU memory pico durante texture generation
+  - Velocidade rede do host (afeta download)
+
+(Atualizar após primeiro run real)
+
+## Cumulativo
+
+| Mês | Total gasto | Outputs aceitos |
+|---|---|---|
+| 2026-04 | $0.00 | 0 (zero ainda — pipeline preparada mas não rodada) |
+
+## Budget cap
+
+Pré-aprovação Anderson: **$1/instância sem perguntar, sempre destruir
+pós-uso**. Acima de $1 → perguntar antes.
+
+Limite de queima recomendado por sessão de iteração: **$2** (descontando
+setup amortizado). Se passar disso sem output usável → reavaliar
+abordagem (talvez a estante via IA não está funcionando, voltar pra
+procedural turbinado round 4 ou pivotar pra Tripo/Meshy API).

docs/troubleshooting.md

@@ -0,0 +1,155 @@
+# Troubleshooting — EDou 3D Pipeline
+
+Erros comuns + soluções. Atualizar conforme bater novos.
+
+## Setup phase
+
+### `nvidia-smi: command not found`
+Instance Vast.ai sem GPU ou template wrong. Re-spin escolhendo template
+PyTorch/CUDA explicitamente.
+
+### `CUDA out of memory` no install
+Algum script de exemplo carregou modelo antes de tu rodar inferência.
+```bash
+nvidia-smi  # ver processos
+# kill PID se necessário
+```
+
+### `pip install -e .` falha com C++ build error
+Falta dependência de sistema:
+```bash
+apt-get install build-essential cmake python3-dev libgl1-mesa-glx
+```
+
+### `huggingface-cli` não autentica
+Modelos públicos do Tencent não precisam login. Se pedir token:
+```bash
+huggingface-cli login
+# Cole token de huggingface.co/settings/tokens (read scope)
+```
+
+### Download de weights muito lento
+Vast.ai a velocidade varia bastante por host. Se <10MB/s, considera:
+- Re-spin em outro host (filtrar Inet > 500Mbps)
+- Usar `aria2c` em vez de `huggingface-cli`:
+  ```bash
+  apt-get install aria2
+  aria2c -x 16 -s 16 <url-direta>
+  ```
+
+## Verify phase
+
+### `from hy3dgen.shapegen import ...` → ModuleNotFoundError
+```bash
+cd ~/work/hunyuan
+pip install -e .
+# Re-tenta
+```
+
+### Hunyuan generation produces all-zero mesh
+Imagem de input ruim ou modelo não baixou completamente.
+```bash
+# Verifica weights
+ls -la ~/work/hunyuan/weights/
+# Deve ter ~5-10GB de arquivos .safetensors / .bin
+```
+
+## Pipeline run phase
+
+### SDXL geração: imagem com pessoa/texto/watermark indesejado
+Negative prompt insuficiente. Adicionar em `prompts/estante_baroque.txt`
+(positive já filtra; negative é hard-coded em `run_estante_pipeline.sh`).
+Se persistir, editar negative no script.
+
+### Hunyuan: mesh gerado é só uma esfera/cubo
+Imagem de referência sem silhueta clara. Re-gerar imagem com:
+- Fundo branco/neutro
+- Iluminação plana sem sombras duras
+- Vista frontal (não 3/4 nem perspectiva extrema)
+
+### Hunyuan: textura aplica errado (esticada/distorcida)
+UV unwrap do Hunyuan é hit-or-miss. Soluções:
+- Skip texture step: `--no-texture` flag → usa só shape, aplica
+  PolyHaven materials no Unity (recomendado pro EDou)
+- Refinar imagem de input (mais detalhe = melhor UV)
+
+### Hunyuan: texture step falha com `paint pipeline error`
+```bash
+# Verifica que texture deps compilaram corretamente
+cd ~/work/hunyuan/hy3dgen/texgen/custom_rasterizer
+pip install -e . --force-reinstall
+cd ../differentiable_renderer
+pip install -e . --force-reinstall
+```
+
+## Blender post-process phase
+
+### `blender: command not found`
+Local: instalar Blender 5.x via brew (macOS) ou apt (Linux):
+```bash
+brew install --cask blender  # macOS
+# ou
+sudo snap install blender --classic  # Ubuntu
+```
+
+### Script add_estante_anchors.py: "import bpy" falha
+Tem que rodar via blender, não python direto:
+```bash
+# ERRADO:
+python add_estante_anchors.py
+# CERTO:
+blender --background --python add_estante_anchors.py -- --input ...
+```
+
+### FBX gerado não importa no Unity
+Verificar:
+1. Unity Console por erros de import (ProjectSettings → Console)
+2. FBX size > 0 KB (script falhou silenciosamente?)
+3. Re-export Blender com `axis_forward=-Z, axis_up=Y, bake_space_transform=True`
+
+### Empties não aparecem no Unity após import FBX
+Inspector do FBX:
+- Model tab: Import Cameras + Import Lights ✗ (não usar)
+- Animation tab: Import Animation ✗
+- Rig tab: Animation Type = None
+- Re-import via "Apply" → Empties devem virar GameObjects vazios children
+  do mesh root
+
+### EstantePolyHavenSetup não remap material no FBX gerado
+O slot de material precisa se chamar `MadeiraMogno`. Verificar:
+```bash
+# Em Blender com o FBX aberto:
+# Outliner → mesh → Material → slot 0 name?
+```
+Se diferente, editar `add_estante_anchors.py` linha que renomeia material.
+
+## Cost overruns
+
+### Esqueci de destruir instance, $$ rolando
+Acessa imediatamente: vast.ai/console → Instances → Destroy.
+Cobrança continua até confirmar destroy. Snapshot disk se quiser
+preservar work.
+
+### Custo total > $1 sem produzir output útil
+Diagnóstico:
+1. tmux session ainda ativa? (work em progresso?)
+2. Setup falhou meio do caminho? (parou de funcionar mas instance ligado)
+3. Pra cortar perdas: download que tiver pronto + destroy.
+
+## Unity integration phase
+
+### Estante FBX importado mas materiais magenta
+URP shader missing. `EDou → Configurar URP Pipeline` (já existe no projeto).
+
+### Estante visível mas livros não spawnam nas prateleiras
+Empties não estão presentes ou nomeados errado. Em Unity:
+```
+Hierarchy → estante prefab → expand
+  Children precisam: Prateleira_0, Prateleira_1, Prateleira_2, Prateleira_3
+```
+Se ausentes, voltar pro Blender + re-export com empties.
+
+### Plaqueta texto não aparece
+EstantePrefabBuilder.CriarPlaqueta busca `Plaqueta_Anchor`. Se não
+encontrar, fallback é lateral direita. Verificar empty Plaqueta_Anchor
+existe no FBX.

docs/vastai_runbook.md

@@ -0,0 +1,172 @@
+# Vast.ai Runbook — EDou 3D Pipeline
+
+Walkthrough completo de spin → setup → uso → destruir instance Vast.ai
+pra rodar Hunyuan3D-2.1.
+
+> **Pré-aprovação Anderson**: <$1/instância sem perguntar, sempre destruir
+> pós-uso. Acima disso, perguntar.
+
+## 1. Setup conta Vast.ai (uma vez)
+
+1. Cadastro em [vast.ai](https://vast.ai/console/create/)
+2. Add credits ($5-10 inicial — sobra muito)
+3. Gera SSH key local se ainda não tem:
+   ```bash
+   ssh-keygen -t ed25519 -C "andersonabsmelo@gmail.com" -f ~/.ssh/edou_vastai
+   ```
+4. Copia public key pro Vast.ai: Console → Account → SSH keys → Add
+   ```bash
+   cat ~/.ssh/edou_vastai.pub | pbcopy  # macOS
+   ```
+
+## 2. Spin up instance
+
+Vai pro [Vast.ai search console](https://cloud.vast.ai/create/) e filtra:
+
+| Filtro | Valor recomendado |
+|---|---|
+| GPU | RTX 3090 ou 4090 (24GB) |
+| Disk | 50+ GB |
+| Reliability | >95% |
+| Verified | ✓ |
+| Inet up/down | >100 Mbps (download de weights) |
+| Image template | `pytorch/pytorch:2.1.0-cuda12.1-cudnn8-devel` (ou CUDA 12.1+ similar) |
+| Price | <$0.40/hr (3090), <$0.80/hr (4090) |
+
+**Exemplo realista**: RTX 3090 a $0.25/hr, 60GB disk, 99% reliability.
+
+Click **Rent** → instance starting.
+
+## 3. SSH no instance
+
+Após status "Running":
+
+```bash
+# Pega SSH command do Vast.ai console (instance details → Connect → SSH)
+ssh -i ~/.ssh/edou_vastai -p <PORT> root@<IP> -L 8188:localhost:8188
+
+# -L 8188:localhost:8188 abre túnel pra ComfyUI no browser local
+```
+
+## 4. tmux pra sessões persistentes
+
+**SEMPRE rode dentro de tmux**. Se SSH cair, instance continua rodando o
+trabalho. Sem tmux + SSH cair = setup interrompido + créditos queimados.
+
+```bash
+tmux new -s edou
+# Dentro do tmux: roda os scripts
+
+# Detach: Ctrl+B depois D
+# Reattach (mesma SSH ou nova): tmux attach -t edou
+# Listar sessões: tmux ls
+# Kill sessão: tmux kill-session -t edou
+```
+
+## 5. Clone repo + setup
+
+```bash
+# Dentro do tmux:
+cd ~
+# Clona seu repo HF (depois de tu pushar o 3d-pipeline lá)
+git clone https://huggingface.co/<seu-username>/edou-3d.git
+cd edou-3d
+
+# Setup (~30-45min)
+bash setup/install_hunyuan3d.sh
+
+# Download models (~30-60min, ~30GB) — vai dormir, deixa rodando no tmux
+bash setup/download_models.sh
+
+# Smoke test (~5min) — confirma que tudo funciona
+bash setup/verify_install.sh
+```
+
+## 6. Uso — gerar estante
+
+```bash
+# Edita prompt se quiser:
+nano prompts/estante_baroque.txt
+
+# Roda pipeline (~5-10min: SDXL ~30s + Hunyuan shape ~3min + texture ~3min)
+bash setup/run_estante_pipeline.sh --output-name estante_v1
+
+# Resultado em ~/work/outputs/runs/estante_v1/
+ls -la ~/work/outputs/runs/estante_v1/
+# - reference.png   (imagem SDXL)
+# - shape_only.glb  (Hunyuan sem textura)
+# - final.glb       (Hunyuan com PBR — usar este)
+```
+
+## 7. Download local + Blender post
+
+**Antes de destruir o instance**, baixa os GLBs:
+
+```bash
+# No laptop (não no instance):
+cd ~/Desktop/Projetos/edou/3d-pipeline/outputs
+scp -i ~/.ssh/edou_vastai -P <PORT> \
+    root@<IP>:~/work/outputs/runs/estante_v1/final.glb \
+    ./estante_v1.glb
+
+# Blender post-processing (local, gratuito)
+cd ..
+blender --background --python blender/add_estante_anchors.py -- \
+    --input outputs/estante_v1.glb \
+    --output-fbx outputs/estante_hero_ai.fbx
+
+# Copia pro Unity
+cp outputs/estante_hero_ai.fbx \
+   ../unity-library/EDouLibrary/Assets/_Project/Models/Furniture/
+```
+
+## 8. Destruir instance ⚠️ CRITICAL
+
+**Esquecer = $$/hr indo continuamente.** Após baixar os GLBs:
+
+1. Vast.ai console → instance → **DESTROY**
+2. Confirma: "Yes, destroy"
+3. Verifica em "Instances" que o estado virou "Stopped"
+4. Storage permanente NÃO é cobrado após destroy (a menos que tu tenha
+   alocado volume persistente — pra Hunyuan não precisa)
+
+Custo estimado primeiro run completo:
+- Setup + downloads + smoke + 1 estante: ~3-4 horas RTX 3090 a $0.25/hr = **~$1**
+
+## 9. Monitoring durante uso
+
+```bash
+# GPU usage
+watch -n1 nvidia-smi
+
+# Disk space
+df -h /
+
+# Network (download progress)
+iftop  # se instalado
+
+# Cost tracking
+# Vast.ai console mostra $/hr e total acumulado por instance
+```
+
+## 10. Re-uso instance (sessões futuras)
+
+Após destruir, próxima sessão precisa novo instance. Pra acelerar:
+- **Snapshot persistent storage** — opcional, custa ~$0.01/GB/mês
+  (50GB × $0.01 = $0.50/mês). Permite reuso sem re-download.
+- **Sem snapshot**: cada sessão re-baixa weights (~30min). Aceitável
+  pra uso esporádico.
+
+Se for usar Hunyuan >2x/semana → snapshot vale a pena.
+Se for esporádico → re-download cada vez.
+
+## Cost log template
+
+Manter em `docs/cost_tracking.md`:
+
+```
+| Data | Duração | GPU | $/hr | Total | Output |
+|---|---|---|---|---|---|
+| 2026-04-29 | 2h45 | RTX 3090 | $0.25 | $0.69 | estante_v1.glb (rejected) |
+| 2026-04-30 | 1h20 | RTX 3090 | $0.27 | $0.36 | estante_v3.glb (✓ aprovado) |
+```

outputs/README.md

@@ -0,0 +1,33 @@
+# Outputs/ — gerados pelos scripts (gitignored)
+
+Diretório onde os artefatos de cada run são salvos. Os arquivos
+`*.glb`, `*.fbx`, `*.png`, etc. são gitignored (.gitignore root) porque:
+
+- Ficam grandes (10-100MB por GLB)
+- Mudam frequentemente entre iterações
+- Versão final aprovada vai pro Unity Assets/Furniture/, não pra cá
+
+## Estrutura esperada
+
+```
+outputs/
+├── runs/                       # cada run em pasta separada com timestamp
+│   ├── estante_v1/
+│   │   ├── reference.png       # SDXL output
+│   │   ├── shape_only.glb      # Hunyuan shape (sem texture)
+│   │   └── final.glb           # Hunyuan textured (USAR ESTE)
+│   ├── estante_v2/
+│   │   └── ...
+│   └── casco_v1/
+│       └── ...
+└── estante_hero_ai.fbx         # output final do Blender post-process
+```
+
+## Workflow
+
+1. `bash setup/run_estante_pipeline.sh` cria `runs/estante_<timestamp>/`
+2. Anderson avalia visualmente (abre `final.glb` em viewer GLB ou Blender)
+3. Se bom → roda `add_estante_anchors.py` → produz `estante_hero_ai.fbx`
+4. Copia FBX pro Unity: `cp estante_hero_ai.fbx ../unity-library/.../Furniture/`
+5. Mantém `runs/` localmente pra histórico (ocasional limpeza manual quando
+   ficar grande demais)

prompts/README.md

@@ -0,0 +1,58 @@
+# Prompt Engineering — EDou 3D
+
+Lições e iterações sobre prompts pra Hunyuan3D-2.1 (via SDXL → image → 3D).
+
+## Princípios para Hunyuan3D image-to-3D
+
+Hunyuan3D não recebe texto direto — ele recebe IMAGEM e gera 3D. Logo,
+**toda a engenharia de prompt vai pro SDXL** que cria a imagem de
+referência. Características críticas da imagem que geram bom 3D:
+
+1. **Objeto isolado, fundo neutro** — fundo complexo confunde o modelo de shape
+2. **Iluminação suave + contraste claro** — sombras duras enganam o modelo de profundidade
+3. **Vista frontal direta** — perspectivas extremas distorcem proporções
+4. **Sem texto/letras** — Hunyuan tenta extrudar texto como geometria, vira ruído
+5. **Sem pessoas/personagens** — modelo otimizado pra objetos
+6. **Detalhes nítidos com sharpness alta** — blur reduz definição da silhueta gerada
+7. **1024×1024** mínimo (SDXL native), idealmente 1536 com refiner
+
+## Negative prompts padrão (sempre incluir)
+
+```
+person, people, human, character, face,
+text, letters, watermark, signature, logo,
+blurry, distorted, low quality, deformed,
+sketch, drawing, painting, cartoon,
+multiple objects, cluttered scene
+```
+
+## Iteração esperada
+
+Hunyuan tira ~3-5 imagens diferentes pra encontrar uma que gera bom 3D.
+Comum: imagem que parece linda em 2D mas gera 3D ruim porque tem
+ambiguidade de profundidade (ex: ornamentos muito densos = textura
+plana em vez de relevo).
+
+## Arquivos
+
+- `estante_baroque.txt` — prompt pra estante hero piece (uma estante isolada)
+- `casco_hogwarts.txt` — prompt pro corredor da biblioteca (interior arquitetural)
+
+## Dicas iteração estante
+
+Se primeira gen ficar com proporções erradas:
+- **Muito largo**: adicionar "narrow tall vertical cabinet"
+- **Muito raso**: adicionar "deep sturdy bookcase, 50cm depth"
+- **Sem prateleiras visíveis**: adicionar "with 4 horizontal wooden shelves clearly visible"
+- **Demasiado ornamentado**: remover "ornate" e "baroque", adicionar "elegant simple"
+- **Pouco ornamentado**: adicionar "richly carved", "highly decorated"
+
+## Dicas iteração casco
+
+Casco é texturizado mais como AMBIENTE que como objeto. Pode dar 3D
+ruim mesmo com imagem boa (interiores são notoriamente difíceis pra
+text-to-3D atual). Se Hunyuan falhar com casco:
+- Plano B: gerar PAREDES individuais (1 imagem de painel de parede,
+  Hunyuan cria 1 mesh, replica em Unity)
+- Plano C: cair em casco procedural (Blender + create_arch_pointed
+  existente em geometry.py + texture PolyHaven)

prompts/casco_hogwarts.txt

@@ -0,0 +1,11 @@
+Hogwarts library interior corridor, gothic medieval architecture,
+tall stone walls with vaulted ribbed ceiling,
+stained glass windows with colored panels casting warm light,
+dark wooden floor with worn texture,
+gothic pointed arches and stone columns flanking the corridor,
+moody atmospheric lighting from candles and natural daylight,
+inspired by Trinity College Long Room Dublin and Strahov Monastery Library,
+photorealistic interior architecture, no people, no furniture,
+empty room ready for decoration,
+front-facing perspective showing depth into corridor,
+cinematic 16:9 aspect, high detail, sharp focus

prompts/estante_baroque.txt

@@ -0,0 +1,12 @@
+Ornate baroque library bookshelf, single tall vertical cabinet,
+made of dark mahogany wood with rich aged patina,
+gold leaf gilded ornaments and bronze decorative brackets at corners,
+gothic arched pediment top with carved volutes flanking the sides,
+turned baluster columns with composite capitals on all four corners,
+four horizontal shelves visible inside, ornate central shield-shaped plaque on the pediment,
+double cornice with dentil molding and ovolo band,
+inspired by Strahov Monastery Library Prague,
+photorealistic, museum quality woodworking,
+studio product photography lighting, neutral background,
+front view, full body shot, isolated object,
+high detail, sharp focus, no text, no people

setup/download_models.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# download_models.sh
+# Baixa weights do Hunyuan3D-2.1 + SDXL pra ComfyUI.
+# Total ~30GB. Roda em background com tmux pra não travar SSH.
+#
+# Uso:
+#   bash download_models.sh
+#
+# IMPORTANTE: tem que rodar APÓS install_hunyuan3d.sh.
+
+set -euo pipefail
+
+WORK_DIR="${WORK_DIR:-$HOME/work}"
+VENV_DIR="${VENV_DIR:-$HOME/3d-env}"
+
+source "$VENV_DIR/bin/activate"
+
+echo "============================================================"
+echo "Download de model weights (~30GB total)"
+echo "============================================================"
+
+# Hunyuan3D-2.1 weights — a HF repo do Tencent oficial
+# (verificar repo name — Tencent reorg pode renomear; ajustar se erro 404)
+HF_HUNYUAN_REPO="${HF_HUNYUAN_REPO:-tencent/Hunyuan3D-2.1}"
+HUNYUAN_WEIGHTS_DIR="$WORK_DIR/hunyuan/weights"
+
+echo ""
+echo "[1/2] Hunyuan3D-2.1 weights de $HF_HUNYUAN_REPO..."
+mkdir -p "$HUNYUAN_WEIGHTS_DIR"
+huggingface-cli download "$HF_HUNYUAN_REPO" \
+    --local-dir "$HUNYUAN_WEIGHTS_DIR" \
+    --local-dir-use-symlinks False \
+    || {
+        echo "  ⚠ Falhou. Tentar fallback Hunyuan3D-2 (versão 2.0)..."
+        huggingface-cli download "tencent/Hunyuan3D-2" \
+            --local-dir "$HUNYUAN_WEIGHTS_DIR" \
+            --local-dir-use-symlinks False
+    }
+
+# SDXL pra ComfyUI (geração de imagem de referência)
+SDXL_REPO="${SDXL_REPO:-stabilityai/stable-diffusion-xl-base-1.0}"
+SDXL_FILE="sd_xl_base_1.0.safetensors"
+COMFY_CKPT_DIR="$WORK_DIR/comfyui/models/checkpoints"
+
+echo ""
+echo "[2/2] SDXL base 1.0 pra ComfyUI..."
+mkdir -p "$COMFY_CKPT_DIR"
+if [ ! -f "$COMFY_CKPT_DIR/$SDXL_FILE" ]; then
+    huggingface-cli download "$SDXL_REPO" "$SDXL_FILE" \
+        --local-dir "$COMFY_CKPT_DIR" \
+        --local-dir-use-symlinks False
+else
+    echo "  $SDXL_FILE já existe, skip."
+fi
+
+# Refiner SDXL (opcional mas melhora qualidade da imagem de referência)
+SDXL_REFINER_FILE="sd_xl_refiner_1.0.safetensors"
+SDXL_REFINER_REPO="stabilityai/stable-diffusion-xl-refiner-1.0"
+echo ""
+echo "[bonus] SDXL refiner 1.0 (opcional — melhora detalhes)..."
+if [ ! -f "$COMFY_CKPT_DIR/$SDXL_REFINER_FILE" ]; then
+    huggingface-cli download "$SDXL_REFINER_REPO" "$SDXL_REFINER_FILE" \
+        --local-dir "$COMFY_CKPT_DIR" \
+        --local-dir-use-symlinks False \
+        || echo "  refiner skip (falhou — não bloqueia pipeline)"
+else
+    echo "  refiner já existe, skip."
+fi
+
+# VAE (opcional, melhor cor)
+VAE_FILE="sdxl_vae.safetensors"
+VAE_REPO="madebyollin/sdxl-vae-fp16-fix"
+COMFY_VAE_DIR="$WORK_DIR/comfyui/models/vae"
+mkdir -p "$COMFY_VAE_DIR"
+echo ""
+echo "[bonus] VAE FP16 fix..."
+if [ ! -f "$COMFY_VAE_DIR/$VAE_FILE" ]; then
+    huggingface-cli download "$VAE_REPO" \
+        --local-dir "$COMFY_VAE_DIR" \
+        --local-dir-use-symlinks False \
+        || echo "  vae skip (não bloqueia)"
+else
+    echo "  vae já existe, skip."
+fi
+
+echo ""
+echo "============================================================"
+echo "✅ Models baixados em:"
+echo "   Hunyuan: $HUNYUAN_WEIGHTS_DIR ($(du -sh $HUNYUAN_WEIGHTS_DIR 2>/dev/null | cut -f1))"
+echo "   SDXL:    $COMFY_CKPT_DIR ($(du -sh $COMFY_CKPT_DIR 2>/dev/null | cut -f1))"
+echo "============================================================"
+echo ""
+echo "Próximo: bash verify_install.sh"

setup/install_hunyuan3d.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# install_hunyuan3d.sh
+# Setup Hunyuan3D-2.1 + ComfyUI numa GPU instance Vast.ai (Ubuntu 22.04 + CUDA 12.1).
+# Tested target: RTX 3090 (24GB VRAM) ou superior.
+#
+# Uso:
+#   bash install_hunyuan3d.sh
+#
+# Tempo esperado: ~30-45min (sem download de weights — esses vão em download_models.sh).
+# IMPORTANTE: rode dentro de tmux! Conexão SSH cair = setup interrompido.
+
+set -euo pipefail
+
+WORK_DIR="${WORK_DIR:-$HOME/work}"
+VENV_DIR="${VENV_DIR:-$HOME/3d-env}"
+
+echo "============================================================"
+echo "EDou 3D Pipeline — Hunyuan3D-2.1 + ComfyUI install"
+echo "WORK_DIR=$WORK_DIR  VENV_DIR=$VENV_DIR"
+echo "============================================================"
+
+# 0. Sanity check — GPU presente
+if ! command -v nvidia-smi >/dev/null 2>&1; then
+    echo "ERRO: nvidia-smi não encontrado. Instance sem GPU?"
+    exit 1
+fi
+nvidia-smi | head -20
+
+# 1. Sistema (sudo varia por instance — Vast.ai geralmente já é root)
+echo ""
+echo "[1/7] System dependencies..."
+if command -v sudo >/dev/null 2>&1; then SUDO="sudo"; else SUDO=""; fi
+$SUDO apt-get update -qq
+$SUDO apt-get install -y -qq \
+    git wget curl tmux htop \
+    python3-pip python3-venv python3-dev \
+    build-essential cmake \
+    libgl1-mesa-glx libglib2.0-0 \
+    libsm6 libxext6 libxrender-dev libgomp1
+
+# 2. Python venv (isola dependências)
+echo ""
+echo "[2/7] Python virtual env at $VENV_DIR..."
+python3 -m venv "$VENV_DIR"
+source "$VENV_DIR/bin/activate"
+pip install --upgrade pip wheel setuptools
+
+# 3. PyTorch matching CUDA 12.1
+echo ""
+echo "[3/7] PyTorch (CUDA 12.1)..."
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+
+# 4. HuggingFace CLI (pra download de weights depois)
+echo ""
+echo "[4/7] HuggingFace Hub CLI..."
+pip install -U "huggingface_hub[cli]"
+
+# 5. Hunyuan3D-2.1
+echo ""
+echo "[5/7] Hunyuan3D-2.1 clone + install..."
+mkdir -p "$WORK_DIR" && cd "$WORK_DIR"
+if [ ! -d "hunyuan" ]; then
+    git clone https://github.com/Tencent/Hunyuan3D-2.git hunyuan
+fi
+cd hunyuan
+git pull origin main
+pip install -r requirements.txt
+pip install -e .
+
+# Texture custom rasterizer + differentiable renderer (compilam C++/CUDA — pode demorar)
+echo ""
+echo "  → Building custom rasterizer (C++/CUDA, ~3-5min)..."
+if [ -d "hy3dgen/texgen/custom_rasterizer" ]; then
+    cd hy3dgen/texgen/custom_rasterizer && pip install -e . && cd "$WORK_DIR/hunyuan"
+fi
+echo "  → Building differentiable renderer..."
+if [ -d "hy3dgen/texgen/differentiable_renderer" ]; then
+    cd hy3dgen/texgen/differentiable_renderer && pip install -e . && cd "$WORK_DIR/hunyuan"
+fi
+
+# 6. ComfyUI (pra geração de imagem via SDXL)
+echo ""
+echo "[6/7] ComfyUI clone + install..."
+cd "$WORK_DIR"
+if [ ! -d "comfyui" ]; then
+    git clone https://github.com/comfyanonymous/ComfyUI.git comfyui
+fi
+cd comfyui
+git pull origin master
+pip install -r requirements.txt
+
+# 7. Final check
+echo ""
+echo "[7/7] Verificações finais..."
+python3 -c "import torch; print(f'  PyTorch: {torch.__version__} | CUDA: {torch.cuda.is_available()} | Device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"CPU\"}')"
+python3 -c "import sys; sys.path.insert(0, '$WORK_DIR/hunyuan'); from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; print('  Hunyuan3D import OK')" || echo "  ⚠ Hunyuan3D import falhou — checar logs"
+
+echo ""
+echo "============================================================"
+echo "✅ Install completo. Próximo passo: bash download_models.sh"
+echo "============================================================"
+echo ""
+echo "Lembrete: ative o venv em sessões SSH novas:"
+echo "  source $VENV_DIR/bin/activate"

setup/run_estante_pipeline.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+# run_estante_pipeline.sh
+# Pipeline ponta-a-ponta: SDXL gera imagem de referência → Hunyuan3D
+# converte em GLB com PBR textures.
+#
+# Uso:
+#   bash run_estante_pipeline.sh [--prompt-file prompts/estante_baroque.txt]
+#                                [--output-name estante_v1]
+
+set -euo pipefail
+
+WORK_DIR="${WORK_DIR:-$HOME/work}"
+VENV_DIR="${VENV_DIR:-$HOME/3d-env}"
+REPO_DIR="${REPO_DIR:-$(dirname "$(realpath "$0")")/..}"
+OUTPUT_DIR="${OUTPUT_DIR:-$WORK_DIR/outputs}"
+
+# Args
+PROMPT_FILE="$REPO_DIR/prompts/estante_baroque.txt"
+OUTPUT_NAME="estante_$(date +%Y%m%d_%H%M%S)"
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --prompt-file) PROMPT_FILE="$2"; shift 2 ;;
+        --output-name) OUTPUT_NAME="$2"; shift 2 ;;
+        *) echo "Arg desconhecido: $1"; exit 1 ;;
+    esac
+done
+
+source "$VENV_DIR/bin/activate"
+mkdir -p "$OUTPUT_DIR/runs/$OUTPUT_NAME"
+
+PROMPT=$(cat "$PROMPT_FILE")
+echo "============================================================"
+echo "Pipeline estante hero"
+echo "Prompt file: $PROMPT_FILE"
+echo "Output: $OUTPUT_DIR/runs/$OUTPUT_NAME"
+echo "============================================================"
+echo ""
+echo "Prompt:"
+echo "$PROMPT" | head -5
+echo "..."
+echo ""
+
+# Etapa 1: SDXL gera imagem de referência
+# Usa script Python standalone com pipeline diffusers (mais simples que ComfyUI headless).
+REF_IMG="$OUTPUT_DIR/runs/$OUTPUT_NAME/reference.png"
+echo "[1/2] SDXL gerando imagem de referência..."
+python3 - <<PYEOF
+from diffusers import StableDiffusionXLPipeline
+import torch
+
+prompt = """$PROMPT"""
+
+pipe = StableDiffusionXLPipeline.from_single_file(
+    "$WORK_DIR/comfyui/models/checkpoints/sd_xl_base_1.0.safetensors",
+    torch_dtype=torch.float16,
+    use_safetensors=True,
+)
+pipe = pipe.to("cuda")
+pipe.enable_attention_slicing()
+
+# Negative prompt: evitar pessoas, texto, watermarks
+negative = "person, people, human, text, watermark, signature, blurry, distorted, low quality, sketch, drawing"
+
+print("  Gerando 1024x1024 (steps=30, guidance=7.5)...")
+image = pipe(
+    prompt=prompt,
+    negative_prompt=negative,
+    width=1024,
+    height=1024,
+    num_inference_steps=30,
+    guidance_scale=7.5,
+).images[0]
+
+image.save("$REF_IMG")
+print(f"  ✅ Reference image: $REF_IMG")
+PYEOF
+
+echo ""
+echo "[2/2] Hunyuan3D convertendo imagem em mesh + textura..."
+python3 - <<PYEOF
+import os, sys, time
+sys.path.insert(0, "$WORK_DIR/hunyuan")
+
+from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
+from hy3dgen.texgen import Hunyuan3DPaintPipeline
+
+print("  Carregando shape pipeline...")
+t0 = time.time()
+shape_pipe = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained("$WORK_DIR/hunyuan/weights")
+print(f"    {time.time()-t0:.1f}s")
+
+print("  Gerando shape (Hunyuan3D-2.1, ~1-3min)...")
+t0 = time.time()
+mesh = shape_pipe(image="$REF_IMG")[0]
+print(f"    {time.time()-t0:.1f}s — verts={len(mesh.vertices)}, faces={len(mesh.faces)}")
+
+mesh_path = "$OUTPUT_DIR/runs/$OUTPUT_NAME/shape_only.glb"
+mesh.export(mesh_path)
+print(f"  ✅ Shape: $OUTPUT_DIR/runs/$OUTPUT_NAME/shape_only.glb")
+
+print("  Carregando texture pipeline...")
+t0 = time.time()
+try:
+    texgen = Hunyuan3DPaintPipeline.from_pretrained("$WORK_DIR/hunyuan/weights")
+    print(f"    {time.time()-t0:.1f}s")
+
+    print("  Gerando textures PBR (~2-4min)...")
+    t0 = time.time()
+    textured = texgen(mesh, image="$REF_IMG")
+    print(f"    {time.time()-t0:.1f}s")
+
+    final_path = "$OUTPUT_DIR/runs/$OUTPUT_NAME/final.glb"
+    textured.export(final_path)
+    print(f"  ✅ Final (textured): {final_path}")
+except Exception as e:
+    print(f"  ⚠ Texture step falhou ({e}). Mesh sem textura disponível em shape_only.glb.")
+PYEOF
+
+echo ""
+echo "============================================================"
+echo "✅ Pipeline completo. Resultados em:"
+echo "   $OUTPUT_DIR/runs/$OUTPUT_NAME/"
+echo ""
+echo "Files:"
+ls -la "$OUTPUT_DIR/runs/$OUTPUT_NAME/"
+echo "============================================================"
+echo ""
+echo "Próximo: scp pra local + Blender post-process:"
+echo "   scp <vastai-ip>:$OUTPUT_DIR/runs/$OUTPUT_NAME/final.glb ./outputs/"
+echo "   blender --background --python blender/add_estante_anchors.py -- ./outputs/final.glb"

setup/verify_install.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# verify_install.sh
+# Smoke test: gera 1 mesh teste com Hunyuan3D pra confirmar que tudo
+# funciona ANTES de gastar tempo iterando prompts.
+#
+# Uso:
+#   bash verify_install.sh
+
+set -euo pipefail
+
+WORK_DIR="${WORK_DIR:-$HOME/work}"
+VENV_DIR="${VENV_DIR:-$HOME/3d-env}"
+OUTPUT_DIR="${OUTPUT_DIR:-$WORK_DIR/outputs}"
+
+source "$VENV_DIR/bin/activate"
+
+mkdir -p "$OUTPUT_DIR"
+
+echo "============================================================"
+echo "Smoke test Hunyuan3D-2.1"
+echo "============================================================"
+
+# Verifica imagem de teste — usa uma sample do próprio repo Hunyuan,
+# ou baixa rapida de um asset clássico (esfera, cubo, etc).
+TEST_IMG="$WORK_DIR/hunyuan/assets/example_images/004.png"
+if [ ! -f "$TEST_IMG" ]; then
+    # Fallback: baixar uma imagem test simples
+    TEST_IMG="$OUTPUT_DIR/test_input.png"
+    echo "Sample do repo não encontrado, baixando test image..."
+    wget -O "$TEST_IMG" \
+        "https://upload.wikimedia.org/wikipedia/commons/thumb/8/8a/Banana-Single.jpg/640px-Banana-Single.jpg" \
+        || { echo "ERRO: falha no download da test image"; exit 1; }
+fi
+
+echo "Test image: $TEST_IMG"
+echo ""
+
+# Inferência simples Hunyuan3D
+python3 - <<PYEOF
+import os, sys, time
+sys.path.insert(0, os.path.expanduser("$WORK_DIR/hunyuan"))
+
+from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
+
+print("Carregando Hunyuan3D pipeline (pode demorar ~1min na primeira vez)...")
+t0 = time.time()
+pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
+    "$WORK_DIR/hunyuan/weights",
+)
+print(f"  Loaded em {time.time()-t0:.1f}s")
+
+print("Gerando mesh do test image...")
+t0 = time.time()
+mesh = pipeline(image="$TEST_IMG")[0]
+print(f"  Generated em {time.time()-t0:.1f}s")
+print(f"  Verts: {len(mesh.vertices)}  Faces: {len(mesh.faces)}")
+
+out_glb = "$OUTPUT_DIR/smoke_test.glb"
+mesh.export(out_glb)
+print(f"✅ Salvo em {out_glb}")
+PYEOF
+
+echo ""
+echo "============================================================"
+echo "✅ Smoke test passou. Hunyuan3D operacional."
+echo "Resultado: $OUTPUT_DIR/smoke_test.glb (${$(du -h $OUTPUT_DIR/smoke_test.glb | cut -f1)})"
+echo "============================================================"
+echo ""
+echo "Pronto pra gerar a estante: bash run_estante_pipeline.sh"

workflows/hunyuan_inference.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""
+hunyuan_inference.py — script Python standalone pra rodar Hunyuan3D-2.1
+em qualquer imagem de input. Usado pelo run_estante_pipeline.sh mas pode
+ser executado manualmente também.
+
+Uso:
+    python3 hunyuan_inference.py --image path/to/ref.png --output out.glb [--no-texture]
+
+Requer venv ativo + weights baixados em $WORK_DIR/hunyuan/weights.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Hunyuan3D-2.1 inference")
+    parser.add_argument("--image", required=True, type=Path, help="Reference image (PNG/JPG)")
+    parser.add_argument("--output", required=True, type=Path, help="Output GLB path")
+    parser.add_argument("--weights", default=os.path.expanduser("~/work/hunyuan/weights"),
+                        help="Hunyuan weights dir")
+    parser.add_argument("--no-texture", action="store_true",
+                        help="Skip texture generation (faster, mesh sem PBR)")
+    parser.add_argument("--seed", type=int, default=42)
+    args = parser.parse_args()
+
+    if not args.image.exists():
+        print(f"ERRO: imagem não encontrada: {args.image}", file=sys.stderr)
+        return 1
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+
+    # Add Hunyuan repo to path
+    repo_path = Path(args.weights).parent
+    sys.path.insert(0, str(repo_path))
+
+    from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
+
+    print(f"[hunyuan] Image: {args.image}")
+    print(f"[hunyuan] Output: {args.output}")
+    print(f"[hunyuan] Weights: {args.weights}")
+
+    print("[hunyuan] Loading shape pipeline...")
+    t0 = time.time()
+    shape_pipe = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(args.weights)
+    print(f"  loaded em {time.time()-t0:.1f}s")
+
+    print("[hunyuan] Generating shape...")
+    t0 = time.time()
+    mesh = shape_pipe(image=str(args.image), seed=args.seed)[0]
+    print(f"  generated em {time.time()-t0:.1f}s")
+    print(f"  verts={len(mesh.vertices)}  faces={len(mesh.faces)}")
+
+    if not args.no_texture:
+        print("[hunyuan] Loading texture pipeline...")
+        try:
+            from hy3dgen.texgen import Hunyuan3DPaintPipeline
+            t0 = time.time()
+            texgen = Hunyuan3DPaintPipeline.from_pretrained(args.weights)
+            print(f"  loaded em {time.time()-t0:.1f}s")
+
+            print("[hunyuan] Painting texture...")
+            t0 = time.time()
+            mesh = texgen(mesh, image=str(args.image))
+            print(f"  painted em {time.time()-t0:.1f}s")
+        except ImportError as e:
+            print(f"  ⚠ texgen import falhou ({e}). Mesh sem textura.", file=sys.stderr)
+        except Exception as e:
+            print(f"  ⚠ texgen erro ({e}). Salvando mesh untextured.", file=sys.stderr)
+
+    print(f"[hunyuan] Exporting {args.output}...")
+    mesh.export(str(args.output))
+    size_mb = args.output.stat().st_size / 1024 / 1024
+    print(f"  ✅ {args.output} ({size_mb:.1f} MB)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

workflows/sdxl_estante.json

@@ -0,0 +1,19 @@
+{
+  "_comment": "ComfyUI workflow JSON (SDXL base + refiner) pra gerar imagem de referência da estante. Importar via ComfyUI web UI: Load → este arquivo. Pode também ser feito programaticamente via run_estante_pipeline.sh que usa diffusers diretamente (não ComfyUI). Mantido aqui pra quem preferir UI manual.",
+  "_workflow_version": "1.0",
+  "_target_resolution": "1024x1024",
+  "_steps": 30,
+  "_guidance_scale": 7.5,
+  "_notes": "Anderson — quando rodar ComfyUI no Vast.ai instance, abra túnel SSH na porta 8188:\nssh -L 8188:localhost:8188 root@<vastai-ip>\nhttp://localhost:8188 no browser local.",
+  "nodes": {
+    "_skeleton": "Workflow real será exportado da UI ComfyUI numa primeira sessão de uso. Esse JSON é placeholder pra estrutura do repo. Substituir pelo export real quando tiver workflow validado.",
+    "1_loader": "CheckpointLoaderSimple → sd_xl_base_1.0.safetensors",
+    "2_positive": "CLIPTextEncode (positive prompt do prompts/estante_baroque.txt)",
+    "3_negative": "CLIPTextEncode (negative prompt — pessoas/texto/blur)",
+    "4_latent": "EmptyLatentImage 1024x1024",
+    "5_sampler": "KSampler (steps=30, cfg=7.5, sampler=dpmpp_2m, scheduler=karras)",
+    "6_decode": "VAEDecode",
+    "7_save": "SaveImage → outputs/runs/<timestamp>/reference.png"
+  },
+  "_alternative": "Pra automação via Python: usar diffusers StableDiffusionXLPipeline.from_single_file() — código já implementado em setup/run_estante_pipeline.sh."
+}