blender-scene-rendering

Blender 场景与渲染专家

概述

此技能为 Blender 5.x 场景设置、渲染配置、输出管线、文件导入/导出、链接/追加、视口设置以及项目级 Python 自动化提供专家指导。参考文件包含完整的设置目录和 Python API 用法模式。

MCP 优先方式

更改渲染设置、导入文件、配置色彩管理，以及直接在正在运行的 Blender 会话中启动渲染时，优先使用官方 Blender MCP Server（Blender Lab，Blender 5.1+）。只有在 MCP 服务未连接时，才回退到生成 Python 脚本。

**检测：**在会话开始时，查找名称与 execute_blender_code、get_objects_summary 或 search_api_docs 匹配的工具——这些属于官方 blender-mcp 服务。如果其中任意工具存在，即表示 MCP 可用。

此技能使用的工具：

• execute_blender_code — 在实时会话中运行 bpy Python（主要操作）
• get_objects_summary、get_object_detail_summary — 修改前检查场景状态
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — 清点文件内容
• search_api_docs、get_python_api_docs、search_manual_docs — 调用前确认正确的 API/操作符名称
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — 验证视觉效果
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — 操作 UI，让更改可见
• render_thumbnail_to_path、render_viewport_to_path — 获取快速视觉反馈

**工作流：**使用 get_* / search_* 工具检查 → 通过 execute_blender_code 修改 → 使用截图或摘要工具验证。代码块应保持简短且可幂等执行，以便轻松定位故障。

设置说明：参见 docs/blender-mcp-setup.md。

任务决策树

• “设置渲染 / 配置 Cycles 或 EEVEE” -> 参见渲染引擎配置
• “更改分辨率 / 输出格式” -> 参见输出设置
• “调整采样 / 降噪” -> 参见采样与降噪
• “色彩管理 / Filmic / AgX” -> 参见色彩管理
• “设置世界 / 环境 / HDRI” -> 参见世界与环境
• “导入 FBX / glTF / OBJ / USD” -> 参见导入/导出
• “从其他 .blend 文件链接或追加” -> 参见链接与追加
• “配置单位 / 帧范围 / FPS” -> 参见场景设置
• “视图层 / 渲染通道” -> 参见视图层
• “视口着色 / 叠加层” -> 参见视口配置
• “批量渲染 / 自动化输出” -> 参见批量渲染
• “渲染效果不对” -> 参见调试部分

渲染引擎配置

切换到 Cycles

import bpy

scene = bpy.context.scene
scene.render.engine = 'CYCLES'

# Device: CPU or GPU
cycles = scene.cycles
cycles.device = 'GPU'

# GPU compute device type
prefs = bpy.context.preferences.addons['cycles'].preferences
prefs.compute_device_type = 'CUDA'  # CUDA, OPTIX, HIP, METAL, ONEAPI
prefs.get_devices()  # Refresh device list
for device in prefs.devices:
    device.use = True  # Enable all available devices

切换到 EEVEE

import bpy

scene = bpy.context.scene
scene.render.engine = 'BLENDER_EEVEE'  # Blender 4.x+/5.x EEVEE

eevee = scene.eevee

# Shadows
eevee.shadow_ray_count = 1
eevee.shadow_step_count = 6

# Ray tracing
eevee.use_raytracing = True
eevee.ray_tracing_method = 'SCREEN'  # SCREEN or FULL

# Emission transparency (for emissive materials that need alpha blending)
# Set per-material: material.surface_render_method = 'BLENDED'

# Ambient Occlusion (baked into lighting in EEVEE)

Workbench（实体/预览）

import bpy
bpy.context.scene.render.engine = 'BLENDER_WORKBENCH'

输出设置

分辨率与帧范围

import bpy

render = bpy.context.scene.render

# Resolution
render.resolution_x = 1920
render.resolution_y = 1080
render.resolution_percentage = 100

# Frame range
scene = bpy.context.scene
scene.frame_start = 1
scene.frame_end = 250
scene.frame_step = 1
scene.frame_current = 1

# FPS
render.fps = 24
render.fps_base = 1.0  # Actual FPS = fps / fps_base

输出格式

import bpy

render = bpy.context.scene.render
render.filepath = "//output/render_"  # // = relative to .blend file

# Image format
# Image format
render.image_settings.file_format = 'PNG'  # PNG, JPEG, OPEN_EXR, OPEN_EXR_MULTILAYER, TIFF, BMP, HDR, FFMPEG, AVIF (5.1)
render.image_settings.color_mode = 'RGBA'  # BW, RGB, RGBA
render.image_settings.color_depth = '16'   # 8, 16 (PNG/TIFF), 16/32 (EXR)
render.image_settings.compression = 15     # PNG compression 0-100

