---

name: create-3d-scene description: > Eine Blender-Szene programmatisch ueber Python (bpy) mit Objekten, Materialien, Beleuchtung, Kamera und Umgebungskonfiguration einrichten. Verwenden beim Erstellen reproduzierbarer 3D-Visualisierungsszenen, beim Automatisieren von Produkt- oder Architekturrendering-Setup, beim programmatischen Generieren mehrerer Szenenvariationen, beim Erstellen von Vorlagenszenen fuer Stapel- Rendering-Workflows oder beim Integrieren von 3D-Visualisierung in Datenpipelines. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: blender complexity: intermediate language: Python tags: blender, bpy, 3d, scene-setup, materials, lighting, camera locale: de source_locale: en source_commit: 75ded7a1 fence_basis_commit: 75ded7a1 translator: claude translation_date: "2026-03-17"

3D-Szene erstellen

Eine vollstaendige Blender-Szene programmatisch mit der Python-API (bpy) einrichten. Szenenhierarchie konfigurieren, Mesh-Objekte hinzufuegen, PBR-Materialien mit node-basierten Shadern erstellen, Beleuchtung und Kameras positionieren und Umgebungs-/Welteinstellungen einrichten.

Wann verwenden

• Reproduzierbare 3D-Visualisierungsszenen von Grund auf erstellen
• Produktvisualisierung oder Architekturrendering-Setup automatisieren
• Mehrere Szenenvariationen programmatisch generieren
• Vorlagenszenen fuer Stapel-Rendering-Workflows erstellen
• Szenenlayouts vor manueller Verfeinerung prototypisieren
• 3D-Visualisierung in Datenpipelines oder Berichtssysteme integrieren

Eingaben

Eingabe	Typ	Beschreibung	Beispiel
Szenenspezifikationen	Konfiguration	Objekte, Materialien, Beleuchtungsanforderungen	Produktabmessungen, Materialfarben, Beleuchtungssetup
Ausgabeanforderungen	Parameter	Aufloesung, Render-Engine, Qualitaetseinstellungen	1920x1080, Cycles, 128 Samples
Asset-Pfade	Dateipfade	Externe Modelle, Texturen, HDRIs	/path/to/hdri.exr, product_model.obj
Kameraeinstellungen	Parameter	Position, Rotation, Brennweite, DOF	location=(7,-7,5), lens=50mm
Umgebung	Konfiguration	Welt-Shader, Hintergrund, Umgebungseinstellungen	HDRI-Beleuchtung, Volltonfarbe, Verlauf

Vorgehensweise

1. Skriptstruktur einrichten

Ein Python-Skript mit korrekten Imports und Struktur erstellen:

#!/usr/bin/env python3
"""
Scene setup script for Blender.
Usage: blender --background --python setup_scene.py
"""

import bpy
import math
import os
from pathlib import Path

def clear_scene():
    """Remove all objects from the scene."""
    bpy.ops.object.select_all(action='SELECT')
    bpy.ops.object.delete(use_global=False)

    # Clear orphaned data
    for block in bpy.data.meshes:
        if block.users == 0:
            bpy.data.meshes.remove(block)

    for block in bpy.data.materials:
        if block.users == 0:
            bpy.data.materials.remove(block)

def main():
    clear_scene()
    # Scene setup steps follow

if __name__ == "__main__":
    main()

Erwartet: Skriptstruktur mit clear_scene()- und main()-Funktionen Bei Fehler: Python-Syntax ueberpruefen, bpy-Import in der Blender-Python-Umgebung testen

2. Mesh-Objekte hinzufuegen

Primitive oder importierte Mesh-Objekte erstellen:

def add_objects():
    """Add mesh objects to scene."""
    # Add cube
    bpy.ops.mesh.primitive_cube_add(
        size=2.0,
        location=(0, 0, 1)
    )
    cube = bpy.context.active_object
    cube.name = "Product_Base"

    # Add sphere
    bpy.ops.mesh.primitive_uv_sphere_add(
        radius=1.0,
        segments=32,
        ring_count=16,
        location=(3, 0, 1)
    )
    sphere = bpy.context.active_object
    sphere.name = "Detail_Sphere"

    # Import external model (optional)
    # bpy.ops.import_scene.obj(filepath="model.obj")

    return cube, sphere

Erwartet: Objekte erscheinen in der Szene mit korrekten Namen und Positionen Bei Fehler: Operator-Syntax pruefen, Koordinaten verifizieren, sicherstellen, dass keine Namenskonflikte bestehen

3. Materialien mit Node-basierten Shadern erstellen

PBR-Materialien mit Shader-Nodes einrichten:

