Back to Details

blender-rendering

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Blender Rendering

Blender 渲染

Render efficiently. The defaults are wrong for production; the recipes below are tuned for the common cases.
高效渲染。默认设置不适合生产环境；以下方案针对常见场景进行了优化。

Engine decision tree

引擎决策树

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)
Quick rule:
  • Stills, archviz, product, hero shots → Cycles
  • Animation previews, motion graphics, stylized → EEVEE
需要照片级真实感？焦散效果？精确的次表面散射？大量玻璃材质？
├── 是 → Cycles（路径追踪器）
└── 否  → 需要速度？风格化外观？动画迭代？
          ├── 是 → EEVEE
          └── 否  → Cycles（照片级真实感的默认备选）
快速规则:
  • 静帧、建筑可视化、产品展示、主视觉镜头 → Cycles
  • 动画预览、动态图形、风格化内容 → EEVEE

Reference-look handoff

参考风格对接

If the goal is to match an original/reference image rather than make a generally attractive render, chain-load 
reference-look-calibration
. It owns measurement of hue/saturation/value, object extent, glow/aura color, and before/after look metrics. This skill should then apply the requested material/lighting/render changes within that calibrated target.
如果目标是匹配原始/参考图像而非制作通用美观的渲染结果，请调用
reference-look-calibration
。该技能负责测量色相/饱和度/明度、物体范围、光晕/光效颜色，以及前后风格指标。本技能将在该校准目标内应用所需的材质/灯光/渲染调整。

Recipes

方案

Recipe 1 — Cycles production preset (256 samples + denoise)

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

python
import bpy

scene = bpy.context.scene
scene.render.engine = 'CYCLES'
scene.cycles.device = 'GPU'
python
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
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
scene.cycles.use_denoising = True scene.cycles.denoiser = 'OPENIMAGEDENOISE' # 安全默认值；NVIDIA RTX设备可切换为'OPTIX'

Light paths (defaults are reasonable; bump transmission for glass-rich scenes)

光路（默认设置合理；含大量玻璃材质的场景可提高透射反弹次数）

scene.cycles.max_bounces = 12 scene.cycles.transmission_bounces = 12
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')
undefined
scene.render.resolution_x = 1920 scene.render.resolution_y = 1080 scene.render.resolution_percentage = 100
print('render:cycles_production_preset')
undefined

Recipe 2 — Cycles draft preset (faster iteration)

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

python
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')
python
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    # 测试用半分辨率
print('render:cycles_draft')

Recipe 3 — EEVEE preset

方案3 — EEVEE预设

python
import bpy

scene = bpy.context.scene
python
import bpy

scene = bpy.context.scene

Engine name changed across versions:

引擎名称随版本变化:

Blender ≤ 4.1: 'BLENDER_EEVEE'

Blender ≤ 4.1: 'BLENDER_EEVEE'

Blender 4.2 only: 'BLENDER_EEVEE_NEXT' (transitional; replaced)

Blender 4.2专属: 'BLENDER_EEVEE_NEXT'（过渡版本；已被替换）

Blender ≥ 5.0: 'BLENDER_EEVEE' (the new EEVEE replaced the old)

Blender ≥ 5.0: 'BLENDER_EEVEE'（新版EEVEE替代旧版）

Try the new name first; fall back if it doesn't exist on this Blender.

优先尝试新名称；若当前Blender不支持则回退到旧名称。

try: scene.render.engine = 'BLENDER_EEVEE_NEXT' except (TypeError, ValueError): scene.render.engine = 'BLENDER_EEVEE'
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)

EEVEE设置（eevee命名空间在4.x和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 limitations to know**:
- Reflections are screen-space (can't reflect what's off-screen) — workaround: place Reflection Plane / Cubemap probes
- Same for refraction
- Indirect light baked, not real-time — bake Light Probes for accurate bounce
- No accurate caustics
if hasattr(scene, 'eevee'): scene.eevee.taa_render_samples = 64 scene.eevee.taa_samples = 16 scene.eevee.use_gtao = True # 屏幕空间环境光遮蔽 scene.eevee.gtao_distance = 0.2 scene.eevee.use_bloom = True # 光晕效果 scene.eevee.use_ssr = True # 屏幕空间反射 scene.eevee.use_ssr_refraction = True # 玻璃材质适用 scene.eevee.use_volumetric_lights = True scene.render.resolution_x = 1920 scene.render.resolution_y = 1080 print('render:eevee_preset')