# EXR settings
render.image_settings.file_format = 'OPEN_EXR'
render.image_settings.exr_codec = 'DWAA'  # NONE, PXR24, ZIP, PIZ, RLE, ZIPS, DWAA, DWAB
render.image_settings.color_depth = '32'

# Video (FFmpeg)
render.image_settings.file_format = 'FFMPEG'
render.ffmpeg.format = 'MPEG4'        # MPEG4, MKV, WEBM, AVI, QUICKTIME
render.ffmpeg.codec = 'H264'          # H264, MPEG4, WEBM, PNG, HUFFYUV, DNXHD, FFV1
render.ffmpeg.constant_rate_factor = 'MEDIUM'  # NONE, LOSSLESS, PERC_LOSSLESS, HIGH, MEDIUM, LOW, LOWEST
render.ffmpeg.audio_codec = 'AAC'     # NONE, AAC, AC3, FLAC, MP2, MP3, OPUS, PCM, VORBIS

OpenEXR HTJ2K（5.1 新增）

1. 新的 EXR 编解码器：render.image_settings.exr_codec = 'HTJ2K'
2. 为 EXR 文件提供高吞吐量 JPEG 2000 压缩
3. 对于多层 EXR 输出，压缩率优于 DWAA/DWAB

视频自定义 CRF（5.1）

1. FFmpeg 的 constant_rate_factor 现在支持整数值，可实现更精细的控制
2. 示例：render.ffmpeg.constant_rate_factor = 'HIGH'，或直接设置数值 CRF

AVIF 格式（5.1 新增）

render.image_settings.file_format = 'AVIF' render.image_settings.avif_compression = 50 # 质量 0-100

采样与降噪

Cycles 采样

import bpy

cycles = bpy.context.scene.cycles

# Render samples
cycles.samples = 256
cycles.use_adaptive_sampling = True
cycles.adaptive_threshold = 0.01    # Lower = higher quality
cycles.adaptive_min_samples = 64

# Viewport samples
cycles.preview_samples = 32
cycles.use_preview_adaptive_sampling = True

# Time limit (0 = disabled)
cycles.time_limit = 0.0

# Seed
cycles.seed = 0
cycles.use_animated_seed = True  # Different seed per frame

# Light paths
cycles.max_bounces = 12
cycles.diffuse_bounces = 4
cycles.glossy_bounces = 4
cycles.transmission_bounces = 12
cycles.volume_bounces = 0
cycles.transparent_max_bounces = 8

# Caustics
cycles.caustics_reflective = False
cycles.caustics_refractive = False

# Clamping (reduce fireflies)
cycles.sample_clamp_direct = 0.0    # 0 = disabled
cycles.sample_clamp_indirect = 10.0

降噪

import bpy

scene = bpy.context.scene
cycles = scene.cycles

# Render denoising
scene.cycles.use_denoising = True
scene.cycles.denoiser = 'OPENIMAGEDENOISE'  # OPENIMAGEDENOISE or OPTIX
scene.cycles.denoising_input_passes = 'RGB_ALBEDO_NORMAL'  # RGB, RGB_ALBEDO, RGB_ALBEDO_NORMAL
scene.cycles.denoising_prefilter = 'ACCURATE'  # NONE, FAST, ACCURATE

# Viewport denoising
scene.cycles.use_preview_denoising = True
scene.cycles.preview_denoiser = 'OPENIMAGEDENOISE'
scene.cycles.preview_denoising_start_sample = 1

色彩管理

配置色彩管理

import bpy

cm = bpy.context.scene.view_settings
ds = bpy.context.scene.display_settings

# Display device
ds.display_device = 'sRGB'  # sRGB, None

# View transform
cm.view_transform = 'AgX'       # Standard, Filmic, AgX, Raw, False Color
cm.look = 'None'                 # None, AgX - Punchy, AgX - Golden, etc.

# Exposure and gamma
cm.exposure = 0.0
cm.gamma = 1.0

# Sequencer color space
bpy.context.scene.sequencer_colorspace_settings.name = 'sRGB'

常见视图变换：

变换	用途
AgX	Blender 4.0+/5.x 的默认选项，动态范围宽
Filmic	旧版默认选项，适用于照片级真实感场景
Standard	直接使用 sRGB（UI 元素、非照片级真实感场景）
Raw	不进行变换（数据传递、遮罩）

世界与环境

HDRI 环境

import bpy

world = bpy.context.scene.world
if world is None:
    world = bpy.data.worlds.new("World")
    bpy.context.scene.world = world

world.use_nodes = True
nodes = world.node_tree.nodes
links = world.node_tree.links
nodes.clear()

# Background + Environment Texture
bg = nodes.new('ShaderNodeBackground')
env_tex = nodes.new('ShaderNodeTexEnvironment')
env_tex.image = bpy.data.images.load("//hdri/studio.exr")
mapping = nodes.new('ShaderNodeMapping')
tex_coord = nodes.new('ShaderNodeTexCoord')
output = nodes.new('ShaderNodeOutputWorld')