def create_material(name, base_color, metallic=0.0, roughness=0.5):
    """Create a PBR material with node setup."""
    # Create material
    mat = bpy.data.materials.new(name=name)
    mat.use_nodes = True
    nodes = mat.node_tree.nodes
    links = mat.node_tree.links

    # Clear default nodes
    nodes.clear()

    # Add Principled BSDF
    node_bsdf = nodes.new(type='ShaderNodeBsdfPrincipled')
    node_bsdf.location = (0, 0)
    node_bsdf.inputs['Base Color'].default_value = base_color + (1.0,)  # Add alpha
    node_bsdf.inputs['Metallic'].default_value = metallic
    node_bsdf.inputs['Roughness'].default_value = roughness

    # Add Material Output
    node_output = nodes.new(type='ShaderNodeOutputMaterial')
    node_output.location = (300, 0)

    # Link nodes
    links.new(node_bsdf.outputs['BSDF'], node_output.inputs['Surface'])

    return mat

def apply_materials(cube, sphere):
    """Apply materials to objects."""
    # Create materials
    mat_red = create_material("RedPlastic", (0.8, 0.1, 0.1), metallic=0.0, roughness=0.4)
    mat_metal = create_material("Metal", (0.8, 0.8, 0.8), metallic=1.0, roughness=0.2)

    # Assign to objects
    if cube.data.materials:
        cube.data.materials[0] = mat_red
    else:
        cube.data.materials.append(mat_red)

    if sphere.data.materials:
        sphere.data.materials[0] = mat_metal
    else:
        sphere.data.materials.append(mat_metal)

Erwartet: Materialien im Shader-Editor mit korrekten Node-Verbindungen sichtbar Bei Fehler: Node-Typen auf Existenz pruefen, Link-Syntax verifizieren, sicherstellen, dass Farbwerte im Bereich [0,1] liegen

4. Beleuchtung einrichten

Lichter fuer die Szenenbeleuchtung konfigurieren:

def setup_lighting():
    """Add lights to scene."""
    # Sun light
    bpy.ops.object.light_add(
        type='SUN',
        location=(5, 5, 10)
    )
    sun = bpy.context.active_object
    sun.name = "KeyLight"
    sun.data.energy = 3.0
    sun.rotation_euler = (math.radians(45), 0, math.radians(45))

    # Area light (fill light)
    bpy.ops.object.light_add(
        type='AREA',
        location=(-4, -4, 6)
    )
    area = bpy.context.active_object
    area.name = "FillLight"
    area.data.energy = 200.0
    area.data.size = 5.0
    area.rotation_euler = (math.radians(60), 0, math.radians(-135))

    # Point light (rim light)
    bpy.ops.object.light_add(
        type='POINT',
        location=(2, -5, 3)
    )
    point = bpy.context.active_object
    point.name = "RimLight"
    point.data.energy = 500.0

Erwartet: Drei Lichter mit angemessenen Intensitaeten und Positionen Bei Fehler: Energiewerte fuer Render-Engine anpassen (Cycles vs. EEVEE), Rotationsformat pruefen

5. Kamera positionieren

Kamera mit korrektem Bildausschnitt einrichten:

def setup_camera():
    """Add and configure camera."""
    bpy.ops.object.camera_add(
        location=(7, -7, 5)
    )
    camera = bpy.context.active_object
    camera.name = "MainCamera"

    # Point camera at origin
    direction = (0, 0, 1) - camera.location
    rot_quat = direction.to_track_quat('-Z', 'Y')
    camera.rotation_euler = rot_quat.to_euler()

    # Camera settings
    camera.data.lens = 50  # Focal length in mm
    camera.data.dof.use_dof = True
    camera.data.dof.focus_distance = 10.0
    camera.data.dof.aperture_fstop = 2.8

    # Set as active camera
    bpy.context.scene.camera = camera

Erwartet: Kamera mit korrekter Brennweite und DOF-Einstellungen positioniert Bei Fehler: Einfachere Rotationsmethode verwenden, wenn track_to fehlschlaegt, Objektiveinheiten verifizieren

6. Weltumgebung konfigurieren

Welt-Shader und Hintergrund einrichten:

def setup_world():
    """Configure world environment."""
    world = bpy.data.worlds['World']
    world.use_nodes = True
    nodes = world.node_tree.nodes
    links = world.node_tree.links

    # Clear default nodes
    nodes.clear()

    # Add Environment Texture (for HDRI)
    node_env = nodes.new(type='ShaderNodeTexEnvironment')
    node_env.location = (-300, 0)

    # Load HDRI if available
    hdri_path = "/path/to/hdri.exr"
    if os.path.exists(hdri_path):
        node_env.image = bpy.data.images.load(hdri_path)

    # Add Background shader
    node_bg = nodes.new(type='ShaderNodeBackground')
    node_bg.location = (0, 0)
    node_bg.inputs['Strength'].default_value = 1.0

    # Add World Output
    node_output = nodes.new(type='ShaderNodeOutputWorld')
    node_output.location = (300, 0)

    # Link nodes
    links.new(node_env.outputs['Color'], node_bg.inputs['Color'])
    links.new(node_bg.outputs['Background'], node_output.inputs['Surface'])

