数字展厅里的展品需要从不同方向观察。平面图片适合快速浏览空间模型则让读者检查轮廓、遮挡关系和表面细节。把模型接入应用时除了第一帧画面还要处理文件来源、相机位置、加载失败和离开页面后的资源释放。实验提供一个独立的 3DGS 浏览器选择本地模型加载到原生 3D 场景通过两个滑块调整水平观察角度和距离再一键恢复初始视角。这条链路可以作为数字博物馆后续接入知识热点、空间讲解和展厅漫游的基础。先分清版本与模型类型HarmonyOS 7 对应的开发套件采用 API 26。Spatial Recon Kit 的基础 GSNode 渲染接口从 6.0.1(21) 已经提供API 26 增加了分块 3DGS 等能力。这里先建立基础加载和生命周期流程大场景实验再接入 TiledGSNode。基础渲染接口的起始版本应以 spatialRender API 文档为准。模型文件也要区分。GLB 是容器扩展名相同并不意味着内部数据相同传统 Mesh 模型通常以三角网格、材质和纹理描述物体3DGS 模型需要包含高斯表示及加载器支持的数据组织。把普通 Mesh GLB 交给 GSPlugin不能据此判断高斯渲染能力是否可用。实验使用文件选择器接收自有或合法授权的高斯 GLB 或 PLY。官方加载指南列出MP4、PLY、GLB三种格式本Demo只实现后两种导入。文件头检查只能排除明显损坏的数据实际是否具备可加载的高斯数据仍由 GSPlugin 判断。现有神兽插画也不能直接充当完整三维模型生成或重建模型属于单独的素材生产流程。文件选择与渲染分开处理系统文件选择器返回的 URI 承担访问授权渲染层需要稳定可读的输入。ModelRepository 负责打开选择结果、检查文件头再复制到应用沙箱。这样控制器接收的始终是沙箱文件 URI页面不需要管理文件描述符。实验设置128 MiB的模型导入上限这是Demo资源预算不是平台限制。GLB分支检查魔数、版本2和声明长度PLY分支读取至多64 KiB文件头检查格式声明、正整数顶点数、end_header以及其后存在数据。ASCII、大小端二进制PLY均可通过基本头部检查但这不验证全部属性和负载。两种文件分别复制到selected-model.glb和selected-model.ply不把PLY改名为GLB。文件描述符在finally中关闭。constheadernewDataView(buffer);if(count12||header.getUint32(0,true)!0x46546C67||header.getUint32(4,true)!2||header.getUint32(8,true)!stat.size){thrownewError(GLB 文件头或长度不合法);}awaitfileIo.copyFile(input.fd,destination);这个检查不是完整的格式验证器也不以文件后缀决定“3DGS 加载成功”。文件通过预检后仍然可能因数据布局、扩展、设备能力或资源压力加载失败。场景、相机和高斯节点的创建顺序Apartment 场景使用两份 PLY 对照原转换版本包含14个float字段order版本调整字段顺序并补上零法线。2026年9月24日在HBN-AL80/API26上固定水平旋转137°、距离4和相机Y0order版本显示可辨的家具与室内结构原转换版本仍呈粉色模糊画面。order版本的倒置通过相机绕Z轴滚转180°纠正关闭翻转后恢复倒置这一开关保留模型角度和相机位置。两个版本同时存在字段顺序及法线差异还需单变量样本区分具体原因见相机方向与文件版本对照。素材署名SA3D_RD_XP47 — Stephane AgulloCC-BY-4.0本图展示其转换模型的实机结果。转换方式、哈希、对照截图和计时范围见验证记录。控制器先取得默认 RenderContext加载 GSPlugin再创建 Scene。相机建立后设置裁剪面、视角和背景色最后调用 loadGSNode 把模型加入场景根节点。constcontextScene.getDefaultRenderContext();if(!context){thrownewError(当前设备无法创建 3D 渲染上下文);}context.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);constsceneawaitScene.load();constcamera:Cameraawaitscene.getResourceFactory().createCamera({name:LabCamera});camera.position{x:0,y:0,z:4};camera.nearPlane0.01;camera.farPlane1000;camera.fovMath.PI/3;camera.enabledtrue;constnodeawaitspatialRender.GSPlugin.loadGSNode(scene,{uri:uri,offset:0},scene.root);offset 是文件中数据的字节偏移本例取 0它不是模型位置。模型位置由节点的 position 调整。混淆这两个参数会把文件读取错误和空间坐标错误混在一起。初始相机位于 Z 轴正方向适合围绕原点组织的样本。对于原点远离物体、尺寸跨度很大的模型应先确认模型包围范围再调整中心、观察距离和裁剪面不要通过持续增大远裁剪面掩盖素材坐标问题。滑块怎样映射到空间变化页面保留 yaw、distance 和 cameraRoll 状态控制器将它们分别写入模型旋转、相机位置和相机朝向。水平旋转使用绕 Y 轴的四元数this.node.rotation{x:0,y:Math.sin(yaw/2),z:0,w:Math.cos(yaw/2)};this.camera.position{x:0,y:0,z:Math.max(0.2,Math.min(30,distance))};滑块显示角度进入控制器前换算成弧度。本例旋转模型、沿 Z 轴移动相机属于物体浏览交互自由漫游还需要相机平移、朝向与碰撞/边界策略。画面翻转把 cameraRoll 在0和π之间切换通过相机Z轴四元数滚转纠正当前样本的倒置它不改变模型的水平角或观察距离。复位同时恢复页面状态、相机滚转和控制器状态。处理“返回以后才加载完成”Scene.load、createCamera、loadGSNode 都有异步阶段。用户可能在等待期间离开页面也可能开始一次新的加载。控制器每次 dispose 都增加 generation加载开始记录当前值节点返回后再次比较。if(generation!this.generation){scene.destroy();returnundefined;}旧请求只释放自己的临时 Scene不向页面提交结果。当前请求发生异常时也销毁临时场景。页面退出时先解除 Component3D 使用的 scene 引用再销毁控制器持有的场景。模型选择按钮在一次操作期间禁用避免多个导入同时覆盖同一沙箱文件。这些规则让 Scene 的所有权保持清楚加载完成前属于局部操作结果仍有效时交给控制器过期或失败则就地释放。后续加入纹理、动画和音源也可以沿用同一归属关系。将所有权对应到释放动作资源持有阶段释放或交接选择器文件描述符检查与复制期间finally 关闭不交给页面保存临时 Scene场景与节点异步创建期间过期或失败立即销毁已接收 Scene控制器与页面展示期间页面解除引用后由控制器销毁沙箱模型文件导入完成后与渲染场景分开管理不因退出页面随意删文件generation 解决的是结果归属旧请求完成时不绑定新页面。它不会中断系统加载也不能弥补某条异常路径没有销毁 Scene 的问题。因此复查代码时需要同时检查代次判断和异常清理而不能只搜索是否存在 dispose。如何复现实验在支持该能力的设备安装实验应用打开“01 3DGS 空间渲染”选择合法高斯GLB或PLY。先检查模型是否完整可见再把水平角度调整到两个不同位置改变观察距离最后复位。场景应观察的结果正常模型节点加载完成模型可见角度变化改变画面普通或损坏 GLB明确报告错误不把空场景标为渲染成功取消选择保留当前状态不发起新加载加载中退出迟到结果不重新绑定页面临时 Scene 被释放连续进入退出对照内存与句柄记录检查是否持续增长验收截图应包含模型至少两个角度与复位画面空背景、入口页和加载提示不能替代渲染结果。性能记录应固定模型哈希、设备、系统版本和操作路线分别统计文件导入与引擎加载耗时。对数字博物馆来说这个浏览器可以先承载一件模型再逐步增加知识热点。热点绑定真实资料模型资源按进入页面时加载、离开时释放能让三维观察自然接入现有图鉴而无需将所有内容一次性改成空间场景。参考官方 3DGS 渲染 API、HarmonyOS 7 新能力。加载代次如何保护已退出的场景SpatialSceneController 在加载完成后再次比较代次过期结果销毁临时场景。视角控制只访问当前场景退出先使旧代次失效再释放资源。import{Scene,Camera}fromkit.ArkGraphics3D;import{spatialRender}fromkit.SpatialReconKit;exportclassSpatialSceneController{privatescene:Scene|undefinedundefined;privatecamera:Camera|undefinedundefined;privatenode:spatialRender.GSNode|undefinedundefined;privategeneration:number0;privateoriginalVignette:number0.4;privateoriginalFringe:number0.2;asyncload(uri:string):PromiseScene|undefined{this.dispose();constgenerationthis.generation;constcontextScene.getDefaultRenderContext();if(!context){thrownewError(当前设备无法创建 3D 渲染上下文);}context.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);constsceneawaitScene.load();try{constcamera:Cameraawaitscene.getResourceFactory().createCamera({name:LabCamera});camera.position{x:0,y:0,z:4};camera.nearPlane0.01;camera.farPlane1000;camera.fovMath.PI/3;camera.clearColor{r:0.06,g:0.09,b:0.13,a:1};camera.enabledtrue;constnodeawaitspatialRender.GSPlugin.loadGSNode(scene,{uri:uri,offset:0},scene.root);if(generation!this.generation){scene.destroy();returnundefined;}this.scenescene;this.cameracamera;this.originalVignettecamera.postProcess?.vignette?.intensity??0.4;this.originalFringecamera.postProcess?.colorFringe?.intensity??0.2;this.nodenode;returnscene;}catch(error){scene.destroy();throwerrorasError;}}setView(yaw:number,distance:number,cameraY:number0,cameraRoll:number0):void{if(!this.node||!this.camera||!Number.isFinite(yaw)||!Number.isFinite(distance)||!Number.isFinite(cameraY)||!Number.isFinite(cameraRoll)){return;}this.node.rotation{x:0,y:Math.sin(yaw/2),z:0,w:Math.cos(yaw/2)};this.camera.rotation{x:0,y:0,z:Math.sin(cameraRoll/2),w:Math.cos(cameraRoll/2)};this.camera.position{x:0,y:Math.max(-1,Math.min(1,cameraY)),z:Math.max(0.2,Math.min(30,distance))};}setEdgeEffectsDisabled(disabled:boolean):void{if(!this.camera){return;}// Mutate live proxies: replacing the root can dispose native child wrappers.constsettingsthis.camera.postProcess;if(settings?.vignette){settings.vignette.intensitydisabled?0:this.originalVignette;}if(settings?.colorFringe){settings.colorFringe.intensitydisabled?0:this.originalFringe;}}setApartmentView():void{if(!this.node||!this.camera){return;}// 此预设仅用于固定 Apartment 样本与独立渲染器的中心视角对照。this.node.rotation{x:0,y:0,z:0,w:1};this.camera.position{x:-4.33,y:-1.29,z:-4.85};this.camera.rotation{x:0,y:0,z:1,w:0};}dispose():void{this.generation;this.nodeundefined;this.cameraundefined;if(this.scene){this.scene.destroy();this.sceneundefined;}}}操作或边界应检查的结果加载未结束即退出迟到场景必须销毁不挂到页面重新进入再加载旧结果不能替换新场景视距越界收敛到控制器允许范围用最小样本区分加载成功与画质通过在HBN-AL80/API26上另外用945个高斯组成红、绿、蓝三个面板分别导入仅基础球谐字段的PLY和补零高阶字段的PLY。两份均显示可辨识的三列颜色补零版旋转47°时画面相应转动但两版都出现横向断缝不能据此认定画质通过。补零没有消除异常因此不能把现有公寓模型的模糊拉伸简单归因于缺少高阶球谐字段。这组素材是可复现的合成诊断样本不是实物重建产物也不替代真实场景验收。后续仍需核对渲染参数和场景观察位置截图、输入哈希及验证边界见最小样本真机对照。随后只将全部Y坐标增加0.0225其余字段保持不变横缝在真机截图中消失同一应用重新加载原始SH0后横缝再次出现。这将排查范围进一步缩小到坐标或投影相关因素但模型平移同时改变两者尚不能断言是零坐标解析缺陷也不建议直接平移真实素材作为修复。详见Y坐标对照证据。进一步保持原始PLY不变、只加载一次将相机Y从0切到-0.0225横缝消失复位到0后再次出现。该对照不支持“导入时永久丢弃零坐标行”的解释排查方向应转向相机相对位置及投影相关环节。实验页保留高度切换用于复现默认仍为0不把偏移作为正式修复。见相机连续对照。暗角和色边也应与模型问题分开在同一视口内将两项强度置零边缘变暗消失横向空洞仍在。恢复参数后中心亮度与首次画面不一致说明参数写回不能直接当成完整原生状态恢复当前诊断按钮不适合严格颜色质量比较需进一步核对缺省值和设置回读。此次没有关闭全部后处理详见强度对照及限制。后处理引用修正与源码依据2026-09-209月21日复测更新原位修改版本完成默认→强度归零→恢复的一轮真机对照。默认与恢复目视一致渲染区域规则网格抽样的 62160 个 RGB 通道值差异为 0之前中心明显变亮未复现横缝仍然存在。此结果只覆盖固定样本、本机和这次操作不代表整体画质验收通过。截图、包身份核验边界和抽样方法见真机复测记录。以下“尚未复测”描述保留为9月20日记录。上面的控制器已改为直接修改当前暗角、色边的强度避免替换整个后处理对象并复用可能失效的原生子对象引用。宿主测试与编译已通过新版真机视觉恢复尚未复测因此前述亮度差异仍是未关闭问题。开源实现还提供了投影特征向量退化的排查方向但没有证据证明鸿蒙 GSPlugin 使用相同实现。详见源码调查与验证边界。独立参考渲染对照2026-09-21同一 SH0 探针在 PlayCanvas 2.22.2 的两个相机高度下均没有横缝。Apartment 的原转换 PLY 在默认位置也模糊而相机移到近似中心并绕 Z 轴翻转后门窗、植物和室内结构清楚可辨。因此应先检查取景不能仅凭模糊画面判定格式不兼容。该中心位置还未在鸿蒙真机复测参考图也不能替代真机验收。参数、截图、输入校验和复跑方法见独立渲染器对照。Apartment 专用视角真机复测2026-09-21已把参考相机位置加入 Demo 的手动专用预设并验证复位恢复位置和朝向。真机画面会随预设改变但仍然粉色模糊、拉伸暗角与色边强度归零也未解决。该项画质验收仍未通过不应把独立渲染器里的清晰画面作为鸿蒙效果证明。输入身份核验限制、截图和下一步见专用视角实机记录。三点非均匀尺度探针2026-09-21新增红横、绿斜、蓝竖三个高斯椭圆的最小样本。参考渲染符合预期真机虽报告加载完成却只显示背景强度归零也未改善。因此本次尚不能判定旋转顺序错误应继续用相同点数的各向同性对照和点数递增实验区分原因。下载文件哈希一致应用沙箱复制结果仍待独立核验。详见三点探针记录。同点数尺度对照更新2026-09-21三点非均匀尺度和三点各向同性样本在真机上都只显示背景945 点非均匀尺度样本则可以显示六块 RGB 面板但行间出现横向间隙。说明“非均匀尺度单独导致三点不可见”证据不足点数/批量规模或渲染阈值更值得继续排查。参考渲染、真机截图和输入哈希见探针记录。945点各向同性密集对照2026-09-22与945点非均匀样本保持位置、颜色、透明度和四元数一致仅把三个尺度改为相同值。参考渲染和真机都能显示面板真机行间横缝仍在形态与非均匀样本一致。因此尺度各向异性不是主要解释继续排查行级投影/排序路径。详见各向同性密集探针记录。开源 16 点样本参考对照2026-09-23从 Apache-2.0 开源项目固定提交取得的 16-Gaussian PLY在真机文件选择器中导入并返回“加载完成”默认相机画面却为空白。同一 SHA-256 文件用 PlayCanvas 2.22.2、相同的主要默认相机参数独立渲染可以看到黄、灰、蓝色带。这证明该文件在独立渲染器里有可见内容却不能单独认定鸿蒙插件有缺陷应用沙箱副本、实际相机矩阵和视口尚未逐项核对。这份16点样本的默认视角仍为空白Apartment order版本的可辨场景与展厅联动另见9月24日实测。输入来源、真机与参考截图、可复跑参数见开源样本对照记录。