Blender中的材质、光照与渲染
你通过BlenderLab连接在用户的Blender中工作。 视口截图和最终渲染是两回事：截图显示的是视口当前的着色模式，而渲染使用的是渲染引擎、灯光和世界。大多数“看起来没问题但渲染出来不对”的问题都源于此。
你的Blender连接
你通过BlenderLab（官方Blender Lab服务器）工作；其工具是 blenderlab_…：
- 场景内容：
get_objects_summary；单个对象详情：get_object_detail_summary（按name）。文件（无论是否保存）及其路径：get_blendfile_summary_path_info。 - 运行Python：
execute_blender_code。调用之间不保留任何状态（在每个脚本中携带辅助函数）；脚本打印的内容会返回，赋值给result的字典会作为数据返回。它的保护机制会拒绝某些操作符（如退出Blender、恢复出厂设置）。 - 查看3D视口：
get_screenshot_of_area_as_image，参数area_ui_type: "VIEW_3D"（整个窗口：get_screenshot_of_window_as_image）；将视口聚焦到对象：jump_to_view3d_object_by_name。 - 检查Python API：
get_python_api_docs（例如bpy.types.BevelModifier这样的标识符）、search_api_docs；手册：search_manual_docs。 - 快速渲染：
render_thumbnail_to_path、render_viewport_to_path；图像会保存到Blender的临时文件夹，结果返回真实路径。 - 导出：代码（
bpy.ops.export_scene.gltf、bpy.ops.export_scene.fbx）。 - 资源库和3D生成器：无。构建对象，或要求用户提供要导入的文件。
如果这些工具不可用，请停止并说明原因：用户需要安装BlenderLab连接（工具→连接），将其授予此代理，并保持Blender打开且插件的服务器已启动。如果无法完成工作，不要描述成已完成。
工作顺序
- 观察：使用场景工具；检查哪些对象、哪些已有材质、是否有相机、灯光、世界？读取
bpy.app.version_string和当前渲染引擎。 - 材质，每个不同的表面一个材质，以其名称命名（如
Oak_Wood、Brushed_Steel），并在对象间复用。 - 光照和世界在评估任何材质之前：不能在黑暗中评估材质。
- 相机：对准主体，使用合适的焦距。
- 测试渲染小尺寸（25-50%分辨率，少量样本），检查并修复。
- 最终渲染到文件，并报告路径、引擎、分辨率和时间。
每个步骤的代码在 references/shading-and-render.md 中。在编写第一个脚本之前请先打开它。
材质：常见问题
- 颜色设置在了错误的位置。
material.diffuse_color和object.color只是视口显示颜色：它们不参与渲染。参与渲染的颜色是 Principled BSDF 节点的 Base Color 输入。如果想要实体模式视口匹配，请同时设置两者。 - Blender 4.0 中输入名称发生了变化。
Transmission变成了Transmission Weight，Emission变成了Emission Color，Specular变成了Specular IOR Level，Clearcoat变成了Coat Weight，Subsurface变成了Subsurface Weight。在设置之前，按名称查找输入并检查它是否存在；如果不确定，请使用连接的API工具。 - 材质已创建但从未分配。 将其附加到
obj.data.materials；对于网格不同部分的不同材质，设置polygon.material_index。 - 按类型查找节点，而不是按名称。 节点仅在英文界面中称为“Principled BSDF”。请使用
next(n for n in nodes if n.type == 'BSDF_PRINCIPLED')。
| 表面类型 | Principled BSDF 设置 |
|---|---|
| 涂漆、塑料 | Base Color；Roughness 0.3-0.6；Metallic 0 |
| 金属 | Metallic 1.0；Base Color = 金属本身的颜色；Roughness 0.15-0.5 |
| 玻璃 | Transmission Weight 1.0；Roughness 0-0.05；IOR 1.45；需要有世界或灯光才能有东西可折射 |
| 发光 | Emission Color + Emission Strength（1-20） |
| 橡胶、布料、哑光 | Roughness 0.8-1.0 |
| 车漆、清漆 | Coat Weight 1.0；Coat Roughness 0.05 |
Metallic 应为 0 或 1，几乎不取中间值。纯黑 (0, 0, 0) 和纯白 (1, 1, 1) 的Base Color在光照下看起来很奇怪：请保持在约 0.03-0.9 的范围内。
光照与世界
- 没有世界也没有灯光意味着全黑渲染，而即使有灯光，玻璃或铬材质在空荡荡的世界中渲染也会变黑，因为没有东西可以反射或折射。给世界赋予颜色和强度，或者使用HDRI。
- 一个可靠的起点：一个大的面光作为主光（与对象成45°角，位于一侧上方），另一侧一个较弱的补光，背后一个轮廓光，以及一个低强度（0.2-0.5）的世界。
- 面光的功率以瓦特为单位，并且需要足够大：一个距离小物体2米的1米面光大约需要100-500 W。太阳光的强度不同：2-5。
- 在对象下方放置一个地面平面以获得接触阴影；没有它对象会悬浮。
- HDRI可以一步实现真实的光照和反射。Blender连接可以下载Poly Haven的HDRI：这是第三方内容，需要在HydraOps中批准，因此请先征询意见。在BlenderLab上，请要求用户提供HDRI文件。
渲染引擎
| EEVEE | Cycles | |
|---|---|---|
| 速度 | 秒 | 秒到分钟 |
| 用途 | 预览、风格化、动画 | 最终静帧、玻璃、精确光照 |
| 注意事项 | 反射和折射需要启用光线追踪；否则玻璃和光泽表面看起来平淡或有颗粒感 | 噪点：提高样本数并保持降噪开启；仅当用户配置了GPU时才使用GPU |
不同版本的EEVEE引擎标识符不同（4.2-4.5版本为 BLENDER_EEVEE_NEXT，之前和之后为 BLENDER_EEVEE）：参考文件显示了如何无需猜测地进行设置。不要更改用户的渲染设备或偏好设置。
相机
- 如果没有相机则创建一个，并将其设为场景相机；除非用户要求，否则不要移动用户已放置的相机。
- 使用“跟踪到”约束将其对准主体或空对象；物体使用50-85mm，房间和环境使用24-35mm。
- 通过小尺寸测试渲染来检查构图，而不是通过视口截图（视口并非相机视图，除非你切换到相机视图）。
渲染
- 渲染到文件，使用用户能找到的文件夹中的绝对路径（如果.blend已保存则放在其旁边，否则询问用户或使用用户的临时文件夹），并报告完整路径。除非事先说明，否则不要覆盖现有文件。使用代码完成（参考文件中有）：BlenderLab自己的渲染工具仅用于快速检查，无论你给它什么路径，它都会写入Blender的临时文件夹；报告工具结果中给出的路径。
- 先小尺寸测试。全分辨率Cycles渲染可能需要几分钟，并且在运行时阻塞Blender；在开始长时间渲染前告知用户。
- 在宣布成功之前检查结果：视口截图不能显示渲染结果。如果你自己无法查看渲染文件，请直接说明，并描述你设置的内容，而不是图像“看起来的样子”。
- 色彩管理：默认的视图变换（AgX或Filmic）为了真实感会降低强颜色的饱和度；对于需要精确匹配的平面图形颜色，请使用
Standard。
故障排查
| 症状 | 常见原因 |
|---|---|
| 渲染全黑 | 无灯光且无世界；相机在对象内部；对象隐藏了渲染 |
| 对象为灰色或白色 | 材质未分配，或颜色设置在了 diffuse_color 而不是Base Color上 |
| 玻璃为黑色 | 世界为空；在EEVEE中，光线追踪关闭 |
| 粉色或品红色 | 缺少图像纹理文件 |
| 颗粒感 | Cycles：样本数少或未开启降噪。EEVEE：光线追踪关闭 or 柔和阴影样本少 |
| 平淡、无深度 | 只有世界光：添加主光和地面平面 |
| 颜色过淡 | 视图变换：尝试 Standard，或降低曝光度 |
| 曲面呈块状 | 平面着色：启用平滑着色 |
在你说完成之前
- 每个可见对象都已分配材质，且其Base Color已在节点上设置。
- 存在灯光或发光的 World，以及能够框住主体的相机。
- 已将渲染写入文件，并给出了路径、引擎和分辨率。
- 你只更改了被要求的部分：没有删除对象，没有更改偏好设置。