在这里插入图片描述

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀

前言

用 XR Kit 的 3DGS 能力扫同一个物体,扫两遍,结果一次清晰完整,一次糊成一片、局部直接塌掉。参数没变,代码没变,问题出在哪?

大概率不是代码问题,是输入数据的问题。

3DGS(三维高斯泼溅)的端侧重建链路分三段:图像预处理 → 训练 → 渲染。每一段的质量都强依赖上一段的输出,而最上游的图像预处理,完全取决于你喂进去的图像序列质量。拍得不好,后面两步再跑也救不回来。

这篇文章就聚焦这一件事:输入图像序列怎么拍,才能让重建效果稳定。从官方文档里整理出四个维度:拍摄角度覆盖、光照条件、背景选择、素材覆盖程度,逐一拆开看。

一、先把能力边界搞清楚

HarmonyOS 通过 XR Kit 提供 3DGS 端侧重建能力。在正式讨论输入质量之前,有几个约束必须先确认。

支持设备: 仅 Phone(手机),模拟器不支持。
支持系统: HarmonyOS 5.0.2 及以上版本。
API Level: API 14。
Kit: XR Kit(@kit.XRKit)。
所需权限: ohos.permission.CAMERA(需在 module.json5 中声明,且为用户授权类型)。

这个能力目前不支持平板、折叠屏或 2in1 设备,仅限 Phone 真机。想用模拟器跑通流程是走不通的。

整个重建管线的顺序是固定的:

输入视频/图像序列
    ↓
图像预处理(Preprocessing)
    — 特征点提取 & 特征点匹配
    — 输出:相机位姿 + 初始 3D 点云
        ↓
3DGS 训练(Training)
    — 高斯椭球参数优化
    — 输出:高斯椭球参数
        ↓
3DGS 渲染(Rendering)
    — 指定视点光栅化渲染
    — 输出:渲染图像

图像预处理失败,训练就没有输入;训练效果差,渲染出来的结果就会糊或有伪影。这条链路的瓶颈往往卡在最前面的预处理环节,而预处理的质量几乎完全由输入的图像序列决定。

二、工程配置最小示例

在进入拍摄讨论之前,先把工程侧的配置确认好,避免权限问题干扰后续排查。

module.json5 权限配置:

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:camera_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

reason 字段必须指向 string 资源文件中的一个真实字符串,不能直接写裸字符串,否则上架审核阶段会被拦截。

核心调用流程(ArkTS):

这段代码按照官方文档提供的接口组织为最小示例,展示了从初始化到逐步推进三个阶段的基本结构。

import { xrKit } from '@kit.XRKit';

// 1. 初始化并配置
const gaussianSplatting = new xrKit.GaussianSplatting();

const config: xrKit.GaussianSplattingConfig = {
  inputType: xrKit.InputType.VIDEO,
  videoPath: '/data/storage/el2/base/files/input.mp4', // 需使用应用沙箱内的真实绝对路径
};

gaussianSplatting.start(config);

// 2. 图像预处理
const inputData: xrKit.InputData = gaussianSplatting.getInputData();

gaussianSplatting.preprocessing(inputData, (preprocessingResult) => {
  if (preprocessingResult.code !== 0) {
    // 预处理失败,重建无法继续
    console.error('preprocessing failed, code: ' + preprocessingResult.code);
    return;
  }

  console.log('preprocessing success');

  // 3. 3DGS 训练
  gaussianSplatting.training(preprocessingResult, (trainingResult) => {
    if (trainingResult.code !== 0) {
      console.error('training failed, code: ' + trainingResult.code);
      return;
    }

    console.log('training success, gaussian data size: ' + trainingResult.gaussianData.length);

    // 4. 渲染
    const renderConfig: xrKit.RenderConfig = {
      width: 1024,
      height: 1024,
      cameraPos: [0, 0, 3],
      cameraTarget: [0, 0, 0],
      cameraUp: [0, 1, 0],
      fovY: 45,
    };

    gaussianSplatting.rendering(trainingResult.gaussianData, renderConfig, (renderResult) => {
      if (renderResult.code === 0) {
        console.log('rendering success, image size: ' + renderResult.image.length);
      }
    });
  });
});

// 完成后释放资源
gaussianSplatting.release();