**需要了解的EEVEE局限性**:
- 反射基于屏幕空间（无法反射屏幕外内容）——解决方法：放置反射平面/立方体贴图探针
- 折射同理
- 间接光为烘焙效果，非实时——烘焙灯光探针以获得准确的反弹效果
- 无精确焦散效果

Recipe 4 — Color management

方案4 — 色彩管理

python
import bpy

scene = bpy.context.scene
python
import bpy

scene = bpy.context.scene

View transform — controls the "look" mapping HDR → display

视图变换——控制从HDR到显示的“风格”映射

scene.view_settings.view_transform = 'AgX' # default Blender 4.x; replaces Filmic scene.view_settings.look = 'AgX - Medium High Contrast'
scene.view_settings.view_transform = 'AgX' # Blender 4.x默认设置；替代Filmic scene.view_settings.look = 'AgX - Medium High Contrast'

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

可选：'Filmic'（旧版但仍受支持）、'Standard'（高光过饱和）

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

**Rule**: Never use 'Standard' for photographic output — it blows out highlights. AgX or Filmic almost always.
scene.view_settings.exposure = 0.0 scene.view_settings.gamma = 1.0 print('render:colormanagement_AgX')

**规则**: 摄影输出绝不要使用'Standard'——它会导致高光过曝。几乎所有场景都应使用AgX或Filmic。

Recipe 5 — Render a single frame to PNG

方案5 — 渲染单帧为PNG

⚠ 
bpy.ops.render.render()
fails with 
Error: Cannot render, no camera
if 
scene.camera
is None. Always run the camera guard first. The guard auto-assigns the first CAMERA-type object if the scene has any, and raises a clear error otherwise.
python
import bpy

scene = bpy.context.scene
⚠ 若
scene.camera
为None，
bpy.ops.render.render()
会报错
Error: Cannot render, no camera
。 务必先运行相机检查逻辑。该逻辑会自动分配场景中的第一个CAMERA类型对象；若场景中无相机，则抛出清晰的错误提示。
python
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}")

After this, verify with Bash: `ls -la /tmp/output_hero.png` — confirm file exists and report size.
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("场景中无相机——渲染前请添加相机") 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位格式便于后期合成 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`——确认文件存在并报告文件大小。

Recipe 6 — Render an animation as PNG sequence

方案6 — 渲染动画为PNG序列

python
import bpy

scene = bpy.context.scene
python
import bpy

scene = bpy.context.scene

Camera guard — same pattern as Recipe 5

相机检查——与方案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, ...
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("场景中无相机——渲染前请添加相机") 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_' # 输出文件：frame_0001.png, frame_0002.png, ...

Resilience: keep partial work on crash

容错设置：崩溃时保留已完成的部分工作

scene.render.use_placeholder = True scene.render.use_overwrite = False
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')

**Pro pattern**: render to PNG sequence, then encode to MP4 with ffmpeg afterward:

```bash
ffmpeg -framerate 24 -i frame_%04d.png -c:v libx264 -pix_fmt yuv420p -crf 18 anim.mp4
scene.render.use_persistent_data = True
bpy.ops.render.render(animation=True) print('render:animation_done')

**专业流程**: 先渲染为PNG序列，再用ffmpeg编码为MP4：

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

Recipe 7 — Performance tuning for slow renders

方案7 — 慢渲染性能调优

python
import bpy

scene = bpy.context.scene
python
import bpy

scene = bpy.context.scene

1. Cap subdivision in render

1. 限制渲染时的细分级别

scene.render.use_simplify = True scene.render.simplify_subdivision = 1 scene.render.simplify_subdivision_render = 2
scene.render.use_simplify = True scene.render.simplify_subdivision = 1 scene.render.simplify_subdivision_render = 2

2. Higher noise threshold (faster, more denoiser-dependent)

2. 提高噪点阈值（速度更快，更依赖降噪器）

scene.cycles.adaptive_threshold = 0.05
scene.cycles.adaptive_threshold = 0.05