links.new(tex_coord.outputs['Generated'], mapping.inputs['Vector'])
links.new(mapping.outputs['Vector'], env_tex.inputs['Vector'])
links.new(env_tex.outputs['Color'], bg.inputs['Color'])
links.new(bg.outputs['Background'], output.inputs['Surface'])

bg.inputs['Strength'].default_value = 1.0

纯色世界

import bpy

world = bpy.context.scene.world
world.use_nodes = True
nodes = world.node_tree.nodes
bg = nodes.get('Background')
bg.inputs['Color'].default_value = (0.05, 0.05, 0.05, 1.0)
bg.inputs['Strength'].default_value = 1.0

导入/导出

常见导入操作

import bpy

# FBX
bpy.ops.import_scene.fbx(filepath="/path/to/model.fbx")

# glTF / GLB
bpy.ops.import_scene.gltf(filepath="/path/to/model.glb")

# OBJ
bpy.ops.wm.obj_import(filepath="/path/to/model.obj")

# USD
bpy.ops.wm.usd_import(filepath="/path/to/scene.usdc")

# Alembic
bpy.ops.wm.alembic_import(filepath="/path/to/cache.abc")

# STL
bpy.ops.wm.stl_import(filepath="/path/to/model.stl")

# SVG
bpy.ops.import_curve.svg(filepath="/path/to/graphic.svg")

常见导出操作

import bpy

# FBX
bpy.ops.export_scene.fbx(
    filepath="/path/to/export.fbx",
    use_selection=True,          # Export selected only
    apply_scale_options='FBX_SCALE_ALL',
    axis_forward='-Z',
    axis_up='Y',
    use_mesh_modifiers=True,
    mesh_smooth_type='FACE',
    add_leaf_bones=False,
    bake_anim=True,
)

# glTF / GLB
bpy.ops.export_scene.gltf(
    filepath="/path/to/export.glb",
    export_format='GLB',         # GLB (binary), GLTF_SEPARATE, GLTF_EMBEDDED
    use_selection=True,
    export_apply=True,           # Apply modifiers
    export_animations=True,
    export_draco_mesh_compression_enable=False,
)

# OBJ
bpy.ops.wm.obj_export(
    filepath="/path/to/export.obj",
    export_selected_objects=True,
    apply_modifiers=True,
    export_uv=True,
    export_normals=True,
    export_materials=True,
)

# USD
bpy.ops.wm.usd_export(
    filepath="/path/to/export.usdc",
    selected_objects_only=True,
    export_animation=True,
    export_hair=True,
)

# Alembic
bpy.ops.wm.alembic_export(
    filepath="/path/to/export.abc",
    selected=True,
    start=1,
    end=250,
)

# STL
bpy.ops.wm.stl_export(
    filepath="/path/to/export.stl",
    export_selected_objects=True,
    apply_modifiers=True,
)

链接与追加

追加（复制到当前文件）

import bpy

blend_path = "/path/to/library.blend"

# Append a single object
with bpy.data.libraries.load(blend_path) as (data_from, data_to):
    data_to.objects = ["ObjectName"]

# Link appended objects to active collection
for obj in data_to.objects:
    if obj is not None:
        bpy.context.collection.objects.link(obj)

# Append specific data types
with bpy.data.libraries.load(blend_path) as (data_from, data_to):
    data_to.materials = ["MaterialName"]
    data_to.node_groups = ["NodeGroupName"]
    data_to.collections = ["CollectionName"]
    data_to.worlds = ["WorldName"]

链接（引用并保持连接）

import bpy

blend_path = "/path/to/library.blend"

with bpy.data.libraries.load(blend_path, link=True) as (data_from, data_to):
    data_to.collections = ["CollectionName"]

# Link collection instance to scene
for coll in data_to.collections:
    if coll is not None:
        bpy.context.collection.children.link(coll)

# Make library override (editable linked data)
# Select linked object first
bpy.ops.object.make_override_library()

重新加载/重新定位库

import bpy

for lib in bpy.data.libraries:
    lib.reload()  # Reload from disk

# Relocate a library to a new path
# lib.filepath = "/new/path/to/library.blend"
# lib.reload()

场景设置

单位

import bpy

unit = bpy.context.scene.unit_settings
unit.system = 'METRIC'          # NONE, METRIC, IMPERIAL
unit.scale_length = 1.0         # 1.0 = 1 Blender unit = 1 meter
unit.length_unit = 'METERS'     # ADAPTIVE, KILOMETERS, METERS, CENTIMETERS, MILLIMETERS, MICROMETERS
unit.use_separate = True        # Use separate units (e.g., 1m 50cm)
unit.temperature_unit = 'CELSIUS'

