blender

Blender 控制

Blender（/Applications/Blender.app）可通过 Python 使用 bpy、bmesh 和 mathutils 编写脚本。通过 Blender Bridge 控制它——这是一个运行在 已启动 Blender GUI 内的脚本，可执行 POST 到 127.0.0.1:8736 的任意构建脚本。由于它在实时会话的主线程中运行，因此可以合法写入 bpy.data，视口会随着构建过程更新，也可以截取视口截图。本文档中的所有内容均已在 Blender 5.2.2 LTS（内置 Python 3.13）上执行并验证——这是当前稳定版本；5.2 是 LTS 系列，因此适用于所有 5.2.x 版本。检查 ping 回复中的 version：如果使用的是更新版本，请以实时会话为准，先探测再作假设。

• scripts/blender-bridge.py — 在 Blender 内运行的桥接脚本。
• scripts/blender-send.sh — 发送 .py 文件（或 -c 'inline'）并打印捕获的输出；--ping 检查服务是否运行，--state 将场景导出为 JSON。
• scripts/example-product-shot.py — 模型 → 材质 → 三点布光 → 相机 → 测量 → 渲染。
• scripts/example-animated-logo.py — 文本 → 关键帧 → 几何节点散布 → 帧序列 → 视频。

编写任何内容前，请先阅读 references/gotchas.md。 Blender 的 API 在 5.x 中发生了重大变化，模型记住的大部分内容——action.fcurves、scene.node_tree、mod["Socket_2"]、BLENDER_EEVEE_NEXT、use_nodes = True——现在都已错误或弃用。

控制循环

1. 用户启动桥接脚本（一次性操作）。无法远程完成此操作——如果执行 bash scripts/blender-send.sh --ping 没有收到回复，请让用户选择以下一种方式：

   • 将 scripts/blender-bridge.py 复制到 ~/Library/Application Support/Blender/5.2/scripts/startup/blender_bridge.py（该文件夹对应正在运行的 major.minor 版本），然后重启 Blender——之后每次启动都会自动运行（推荐）；或
   • 打开 Scripting 工作区，将文件粘贴到文本编辑器中，然后按 Run Script（⌥P）——仅在当前会话中有效；或
   • 通过 Preferences ▸ Add-ons ▸ Install 将其安装为插件。

   ping 成功时会返回 {"ok": true, "bridge": "blender", "bridge_version": "1.2.0", "version": "5.2.2 LTS", ...}。 bridge_version 较旧表示用户安装的副本已过时——请让他们重新复制文件（旧版副本会在摄像机和空物体上调用 metrics() 时崩溃）。

2. 构建前先查看：bash scripts/blender-send.sh --state 会返回对象及其类型、集合、材质、节点组、帧范围、分辨率、渲染引擎，以及文件是否有未保存的更改——这比编写脚本来查询更省事。

3. 编写构建脚本：以以下速查表和合适的参考文件为基础，在临时目录中编写脚本。

4. 发送脚本：OUT=/path/to/outdir bash scripts/blender-send.sh /path/build.py。桥接脚本会在实时会话中运行脚本，并返回脚本捕获的标准输出；出错时会返回回溯信息，发送器以非零状态退出。对于耗时的渲染和烘焙，可设置 BLENDER_SEND_TIMEOUT=900（秒）。脚本在 Blender 内运行，因此无法获取 shell 的环境——请通过 --arg quality=final --arg samples=128 为发送内容设置参数，并使用 ARGS.get("quality", "preview") 读取（值为字符串）。

5. 反馈：首先查看返回的标准输出；使用 metrics(...) 检查结构化几何数据；使用 snapshot(...) 获取视口 PNG 以供查看；使用 render(...) 执行实际渲染。

6. 迭代：检查、修复并重新发送。脚本必须可重复运行——在 stage("name") 内构建，以便重新发送时替换自身输出，而不是不断堆叠副本。

参考路由

任务	阅读
开始前的所有事项	gotchas.md
数据块、变换、集合、依赖关系图、场景	api-reference.md
bmesh、修改器、曲线、文本、UV、布尔运算	modeling.md
材质、着色器节点、纹理、世界/HDRI、灯光、相机	shading.md
程序化几何、散布、实例化、字段、区域	geometry-nodes.md
关键帧、F 曲线、驱动器、NLA、骨架、IK、形状键	animation-rigging.md
刚体、布料、软体、粒子、毛发、流体、烘焙	simulation.md
EEVEE/Cycles 设置、通道、合成器、输出、视频	rendering.md
2D / 卡通线稿、Line Art	grease-pencil.md
剪辑、标题、转场、最终剪辑	vse.md
glTF、FBX、USD、Alembic、OBJ、STL、.blend 追加/链接	io-formats.md

注入的命名空间

已预先导入：bpy、bmesh、mathutils、Vector、Matrix、Euler、Quaternion、 math、os、json，以及 OUT（来自 $OUT，也可通过 os.environ["OUT"] 获取）、ARGS（将 --arg KEY=VALUE 字符串作为字典），还有以下辅助函数：

辅助函数	功能
stage(name)	获取或重新创建指定名称的集合，并将其设为活动集合 — 让重复发送保持幂等（也会释放旧对象遗留的孤立网格、材质和节点组）
sync()	view_layer.update()；读取 matrix_world 前必须调用
evaluated(ob)	经过 depsgraph 求值的对象（修改器 / 几何节点结果）
frame(n)	frame_set(n) + depsgraph 更新
metrics(objs, path=)	字典 + JSON：数量、顶点/三角形、世界边界框、材质、帧范围
snapshot(path, view=, shading=, fit=)	视口 PNG（快速目视检查）
render(path, engine=, samples=, ...)	实际 EEVEE/Cycles 静帧；会还原触及的所有设置
frame_view(objs, view=)	调整视口朝向（ISO/FRONT/TOP/CAMERA/…）
world_bounds(objs)	世界空间中的 (min, max)
fcurves(ob) / fcurve(ob, path, i) / channelbag(ob)	访问带槽动作的 F 曲线
gn_input(mod, name, value=, attribute=)	按名称读取/设置几何节点修改器输入
ui_override(area)	为少数需要编辑器上下文的 bpy.ops 提供上下文覆盖

