blender-rendering

Blender 渲染

高效渲染。默认设置不适合生产环境；以下方案针对常见场景进行了调整。

渲染引擎选择流程

Need photoreal? Caustics? Accurate SSS? Glass-rich?
├── YES → Cycles (path tracer)
└── NO  → Need speed? Stylized look? Animation iteration?
          ├── YES → EEVEE
          └── NO  → Cycles (default fallback for photoreal)

快速规则：

• 静帧、建筑可视化、产品、主视觉镜头 → Cycles
• 动画预览、动态图形、风格化内容 → EEVEE

参考效果交接

如果目标是匹配原图／参考图，而不是制作普遍看来更吸引人的渲染，请链式加载 reference-look-calibration。它负责测量色相／饱和度／明度、对象范围、辉光／光晕颜色，以及前后效果指标。然后，本技能应在校准后的目标范围内应用所需的材质／灯光／渲染更改。

配方

配方 1 — Cycles 生产预设（256 个采样 + 降噪）

import bpy

scene = bpy.context.scene
scene.render.engine = 'CYCLES'
scene.cycles.device = 'GPU'

# Sampling
scene.cycles.samples = 256
scene.cycles.use_adaptive_sampling = True
scene.cycles.adaptive_threshold = 0.01
scene.cycles.adaptive_min_samples = 32

# Denoising (recommended)
scene.cycles.use_denoising = True
scene.cycles.denoiser = 'OPENIMAGEDENOISE'   # safe default; switch to 'OPTIX' on NVIDIA RTX

# Light paths (defaults are reasonable; bump transmission for glass-rich scenes)
scene.cycles.max_bounces = 12
scene.cycles.transmission_bounces = 12

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

print('render:cycles_production_preset')

配方 2 — Cycles 草稿预设（更快迭代）

import bpy

scene = bpy.context.scene
scene.render.engine = 'CYCLES'
scene.cycles.device = 'GPU'
scene.cycles.samples = 64
scene.cycles.use_adaptive_sampling = True
scene.cycles.adaptive_threshold = 0.05
scene.cycles.use_denoising = True
scene.render.resolution_percentage = 50    # half res for tests
print('render:cycles_draft')

配方 3 — EEVEE 预设

import bpy

scene = bpy.context.scene

# Engine name changed across versions:
#   Blender ≤ 4.1:        'BLENDER_EEVEE'
#   Blender 4.2 only:     'BLENDER_EEVEE_NEXT' (transitional; replaced)
#   Blender ≥ 5.0:        'BLENDER_EEVEE' (the new EEVEE replaced the old)
# Try the new name first; fall back if it doesn't exist on this Blender.
try:
    scene.render.engine = 'BLENDER_EEVEE_NEXT'
except (TypeError, ValueError):
    scene.render.engine = 'BLENDER_EEVEE'

# EEVEE settings (eevee namespace exists in 4.x and 5.x)
if hasattr(scene, 'eevee'):
    scene.eevee.taa_render_samples = 64
    scene.eevee.taa_samples = 16
scene.eevee.use_gtao = True            # screen-space AO
scene.eevee.gtao_distance = 0.2
scene.eevee.use_bloom = True            # glow
scene.eevee.use_ssr = True              # screen-space reflections
scene.eevee.use_ssr_refraction = True   # for glass
scene.eevee.use_volumetric_lights = True
scene.render.resolution_x = 1920
scene.render.resolution_y = 1080
print('render:eevee_preset')

需要了解的 EEVEE 限制：

• 反射采用屏幕空间方式（无法反射屏幕外的内容）——解决方法：放置 Reflection Plane／Cubemap 探针
• 折射也有相同限制
• 间接光为烘焙光照，而非实时光照——烘焙 Light Probe 可获得准确的反弹光照
• 无法准确渲染焦散

配方 4 — 色彩管理

import bpy

scene = bpy.context.scene

# View transform — controls the "look" mapping HDR → display
scene.view_settings.view_transform = 'AgX'         # default Blender 4.x; replaces Filmic
scene.view_settings.look = 'AgX - Medium High Contrast'

# Or: 'Filmic' (older but still supported), 'Standard' (oversaturates highlights)

scene.view_settings.exposure = 0.0
scene.view_settings.gamma = 1.0
print('render:colormanagement_AgX')

规则：照片级输出绝不要使用「Standard」——它会导致高光过曝。几乎总是使用 AgX 或 Filmic。

配方 5 — 将单帧渲染为 PNG

⚠ **如果 scene.camera 为 None，bpy.ops.render.render() 会报错：Error: Cannot render, no camera。**务必先运行相机保护程序。如果场景中存在 CAMERA 类型的对象，它会自动分配第一个对象；否则会抛出清晰的错误。

import bpy

scene = bpy.context.scene