Erwartet: Welt-Shader mit HDRI oder Volltonhintergrund konfiguriert Bei Fehler: HDRI-Laden ueberspringen, wenn Datei fehlt, Background-Node allein mit Farbe verwenden

7. Render-Einstellungen konfigurieren

Grundlegende Renderparameter festlegen:

def setup_render_settings():
    """Configure render settings."""
    scene = bpy.context.scene

    # Render engine
    scene.render.engine = 'CYCLES'  # or 'BLENDER_EEVEE'
    scene.cycles.samples = 128
    scene.cycles.use_denoising = True

    # Output settings
    scene.render.resolution_x = 1920
    scene.render.resolution_y = 1080
    scene.render.resolution_percentage = 100

    # File format
    scene.render.image_settings.file_format = 'PNG'
    scene.render.image_settings.color_mode = 'RGBA'
    scene.render.image_settings.color_depth = '16'
    scene.render.filepath = "/tmp/render_"

Erwartet: Render-Einstellungen konfiguriert, bereit zum Rendern Bei Fehler: Engine-Namenorthografie pruefen, sicherstellen, dass Aufloesungswerte positive Ganzzahlen sind

8. Szenenhierarchie organisieren

Collections zur Organisation erstellen:

def organize_collections():
    """Organize objects into collections."""
    # Create collections
    col_geometry = bpy.data.collections.new("Geometry")
    col_lights = bpy.data.collections.new("Lights")
    col_cameras = bpy.data.collections.new("Cameras")

    # Link to scene
    bpy.context.scene.collection.children.link(col_geometry)
    bpy.context.scene.collection.children.link(col_lights)
    bpy.context.scene.collection.children.link(col_cameras)

    # Move objects to collections
    for obj in bpy.data.objects:
        # Unlink from main collection
        bpy.context.scene.collection.objects.unlink(obj)

        # Link to appropriate collection
        if obj.type == 'MESH':
            col_geometry.objects.link(obj)
        elif obj.type == 'LIGHT':
            col_lights.objects.link(obj)
        elif obj.type == 'CAMERA':
            col_cameras.objects.link(obj)

Erwartet: Objekte in benannten Collections fuer einfachere Verwaltung organisiert Bei Fehler: Pruefen, ob Collection bereits existiert, bevor sie erstellt wird, verwaiste Objekte behandeln

Validierung

• Skript laeuft ohne Fehler im Blender-Hintergrundmodus
• Alle erwarteten Objekte im Szenen-Outliner vorhanden
• Materialien zeigen korrekte Farben und Eigenschaften im Shader-Editor
• Kamera positioniert mit Objekten im Bildausschnitt
• Beleuchtung bietet ausreichende Ausleuchtung (Testrender)
• Weltumgebung laedt korrekt (HDRI oder Hintergrundfarbe)
• Render-Einstellungen angemessen fuer Ausgabeanforderungen konfiguriert
• Szene logisch in Collections organisiert
• Keine verwaisten Datenbloecke (Materialien, Meshes ohne Benutzer)
• Skript enthaelt clear_scene() fuer Reproduzierbarkeit

Haeufige Stolperfallen

1. Objektbenennungskonflikte: Eindeutige Namen verwenden, vor dem Erstellen auf bestehende Objekte pruefen
2. Falsches Farbformat: RGB-Werte muessen Tupel (r, g, b, a) im Bereich [0,1] sein
3. Fehlender Alpha-Kanal: Beim Setzen von Farben Alpha einschliessen: (r, g, b, 1.0)
4. Node-Verbindungsfehler: Node-Typen auf erwartete Ein-/Ausgaenge vor dem Verlinken verifizieren
5. Kamera nicht aktiv: bpy.context.scene.camera = camera_object muss gesetzt werden
6. Relative vs. absolute Pfade: Absolute Pfade oder Path() fuer plattformuebergreifende Kompatibilitaet verwenden
7. Einheitenverwirrung: Blender verwendet standardmaessig Meter, Kameraobjektiv in Millimetern
8. Rotationsformate: math.radians() fuer Grad-zu-Radiant-Umrechnung verwenden
9. Render-Engine-Unterschiede: EEVEE und Cycles haben unterschiedliche Funktionen und Parameter
10. Speicherlecks: Verwaiste Datenbloecke bereinigen, um Speicheraufbau bei Stapeloperationen zu verhindern

Verwandte Skills

• script-blender-automation — Fortgeschrittene Scripting-Muster fuer prozedurale Modellierung und Stapeloperationen
• render-blender-output — Rendering-Pipeline konfigurieren und Renders ausfuehren
• create-2d-composition — 2D-Grafik-Komposition mit aehnlichen Scripting-Ansaetzen