多个场景

import bpy

# Create new scene
new_scene = bpy.data.scenes.new("MyScene")

# Copy scene (Full Copy = independent copy of all data)
bpy.ops.scene.new(type='FULL_COPY')  # NEW, EMPTY, LINK_COPY, FULL_COPY

# Switch active scene
bpy.context.window.scene = bpy.data.scenes["MyScene"]

# Delete scene
bpy.data.scenes.remove(bpy.data.scenes["MyScene"])

视图层

配置视图层

import bpy

scene = bpy.context.scene

# Create view layer
vl = scene.view_layers.new("MyLayer")

# Enable/disable collections per layer
vl.layer_collection.children["CollectionName"].exclude = True

# Render passes
vl.use_pass_combined = True
vl.use_pass_z = True
vl.use_pass_normal = True
vl.use_pass_diffuse_color = True
vl.use_pass_glossy_color = True
vl.use_pass_emit = True
vl.use_pass_ambient_occlusion = True
vl.use_pass_shadow = True
vl.use_pass_mist = True

# Cryptomatte
vl.use_pass_cryptomatte_object = True
vl.use_pass_cryptomatte_material = True
vl.use_pass_cryptomatte_asset = True

视口配置

视口着色

import bpy

# Access 3D viewport shading
for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                shading = space.shading

                # Shading type: WIREFRAME, SOLID, MATERIAL, RENDERED
                shading.type = 'MATERIAL'

                # Solid mode options
                shading.light = 'STUDIO'       # STUDIO, MATCAP, FLAT
                shading.color_type = 'MATERIAL' # MATERIAL, SINGLE, OBJECT, RANDOM, VERTEX, TEXTURE

                # Rendered mode options
                shading.use_scene_lights_render = True
                shading.use_scene_world_render = True

                break

叠加层

import bpy

for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                overlay = space.overlay

                overlay.show_overlays = True
                overlay.show_floor = True
                overlay.show_axis_x = True
                overlay.show_axis_y = True
                overlay.show_wireframes = False
                overlay.show_face_orientation = False
                overlay.show_stats = True

                break

批量渲染

渲染所有摄像机

import bpy

scene = bpy.context.scene
original_camera = scene.camera

for obj in bpy.data.objects:
    if obj.type == 'CAMERA':
        scene.camera = obj
        scene.render.filepath = f"//output/{obj.name}_"
        bpy.ops.render.render(write_still=True)

scene.camera = original_camera

渲染多个场景

import bpy

for scene in bpy.data.scenes:
    scene.render.filepath = f"//output/{scene.name}_"
    bpy.ops.render.render(write_still=True, scene=scene.name)

渲染动画

import bpy
bpy.ops.render.render(animation=True)  # Renders full frame range

调试

渲染问题

问题	原因	解决方法
渲染结果为黑色	没有灯光，摄像机朝向错误	添加灯光，检查摄像机方向和裁剪范围
渲染结果有噪点	采样数较低	增大 cycles.samples，启用降噪
出现亮点（高亮像素）	焦散或无界光源	设置 sample_clamp_indirect = 10，禁用焦散
颜色看起来褪色	色彩管理设置错误	将视图变换设为 AgX 或 Filmic
颜色过于饱和/对比度过高	视图变换不匹配	尝试将 AgX 与 None 外观搭配使用
导出时缺少纹理	纹理未打包或路径损坏	导出前运行 bpy.ops.file.pack_all()，或使用 export_format='GLB'
导入比例错误	应用之间的单位不匹配	调整 scale_length 或导入比例选项
链接的对象未更新	库未重新加载	bpy.data.libraries["lib"].reload()
视口运行缓慢	渲染模式下对象过多	切换到实体模式，降低细分级别，使用集合可见性
缺少渲染通道	未在视图层上启用通道	在视图层属性中启用通道
EEVEE 的效果与 Cycles 不同	两种引擎的光照效果不同	启用光线追踪的 EEVEE Next 可缩小差距

参考文件

• references/python_api.md — 场景/渲染/I/O 操作的完整 Python API 模式
• references/settings_reference.md — 所有渲染引擎设置、输出格式、色彩管理选项、导入/导出格式选项

Blender 5.1 变更

OpenColorIO 2.5

1. Blender 5.1 随附 OpenColorIO 2.5
2. 改进了色彩空间处理和显示变换
3. 提升了 AgX 和其他视图变换的准确性

Cycles 性能

1. 复杂场景的渲染速度显著提升
2. 改进了自适应采样的收敛效果

EEVEE 性能

1. 降低屏幕空间效果的内存占用
2. 加快光线追踪计算

世界节点中的光线路径

1. 光线路径节点现在可用于世界节点树（不再仅限于材质）
2. 支持在环境材质中按灯光类型应用效果