# Camera guard — required before every render
def ensure_camera(scene):
    if scene.camera is not None:
        return scene.camera.name
    cams = [o for o in bpy.data.objects if o.type == 'CAMERA']
    if not cams:
        raise RuntimeError("No camera in scene — add one before rendering")
    scene.camera = cams[0]
    return cams[0].name

cam_name = ensure_camera(scene)
print(f"camera:{cam_name}")

scene.render.image_settings.file_format = 'PNG'
scene.render.image_settings.color_mode = 'RGBA'
scene.render.image_settings.color_depth = '16'    # 16-bit for compositing later
scene.render.filepath = '/tmp/output_hero.png'

bpy.ops.render.render(write_still=True)
print(f"render:saved {scene.render.filepath}")

之后，使用 Bash 验证：ls -la /tmp/output_hero.png——确认文件存在并报告大小。

配方 6 — 将动画渲染为 PNG 序列

import bpy

scene = bpy.context.scene

# Camera guard — same pattern as Recipe 5
def ensure_camera(scene):
    if scene.camera is not None:
        return scene.camera.name
    cams = [o for o in bpy.data.objects if o.type == 'CAMERA']
    if not cams:
        raise RuntimeError("No camera in scene — add one before rendering")
    scene.camera = cams[0]
    return cams[0].name

cam_name = ensure_camera(scene)
print(f"camera:{cam_name}")

scene.frame_start = 1
scene.frame_end = 240
scene.render.fps = 24

scene.render.image_settings.file_format = 'PNG'
scene.render.filepath = '/tmp/anim/frame_'   # output: frame_0001.png, frame_0002.png, ...

# Resilience: keep partial work on crash
scene.render.use_placeholder = True
scene.render.use_overwrite = False

# Reuse mesh data between frames (faster)
scene.render.use_persistent_data = True

bpy.ops.render.render(animation=True)
print('render:animation_done')

专业做法：先渲染为 PNG 序列，再用 ffmpeg 编码为 MP4：

ffmpeg -framerate 24 -i frame_%04d.png -c:v libx264 -pix_fmt yuv420p -crf 18 anim.mp4

配方 7 — 慢速渲染的性能调优

import bpy

scene = bpy.context.scene

# 1. Cap subdivision in render
scene.render.use_simplify = True
scene.render.simplify_subdivision = 1
scene.render.simplify_subdivision_render = 2

# 2. Higher noise threshold (faster, more denoiser-dependent)
scene.cycles.adaptive_threshold = 0.05

# 3. Lower light path bounces (lose some realism)
scene.cycles.max_bounces = 8
scene.cycles.diffuse_bounces = 3
scene.cycles.glossy_bounces = 3
print('render:performance_tuned')

配方 8 — 配置 GPU 计算设备（一次性设置）

import bpy

prefs = bpy.context.preferences.addons['cycles'].preferences
prefs.compute_device_type = 'OPTIX'   # or 'CUDA', 'HIP' (AMD), 'METAL' (Mac)
for device in prefs.devices:
    device.use = True
print(f"gpu:{prefs.compute_device_type} devices:{len(prefs.devices)}")

这是 Blender 的偏好设置——每台机器只需运行一次。

采样数量指南

场景类型	采样数	原因
户外、直射阳光	64–128	主要为直射光
常规产品／肖像	256	标准画质
带反弹光的室内场景	512	间接光越多，噪点越多
焦散、玻璃、复杂的 SSS	1024–2048	最难收敛

始终配合降噪使用。256 个采样 + 降噪的视觉质量约等于 4096 个未降噪采样。

常见问题

现象	修复方法
Error: Cannot render, no camera	scene.camera is None。使用配方 5／6 开头的 ensure_camera() 保护程序——它会自动分配第一个 CAMERA 对象；如果不存在，则抛出清晰的错误
渲染耗时数小时	减少采样数；启用自适应采样；降低反弹次数
Cycles 未使用 GPU	在偏好设置中配置计算设备（配方 8）
直接渲染为 MP4，崩溃后文件丢失	渲染为 PNG 序列，之后再编码
Standard 视图变换导致高光过曝	使用 AgX 或 Filmic
玻璃渲染为黑色	增加 transmission_bounces（16+）
EEVEE 缺少反射	添加 Reflection Plane／Cubemap 探针
动画帧间闪烁	使用持久化数据；考虑使用时域降噪
输出文件为空／未渲染任何内容	先设置 scene.render.filepath；静帧需检查 write_still=True

何时加载 references/overview.md

在以下情况下加载：

• 需要详细比较渲染引擎（Cycles 与 EEVEE 功能矩阵）
• 针对特定场景类型（焦散、植被、毛发）调节光线路径
• 在合成器中使用灯光组重新打光
• 使用 AOV／自定义渲染通道
• 分布式／渲染农场渲染

参考文档包含：完整的 Cycles 与 EEVEE 对比矩阵、按场景划分的采样数量指南、降噪器比较（OptiX 与 OIDN）、光线路径反弹调节、色彩管理深入解析，以及动画渲染最佳实践。