3d-virtual-tour

3D 虚拟导览

通过移动、地标和直接导航，帮助访客了解一个地点。确保路线、摄像机、房间标签和控件彼此一致。

规划导览模式

检查场景、坐标系、比例、楼层高度、门洞、渲染器、摄像机控件和资源加载路径。保留现有架构和交互。根据体验的实际需求选择导航模式：

模式	摄像机控制者	导航方式
导览路线	预设路线采样器	滚动、播放/暂停或上一个/下一个停靠点
房间目的地	预设房间姿态或路线停靠点	房间列表、热点或楼层平面图
查看	有边界的轨道控制器	拖动、双指缩放、缩放和返回
自由行走（按需启用）	带碰撞检测的第一人称控制器	移动和视角控制

对于 Seijaku 风格的体验，先采用导览路线、房间目的地和可选的模型查看功能。仅在用户要求或确有需要时添加自由行走；单靠轨道控制无法在室内行走。如果源内容只有一组全景图像，应使用相互链接的全景视点，而不要暗示其中包含可导航的几何空间深度。

沿真实门洞设计路线

将路线关键帧存储为进度/时间、位置、注视目标或朝向，以及视野。将停靠点存储为稳定的 ID、标签、路线坐标和关联的资源组。使路线坐标独立于页面高度或动画时钟，以便房间链接不受布局变更影响。

在狭窄门洞之前、之中和之后布置关键帧。使用相对于地面的眼睛高度，考虑抬高的地板和台阶，并在转弯或重要视点前减速。保持地平线稳定，避免同时大幅改变位置、注视方向和视野。应优先选择符合物理实际的比例，而不是使用过宽的镜头拉伸房间。

使用按时间参数化的 Hermite 插值、合适的样条曲线或预设动画。Seijaku 使用非均匀定时的 Hermite 关键帧来控制位置、注视方向和视野。向心样条也是一种实用选择，但任何平滑曲线都可能在无碰撞的关键帧之间切角。检查完整的插值路径，包括摄像机近裁剪面的净空，确保其不与墙壁、天花板、家具和门框相交。

曲线参数并不自动等同于距离或行进时间。若需要大致恒定的速度，请使用弧长采样；也可以有意调整分段时间，以便暂停并展现地标。查看 Curve，了解已安装渲染器的参数化方法。

使用朝向关键帧时，应通过四元数球面线性插值（slerp）进行朝向插值。如果插值注视目标，应避免目标越过摄像机或与其重合，否则方向可能翻转。视野或宽高比发生变化时，应更新投影矩阵。

让一个控制器最终掌控摄像机

使用小型导航状态机，并确保每帧只对摄像机进行一次最终写入。输入只请求状态变更；路线采样器、环绕控制器和过渡处理程序不得同时独立修改实时摄像机。

进入查看模式时，应保存当前路线坐标、当前站点、播放状态，以及任何滚动书签。从查看者当前所在的建筑一侧选择兼容视角，初始化查看模式。查看期间冻结引导式路线的推进。

使用经过验证的过渡路径，在交接过程中混合位置、朝向和视野。室内到室外环绕视角的直线路径可能穿过屋顶；即使是向上的弧线路径，也需要检查。使用安全航点；如果没有可信的连续路径，则短暂淡出并直接切换到目的地。将环绕距离和俯仰角限制在预期查看区域内。

返回时，恢复已保存的引导状态，使滚动位置同步，清除过期的拖动速度，并且仅在之前正在播放时恢复播放。禁用非活动控制器和过期的阻尼更新，避免它们在过渡后拉动摄像机。新的导航请求应根据当前视角替换待处理的目的地，而不是排队播放多个相互竞争的补间动画。

连接房间、地图和控件

让房间卡片、章节导航栏、平面图区域和场景热点共用同一站点注册表。使用明确的世界坐标到平面图坐标变换；不要假设平面图的纵轴与世界 Z 轴一致。在边界处使用滞回机制，避免当前房间或路线段的高亮闪烁。

