Blender-Animation — Python-gesteuerte 3D-Arbeit

Was macht Blender-Animation — Python-gesteuerte 3D-Arbeit?

Steuere Blender über bpy im Hintergrundmodus mit einem Skript, das du erneut ausführen kannst. Behandle die .blend-Datei als Build-Artefakt des Skripts: Das Skript ist die Quelle der Wahrheit, die Datei ist das Lieferobjekt.

Lies references/BLENDER-PLAYBOOK.md für Architektur und Urteilsvermögen sowie references/BLENDER-RECIPES.md für kopierfertige Code-Muster. Überprüfe jedes API-Detail anhand der Dokumentation der installierten Blender-Version; die Python-API ändert sich zwischen den Versionen.

1. Überprüfe zuerst die Umgebung

blender --version
blender --background --factory-startup --python-expr \
  "import bpy, sys; print('BLENDER', bpy.app.version_string); print('PY', sys.version.split()[0]); print('ENGINES', [e.bl_idname for e in bpy.types.RenderEngine.__subclasses__()][:5])"

Regeln:

• bpy gehört zu Blenders mitgeliefertem Python. Installiere bpy niemals mit pip install und führe Szenenskripte niemals mit System-Python aus.
• Verwende --python-exit-code 1, damit eine Python-Ausnahme den Shell-Befehl fehlschlagen lässt, anstatt einen stillen Erfolg zu produzieren.
• Verwende --factory-startup für saubere Builds; verwende es niemals, um ein offenes Projekt des Benutzers zu löschen.
• Protokolliere die Blender-Version, die Engine, den Frame-Bereich, die Auflösung, die FPS und den Ausgabepfad zu Beginn jedes Renderings.

2. Kanonische Aufrufe

# Eine Szene von Grund auf bauen und die .blend-Datei speichern
blender --background --factory-startup --python-exit-code 1 --python blender/scripts/build_scene.py

# Ein vorhandenes Projekt ändern
blender --background project.blend --python-exit-code 1 --python blender/scripts/update_scene.py

# Die gespeicherte Animation rendern
blender --background project.blend --render-anim

# Ein einzelnes Frame rendern
blender --background project.blend --render-frame 120

# Einen Bereich sicher rendern (Bildsequenz)
blender --background project.blend --python-exit-code 1 --python blender/scripts/render_frames.py

Führe lange Jobs mit umgeleiteter Ausgabe in logs/ aus und bevorzuge immer eine Bildsequenz für alles, was du möglicherweise fortsetzen musst.

3. Skript-Architektur

Beginne mit einer Datei für eine kleine Szene. Teile auf, wenn die Szene etwa 300 Zeilen überschreitet oder mehr als einen Shot hat:

blender/
  config.py          # fps, frame range, resolution, palette, paths, seed
  build.py           # Einstiegspunkt: reset → setup → build shots → save
  scene_setup.py     # world, units, collections, render settings
  geometry.py        # primitives, curves, parametric meshes
  materials.py       # node builders, reusable material factory
  animation.py       # keyframes, drivers, procedural motion
  camera.py          # rigs, orbit/dolly, DOF, framing checks
  lighting.py        # key/fill/rim, HDRI, emissive accents
  simulation.py      # particles, rigid body, cloth — cache setup
  render.py          # engine, samples, output, contact sheet, encode
  shots/             # ein Modul pro Shot: shot_01.py, shot_02.py

Nicht verhandelbar:

• Idempotent. Durch erneutes Ausführen des Builds werden nur Ihre benannten Collections/Objekte aktualisiert; es werden nie Geometrien dupliziert oder nicht zugehörige Benutzerinhalte gelöscht.
• Benannt. Main_Logo, Cam_Orbit, Light_Key, Emitter_Particles. Verwende niemals Cube.003.
• Konfiguriert. Jeder einstellbare Wert lebt in config.py oder einer Dataclass, sodass eine Änderung eine einzeilige Anpassung ist.
• Assertiv. Scheitere lautstark, wenn ein Asset, eine Kamera, eine Schriftart oder ein Ausgabeverzeichnis fehlt.
• Begrenzt. Die Bereinigung löscht nur Collections, deren Namen du besitzt, z. B. mit Präfix MS_.

4. Szenenkonstruktion

