想展示 3D 模型？ArkGraphics 3D 和 Spatial Recon 怎么用

如果你要做一个"3D 模型查看器"——比如让用户在手机上查看一个 3D 扫描的房间、一个 3D 建模的产品，或者一个 AR 场景里的虚拟物体，HarmonyOS 提供了两套 3D 能力：

• ArkGraphics 3D：通用的 3D 场景管理，可以加载 glTF 模型、操作节点、设置材质和光照。
• Spatial Recon Kit：专门做 3DGS（3D Gaussian Splatting）渲染，适合展示空间扫描重建的结果。

今天我们来看看这两个 Kit 的基本用法。

ArkGraphics 3D 和 Spatial Recon Kit 的定位和能力对比：

ArkGraphics 3D：3D 场景的基础

ArkGraphics 3D 是 HarmonyOS 的 3D 图形基础模块，提供了场景（Scene）、节点（Node）、资源（Resources）等核心概念。

核心概念

Scene（场景）：整个 3D 世界的容器。你可以往里面添加模型、灯光、相机等元素。

Node（节点）：场景里的每一个"东西"都是一个节点。模型是节点、灯光是节点、相机也是节点。节点之间有父子关系，形成一棵"节点树"。移动父节点，子节点会跟着移动。

RenderContext（渲染上下文）：管理渲染资源和插件。加载 3D 模型、创建效果都需要通过它。

加载一个 glTF 模型

glTF 是 3D 模型的标准格式（就像图片的 JPG 一样）。ArkGraphics 3D 可以直接加载 glTF 文件：

import { Scene, RenderContext } from '@kit.ArkGraphics3D';

// 加载场景
Scene.load().then(async (scene: Scene) => {
  let uri = "OhosRawFile://assets/gltf/model.glb";
  let offset = 0;

  // 加载模型到场景根节点
  let node = await scene.load(uri, offset, scene.root);

  // 设置节点位置
  node.position = { x: 0, y: 0, z: -2 };  // 放在相机前方 2 米

  // 设置节点缩放
  node.scale = { x: 1, y: 1, z: 1 };

  // 设置节点可见性
  node.visible = true;
});

Scene.load() 创建一个新的场景。scene.load(uri, offset, parent) 加载一个 glTF 模型，并把它挂到指定的父节点下。

OhosRawFile:// 是 HarmonyOS 的资源路径协议，指向项目的 rawfile 文件夹。

节点操作

加载后的节点可以自由操作：

// 移动
node.position = { x: 1, y: 0, z: 0 };

// 缩放
node.scale = { x: 2, y: 2, z: 2 };

// 旋转（用四元数表示）
node.rotation = { x: 0, y: 0.707, z: 0, w: 0.707 };  // 绕 Y 轴旋转 90 度

// 显示/隐藏
node.visible = false;

获取渲染上下文

let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

渲染上下文是和渲染管线交互的入口。加载插件、创建效果等操作都需要通过它。

Spatial Recon Kit：3DGS 渲染

加载 3DGS 模型的完整流程如下：

3DGS（3D Gaussian Splatting）是一种新兴的 3D 重建和渲染技术。它通过大量"高斯点"来表示 3D 场景，每个高斯点有位置、颜色、大小等属性。渲染时，把这些高斯点"泼洒"到屏幕上，就能重建出逼真的 3D 场景。

和传统的三角形网格（glTF）相比，3DGS 的优势是：

• 渲染速度快（不需要光栅化三角形）
• 场景重建精度高（适合扫描真实环境）
• 文件体积可能更小

基本用法

import { Scene, RenderContext } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

// 1. 获取渲染上下文
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();

if (renderContext != null) {
  // 2. 加载 3DGS 插件（必须！）
  renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);

  // 3. 加载场景
  Scene.load().then(async (scene: Scene) => {
    let uri = "OhosRawFile://assets/gltf/model.glb";
    let offset = 0;

    // 4. 加载 3DGS 模型
    let gsNode: spatialRender.GSNode = await spatialRender.GSPlugin.loadGSNode(
      scene, { uri, offset }, scene.root
    );

    // 5. 设置节点属性
    gsNode.position = { x: 3, y: 0, z: 0 };
    gsNode.scale = { x: 1.5, y: 1.5, z: 1.5 };
    gsNode.visible = true;
  });
}

关键步骤：

1. loadPlugin：必须先加载 GSPlugin.PLUGIN_ID，否则后续调用会出问题。
2. loadGSNode：加载 3DGS 模型，返回一个 GSNode 对象。
3. GSNode 继承自 Node，所以可以用和普通节点一样的方式操作（position、scale、visible 等）。

特效

Spatial Recon Kit 还提供了几种视觉特效：

// 复古效果
renderContext.loadPlugin(spatialRender.GSPlugin.RETRO_EFFECT_ID);

// 漫画效果
renderContext.loadPlugin(spatialRender.GSPlugin.COMIC_EFFECT_ID);

// 黑白 bit 效果
renderContext.loadPlugin(spatialRender.GSPlugin.OBRA_DINN_EFFECT_ID);

// 颜色编辑效果
renderContext.loadPlugin(spatialRender.GSPlugin.COLOR_EDITING_EFFECT_ID);

这些特效可以给 3DGS 渲染结果加上不同的艺术风格。

完整示例：3D 模型查看器

import { Scene, RenderContext } from '@kit.ArkGraphics3D';
import { spatialRender } from '@kit.SpatialReconKit';

@Entry
@Component
struct ModelViewer {
  @State status: string = '加载中...';

  async aboutToAppear() {
    let renderContext = Scene.getDefaultRenderContext();
    if (renderContext == null) {
      this.status = '渲染上下文不可用';
      return;
    }

    // 加载 3DGS 插件
    renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);

    try {
      let scene = await Scene.load();
      let uri = "OhosRawFile://assets/gltf/model.glb";

      let gsNode = await spatialRender.GSPlugin.loadGSNode(
        scene, { uri, offset: 0 }, scene.root
      );

      gsNode.position = { x: 0, y: 0, z: -3 };
      gsNode.scale = { x: 1, y: 1, z: 1 };
      gsNode.visible = true;

      this.status = '模型加载成功';
    } catch (err) {
      this.status = `加载失败: ${err}`;
    }
  }

  build() {
    Column() {
      Text(this.status)
        .fontSize(18)
        .margin(20)

      // 3D 渲染区域（需要配合 Scene 组件）
    }
    .width('100%')
    .height('100%')
  }
}

小结

能力	Kit	用途
glTF 模型加载	ArkGraphics 3D	加载标准 3D 模型
节点操作	ArkGraphics 3D	移动、旋转、缩放
材质/光照	ArkGraphics 3D	设置外观
3DGS 渲染	Spatial Recon Kit	空间扫描重建
特效	Spatial Recon Kit	复古/漫画等艺术风格

ArkGraphics 3D 适合通用的 3D 场景，Spatial Recon Kit 适合空间扫描和 3DGS 数据。两者可以结合使用——在同一个场景里，既有 glTF 模型，也有 3DGS 渲染。

下一篇我们来看 XEngine Kit——GPU 加速引擎，看看怎么做 VRS、超分辨率和光线追踪。