三个阶段各自有独立的回调,每个阶段的 code 字段是判断成功与否的入口。预处理失败不要继续往后调用训练接口,官方文档里的常见问题明确指出:预处理结果不好会直接影响训练效果,二者是强依赖关系。

三、四个维度,逐一拆开看

官方文档在"常见问题"部分对输入质量问题有明确说明。以下四个维度都来自官方资料中可查的原因描述,不是推测。

3.1 拍摄角度:覆盖不全是预处理失败最常见的原因

官方文档原文:

输入视频/图像序列覆盖不全:物体的某些角度没有被拍摄到,导致特征点匹配失败,相机位姿估计失败。

图像预处理做的事情是特征点提取和特征点匹配,它需要在相邻帧之间找到足够多的公共特征点,才能估算出每张图对应的相机位姿。如果某个方向只拍了一张或几张,相邻帧之间重叠区域太少,特征点匹配就会失败,位姿估计也跟着失败。

实际拍摄时,可以用下面这个思路组织路径:

  • 围绕物体水平 360° 匀速缓慢移动,保持匀速,避免急停急转;
  • 至少走一圈俯视角(从斜上方向下看),补充顶部信息;
  • 物体有明显内凹或遮挡区域时(比如杯子内壁、瓶口),需要额外补拍那些方向;
  • 拍摄过程中保持物体始终在画面中央,避免物体跑出镜头。

相邻帧之间的重叠程度是关键。如果走动太快,前后两帧的视角变化太大,公共特征点就会变少,位姿估计的精度会降低。

3.2 光照条件:强光和阴暗都是问题

官方文档原文:

光线条件不佳:在强光或阴暗条件下拍摄,导致特征点提取和匹配失败。

这里容易有一个误解:以为光线越亮越好。实际上强光(比如正午直射阳光、强聚光灯)和阴暗(光线严重不足)都会让特征点提取失败,只是失败的原因不同:

  • 过暗: 图像噪声高,细节丢失,特征点提取数量不足;
  • 强直射光或过曝: 高光区域细节饱和,同样提取不到有效特征点;
  • 侧逆光: 物体一侧过暗、一侧过亮,同一物体在不同帧里的光照差异过大,匹配容易出错。

比较稳定的拍摄光照是漫射光(阴天室外、均匀散光室内),物体各面亮度差异不大,特征点提取稳定性最好。

另外还有一类特殊情况——高度反光的物体。官方文档在训练效果不好的原因里提到:

物体表面反光:高度反光的物体(镜子、金属表面等)无法稳定提取特征点,导致重建效果差。

反光表面在不同拍摄角度下呈现出的高光位置是变化的,同一个物理位置在不同帧里看起来完全不同,特征点匹配自然跟不上。这类物体目前用 3DGS 重建效果就是有限制的,不是调参能解决的问题。

3.3 背景选择:复杂背景是特征点匹配的干扰源

官方文档原文:

背景复杂:背景有大量重复纹理或动态变化,干扰特征点匹配。

特征点匹配的算法不会自动区分"哪些是物体的点,哪些是背景的点"。背景里如果有大量重复纹理(比如砖墙、格子桌布、密集图案),算法可能把背景特征点误匹配到不同帧的不同位置,污染相机位姿估计的结果。

背景里有动态变化(人在走动、树叶在抖、风扇在转)的情况更糟,同一背景位置在相邻帧里出现了不同内容,这类"伪特征点"对位姿估计的干扰很难被完全过滤掉。

拍摄 3DGS 素材时,尽量选择简洁、静止的背景。纯色背景板是比较理想的选择,如果没有,至少确保背景里没有明显的动态元素。

3.4 素材覆盖程度:视角数量不足影响训练质量

官方文档在训练效果不好的原因里提到:

输入图像数量太少:训练所需要的图像视角信息不足,导致高斯椭球优化不充分。

图像数量和视角密度是两个维度:

  • 图像总数不够,高斯椭球参数优化的约束条件不足;
  • 某些区域的视角太稀疏(比如只绕了半圈,另外半圈没拍),那个区域的高斯椭球就无法得到充分优化,渲染时会出现伪影或模糊。

官方 Sample 的操作步骤描述的是视频输入模式,用摄像头持续录制一段视频作为图像序列。视频时长和帧率决定了实际送进预处理的图像数量。如果视频太短或者帧率太低,视角覆盖就会不充分。