• Bevorzuge die Daten-API (bpy.data.objects.new, bpy.data.meshes.new, collection.objects.link) gegenüber kontextabhängigen bpy.ops, die von Auswahl, Modus und Bereich abhängen.
• Wenn ein Operator zwingend erforderlich ist, stelle einen ordnungsgemäßen Kontext-Override für diese Version bereit und dokumentiere, warum.
• Baue Materialien durch Nodes und eine kleine Factory-Funktion; kopiere keine 20-Node-Bäume pro Objekt.
• Verwende reale Maßstäbe und setze das Szenen-Einheitensystem; falsche Maßstäbe brechen DOF, Physik und Beleuchtung.
• Halte den World-Node-Baum explizit (Farbe, Stärke, HDRI), sodass Renderings auf einem anderen Rechner reproduzierbar sind.
• Packe oder relativiere Assets. //assets/...-Pfade plus ein Paketordner sind besser als absolute Pfade in den Downloads eines Benutzers.

5. Animation

Wähle den Mechanismus bewusst:

| Bedarf | Verwende | | | Autorisierte Position/Rotation/Skalierung/Materialänderung | Keyframes mit expliziter Interpolation | | Eigenschaft folgt einer anderen Eigenschaft oder einem Ausdruck | Driver (einfache, dokumentierte Ausdrücke) | | Wiederholte/parametrische Bewegung (Orbits, Wellen, Gitter, Spiralen) | Frame-abhängige Mathematik, zustandslos evaluiert | | Tausende von Instanzen, Mustern, Streuung | Geometry Nodes | | Physikalisch emergente Bewegung | Simulationen (Cache, überprüfen des gesamten Bereichs) | | Kamerapfad durch den Raum | Kurve + "Follow Path"-Constraint oder keyframiertes Rig |

Keyframe-Hygiene:

obj.location = (0, 0, 0)
obj.keyframe_insert("location", frame=1)
obj.location = (4, 0, 0)
obj.keyframe_insert("location", frame=48)

for fc in obj.animation_data.action.fcurves:
    for kp in fc.keyframe_points:
        kp.interpolation = 'BEZIER'
        kp.easing = 'EASE_IN_OUT'
        kp.handle_left_type = kp.handle_right_type = 'AUTO_CLAMPED'

• Setze die Interpolation gezielt. Standard-Bezier ist gut für organische Bewegungen; verwende LINEAR für konstante Geschwindigkeit und mechanische Bewegung; verwende CONSTANT für abgestufte/Pixel-Looks.
• Lasse niemals eine unbeabsichtigte Easing auf einem sich wiederholenden Zyklus — es erzeugt einen Ruck am Loop-Punkt.
• Für Loops: Mache Frame 1 und Frame N+1 identisch, rendere dann [1, N].
• Alles Prozedurale muss eine reine Funktion des Frames sein: f(frame). Kein akkumulierender Zustand, kein ungeseeder random.

6. Geometry Nodes und Instanziierung

Verwende Geometry Nodes, wenn du Skalierung, Variation oder nicht-destruktive Kontrolle benötigst:

• Streuen/Instanziieren (Bäume, Trümmer, Sterne, Menschenmengen-Blöcke).
• Parametrische Arrays, Gitter, radiale Muster, islamische geometrische Kachelungen.
• Animierte Verschiebung, Felder und rotations-/skalierungsabhängige Instanzen.
• Konvertieren einer schweren 10.000-Objekt-Python-Schleife in einen Node-Baum.

Baue Nodes mit Namen über nodes.new(...) und links.new(...), nicht über zerbrechliche Indizes. Lege die Knöpfe, die der Benutzer nachfragen wird (Anzahl, Radius, Seed, Geschwindigkeit), als Modifier-Eingaben frei, sodass eine Überarbeitung keine Code-Änderung erfordert.

7. Materialien, Beleuchtung, Kamera

• Materialien: Principled BSDF als Basis; explizite Roughness/Metallic; Emission für Akzente (zurückhaltend — Bloom kann keinen flachen Shot retten). Echte Transparenz nur bei Bedarf und im endgültigen Engine überprüfen.
• Beleuchtung: Key → Fill → Rim → Umgebung. Form und Tiefe gehen vor Dekoration. Überprüfe Belichtung und Spitzenlichter, nicht nur den Viewport.
• Kamera: Wähle Brennweite und Bildausschnitt für das Motiv. Orbit, Dolly, Kran oder starr — jede Bewegung muss einen Grund haben. Überprüfe den Bildausschnitt an den Extrempositionen, nicht nur an Frame 1. Bevorzuge glatte Bezier-Griffe; füge ein sanftes Ausklingen statt eines harten Stopps hinzu.
• Tiefenschärfe: Fokussiere auf den Story-Punkt; verwische niemals kleinen Text.

8. Engines und Render-Einstellungen

