Blender 步进漫游助手

Vision Power 步进漫游助手用于制作“全景图 + 空间模型 + 拍摄点位”的原生步进式漫游。用户点击地面脚印后，播放器会在同一个空间模型中切换到目标全景图，并利用模型完成深度判断、鼠标落点和空间遮挡。

插件把原来的全景相机辅助建模和坐标导出能力合并为一个安装包。新项目不需要再分别安装 PanoCamAdder 和坐标导出插件。

插件能做什么

开始前准备

Blender 版本

• 推荐 Blender 3.6 LTS 或 Blender 4.x。
• 插件不需要额外安装 Python 库。
• 安装包是 ZIP 文件，安装前不要解压。

全景图要求

• 使用宽高比为 2:1 的等距柱状全景图，例如 6000 × 3000。
• 支持 JPG、JPEG、PNG、WebP。
• 每张图片的文件名必须唯一，建议使用 001.jpg、002.jpg 这样的连续编号。
• 导入后不要移动或删除原始图片，否则重新打开 Blender 项目时可能找不到全景环境。
• 最好提前知道每张图片的大致拍摄位置和拍摄正前方。

模型要求

• 模型应具有真实比例，并且所有全景点位与模型使用同一个 Blender 世界坐标。
• 地面、墙体和门洞应与真实空间对应。模型可以没有贴图，但不能只有散乱线条或不封闭的无效面。
• 如果模型由多个对象组成，可以设置一个父级对象作为“漫游模型”。
• 建议在导入模型后应用缩放，避免非等比缩放影响坐标和射线计算。
• 不要通过移动模型原点来修正全景点位，应移动模型对象或全景点位本身。

下载与安装

1. 前往下载中心，下载最新版 ZIP 安装包。
2. 打开 Blender，进入 编辑 > 偏好设置 > 插件。
3. 点击右上角菜单，选择 从磁盘安装。
4. 选择下载的 vision-power-roam-1.0.0.zip。
5. 搜索 Vision Power 步进漫游助手 并启用。
6. 回到 3D 视图，按 N 打开侧边栏。
7. 选择 步进漫游 标签，即可看到三步操作面板。

更新插件时，先在 Blender 插件管理中停用旧版本，再选择新的 ZIP 安装。已经制作的点位和模型保存在 .blend 项目中，不会因为更新插件消失。

面板说明

插件面板分为三个区域。

1. 准备空间

用于选择制作方式、导入全景图、创建基础房间或指定已有模型。

2. 放置全景点

显示当前项目中的所有点位。点击点位名称进行选择，点击眼睛按钮进入该点位的全景参考视图。

3. 检查并导出

显示当前项目的错误和建议。红色错误必须处理后才能导出；黄色建议不会阻止导出，但可能影响漫游效果。

制作方式一：从全景图开始

这种方式适合没有现成模型，但能够根据全景图判断房间结构的项目。

第一步：导入全景图

1. 在面板顶部选择 从全景图开始。
2. 点击 批量导入全景图。
3. 一次选择项目中的全部全景图。
4. 检查面板中的点位数量是否与图片数量一致。

插件会以图片文件名作为点位名称。名称相同的图片会被跳过，防止生成重复场景。

第二步：建立空间模型

1. 选择第一张全景图并点击眼睛按钮。
2. 点击 创建基础房间。
3. 在高级设置中调整房间宽度、深度、墙体高度和厚度。
4. 进入 Blender 编辑模式，根据全景画面调整墙体位置、门洞和房间轮廓。
5. 多房间项目可以继续拉伸或新建网格，但应保持所有空间位于同一世界坐标中。

基础房间只是建模起点，不是从图片自动恢复出的精确模型。普通全景图只记录颜色和方向，没有可靠深度，复杂建筑仍需要人工建模。

第三步：放置其他点位

对每张全景图重复以下操作：

1. 根据真实拍摄位置，把 Blender 的 3D 光标放到对应地面位置。
2. 选中全景点位，点击 移动到 3D 光标。
3. 选中正确的地面对象，点击 使用选中对象作为地面。
4. 点击 吸附到地面。
5. 点击眼睛按钮，检查全景图与周围墙体是否对应。

制作方式二：使用已有模型

这种方式适合已经通过人工建模、扫描、摄影测量或其他软件得到室内模型的项目。