渲染结果模糊还有另一条路径:

如果重建结果整体结构正确但细节模糊,可以适当增加训练迭代次数;如果某些区域出现明显伪影,通常是由于该区域缺乏足够的视角覆盖。

这两种现象对应的处理方向不同,细节模糊的可以调训练参数,伪影问题需要补充那个区域的视角覆盖,从源头解决。

四、几个容易理解错的地方

预处理失败 ≠ 代码写错了。 preprocessing 回调里 code 非零,第一反应往往是检查代码。但预处理失败最常见的原因是输入图像质量或覆盖问题,这些在日志里不会直接告诉你"是因为角度不够",只会给一个错误码。排查顺序应该是:先检查输入视频,再看代码。

videoPath 必须是应用沙箱内的绝对路径。 官方代码示例里写了 /data/storage/el2/base/files/input.mp4,这是应用沙箱路径的典型格式。如果把视频放在别的位置,或者用了相对路径,接口会找不到文件。视频需要先通过文件管理接口复制到应用的沙箱目录里。

三个阶段必须按顺序串行执行,不能并行。 训练依赖预处理的结果,渲染依赖训练的结果。每一步必须在上一步回调成功之后才能调用。这在逻辑上显然,但如果用了异步框架或者 Promise 链,容易写成并发触发。

gaussianSplatting.release() 的调用时机。 要在渲染完成之后才能调用 release(),如果在回调执行过程中提前释放,可能导致后续回调拿不到有效数据。官方示例里 release() 写在最外层,实际使用时需要根据异步回调的完成情况来决定何时调用。

该能力目前不支持模拟器。 官方 Sample 文档明确说明"运行 Sample 需要使用真机,模拟器不支持 3DGS 端侧重建"。在开发阶段如果想先跑通流程,必须连接真机。

五、排查清单

如果预处理阶段失败(code 非零),按这个顺序检查:

  1. 确认设备和系统版本: 是否是 Phone 真机,系统是否 HarmonyOS 5.0.2 及以上(API 14);
  2. 确认权限是否授权: ohos.permission.CAMERA 是否在 module.json5 中声明,用户是否在运行时授予了权限;
  3. 确认视频路径是否正确: videoPath 是否是应用沙箱内的绝对路径,视频文件是否存在;
  4. 检查输入视频质量: 分辨率是否足够,画面是否清晰(有没有严重运动模糊);
  5. 检查视角覆盖: 是否围绕物体拍了至少一圈,各方向是否都有覆盖;
  6. 检查拍摄光照: 光线是否均匀,有没有强直射光或严重过暗;
  7. 检查背景情况: 背景是否简洁,有没有大量重复纹理或动态变化。

如果预处理成功但训练效果差(渲染出来模糊或有伪影):

  • 伪影集中在某个区域 → 该区域视角覆盖不足,重新拍摄时补充那个方向;
  • 整体结构对但细节模糊 → 可以考虑增加训练迭代次数(需确认接口是否支持此参数配置);
  • 高度反光物体 → 这是当前能力的已知限制,拍摄条件优化效果有限。

开发经验总结

  • 3DGS 端侧重建属于 XR Kit,仅支持 HarmonyOS 5.0.2+(API 14),仅限 Phone 真机,模拟器无法使用;
  • 重建管线三段(预处理 → 训练 → 渲染)是强依赖链,输入图像质量是整条链路的决定性因素;
  • 预处理失败的四个主要原因官方文档都有说明:视角覆盖不全、光线不佳、背景复杂、图像分辨率/清晰度不足;
  • 高度反光的物体(镜子、金属表面)是当前 3DGS 重建的已知限制,不是调参问题;
  • videoPath 必须指向应用沙箱内的真实绝对路径,三个阶段必须串行执行,release() 须在所有回调完成后调用。

如果你正在用 3DGS 重建某个具体物体,可以先单独观察一下预处理阶段输出的点云数据量——点云太稀疏通常是视角覆盖或光照问题的直接信号,这个判断往往比等到渲染出来再看要早得多。

❤️ 如果本文帮到了你…

  • 请点个赞,让我知道你还在坚持阅读技术长文!
  • 请收藏本文,因为你以后一定还会用上!
  • 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
Logo

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

更多推荐