# Blender 集成

本库返回纯表和文件路径，不导入 `process.blender`、不连接/清空任何现有场景。

## 推荐流程

1. 搜索与元数据筛选，选定资产 ID。
2. 获取下载计划，检查分辨率和主文件＋依赖的总体积。
3. 下载成功取得 `report.mainFile`。
4. 用 Blender 技能的 `c.exec(code,args)` 或 `process.blender` 的后台接口处理，文件路径通过 JSON 参数传递，不插入 Python 字符串字面量。
5. 模型追加所需 Collection；材质只追加 Material；HDRI 读为 Image，再由建模脚本决定如何使用。

## 在已有 Blender 技能会话中追加模型

本示例只连接已有 `autos` 会话；若没有会话返回错误，不擅自启动或替换场景。实际会增加模型，重复运行会再追加一份。

```aardio
import web.rest.polyHaven;
import autos.skills.blender;

var ph=web.rest.polyHaven("My3DTool/1.0");
var asset,err=ph.downloadAsset("ceramic_vase_03","/assets/ceramic_vase_03/1k",{maxBytes=16*1024*1024});
ph.close();
if(!asset) return null,err;

var b=autos.skills.blender;
var c,err,detail=b.connect();
if(!c) return null,err,detail;

var code=/**
import bpy
path=args['path']
with bpy.data.libraries.load(path, link=False) as (src,dst):
    dst.collections=list(src.collections)
imported=[col for col in dst.collections if col]
children={child for col in imported for child in col.children}
roots=[col for col in imported if col not in children]
for col in roots:
    bpy.context.scene.collection.children.link(col)
result={'collections':[col.name for col in roots], 'source':'Poly Haven'}
**/;
var result,err,detail=c.exec(code,{path=asset.mainFile});
c.close();
return result,err,detail;
```

更复杂的文件应先读取 `src.collections`，再按名称选取需要的集合。这里的 `src/dst` 块追加的是数据块，而不是替换当前 `.blend`。

## 材质与 HDRI 的 Python 片段

以下片段可作为 `c.exec(code,{path=asset.mainFile})` 的 code，`args` 由桥接提供。

```python
import bpy
with bpy.data.libraries.load(args['path'], link=False) as (src,dst):
    dst.materials=list(src.materials)
result={'materials':[mat.name for mat in dst.materials if mat]}
```

由调用方将材质赋给指定对象，不猜测/覆盖当前选中的物体。

```python
import bpy
image=bpy.data.images.load(args['path'], check_existing=True)
result={'image':image.name, 'size':list(image.size)}
```

HDRI 的 World Environment Texture、Strength、旋转和灯光方案由场景脚本决定，不属于下载库职责。

## 独立后台进程

对于不应影响用户当前 Blender 的检查，使用 `process.blender.exec/execfile`。发布的 `PolyHavenBlender.aardio` 范例用后台新进程追加模型集合，验证贴图存在和解码，不打开 GUI、不保存或覆盖场景。

## 已验证与重要边界

2026-09-13 在独立 Blender 5.2.1 LTS 后台进程中从磁盘回读验证：

- `ceramic_vase_03/1k/blend`：追加模型集合，得到 1 个网格、1 个材质，3 张贴图均可定位并解码为 1024×1024。
- `aerial_rocks_02/1k/blend`：仅追加材质，4 张贴图均可定位并解码为 1024×1024。
- `venice_sunset/1k/exr`：可加载为浮点图像，1024×512。

**不能把 API `include` 当成整个示范场景所有外部资源的保证。** 实测 `aerial_rocks_02` 的原 `.blend` 里还保存着一个未列入 include 的示范 World HDRI 绝对路径。直接打开整个文件会遇到这项缺失；仅追加需要的材质可避免带入无关 World。库不从缺失路径猜测、抓取或替换其他资产，也不修改官方文件。

本次为数据加载与贴图路径验证，不是最终画面审美验收。使用时仍须检查比例、材质效果、Blender 版本兼容性和相应渲染结果。