速查表

单位为米和弧度。优先使用数据 API；bpy.ops 用于模式切换、 smart_project、rigidbody.*、nla.bake 以及导入器/导出器。

构建几何体（可重复运行）

coll = stage("hero_v1")                       # owns its own output; safe to re-send
me = bpy.data.meshes.new("Body")
bm = bmesh.new()
bmesh.ops.create_cube(bm, size=2.0)
bmesh.ops.bevel(bm, geom=list(bm.edges), offset=0.06, segments=3, affect="EDGES")
bm.to_mesh(me); bm.free()
ob = bpy.data.objects.new("Body", me)
coll.objects.link(ob)
ob.location = (0, 0, 1)
sync()                                        # before ANY matrix_world read

材质

m = bpy.data.materials.new("Shell")
b = m.node_tree.nodes["Principled BSDF"]
b.inputs["Base Color"].default_value = (0.75, 0.2, 0.15, 1.0)
b.inputs["Roughness"].default_value = 0.35
b.inputs["Metallic"].default_value = 0.0      # no "Specular"/"Emission" inputs since 4.0
ob.data.materials.append(m)

对准主体的相机

cd = bpy.data.cameras.new("Cam"); cd.lens = 50
cam = bpy.data.objects.new("Cam", cd); coll.objects.link(cam)
cam.location = (6, -6, 4)
cam.rotation_euler = (Vector((0, 0, 1)) - cam.location).to_track_quat("-Z", "Y").to_euler()
bpy.context.scene.camera = cam

反馈

m = metrics([ob], path=OUT + "/metrics.json")
print("METRICS", json.dumps(m))               # comes straight back through the sender
print(snapshot(OUT + "/check.png", view="ISO"))
print(render(OUT + "/hero.png", engine="BLENDER_EEVEE", samples=64,
             width=1280, height=720))

关键帧

for f, z in ((1, 0.0), (24, 3.0), (48, 0.0)):
    ob.location.z = z
    ob.keyframe_insert("location", index=2, frame=f)
for kp in fcurves(ob)[0].keyframe_points:     # NOT action.fcurves — that is gone
    kp.interpolation = "BEZIER"
    kp.easing = "EASE_IN_OUT"

导出

bpy.context.view_layer.objects.active = ob; ob.select_set(True)
bpy.ops.export_scene.gltf(filepath=OUT + "/hero.glb", export_format="GLB",
                          use_selection=True)
bpy.ops.wm.obj_export(filepath=OUT + "/hero.obj", export_selected_objects=True)
bpy.ops.wm.save_as_mainfile(filepath=OUT + "/hero.blend", copy=True)

验证

• 返回的 stdout 是即时信号 — print(...) 的内容会直接返回。
• metrics(...) 提供结构化检查（对象/顶点/三角形数量、世界边界框、材质）。 将其写入 $OUT/metrics.json 并读取，以确认几何体，而不必目测。
• snapshot(...) 用于快速目视检查 — 生成视口 OpenGL PNG，无需完整渲染。 shading="RENDERED" 可预览材质和灯光。
• render(...) 用于生成交付内容。如果 Blender 报告成功却未写入任何内容，它会抛出诊断性 RuntimeError。之后会还原触及的所有设置 — 因此，如果用户还需要一个可用 F12 重新渲染同一镜头的 .blend，请在保存前自行设置场景的分辨率、引擎和采样数。
• 交付：$OUT 中的 .glb/.blend 可用用户已有的软件打开。

安全

安装此技能意味着要在用户的机器上运行一个代码执行服务。在要求用户启动桥接服务之前，先说明这一点。

• 桥接服务会绑定到 127.0.0.1:8736（BLENDER_BRIDGE_PORT），并在运行中的会话内执行 POST 到 /run 的任何 Python 代码，使用用户的权限，操作用户打开的文件。请求没有身份验证：任何本地进程，以及共享机器上的其他用户，都能通过它控制 Blender。
• 网页无法做到这一点。携带 Origin 标头或跨站 Sec-Fetch-Site 标头的请求会被拒绝并返回 403，因此用户浏览器中的网页无法访问桥接服务。这项检查是唯一的防护措施——没有令牌。
• 安装方式决定端口会开放多久。 “脚本”工作区 ▸“运行脚本”会持续到 Blender 退出。为方便起见，上文推荐安装到 scripts/startup/，但这会让 Blender 每次启动时都开始监听，无论是否有 Agent 在控制它——应向用户说明这一权衡，而不是擅自假定。
• 要停止桥接服务，请退出 Blender。 没有远程关闭功能；进程结束时端口会释放。

安全注意事项

• 打开的文件可能包含尚未保存的工作。未经询问，切勿调用 bpy.ops.wm.read_homefile() 或 bpy.data.batch_remove。stage() 默认采用非破坏性方式；它会隔离几何体，但不会隔离场景级设置。
• 渲染、烘焙和模拟会阻塞主线程——界面会冻结，直到操作完成。请从小规模开始，并在执行耗时操作前提醒用户。
• 请保存到 $OUT，不要覆盖用户的 .blend 文件；save_as_mainfile(..., copy=True) 会让当前会话继续指向用户自己的文件。