---
name: image-to-3d
description: >
  Bilder in druckbare 3D-Modelle umwandeln via AI (Hunyuan3D-2) + Trimesh-Konvertierung.
  Generiert aus einem 2D-Bild (Foto, Pixel-Art, Zeichnung) ein GLB/STL-Mesh.
  Nicht BambuLab-Design — das ist ein separater Skill (`bambu-3d-design`).
tags:
  - 3d
  - ai-generation
  - stl
  - glb
  - hunyuan3d
  - image-to-mesh
  - trimesh
---

# Image-to-3D: Bilder in 3D-Modelle umwandeln

## Ziel
Aus einem 2D-Bild (Avatar, Foto, Zeichnung, etc.) per AI ein 3D-Mesh generieren und als STL/GLB ausgeben.

## Voraussetzung
```bash
pip install gradio_client trimesh
```

## 3-Schritte-Workflow

### Schritt 1: Hunyuan3D-2 über HuggingFace Spaces aufrufen
```python
from gradio_client import Client, handle_file

c = Client("tencent/Hunyuan3D-2")
img = handle_file("/pfad/zum/bild.jpg")

# Job starten
job = c.submit(
    image=img,
    caption=None,  # Optional
    mv_image_front=None, mv_image_back=None,
    mv_image_left=None, mv_image_right=None,
    steps=30,
    guidance_scale=5.0,
    seed=1234,
    octree_resolution=256,
    check_box_rembg=True,   # Hintergrund automatisch entfernen
    num_chunks=8000,
    randomize_seed=True,
    api_name="/shape_generation"
)

# Auf Ergebnis warten (Timeout freiwillig)
result = job.result(timeout=300)
```

**Rückgabe:**
- `result[0]` — Output-File-Pfad (GLB)

**OR** run `scripts/generate_3d_from_image.py <image.jpg> [caption]` directly.

### Schritt 2: GLB in STL konvertieren
```python
import trimesh

mesh = trimesh.load("/pfad/zur/white_mesh.glb", force='mesh')
mesh.export("/pfad/zum/output.stl")
```

### Schritt 3: Bereitstellung
- **GLB** → Viewer/Teilen/Website (beinhaltet Farbe)
- **STL** → Druck-Workflow (nur Geometrie)

## Post-Processing für Druck

AI-generierte Meshes (Hunyuan3D-2 etc.) sind oft **nicht watertight** — sie haben Löcher, doppelte Faces, oder schwebende Teile.

| Problem | Check | Fix |
|---------|-------|-----|
| Nicht watertight | `mesh.is_watertight` → False | Blender: Edit → Mesh → Clean Up → Merge by Distance → Fill Holes |
| Zu viele Faces | >500k | Blender: Decimate Modifier (Ratio 0.1–0.3) |
| Falsche Skala | Nicht in mm | Blender: S → numerischer Wert → Apply Scale |
| Schwebende Teile | `mesh.split()` > 1 | Entweder alle Teile separat drucken oder Boolean Union |
| Keine Dicke | 2D-artige Flächen | Solidify Modifier (Thickness ~2mm) |

**Schnell-Check in Python:**
```python
import trimesh
mesh = trimesh.load("model.stl")
print("Watertight:", mesh.is_watertight)
print("Volume:", mesh.volume)
print("Bounding box:", mesh.bounding_box.extents)
print("Faces:", len(mesh.faces))
```

**Blender CLI-Reparatur** (batch-fähig):
```python
# Save as repair.py, run with: blender --background --python repair.py
import bpy
bpy.ops.import_mesh.stl(filepath="input.stl")
obj = bpy.context.selected_objects[0]
bpy.context.view_layer.objects.active = obj
bpy.ops.object.editmode_toggle()
bpy.ops.mesh.select_all(action='SELECT')
bpy.ops.mesh.remove_doubles()
bpy.ops.mesh.fill_holes()
bpy.ops.object.editmode_toggle()
bpy.ops.export_mesh.stl(filepath="repaired.stl")
```

## Druck-Tipps

- **GLB** enthält Farbe/Texture → gut für Viewer, **STL** nur Geometrie → für Slicer
- Nach Reparatur in Bambu Studio importieren, Support nur bei Überhängen >45°
- Für kleine Figuren: 0.2mm Layer, 15% Infill, 3 Wände

## Wichtige Hinweise
- Der API-Call braucht `handle_file()` — nicht einfach String-Pfad übergeben.
- Der Space ist kostenlos, aber kann bei Überlastung langsam sein.
- Generiertes Mesh ist oft **nicht watertight** → für Druck "solidify" oder "repair" nötig (z.B. mit Blender, Meshmixer oder `trimesh.repair`).
- Nicht mit `bambu-3d-design` verwechseln — der Skill nutzt parametrisch generierte Box-Geometrie, diesen Image-First AI-Ansatz.