3. Lower light path bounces (lose some realism)

3. 降低光路反弹次数（损失部分真实感）

scene.cycles.max_bounces = 8 scene.cycles.diffuse_bounces = 3 scene.cycles.glossy_bounces = 3 print('render:performance_tuned')
undefined
scene.cycles.max_bounces = 8 scene.cycles.diffuse_bounces = 3 scene.cycles.glossy_bounces = 3 print('render:performance_tuned')
undefined

Recipe 8 — Configure GPU compute device (one-time)

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

python
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)}")
This is a Blender preference — only needs to run once per machine.
python
import bpy

prefs = bpy.context.preferences.addons['cycles'].preferences
prefs.compute_device_type = 'OPTIX'   # 可选'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偏好设置——每台机器只需配置一次。

Sample count guide

采样数指南

Scene typeSamplesWhy
Outdoor, direct sun64–128Mostly direct light
General product/portrait256Standard quality
Indoor with bounce512More indirect = more noise
Caustics, glass, complex SSS1024–2048Hardest to converge
Always pair with denoising. 256 samples + denoise ≈ 4096 raw samples in visual quality.
场景类型采样数原因
户外直射阳光场景64–128主要为直射光
通用产品/人像场景256标准画质
室内反弹光场景512间接光更多=噪点更多
焦散、玻璃、复杂次表面散射场景1024–2048最难收敛
务必配合降噪使用。256采样+降噪的视觉质量≈4096原始采样。

Common pitfalls

常见问题

SymptomFix
Error: Cannot render, no camera
scene.camera is None
. Use the 
ensure_camera()
guard at the top of Recipes 5/6 — it auto-assigns the first CAMERA object or raises a clear error if none exists
Render takes hoursReduce samples; enable adaptive; lower bounces
Cycles GPU not usedConfigure compute device in preferences (Recipe 8)
Render direct to MP4 lost on crashRender PNG sequence, encode after
Standard view transform → blown highlightsUse AgX or Filmic
Glass renders blackIncrease transmission_bounces (16+)
EEVEE missing reflectionsAdd Reflection Plane / Cubemap probes
Animation flickers between framesUse persistent data; consider temporal denoising
Output file empty / nothing renderedSet 
scene.render.filepath
first; check 
write_still=True
for stills
症状解决方法
Error: Cannot render, no camera
scene.camera
为None。在方案5/6开头使用
ensure_camera()
检查逻辑——它会自动分配第一个CAMERA对象，若无则抛出清晰错误
渲染耗时数小时减少采样数；启用自适应采样；降低反弹次数
Cycles未使用GPU在偏好设置中配置计算设备（方案8）
直接渲染为MP4时崩溃导致文件丢失先渲染为PNG序列，再编码
Standard视图变换导致高光过曝使用AgX或Filmic
玻璃材质渲染为黑色提高透射反弹次数（16+）
EEVEE缺少反射效果添加反射平面/立方体贴图探针
动画帧间闪烁使用持久化数据；考虑时序降噪
输出文件为空/无渲染内容先设置
scene.render.filepath
；静帧渲染需确保
write_still=True

When to load 
references/overview.md

何时加载
references/overview.md

Load when:
  • Need detailed engine comparison (Cycles vs EEVEE feature matrix)
  • Tuning light paths for specific scene types (caustics, foliage, hair)
  • Light groups for re-lighting in compositor
  • AOV / custom render passes
  • Distributed / farm rendering
The reference covers: full Cycles vs EEVEE matrix, sample-count guides per scene, denoiser comparison (OptiX vs OIDN), light-path bounce tuning, color management deep-dive, and animation rendering best practices.
在以下场景加载：
  • 需要详细的引擎对比（Cycles vs EEVEE功能矩阵）
  • 针对特定场景类型调整光路（焦散、 foliage、毛发）
  • 使用灯光组在合成器中重新打光
  • AOV/自定义渲染通道
  • 分布式/农场渲染
参考文档涵盖：完整的Cycles vs EEVEE矩阵、各场景采样数指南、降噪器对比（OptiX vs OIDN）、光路反弹调优、色彩管理深度解析，以及动画渲染最佳实践。