| Engine | Verwende für | Kosten | | | EEVEE | Bewegungsgrafiken, stilisierte Arbeit, schnelle Iteration, Vorschauen | Niedrig | | Cycles | Fotorealistisches Licht, Reflexionen, GI, Glas, finaler Look | Hoch | | Workbench | Blocking, Silhouetten, Animatics | Sehr niedrig |

Teste beide, wenn du unsicher bist; die Engine-Geschwindigkeit hängt von der Szene ab, nicht vom Marketing. GPU hängt von Build, Treiber und Betriebssystem ab — behalte immer einen CPU-Pfad.

Setze explizit und protokolliere:

scene.render.engine = 'BLENDER_EEVEE_NEXT'   # 4.2+; ältere Builds verwenden ggf. 'BLENDER_EEVEE'
scene.render.resolution_x, scene.render.resolution_y = 1920, 1080
scene.render.resolution_percentage = 100
scene.render.fps, scene.render.fps_base = 30, 1.0
scene.frame_start, scene.frame_end = 1, 300
scene.render.image_settings.file_format = 'PNG'
scene.render.image_settings.color_mode = 'RGBA'
scene.render.filepath = "//renders/shot_01/frame_"

• Vorschau: 25–50 % Auflösung, niedrige Samples, EEVEE oder Workbench.
• Final: volle Auflösung, Engine für den Look ausgewählt, Denoise, wenn es hilft, korrekte View-Transform.
• Farbe: Entscheide dich einmal für eine View-Transform (AgX/Filmic/Standard), wende sie auf alle Durchgänge an und gleiche sie nachgelagert in Remotion/FFmpeg ab. Nicht übereinstimmende Transforms sind die häufigste Ursache für „die Composite sieht verwaschen aus".
• Lange Renderings → PNG- (oder EXR, wenn HDR benötigt wird) Sequenz, dann Encode. Direkte Videoausgabe ist für schnelle Überprüfungen.

9. Vorschau-Leiter

1. Ein Standbild bei einem repräsentativen Frame.
2. Keyframes: erster, Enthüllung, Höhepunkt, jeder Übergang, letzter.
3. Segment mit niedrigen Samples und niedriger Auflösung, das die schwierigste Bewegung enthält.
4. Vollständige Vorschau bei reduzierter Skalierung, echte FPS.
5. Final erst, wenn 1–4 korrekt aussehen.

Überprüfe mit einem Kontaktbogen plus gezielten Frames:

ffmpeg -i preview.mp4 -vf "fps=2,scale=320:-1,tile=4x4" -frames:v 1 previews/contact.jpg

Achte auf Flackern, Z-Fighting, Popping, Überschneidungen, Texture Swimming, Kamera-Clipping, Belichtungsverschiebungen und unleserliche Schrift.

10. Text, mehrsprachige Arbeit und Logos

• Konvertiere Text erst nach Bestätigung des Textes und der Schriftlizenz in ein Mesh; behalte ein bearbeitbares Textobjekt in der Quelle.
• Überprüfe die Glyphenabdeckung vor der Animation. Für Persisch/Arabisch überprüfe Formgebung, Joining, RTL-Reihenfolge, Diakritika und gemischte Schriftzeichen im gerenderten Frame — eine korrekte Zeichenkette kann trotzdem falsch gerendert werden, wenn der Textpfad nicht formt.
• Für Marken-/Logo-Arbeit: Verwende wenn möglich Vektorquellen; bei Raster, verfolge nach und überprüfe die Kanten bei 4K.
• Fase/Gewichte die Schrift, damit sie das Licht übersteht; vermeide reines Schwarz-auf-Schwarz oder reines Weiß-auf-Weiß-Kanten.

11. Leistung und Zuverlässigkeit

• Instanziiere, dupliziere nicht. Verringere die Unterteilung, bevor du Samples reduzierst.
• Beschränke transparente Ebenen und Volumetrics; sie sind die üblichen Renderzeit-Killer.
• Cache Simulationen und bestätige, dass der Cache im Projekt oder dokumentiert ist.
• Render in Frame-Chargen für empfindliche Jobs; überprüfe Frame-Anzahlen und fange fehlende Frames vor dem Encode.
• Überwache RAM/VRAM/Festplatte. 4K-EXR-Sequenzen sind groß; überprüfe den freien Speicherplatz vor einem langen Render.
• Sichere eine .blend-Datei, bevor du sie mit einer neueren Hauptversion von Blender öffnest/speicherst — neuere Dateien öffnen sich möglicherweise nicht in älteren Builds.

12. Minimales funktionsfähiges Beispiel

