👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 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 控制模型在场景里的表现:

属性类型说明默认值
positionVec3(含 x/y/z)模型在场景中的位置{x:0, y:0, z:0}
scalenumber整体缩放系数1.0
visibleboolean是否渲染该节点true
rotationQuaternion旋转,四元数表示单位四元数

调整位置让模型进入相机视野:

// 把模型往相机前方移动 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. 不支持模拟器

这个在开发阶段容易被忽略。模拟器上运行会直接报错,必须连真机调试,且目标机型需要在官方支持列表里。

九、排查流程参考

如果按文档写完代码却无法正常显示,可以按这个顺序排查:

  1. 确认 API Level:工程 compileSdkVersion 和 compatibleSdkVersion 是否 ≥ 16
  2. 确认设备:目标机型是否在官方支持列表中,是否连真机而非模拟器
  3. 确认依赖:oh-package.json5 是否有 @hw-agconnect/spatial-recon,ohpm install 是否已执行
  4. 确认 surfaceId 时机:GSPlugin.create() 是否在 onLoad 回调里调用
  5. 确认文件路径:.splatv 文件是否已复制到 filesDir,路径是否拼写正确
  6. 确认相机位置:相机是否能看到模型,camera.update() 是否已调用
  7. 查看 HiLog 日志:以 GsViewer 或 GSPlugin 为关键词过滤,确认是否有错误信息

开发经验总结

  • 渲染和重建可以完全分开。只做模型展示,不需要相机权限,不需要接入重建流程,直接从 GSPlugin 入手就够了
  • 链路很清晰:XComponent → surfaceId → GSPlugin → GSScene → GSNode,每一步都有对应的接口,没有隐藏的中间状态
  • 相机是最容易被忽略的一环。模型加载成功不等于能看见,相机和模型的相对位置需要单独调整
  • 资源释放不能省。gsNode.dispose() 和 gsPlugin.release() 要和页面生命周期绑定好,尤其是有多个页面跳转的场景
  • 设备约束是硬限制。API Level 16、特定机型、真机调试,这三条在开发早期就要确认,不要等到联调阶段才发现设备不支持

如果你现在已经有了一个 .splatv 模型文件,可以先用这个最小示例验证渲染链路是否正常,再往上叠加手势控制、UI 交互等业务逻辑。在这之前,值得关注的是:自己的 .splatv 文件是从哪里生成的,如果是用 Spatial Recon Kit 的端侧重建生成的,文件格式和坐标系与通用工具导出的会有差异,这会影响 position 和 scale 的初始值判断。

📝 写在最后

如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!

我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!

感谢你的阅读,我们下篇文章再见~👋

✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