项目地址: https://github.com/blender/blender
官方文档: https://docs.blender.org/
Python API: https://docs.blender.org/api/current/
许可证: GPL-2.0-or-later
最新版本: 5.3.0(2026-11-10 发布构建;GitHub tag 为 2026-11-09,时区差异所致);LTS: 5.2.4(同日发布,5.2 为 LTS 系列,生命周期内只修 bug),截至 2026-11,见 Releases、https://download.blender.org/release/Blender5.3/(5.3)与 https://download.blender.org/release/Blender5.2/(5.2 LTS)
包管理器:
winget install BlenderFoundation.Blender/brew install --cask blender/sudo snap install blender --classic
概述
Blender 是开源 3D 创作套件,通过内置 Python 解释器暴露完整的 bpy API:脚本可读写全部场景数据、调用几乎全部界面功能,适合程序化建模、GIS 数据三维化与无头批处理。Python API 随 Blender 版本发布,无需单独安装:当前稳定版是 5.3(5.3.0,2026-11-10 构建发布),追求长期稳定则用 5.2 LTS(5.2.4,同日发布);文中用到的 bpy 接口在 5.2/5.3 上一致。
核心模块:
| 模块 | 用途 |
|---|---|
bpy.data |
数据块访问(objects、meshes、materials、node_groups…) |
bpy.context |
当前上下文(场景、视图层、选中对象、模式) |
bpy.ops |
操作符(建模、导入导出、渲染、文件管理) |
bpy.types |
类型定义(Object、Mesh、Operator、NodeTree…) |
bpy.msgbus |
消息总线(订阅数据块属性变更) |
mathutils |
Vector / Matrix / Quaternion / Euler 数学库 |
bpy_extras |
辅助工具(io_utils、object_utils、view3d_utils) |
常用交换格式:.blend、glTF 2.0(.gltf/.glb)、OBJ、STL、FBX、PLY、USD、Alembic、SVG。
环境准备
桌面安装
# Windows:官网安装包或 winget
winget install BlenderFoundation.Blender
# macOS
brew install --cask blender
# Linux(Ubuntu 官方推荐 snap)
sudo snap install blender --classic
# 或使用官网 tar.xz(免 root):<https://www.blender.org/download/>
# 发行版仓库的 blender 包通常滞后于官网版本,建议 snap 或官网包
无头(headless)运行
blender -b(--background)不创建窗口,渲染、导入导出、脚本执行均可用,适合服务器与 CI。- 无头环境不需要显示器;Linux 服务器建议使用官网 tar.xz 并补齐基础运行库。
- Blender 内置独立 Python,不依赖系统 Python;脚本中直接
import bpy即可。
验证
blender --version
blender -b --python-expr "import bpy; print(bpy.app.version_string)"
核心 API/命令
命令行运行脚本
blender -b scene.blend -P build.py # 打开文件并执行脚本
blender -b -P gen.py -- --count 100 --out out.glb # 脚本参数置于 -- 之后,脚本内用 sys.argv 读取
blender -b --python-expr "import bpy; print(len(bpy.data.objects))"
blender -b --python-exit-code 1 -P pipeline.py # 脚本异常时以非零码退出,便于 CI 判断
-P 等价于 --python <filepath>;另有 --python-text <name>(执行文本块)与 --python-console(交互控制台)。
数据访问与对象创建
import bpy
from mathutils import Vector
# 无头场景:清空为工厂空设置
bpy.ops.wm.read_factory_settings(use_empty=True)
# 由顶点/面创建网格数据块
mesh = bpy.data.meshes.new("Facade")
mesh.from_pydata([(0, 0, 0), (10, 0, 0), (10, 6, 0), (0, 6, 0)], [], [(0, 1, 2, 3)])
mesh.validate()
# 创建对象并链接到当前集合
obj = bpy.data.objects.new("Building", mesh)
bpy.context.collection.objects.link(obj)
obj.location = Vector((100.0, 50.0, 0.0))
obj.scale = (1.0, 1.0, 3.0) # 简易拉高
bpy.data 集合既可按名称索引(bpy.data.objects["Cube"])也可按序号索引;序号可能随运行变化,脚本中优先用名称或变量引用。
网格与几何操作
mesh = obj.data
mesh.validate() # 检查并修复非法几何
mesh.calc_loop_triangles() # 计算三角剖分(导出前需要)
# 变换优先改对象属性,避免依赖上下文的 bpy.ops
obj.rotation_euler = (0.0, 0.0, 1.5708) # 绕 Z 轴 90 度
bpy.context.view_layer.update() # 属性改动后刷新依赖图
导出 glTF / OBJ / STL
# glTF 2.0(.glb 单文件,Web 首选)
bpy.ops.export_scene.gltf(filepath="out.glb", export_format='GLB', use_selection=False)
# OBJ(4.0 起为新的导入导出器)
bpy.ops.wm.obj_export(filepath="out.obj", export_selected_objects=False)
# STL(4.0 起内置新导入导出器,4.1 起转正)
bpy.ops.wm.stl_export(filepath="out.stl", export_selected_objects=False)
# 保存 .blend
bpy.ops.wm.save_as_mainfile(filepath="scene.blend")
Geometry Nodes 基础(脚本创建节点组)
# 新建几何节点组(GeometryNodeTree)
group = bpy.data.node_groups.new("GN_Extrude", 'GeometryNodeTree')
# 4.0 起用 interface.new_socket 定义输入/输出接口
group.interface.new_socket("Geometry", in_out='INPUT', socket_type='NodeSocketGeometry')
group.interface.new_socket("Geometry", in_out='OUTPUT', socket_type='NodeSocketGeometry')
node_in = group.nodes.new("NodeGroupInput")
node_out = group.nodes.new("NodeGroupOutput")
cube = group.nodes.new("GeometryNodeMeshCube") # 立方体节点
extrude = group.nodes.new("GeometryNodeExtrudeMesh") # 挤出网格节点
group.links.new(node_in.outputs["Geometry"], extrude.inputs["Mesh"])
group.links.new(extrude.outputs["Mesh"], node_out.inputs["Geometry"])
# 将节点组挂到对象修饰器上
obj = bpy.data.objects.new("GN_Object", None)
bpy.context.collection.objects.link(obj)
mod = obj.modifiers.new("GeometryNodes", 'NODES')
mod.node_group = group
# 取评估后网格(应用修饰器结果,用于导出/统计)
depsgraph = bpy.context.evaluated_depsgraph_get()
obj_eval = obj.evaluated_get(depsgraph)
mesh_eval = bpy.data.meshes.new_from_object(obj_eval)
插件开发框架
bl_info = {
"name": "My GIS Tool",
"author": "you",
"version": (1, 0, 0),
"blender": (5, 3, 0), # 最低支持版本;5.2 LTS 上同样可运行
"category": "Object",
}
import bpy
class OBJECT_OT_build_from_footprint(bpy.types.Operator):
bl_idname = "object.build_from_footprint"
bl_label = "Build from Footprint"
def execute(self, context):
self.report({'INFO'}, "done")
return {'FINISHED'}
def register():
bpy.utils.register_class(OBJECT_OT_build_from_footprint)
def unregister():
bpy.utils.unregister_class(OBJECT_OT_build_from_footprint)
if __name__ == "__main__":
register()
传统插件用 bl_info + register()/unregister()(结构取自官方 Add-on Tutorial);4.2 起新式扩展(Extensions)改用 blender_manifest.toml 声明元数据,register/unregister 约定不变。
GIS 数据结合(GeoJSON 生成建筑体块)
import json
import bpy
# 解析 GeoJSON(标准库 json 即可)
with open("footprints.geojson", encoding="utf-8") as f:
gj = json.load(f)
def add_building(ring, height, name):
"""ring: [[lon, lat], ...] 外环;按等距近似投影为米"""
verts = [(x * 111320.0, y * 110540.0, 0.0) for x, y in ring[:-1]] # 去掉闭合点
n = len(verts)
verts += [(x, y, height) for x, y, _ in verts]
faces = [[i, (i + 1) % n, (i + 1) % n + n, i + n] for i in range(n)]
faces.append([i + n for i in range(n)]) # 顶面
mesh = bpy.data.meshes.new(name)
mesh.from_pydata(verts, [], faces)
mesh.validate()
obj = bpy.data.objects.new(name, mesh)
bpy.context.collection.objects.link(obj)
for i, feat in enumerate(gj["features"]):
geom = feat["geometry"]
if geom["type"] == "Polygon":
add_building(geom["coordinates"][0], feat["properties"].get("height", 10.0), f"B_{i}")
bpy.ops.export_scene.gltf(filepath="city.glb", export_format='GLB')
- 上述经纬度转米为等距近似,跨区域或高精度场景应先用 pyproj/GDAL 做投影(UTM/Web Mercator)再写入
verts。 - Shapefile 可用 BlenderGIS 插件导入:
bpy.ops.importgis.shapefile(filepath="districts.shp")(bl_idname 为importgis.shapefile),该插件同时支持 GeoTIFF 与 OSM。 - 大数据量建议先在 GDAL/QGIS 中裁剪、简化、转 GeoJSON,再交给 Blender 生成体块。
典型工作流
输入:建模脚本或 GeoJSON 要素数据;输出:.blend 工程或 glTF/OBJ/STL 文件。
- 准备环境:无头服务器用官网包安装,
blender -b --python-expr "import bpy"验证可用。 - 编写脚本:以
bpy.ops.wm.read_factory_settings(use_empty=True)开始,用bpy.data创建网格/对象并link到集合。 - 建模:简单体块直接
from_pydata;参数化或迭代规则用 Geometry Nodes 节点组 + 修饰器。 - 材质与变换:设置
obj.location/rotation_euler/scale与材质槽,view_layer.update()刷新。 - 导出:按目标平台选择
export_scene.gltf/wm.obj_export/wm.stl_export,显式指定格式与选择参数。 - 批处理:
blender -b -P pipeline.py -- <args>循环处理数据集,配合--python-exit-code接入 CI。
最佳实践
- 脚本优先
bpy.data,而非bpy.ops:bpy.ops依赖上下文(模式、选中、区域),无头环境下易报context is incorrect;必须用操作符时通过bpy.context.temp_override(...)显式提供上下文。 - 导出参数写全:glTF 用
export_format='GLB'控制单文件;OBJ/STL 用export_selected_objects控制范围;导出前确认对象已链接到场景集合。 - Geometry Nodes 结果需评估:修饰器不修改原始网格,导出或统计前经
evaluated_depsgraph_get()+new_from_object()取评估网格。 - 单位与坐标:Blender 内部为米、Z 轴向上;glTF 导出默认转 Y 轴向上,写入 GIS 数据(东-北-高)时保持 Z-up 约定。
- 无头稳定性:CI 中加
--python-exit-code 1;批处理循环用try/except包装,单个要素失败不中断整批。 - 第三方库:Blender 使用内置 Python,不加载系统 site-packages;纯数据解析优先标准库(json、csv),复杂投影/几何处理可调用外部 GDAL 生成中间文件。
常见问题
| 报错 / 现象 | 原因 | 处置 |
|---|---|---|
snap 安装后 blender: command not found |
snap 版可执行文件不在默认 PATH | 路径为 /snap/bin/blender,确认 PATH 或使用绝对路径 |
无头下 bpy.ops 报 context is incorrect |
无 GUI 时没有正确的 context(无窗口、无活动区域) | 改用 bpy.data 直接操作,或用 bpy.context.temp_override(...) 提供上下文 |
脚本报 ModuleNotFoundError(第三方包) |
Blender 使用内置 Python,不加载系统 site-packages | 改用标准库,或由外部工具先生成中间数据 |
-P 脚本执行完但没有输出文件 |
后台模式不会自动保存 | 脚本内显式调用 wm.save_as_mainfile 或对应导出操作符 |
| 导出的 glTF 没有材质 | 材质未用 Principled BSDF,或导出参数关闭了材质 | 改用 Principled BSDF 节点;检查 export_materials 未被关闭 |
| Geometry Nodes 修改器无效果 | 节点组输出未连接,或对象缺少输入几何 | 确认节点组输出接到 Group Output;用 depsgraph 取评估网格验证 |
| 脚本参数没有传入 | 参数放在了 -- 之前,被 Blender 当作自身参数解析 |
参数须放在 -- 之后(blender -b -P s.py -- a b),脚本内从 sys.argv 读取 |
| 4.0 之前的老脚本在新版报错 | 接口改名早于 5.x:interface.new_socket、wm.obj_export/wm.obj_import 自 4.0 起,内置 STL 导入导出器 4.0 为实验性、4.1 起转正,旧插件式操作符已移除 |
节点组改用 interface.new_socket;导出改用 wm.obj_export/wm.stl_export,不要再找 export_scene.obj/export_mesh.stl |
AI 使用建议
- 推荐工作流模式:AI 生成 Blender 脚本时先确定运行模式(GUI 交互或
blender -b -P无头),无头脚本一律从bpy.data出发;GIS 类任务先输出 GeoJSON 中间文件再生成体块脚本,避免在 Blender 内做重投影。 - 关键注意事项:①
bpy.ops依赖上下文,无头环境优先bpy.data;② 修改属性后调用bpy.context.view_layer.update()或重新获取 depsgraph;③ 导出操作符参数(export_format、export_selected_objects)必须显式给出;④ Blender 内置 Python 不加载系统第三方包;⑤ 版本差异集中在节点组接口(interface.new_socket)与导入导出操作符名称(wm.obj_export/wm.stl_export),生成代码前确认目标版本。 - 常用代码模式:
read_factory_settings(use_empty=True)→bpy.data.meshes.new+from_pydata→objects.new+collection.objects.link→ 设置变换/修饰器 →export_scene.gltf/wm.stl_export;批处理外壳blender -b --python-exit-code 1 -P pipeline.py -- <args>。
相关技能
- freecad — 参数化 CAD 与 BIM(精确实体建模,与 Blender 网格流程互补):../freecad/SKILL.md
- openscad — 声明式 CSG 建模(快速生成体块后导入 Blender 渲染):../openscad/SKILL.md
- cadquery — Python 参数化 CAD(精确 B-Rep,可与 Blender 交换 glTF/OBJ):../cadquery/SKILL.md
- occt — 底层 OCCT 几何内核(精确几何运算):../occt/SKILL.md
参考资源
- 官方手册(脚本与扩展章节):https://docs.blender.org/manual/en/latest/advanced/scripting/index.html
- Python API 文档:https://docs.blender.org/api/current/
- API Quickstart:https://docs.blender.org/api/current/info_quickstart.html
- 命令行参数:https://docs.blender.org/manual/en/latest/advanced/command_line/arguments.html
- Add-on 教程:https://docs.blender.org/manual/en/latest/advanced/scripting/addon_tutorial.html
- 扩展(Extensions)指南:https://docs.blender.org/manual/en/latest/advanced/extensions/getting_started.html
- 下载与版本:https://www.blender.org/download/