1. 在 Blender 中导入 OBJ、FBX、GLB 等模型。
2. 检查模型方向、比例和地面高度。
3. 如果模型包含多个对象，选择共同父级；否则选择模型网格本身。
4. 在插件顶部选择 使用已有模型。
5. 点击 使用选中对象作为模型。
6. 选中地面网格，点击 使用选中对象作为地面。
7. 点击 批量导入全景图。
8. 按照实际拍摄位置放置所有点位。

模型没有贴图也可以用于漫游。播放器主要利用模型完成深度、遮挡和地面命中判断，但模型结构必须正确。

如何准确放置点位

水平位置

点位的 Blender X/Y 决定它在平面空间中的位置。点位应该位于真实拍摄位置，而不是房间几何中心。可以结合门口、墙角、柱子等明显参照物判断位置。

相机高度

插件默认相机高度为 1.65 米，可以在高级设置中修改。吸附到地面 会先向下检测地面，再把点位放到“地面高度 + 默认相机高度”。

多楼层项目必须先选择当前楼层对应的地面，否则点位可能吸附到错误楼层。

全景正前方

点位位置正确后，还需要校准全景图方向：

1. 点击点位右侧眼睛按钮进入全景参考视图。
2. 找到画面中的墙体、门或走廊方向。
3. 对照模型中相同结构。
4. 使用 左转 90°、右转 90° 或直接调整 正前方 数值。
5. 切换到相邻点位继续检查，确保空间方向连续。

如果全景图已经提前做过水平偏移，通常保持正前方为 0；如果使用未偏移原图，应保留插件中校准得到的旋转角度。

一键检查说明

插件当前会检查以下内容：

• 是否已经导入全景图和空间模型。
• 原始全景图文件是否仍然存在。
• 全景图是否接近 2:1 比例。
• 点位名称是否重复。
• 相机离地高度是否低于 0.8 米或高于 2.5 米。
• 点位是否可能落在模型平面范围外。
• 模型是否存在非等比缩放。
• 是否已经指定地面对象。

“点位可能在模型外”是范围提示，不代表模型一定错误；不规则模型可以结合 3D 视图人工确认。

导出文件说明

检查通过后点击 一键导出漫游包，选择保存目录。插件会创建带项目名和时间的文件夹，并生成：

插件会按照平台当前使用的 blender_obj_v4 规则转换坐标，不需要手动交换 X/Y 或镜像坐标轴。

上传到 Vision Power

1. 在项目的模型沙盘或步进漫游设置中上传 model.obj。
2. 上传 全景点数据.csv 并关联对应全景图。
3. 如果全景图没有提前做水平偏移，选择“未偏移/自动校正”，让播放器运行时应用 CSV 朝向。
4. 如果图片已经完成水平偏移，选择“已偏移”，避免再次旋转。
5. 保存后先在编辑器中依次切换所有场景，检查模型遮挡、鼠标落点和地面脚印。
6. 确认无误后再发布预览。

CSV 中的点位名称必须能与平台全景场景名称对应。建议 Blender 点位和平台全景图始终使用相同编号。

常见问题

安装后找不到插件面板

确认插件已经启用，然后回到 3D 视图，按 N 打开右侧栏，选择 步进漫游。插件不会出现在图片编辑器或渲染窗口的侧边栏中。

进入全景视图后看不到图片

检查原图是否被移动、改名或删除。重新导入图片后，再选择对应点位进入全景视图。

点击吸附后点位高度不正确

通常是地面对象选错，或者多楼层模型向下命中了其他楼层。选中当前楼层地面，再点击 使用选中对象作为地面 和 吸附到地面。

检查提示模型存在非等比缩放

在 Blender 中选中模型，确认尺寸正确后应用缩放。应用前请备份项目，避免影响已经完成的复杂修改。

点位全部偏移到模型外

检查模型和点位是否使用同一世界坐标，以及导入模型后是否单独移动过模型原点。不要在前端和 Blender 中重复交换坐标轴。

全景图与模型方向相反

先确认图片是否已经水平偏移，再检查点位正前方。未偏移图片应在 Blender 中校准并在平台选择自动校正；已偏移图片不要再次应用旋转。

模型没有贴图能否使用

可以。模型用于深度和碰撞判断，没有贴图也能工作；但地面、墙体、门洞和空间比例必须正确。

是否还需要旧版两个插件

不需要。新插件已经合并全景环境、基础建模、点位操作和 CSV/OBJ 导出。旧插件仅用于维护历史 .blend 项目。