图鉴升级为 3D 展厅后，旋转模型只是第一步。假设一个知识热点位于模型右侧，模型转过半圈后，热点应出现在左侧；与它关联的声音也需要随之换到左侧。若每次播放都使用同一个固定音频坐标，画面与声音就会脱节。
本实验把模型的 Y 轴旋转、观察距离与空间声源连接起来：导入带高斯数据的模型，调整角度，点击按钮生成当前位置的四秒方位测试音。它是离散快照试听，适合逐项核对坐标；滑动过程中不会连续更新正在播放的声源。
先把四套概念分清
同一个热点会经历局部坐标、场景坐标、听者相对坐标和音频输入坐标。模型局部坐标描述热点附着在模型哪里；场景坐标反映模型旋转后的实际位置；听者相对坐标需要减去观察者的位置；音频输入则必须符合音频节点的轴向与范围。
Demo 将一个测试热点固定在模型局部(1,0,0)。它是坐标标定点，并不自动识别模型中的某个展品，也没有把任意模型的一米都解释为真实世界的一米。正式展厅应由内容生产流程提供热点坐标和单位比例。
| 对象 | 本实验约定 |
|---|---|
| 模型 | 围绕 Y 轴旋转，原点位置不变 |
| 相机 | 位于(0,0,distance)，保持朝向场景原点，支持绕Z轴滚转180° |
| 测试热点 | 局部位置(1,0,0) |
| 音频坐标 | 右 X、上 Y、前 Z，三个分量限制在 [-5,5] |
这些约定让首个联动实验可以使用简单变换。未来如果加入相机平移、俯仰或任意朝向，必须使用完整视图变换，不能只改一个角度参数。
模型旋转与声源计算使用同一个状态
3D 页面保存水平旋转角、观察距离与相机滚转角。渲染控制器把角度写入 GSNode 的旋转四元数，同时把距离写入相机 Z 坐标。试听按钮直接读取这三个页面状态，避免再维护一份可能滞后的“音频角度”。
对局部点(x,y,z)，绕 Y 轴旋转后：
constworldX=Math.cos(yaw)*x+Math.sin(yaw)*z;constworldZ=-Math.sin(yaw)*x+Math.cos(yaw)*z;相机未滚转时，音频前向分量是distance - worldZ，高度保持为 y。启用画面翻转后，先用相机滚转的逆变换计算听者坐标：listenerX = cos(roll) * worldX + sin(roll) * y，listenerY = -sin(roll) * worldX + cos(roll) * y。相机滚转π时，听者的X、Y方向同时反号，前向分量保持不变。这个符号来自场景与音频轴向的对应关系，不是靠试听后随意加负号。
相机滚转为0时，局部点(1,0,0)在零度时位于右侧，在180度时位于左侧。这两个输入能直观检查符号；90度则用于观察深度变化。启用画面翻转后，左右方向随听者坐标一同翻转。
超过五米时，为什么不能分别截断 XYZ
场景允许较大的观察距离，而音频位置接口有自己的范围。直接把每个分量分别限制到 [-5,5] 看起来能消除报错，却可能改变声源方向。
例如相对位置(2,1,30)，分别截断会变为(2,1,5)，水平方向比例从2/30变成2/5，听觉上被拉向侧面。本实验对三个分量使用相同缩放系数：
constforward=distance-worldZ;constlistenerX=Math.cos(cameraRoll)*worldX+Math.sin(cameraRoll)*y;constlistenerY=-Math.sin(cameraRoll)*worldX+Math.cos(cameraRoll)*y;constscale=Math.min(1,5/Math.max(Math.abs(listenerX),Math.abs(listenerY),Math.abs(forward),0.001));return{x:listenerX*scale,y:listenerY*scale,z:forward*scale,scale:scale};这样(2,1,30)被映射到约(0.333,0.167,5)，各分量比例保持不变。代价是远距离被压缩，不能再把映射后的米数当作真实展厅距离。实际产品应根据导览场景选择方向优先、展厅分区、统一世界单位或限制活动范围。
一次点击保存一个完整快照
点击试听时，先计算声源位置，再调用普通空间渲染节点的固定摆位模式。后续即使继续移动滑块，本次四秒声音仍使用点击时的位置。按钮文字使用“试听声源快照”，让用户知道需要重新点击才能比较新位置。
constpoint=mapExhibitToAudio(1,0,0,this.yaw*Math.PI/180,this.distance,this.cameraRoll);constresult=awaitthis.audioService.play(0,point.x,point.y,point.z);页面回显映射后的 XYZ 与渲染耗时。这里的耗时只覆盖调用到 Native 返回 PCM，不包括用户听到声音的全部端到端延迟。若要测量交互延迟，还需把播放器创建、启动与输出路由等阶段纳入独立测量。
与空间音频基础篇相比，这一篇增加了坐标关联与同步契约。底层管线沿用同一服务，避免两个独立音频模块对错误码、停止行为和输出格式作出不同解释。
模型加载与声音不能互相拖住生命周期
导入模型经系统选择器获取文件，再复制到应用沙箱。GLB或PLY的基本文件头检查只能说明部分结构，不能证明里面有高斯数据；真正加载由 GSPlugin 完成，不合适的模型会进入加载失败路径。
模型成功加载后才允许试听。离开页面时同步使场景加载结果失效，并停止音频服务。Native 渲染若稍后返回，其代次已经过期，不会重新创建播放器。3D 场景同样有代次检查，防止返回后的异步模型结果继续持有资源。
快照声音使用程序生成的扫频信号，适合检查方向。它还不是讲解内容系统：展品选择、讲解文件、字幕、音量和播放进度都需要在后续内容会话中建立明确关联。
三个角度构成一组可手算的坐标用例
固定局部点 (1,0,0)、相机距离4、相机滚转0，按前面的公式得到下表。这些是公式预期值，不是设备输出记录，浮点测试应使用适当容差。
| yaw | worldX | worldZ | 音频前向 distance-worldZ |
|---|---|---|---|
| 0° | 1 | 0 | 4 |
| 90° | 0 | -1 | 5 |
| 180° | -1 | 0 | 4 |
在这三个点上缩放系数均为 1，便于单独检查旋转符号；再增加远距离样本检查等比例缩放，避免一次用例同时引入多个变量。相机位置或朝向约定改变后，应重新推导这张表，而不是沿用旧预期值修补新公式。
让实验结果能被另一个人复查
坐标测试可先独立于设备完成：零度热点应在右侧，180 度应在左侧；较大距离的映射应保持分量比例；NaN 或无穷数应被拒绝。这些测试发现的是变换和输入问题，不评价系统音效质量。
设备验收再使用同一模型、同一热点与同一耳机。保存零度和 180 度两个画面，同时记录对应音频参数与实际听感。截图可以呈现场景状态，无法单独证明声音具有方位感，因此还需要试听记录或音频采集证据。
后续若升级为连续导览，建议另设实时音频会话：在播放中更新声源参数，对位置采样节流并平滑处理，协调相机、模型和音频线程的时序。不能把每次手势变化都当作新的四秒离线渲染任务，那会产生任务积压和不连贯播放。
参考：HarmonyOS 7 空间与 AI 征文方向、SpatialRender 官方接口。
试听捕获的是哪一次视角
试听取当前视角生成声源快照，完成后把 PCM 交给播放器。选择模型和离页都会改变控制器生命周期，页面只接受仍属于本次操作的结果。这一入口播放离散片段；连续声场更新需要另建持续音频链。
exportinterfaceAudioPoint{x:number;y:number;z:number;scale:number;}/** 模型绕Y轴旋转后，将坐标变换到相机滚转后的听者坐标系，听者前方使用正Z。 */exportfunctionmapExhibitToAudio(x:number,y:number,z:number,yaw:number,distance:number,cameraRoll:number=0):AudioPoint{if(![x,y,z,yaw,distance,cameraRoll].every((value:number)=>Number.isFinite(value))){thrownewError('场景坐标必须为有限数值');}constworldX=Math.cos(yaw)*x+Math.sin(yaw)*z;constworldZ=-Math.sin(yaw)*x+Math.cos(yaw)*z;constforward=distance-worldZ;constlistenerX=Math.cos(cameraRoll)*worldX+Math.sin(cameraRoll)*y;constlistenerY=-Math.sin(cameraRoll)*worldX+Math.cos(cameraRoll)*y;// Preserve bearing by applying one uniform scale, not three independent clamps.constscale=Math.min(1,5/Math.max(Math.abs(listenerX),Math.abs(listenerY),Math.abs(forward),0.001));return{x:listenerX*scale,y:listenerY*scale,z:forward*scale,scale:scale};}import{common}from'@kit.AbilityKit';import{picker}from'@kit.CoreFileKit';import{Scene}from'@kit.ArkGraphics3D';import{SpatialSceneController}from'../services/SpatialSceneController';import{ModelRepository}from'../services/ModelRepository';import{SpatialAudioService}from'../services/SpatialAudioService';import{mapExhibitToAudio}from'../services/TourCoordinates';import{LabTheme}from'../common/LabTheme';import{describeError}from'../common/LabError';@Entry@Componentstruct TourPage{@Statescene:Scene|undefined=undefined;@Statestatus:string='选择带有 3DGS 数据的 GLB 或 PLY。普通网格或点云不等于高斯模型。';@Stateyaw:number=0;@Statedistance:number=4;@StatecameraRoll:number=0;@Statebusy:boolean=false;privateactive:boolean=true;privateaudioService:SpatialAudioService=newSpatialAudioService();@StateaudioStatus:string='试听模型局部点 (1, 0, 0) 的方位测试音';@StateaudioBusy:boolean=false;privatecontroller:SpatialSceneController=newSpatialSceneController();aboutToAppear():void{this.active=true;}aboutToDisappear():void{this.active=false;this.audioService.stop().catch(()=>{});this.scene=undefined;this.controller.dispose();}privateasyncselectModel():Promise<void>{if(this.busy){return;}this.busy=true;try{constcontext=this.getUIContext().getHostContext()ascommon.UIAbilityContext;constviewPicker=newpicker.DocumentViewPicker(context);constoptions=newpicker.DocumentSelectOptions();options.maxSelectNumber=1;constselected=awaitviewPicker.select(options);if(!this.active||selected.length===0){return;}awaitthis.audioService.stop();this.audioStatus='试听模型局部点 (1, 0, 0) 的方位测试音';this.scene=undefined;this.controller.dispose();consturi=awaitModelRepository.importModel(context,selected[0]);if(!this.active){return;}conststart=Date.now();constscene=awaitthis.controller.load(uri);if(this.active&&scene){this.scene=scene;this.yaw=0;this.distance=4;this.cameraRoll=0;this.status=`3DGS 模型加载完成 ·${Date.now()-start}ms`;}}catch(error){if(this.active){this.status=describeError(errorasError);}}finally{this.busy=false;}}privateasynclisten():Promise<void>{if(this.audioBusy){return;}this.audioBusy=true;try{constpoint=mapExhibitToAudio(1,0,0,this.yaw*Math.PI/180,this.distance,this.cameraRoll);this.audioStatus=`声源快照 (${point.x.toFixed(2)},${point.y.toFixed(2)},${point.z.toFixed(2)})m`;constresult=awaitthis.audioService.play(0,point.x,point.y,point.z);if(this.active&&result){this.audioStatus+=`· 渲染${result.renderMs}ms`;}}catch(error){if(this.active){this.audioStatus=describeError(errorasError);}}finally{this.audioBusy=false;}}build(){Column({space:12}){Text('有声展厅 · 视角与声源').fontSize(24).fontWeight(FontWeight.Bold).fontColor(LabTheme.ink)Button('选择 3DGS 模型').enabled(!this.busy).onClick(()=>{this.selectModel();})Text(this.status).fontSize(14).fontColor(LabTheme.muted)if(this.scene){Component3D({scene:this.scene}).width('100%').layoutWeight(1)}else{Text('等待模型').width('100%').layoutWeight(1).textAlign(TextAlign.Center)}Text(this.audioStatus).fontSize(13)Row({space:8}){Button('试听声源快照').fontSize(12).enabled(!!this.scene&&!this.audioBusy&&!this.busy).onClick(()=>{this.listen();})Button(this.cameraRoll===0?'画面翻转：关':'画面翻转：开').fontSize(12).enabled(!!this.scene&&!this.busy&&!this.audioBusy).onClick(()=>{this.cameraRoll=this.cameraRoll===0?Math.PI:0;this.controller.setView(this.yaw*Math.PI/180,this.distance,0,this.cameraRoll);})}Text(`水平旋转：${this.yaw}°`).fontSize(14)Slider({value:this.yaw,min:-180,max:180,step:1}).onChange((value:number)=>{this.yaw=value;this.controller.setView(value*Math.PI/180,this.distance,0,this.cameraRoll);})Text('观察距离').fontSize(14)Slider({value:this.distance,min:0.2,max:30,step:0.1}).onChange((value:number)=>{this.distance=value;this.controller.setView(this.yaw*Math.PI/180,value,0,this.cameraRoll);})Button('复位').onClick(()=>{this.yaw=0;this.distance=4;this.cameraRoll=0;this.controller.setView(0,4);})}.padding(20).height('100%').width('100%').backgroundColor(LabTheme.background)}}| 操作或边界 | 应检查的结果 |
|---|---|
| 选择新模型 | 清理旧场景和试听 |
| 试听开始后转动视角 | 已提交快照不被隐式篡改 |
| 退出页面 | 停止音频并释放场景 |
文件选择器返回有效新文件后，页面先等待音频服务停止，再解除旧场景并导入新模型。取消选择保持当前模型和试听状态；渲染阶段或播放器创建阶段的迟到音频结果由服务代次拦截并释放。
换模型资源合同、音频服务测试和构建结果见第12篇换模型清理旧试听。
order场景的真机联动结果
2026年9月24日，HBN-AL80/API26加载Apartment order版本，距离保持4、相机滚转π。水平角137°时页面回读声源(0.73,0.00,4.68)m，渲染耗时197ms；调到0°后回读(-1.00,-0.00,4.00)m，渲染耗时159ms。这两组回读与相机滚转后的坐标公式一致。
素材：SA3D_R&D_XP47，Stéphane Agullo，CC-BY-4.0；由Apartment SOG转换为PLY并重排字段。
0°重复运行时，系统音频日志记录Native节点实际接收(-1,0,4)，随后播放器Start SUCCESS、Stop SUCCESS和Release end。日志同时存在系统调度、权限与清理提示，保留在实测记录中。这组实验记录坐标传递与播放生命周期；对应耳机的方位主观试听单独安排，页面仍使用离散快照音频。