选择房间时，应沿安全的连接路线前往，或有意切换场景并淡入淡出。不要让摄像机沿直线插值穿过多堵墙。如果存在已选标签和 URL 状态，应让它们与实际目的地保持同步；仅在有意义的导航发生时更新浏览器历史，而不是每帧更新。

为站点使用语义化 HTML 按钮或链接，并在图形地图旁提供可通过键盘访问的房间列表。为热点添加标签，确保焦点清晰可见，并在退出时将焦点恢复到查看模式触发控件。按下 Escape 键或点击可见的“返回”按钮，应能退出查看模式。

在可滚动页面上，除非查看者明确进入交互模式，否则触摸手势应继续用于页面滚动。仅在活动画布区域内捕获指针并设置 touch-action。处理指针取消、失去捕获和窗口失焦；退出时恢复先前的滚动样式。不要拦截表单或无关页面控件上的滚轮或键盘输入。

让场景与导航同步

根据当前路线坐标驱动路线相关的门、说明文字和曝光效果，使向后定位或跳转到某个房间时能立即呈现正确的场景。仅依赖计时器的事件可能导致跳转后摄像机路径上的门仍然关闭。除非导览明确负责控制这些设置，否则应保留用户选择的季节和灯光覆盖设置。

根据路线距离预加载即将到达的房间资源，并在显示直接选定的目的地之前加载该目的地。加载期间显示有用的占位内容或保持视图稳定；可选资源加载失败不应阻止导航。缓存共享纹理和网格，并在收到新请求后取消或忽略过期的目的地加载任务。

仅在区域可见性与当前摄像机模式保持一致时使用它。沿引导式路线隐藏的区域，在查看者环绕模型时可能变得可见。查看期间应重新计算可见性或启用所需区域，避免露出缺失的墙壁或房间。

如果包含自由行走模式，应将移动限制在可行走表面上，并提供碰撞和间隙检查。指针锁定提供的是视角输入，不会处理碰撞或贴地移动。为触屏用户提供等效的导航方式，并提供退出沉浸式控件的可见入口。

动效、加载与生命周期

使用基于帧时间的插值，并在页面隐藏后重置时间基准。页面隐藏时暂停播放和不必要的渲染。在减少动态效果设置下保留静态且信息丰富的视图；房间按钮应直接切换到构图完成的视图，而无需长时间移动摄像机。仅在用户操作后启动音频，并在导航过程中保留静音状态。

只保留一个渲染循环，重复使用临时对象，并避免在指针处理程序中读取布局或进行大量内存分配。优先准备起始房间，并将耗费较大的场景生成、纹理上传和着色器准备分散到合适的阶段。同步调整摄像机取景和渲染目标；优化窄屏视图的构图时，不要让摄像机移入几何体。导览卸载时，移除事件监听器、释放指针捕获并释放自行创建的资源。

验证

• 正向和反向走完整条路线；检查每个起始点、高度变化以及室内外切换。
• 从房间列表和楼层平面图中选择每个房间；确认标签、门、资源和摄像机目标一致。
• 从起点、室内和终点进入检查模式；拖动／缩放，然后返回完全相同的停靠点和播放状态。
• 使用另一个目的地、Escape、调整窗口大小或切换到隐藏标签页中断过渡；确认只有一个摄像机控制方处于活动状态，且滚动锁定不会卡住。
• 测试键盘导航、触摸滚动、指针取消、减少动态效果设置以及资源加载失败。
• 检查桌面端和纵向布局、着色器／控制台错误、起始加载、目标加载和交互时的帧耗时。

参考

阅读 REFERENCES.md，了解 Seijaku 的 KEYS、interp、Film、Orbit、_rooms、_plan 和 goTo 实现，以及相关摄像机 API。其引导式漫游和室外检查是可参考的技巧。基于碰撞的自由漫游以及上述额外的无障碍检查属于实现建议，并非对该参考项目功能的描述。