3DGS 模型在 HarmonyOS 上怎么显示?从 GSPlugin 到 GSNode【鸿蒙心迹】

👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 HarmonyOS 的过程都记录在这里。
🛠️ 主要方向:ArkTS 语言基础、HarmonyOS 原生应用(Stage 模型、UIAbility/ServiceAbility)、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战,以及 Android → 鸿蒙的迁移踩坑与复盘。
🧭 内容节奏:从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘,让每篇都有可落地的代码与方法论。
💡 我相信:写作是把知识内化的过程,分享是让生态更繁荣的方式。
如果你也想拥抱鸿蒙、热爱成长,欢迎关注我,一起交流进步!🚀
前言
想在 HarmonyOS 应用里展示一个 3DGS 模型,通常第一个问题不是"代码怎么写",而是"这件事从哪里开始"。Spatial Recon Kit 把重建和渲染拆成了两段独立流程,如果只想做模型查看器,可以跳过重建直接走渲染路径。这篇文章就聚焦这条路:用 GSPlugin 加载一个 .splatv 文件,通过 GSNode 控制它显示出来。
一、重建和渲染是两回事
Spatial Recon Kit 包含两个阶段:端侧 3DGS 重建和 3DGS 渲染。
重建是从 AR 相机采集的图像序列中,在设备端直接生成 3DGS 模型(.splatv 文件)。这一阶段需要相机权限,依赖端侧 AI 推理能力,对设备硬件要求更高。
渲染是独立能力——给它一个 .splatv 文件,它负责把模型显示出来。不需要完整的重建流程就能使用。本文讨论的就是这条路径:已经有了模型文件,怎么让它在屏幕上渲染出来。
这一点在官方文档里有明确说明:
“3DGS 渲染是 Spatial Recon Kit 提供的一项独立能力,支持 3DGS 模型的加载与实时渲染,无需完整空间重建流程即可直接使用该渲染能力。”
对于只做模型展示场景的开发者,这条路少了很多前置依赖。
二、版本与设备:先确认这两点
API Level 要求:16(对应 HarmonyOS 5.0.2 及以上)
在动手写代码之前,这是第一个要核实的事情。低于这个版本的设备或 SDK 无法使用 Spatial Recon Kit 的任何能力。
其他几点需要明确:
- 不支持模拟器,必须用真机调试
- 目前支持搭载特定 NPU 的华为手机机型,平板、PC 等形态暂不在官方支持列表中
- 3DGS 渲染功能本身不需要额外权限;如果需要从沙箱以外的路径读取模型文件,需要确认文件访问能力
- DevEco Studio 版本要求 5.0.5 Release 及以上
三、工程配置
oh-package.json5
在模块的 oh-package.json5 中添加依赖:
{
"dependencies": {
"@hw-agconnect/spatial-recon": "^1.0.0"
}
}
添加后执行 ohpm install 同步依赖。
build-profile.json5
确认 compileSdkVersion 和 compatibleSdkVersion 不低于 16:
{
"app": {
"compileSdkVersion": 16,
"compatibleSdkVersion": 16
}
}
module.json5
3DGS 纯渲染场景无需额外声明权限。若后续接入端侧重建能力,需要增加 ohos.permission.CAMERA。
四、核心渲染流程
整个渲染链路由四个对象构成:
XComponent(Surface)
↓ surfaceId
GSPlugin(渲染引擎入口)
↓ createScene()
GSScene(场景容器)
↓ loadGSNode(path)
GSNode(模型节点)
理解这条链路,代码就很好理解了。
4.1 XComponent 挂载渲染表面
GSPlugin 的底层渲染需要一个原生 Surface,ArkUI 里通过 XComponent 提供这个 Surface:
// pages/GsViewerPage.ets
import { GSPlugin, GSScene, GSNode } from '@hw-agconnect/spatial-recon';
@Entry
@Component
struct GsViewerPage {
private xComponentController: XComponentController = new XComponentController();
private gsPlugin: GSPlugin | null = null;
private gsScene: GSScene | null = null;
private gsNode: GSNode | null = null;
build() {
Column() {
XComponent({
id: 'gsRenderSurface',
type: 'surface',
controller: this.xComponentController
})
.width('100%')
.height('100%')
.onLoad(async () => {
await this.initGSRenderer();
})
.onDestroy(() => {
this.releaseGSRenderer();
})
}
.width('100%')
.height('100%')
}
// ...
}
type: 'surface' 是必须的,这告诉 ArkUI 这个 XComponent 用于承载原生渲染内容。onLoad 回调里才能安全拿到 surfaceId。
4.2 加载 GSPlugin
private async initGSRenderer(): Promise<void> {
// 获取 XComponent 的原生 Surface ID
const surfaceId = this.xComponentController.getXComponentSurfaceId();
// 创建渲染插件,绑定到该 Surface
this.gsPlugin = await GSPlugin.create(surfaceId);
// 基于插件创建 3DGS 场景
this.gsScene = this.gsPlugin.createScene();
// 加载模型文件(路径指向应用沙箱内的 .splatv 文件)
const modelPath = getContext(this).filesDir + '/model/scene.splatv';
this.gsNode = await this.gsScene.loadGSNode(modelPath);
// 设置模型的初始状态
this.gsNode.position = { x: 0, y: 0, z: 0 };
this.gsNode.scale = 1.0;
this.gsNode.visible = true;
}
GSPlugin.create() 是异步的,它需要时间完成与底层渲染引擎的绑定,不能省掉 await。
4.3 释放资源
private releaseGSRenderer(): void {
if (this.gsNode) {
this.gsNode.dispose();
this.gsNode = null;
}
if (this.gsPlugin) {
this.gsPlugin.release();
this.gsPlugin = null;
}
}
XComponent 销毁时需要主动释放,否则底层渲染资源会泄漏。
五、GSNode 的三个核心属性
加载完成后,通过 GSNode 控制模型在场景里的表现:
| 属性 | 类型 | 说明 | 默认值 |
|---|---|---|---|
position | Vec3(含 x/y/z) | 模型在场景中的位置 | {x:0, y:0, z:0} |
scale | number | 整体缩放系数 | 1.0 |
visible | boolean | 是否渲染该节点 | true |
rotation | Quaternion | 旋转,四元数表示 | 单位四元数 |
调整位置让模型进入相机视野:
// 把模型往相机前方移动 3 个单位
if (this.gsNode) {
this.gsNode.position = { x: 0, y: 0, z: -3 };
this.gsNode.scale = 0.5;
}
visible = false 并不会销毁节点,只是跳过渲染,切换开销很小,适合做显示/隐藏切换。
六、相机与模型的关系
模型加载完却什么也看不到,大概率是相机和模型之间的位置关系没有对上。
通过 GSScene.getCamera() 可以拿到场景相机并调整参数:
// 获取相机,调整到能看见模型的位置
const camera = this.gsScene!.getCamera();
camera.position = { x: 0, y: 1, z: 5 }; // 相机位置
camera.lookAt = { x: 0, y: 0, z: 0 }; // 看向场景原点
camera.up = { x: 0, y: 1, z: 0 }; // 相机上方向
camera.update(); // 提交参数
默认情况下,GSPlugin 会自动绑定 XComponent 的触摸事件,支持:
- 单指拖动旋转模型视角
- 双指捏合缩放
- 双指平移
如果只需要静态展示,不需要额外处理手势,渲染器本身已经接管了这部分交互。
七、最小 3DGS 查看器完整代码
把以上步骤整合为一个可以参考的最小示例:
// pages/GsViewerPage.ets
import { GSPlugin, GSScene, GSNode } from '@hw-agconnect/spatial-recon';
@Entry
@Component
struct GsViewerPage {
private xComponentController: XComponentController = new XComponentController();
private gsPlugin: GSPlugin | null = null;
private gsScene: GSScene | null = null;
private gsNode: GSNode | null = null;
build() {
Stack() {
XComponent({
id: 'gsRenderSurface',
type: 'surface',
controller: this.xComponentController
})
.width('100%')
.height('100%')
.onLoad(async () => {
await this.initRenderer();
})
.onDestroy(() => {
this.releaseRenderer();
})
}
.width('100%')
.height('100%')
.backgroundColor(Color.Black)
}
private async initRenderer(): Promise<void> {
try {
const surfaceId = this.xComponentController.getXComponentSurfaceId();
this.gsPlugin = await GSPlugin.create(surfaceId);
this.gsScene = this.gsPlugin.createScene();
const modelPath = getContext(this).filesDir + '/model/scene.splatv';
this.gsNode = await this.gsScene.loadGSNode(modelPath);
this.gsNode.position = { x: 0, y: 0, z: 0 };
this.gsNode.scale = 1.0;
this.gsNode.visible = true;
// 调整相机到合适位置
const camera = this.gsScene.getCamera();
camera.position = { x: 0, y: 1, z: 5 };
camera.lookAt = { x: 0, y: 0, z: 0 };
camera.up = { x: 0, y: 1, z: 0 };
camera.update();
} catch (error) {
console.error('GsViewer', `Init failed: ${JSON.stringify(error)}`);
}
}
private releaseRenderer(): void {
this.gsNode?.dispose();
this.gsNode = null;
this.gsPlugin?.release();
this.gsPlugin = null;
}
}
这段代码只做一件事:把一个本地 .splatv 文件加载到屏幕上。没有额外的 UI 控制,也没有业务逻辑,便于理解核心链路。
八、容易踩坑的几个地方
1. getXComponentSurfaceId() 只能在 onLoad 回调之后调用
XComponent 的 onLoad 是 Surface 就绪的信号。如果在组件构建阶段(build())或 aboutToAppear() 里就去调用这个方法,Surface 还没准备好,拿到的 surfaceId 是无效的,GSPlugin.create() 会失败。
2. 模型文件路径问题
loadGSNode 接受的是本地文件路径,不是 rawfile 路径。如果模型文件打包在工程的 rawfile 里,需要先通过 resourceManager.getRawFileContent() 把文件复制到应用沙箱的 filesDir 下,再传路径给 loadGSNode。
直接传 rawfile 路径会导致加载失败,这一点容易混淆。
3. 模型加载后什么都不显示
最常见的原因是相机位置和模型位置不在彼此的视野范围内。3DGS 模型没有自动归一化到场景原点的机制,加载后模型的默认 position 是 {0,0,0},但如果相机位置也在原点,会出现视角穿透模型的情况。建议加载后先把相机拉到 z 轴正方向一定距离,再设置 lookAt 朝向原点。
4. GSPlugin.release() 的时机
release() 调用之后,与该 Plugin 关联的 GSScene 和 GSNode 都不能再使用。如果页面有切换到后台又回来的生命周期,需要考虑是否要重新初始化整个链路,而不是复用旧的 Plugin 实例。
5. 不支持模拟器
这个在开发阶段容易被忽略。模拟器上运行会直接报错,必须连真机调试,且目标机型需要在官方支持列表里。
九、排查流程参考
如果按文档写完代码却无法正常显示,可以按这个顺序排查:
- 确认 API Level:工程
compileSdkVersion和compatibleSdkVersion是否 ≥ 16 - 确认设备:目标机型是否在官方支持列表中,是否连真机而非模拟器
- 确认依赖:
oh-package.json5是否有@hw-agconnect/spatial-recon,ohpm install是否已执行 - 确认 surfaceId 时机:
GSPlugin.create()是否在onLoad回调里调用 - 确认文件路径:
.splatv文件是否已复制到filesDir,路径是否拼写正确 - 确认相机位置:相机是否能看到模型,
camera.update()是否已调用 - 查看 HiLog 日志:以
GsViewer或GSPlugin为关键词过滤,确认是否有错误信息
开发经验总结
- 渲染和重建可以完全分开。只做模型展示,不需要相机权限,不需要接入重建流程,直接从 GSPlugin 入手就够了
- 链路很清晰:XComponent → surfaceId → GSPlugin → GSScene → GSNode,每一步都有对应的接口,没有隐藏的中间状态
- 相机是最容易被忽略的一环。模型加载成功不等于能看见,相机和模型的相对位置需要单独调整
- 资源释放不能省。
gsNode.dispose()和gsPlugin.release()要和页面生命周期绑定好,尤其是有多个页面跳转的场景 - 设备约束是硬限制。API Level 16、特定机型、真机调试,这三条在开发早期就要确认,不要等到联调阶段才发现设备不支持
如果你现在已经有了一个 .splatv 模型文件,可以先用这个最小示例验证渲染链路是否正常,再往上叠加手势控制、UI 交互等业务逻辑。在这之前,值得关注的是:自己的 .splatv 文件是从哪里生成的,如果是用 Spatial Recon Kit 的端侧重建生成的,文件格式和坐标系与通用工具导出的会有差异,这会影响 position 和 scale 的初始值判断。
📝 写在最后
如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!
我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!
感谢你的阅读,我们下篇文章再见~👋
✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。
更多推荐



所有评论(0)