造三維場景

以 Python API（bpy）程式化立一完整 Blender 場景。配置場景階層、加網格物件、以節點式著色器造 PBR 材質、置光與相機、設環境/世界之設。

適用時機

• 由頭造可重現之三維可視化場景
• 自動化產品視覺化或建築渲染之設
• 以程式生多場景變體
• 為批次渲染流建範本場景
• 手動精修前之場景佈局原型
• 整合三維可視化於資料管線或報告系統

輸入

輸入	類型	描述	範例
場景規格	配置	物件、材質、光之需	產品尺寸、材色、光設
輸出需求	參數	解析度、渲染引擎、品質設	1920x1080、Cycles、128 取樣
資產路	檔路	外部模型、貼圖、HDRI	/path/to/hdri.exr、product_model.obj
相機設	參數	位、旋、焦距、景深	location=(7,-7,5)、lens=50mm
環境	配置	世界著色器、背景、環境光設	HDRI 光、純色、漸層

步驟

1. 立腳本結構

造一 Python 腳本，含當之匯入與結構：

#!/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()

預期： 腳本結構含 clear_scene() 與 main() 函式 失敗時： 察 Python 語法，驗 bpy 匯入於 Blender Python 環境中可行

2. 加網格物件

造原始或匯入之網格物件：

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

預期： 物件顯於場景，名與位皆合 失敗時： 察運算子語法，驗座標，確保無命名衝突

3. 以節點式著色器造材質

以著色器節點立 PBR 材質：

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)

預期： 材質於著色器編輯器中顯，節點連接無誤 失敗時： 察節點型存否，驗連結語法，確保色值於 [0,1] 區間

4. 立光

配光以照場景：

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

預期： 三光，強度與位皆當 失敗時： 依渲染引擎（Cycles 與 EEVEE 之別）調能量值，察旋轉格式

5. 置相機

立相機，框取得宜：

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

預期： 相機已置，焦距與景深設皆當 失敗時： track_to 敗則用簡旋轉法，驗鏡頭單位

6. 配世界環境

立世界著色器與背景：

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'])

預期： 世界著色器已配 HDRI 或純背景 失敗時： 檔缺則跳 HDRI 載入，單用 Background 節點加色

7. 配渲染設

設基本渲染參數：

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_"

預期： 渲染設已配，可備渲染 失敗時： 察引擎名拼法，驗解析度為正整數

8. 組織場景階層

造集合以便組織：

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)

預期： 物件組織於名集合中，便於管理 失敗時： 造前察集合已存否，處孤立物件

驗證清單

• 腳本於 Blender 背景模式無誤運行
• 所期物件皆顯於場景大綱
• 材質於著色器編輯器中顯正色與性
• 相機已置，物件於框中
• 光給充足之照（測渲染）
• 世界環境載入無誤（HDRI 或背景色）
• 渲染設合輸出需求
• 場景於集合中組織得當
• 無孤立資料塊（無使用者之材質、網格）
• 腳本含 clear_scene() 以便重現

常見陷阱

1. 物件命名衝突：用唯一名，造前察既存物件
2. 色格式誤：RGB 值須為元組 (r, g, b, a) 於 [0,1] 區間
3. 缺 alpha 通道：設色時含 alpha：(r, g, b, 1.0)
4. 節點連接誤：連結前驗節點型有所期之輸入/輸出
5. 相機未激活：須設 bpy.context.scene.camera = camera_object
6. 相對與絕對路之別：用絕對路或 Path() 以跨平台相容
7. 單位之惑：Blender 預設以公尺為單位，相機鏡頭以毫米
8. 旋轉格式：用 math.radians() 行度-弧度之轉換
9. 渲染引擎之別：EEVEE 與 Cycles 有異之功能與參數
10. 記憶體洩漏：清孤立資料塊以防批次操作中之記憶體累積

相關技能

• script-blender-automation：程序化建模與批次操作之進階腳本模式
• render-blender-output：配渲染管線並執渲染
• create-2d-composition：以類似腳本法行二維圖形構圖