# build.py — ausführen mit:
# blender --background --factory-startup --python-exit-code 1 --python build.py
import bpy, bmesh, math, os

scene = bpy.context.scene
scene.frame_start, scene.frame_end = 1, 120
scene.render.fps = 30
scene.render.resolution_x, scene.render.resolution_y = 1920, 1080
scene.render.engine = 'BLENDER_EEVEE_NEXT'
scene.render.filepath = "//renders/frame_"

# eigene Collection bereinigen
col = bpy.data.collections.get("MS_Main") or bpy.data.collections.new("MS_Main")
if col.name not in scene.collection.children:
    scene.collection.children.link(col)

def add_sphere(name, loc, radius, mat):
    """Daten-API-Kugel: keine Operatoren, keine Kontextabhängigkeit."""
    mesh = bpy.data.meshes.new(name)
    bm = bmesh.new()
    bmesh.ops.create_uvsphere(bm, u_segments=32, v_segments=16, radius=radius)
    bm.to_mesh(mesh)
    bm.free()
    obj = bpy.data.objects.new(name, mesh)
    obj.location = loc
    col.objects.link(obj)
    obj.data.materials.append(mat)
    return obj

mat = bpy.data.materials.new("MS_Emission")
mat.use_nodes = True
bsdf = mat.node_tree.nodes["Principled BSDF"]
bsdf.inputs["Base Color"].default_value = (0.05, 0.6, 0.55, 1)
bsdf.inputs["Emission Color"].default_value = (0.1, 0.9, 0.8, 1)
bsdf.inputs["Emission Strength"].default_value = 3.0
bsdf.inputs["Roughness"].default_value = 0.3

core = add_sphere("MS_Core", (0, 0, 1), 0.8, mat)
core.keyframe_insert("scale", frame=1)
core.scale = (1.15, 1.15, 1.15)
core.keyframe_insert("scale", frame=40)
core.scale = (1.0, 1.0, 1.0)
core.keyframe_insert("scale", frame=90)

# Kamera
cam_data = bpy.data.cameras.new("MS_Cam")
cam = bpy.data.objects.new("MS_Cam", cam_data)
col.objects.link(cam)
scene.camera = cam
cam.location = (6, -6, 3)
cam.rotation_euler = (math.radians(75), 0, math.radians(45))

# speichern
os.makedirs(bpy.path.abspath("//renders"), exist_ok=True)
bpy.ops.wm.save_as_mainfile(filepath=bpy.path.abspath("//scene.blend"))
print("BUILD OK", len(col.objects), "objects")

Mehr in references/BLENDER-RECIPES.md: Orbit-Rigs, Easing, Geometry Nodes Scatter, Partikel, Text, Alpha-Pässe, Render-Farm-Skripte und Encode-Befehle.

13. Blender MCP (optionale Bequemlichkeit)

Skripte im Hintergrundmodus sind der Produktionspfad: reproduzierbar, diffbar, debuggbar, CI-freundlich. MCP ist nützlich für interaktive Szeneninspektion und Live-Tweaks in einer bereits geöffneten Sitzung. Es handelt sich um eine Drittanbieter-Integration, nicht um eine Blender-Komponente.

Wenn der Benutzer es wünscht: Überprüfe das Repository und die Lizenz, prüfe die Kompatibilität mit der installierten Blender-Version, verstehe, dass es beliebige Python-Ausführung in Blender gewährt, binde es an Loopback und setze es niemals einem unsicheren Netzwerk aus. Der aktuelle Paketname ist mcp-for-blender; folge den aktuellen Setup-Anweisungen des Repositories anstelle von alten blender-mcp-Schnipseln. Mache es nicht zu einer Abhängigkeit eines ausgelieferten Projekts.

14. Liefergegenstände

Ein Blender-Job ist abgeschlossen, wenn du Folgendes hast:

1. output/final.mp4 (oder das angeforderte Format), validiert mit ffprobe.
2. blender/scripts/*.py — die Build-Quelle.
3. scene.blend — das bearbeitbare Projekt, Assets eingepackt oder relativ.
4. renders/ Bildsequenz (oder dokumentierter Master) aufgehoben, wenn nützlich.
5. README.md — genaue Blender-Version, Installation, Build, Vorschau, finales Rendering und Revisionsbefehle.
6. Ein kurzer Report: Werkzeuge, Auflösung, FPS, Dauer, Frame-Anzahl, was visuell überprüft wurde.

Liefere niemals nur das MP4, wenn der Benutzer nach einer Animation gefragt hat, die er möglicherweise ändern möchte.