HarmonyOS 7 / API 26 3DGS 采集质量门禁：低纹理、反光和运动模糊如何提前拦住

问题先说清楚

3DGS 端侧重建最怕的问题，不是代码跑不起来，而是采集素材一开始就不适合重建。页面看起来已经拍了几十帧，进度条也在走，最后却出现模型碎、表面发飘、局部空洞、纹理糊成一片。这类问题如果等到重建结束再提示，用户已经浪费了时间，开发者也很难从日志里判断到底是哪一段素材坏了。

HarmonyOS 7 / API 26 把 3D 图形、空间能力和端侧计算场景继续往前推，做 3DGS 相关功能时，我更建议把“采集质量门禁”放在重建前面。也就是说，先判断当前素材能不能进入重建，再决定是继续采集、补拍某个角度，还是直接降级成普通 3D 预览。

这篇只讲一个点：采集质量门禁。它不是官方名词，也不是为了堆概念，而是开发时很容易踩到的一层保护：把低纹理、反光、运动模糊、角度覆盖不足这些问题提前拦住。

为什么采集阶段要单独做门禁

3DGS 的结果质量很依赖输入素材。素材不好，后面的算法再努力也只能尽量补救。开发上常见的失败链路大概是这样：

所以我会把采集质量拆成三个维度：画面质量、运动稳定性、覆盖完整度。三个维度都过线，才进入重建；只要有一个维度明显不够，就让用户补采，而不是硬跑。

案例一：低纹理和反光素材提前拦截

第一个案例先看“画面本身适不适合重建”。比如拍一个白色杯子、白墙、亮面锅盖。肉眼看起来没问题，但算法拿到的是缺少稳定特征点的画面。结果就是重建出来的表面没有可靠支撑。

我会先在采集帧上做一个轻量评分，不追求替代底层算法，只做进入重建前的风险判断。

type CaptureRisk = 'ok' | 'lowTexture' | 'reflective' | 'blurred' | 'tooDark';

interface FrameQualitySample {
  frameId: string;
  sharpness: number;       // 0 - 100，越高越清晰
  textureScore: number;    // 0 - 100，越高纹理越丰富
  highlightRatio: number;  // 0 - 1，高光区域占比
  exposure: number;        // 0 - 100，过暗过亮都不好
}

interface FrameQualityResult {
  usable: boolean;
  risk: CaptureRisk;
  score: number;
  message: string;
}

export class ThreeDgsFrameQualityGate {
  evaluate(sample: FrameQualitySample): FrameQualityResult {
    if (sample.sharpness < 45) {
      return this.reject('blurred', 35, '画面有明显运动模糊，建议放慢移动速度后重新采集');
    }
    if (sample.textureScore < 38) {
      return this.reject('lowTexture', 40, '当前画面纹理太少，建议换一个有边缘、有花纹的角度');
    }
    if (sample.highlightRatio > 0.32) {
      return this.reject('reflective', 42, '高光区域太多，亮面材质会影响重建稳定性');
    }
    if (sample.exposure < 25 || sample.exposure > 85) {
      return this.reject('tooDark', 45, '曝光不稳定，建议调整光线后继续采集');
    }

    const score = Math.round(
      sample.sharpness * 0.35 +
      sample.textureScore * 0.4 +
      (1 - sample.highlightRatio) * 100 * 0.15 +
      sample.exposure * 0.1
    );
    return { usable: score >= 60, risk: 'ok', score, message: '当前帧可以参与重建' };
  }

  private reject(risk: CaptureRisk, score: number, message: string): FrameQualityResult {
    return { usable: false, risk, score, message };
  }
}

这段代码的重点不是几个阈值有多神，而是把“能不能继续采集”从 UI 感觉变成可解释的判断。比如同样是失败，低纹理和反光的处理方式就不一样：低纹理要换角度或增加参照物，反光要调整光线或避开亮面。

复现方式

可以准备两组素材：

1. 白墙、纯色桌面、无明显边缘的物体，纹理分低；
2. 不锈钢杯、亮面锅盖、玻璃杯，高光比例高。

3. 把这两组素材分别送进评分器，页面不应该直接开始重建，而是提示用户补采。这样做的收益很直接：失败不会拖到最后一刻才暴露，用户也知道下一步该怎么拍。

   案例二：移动过快和角度覆盖不足

   第二个案例更接近真实采集过程。用户绕着物体拍一圈时，经常会出现两个问题：一是手机移动太快，帧之间变化过大；二是只拍了正面和侧面，没有补顶部、背面和底部边缘。

   这时只看单帧质量不够，还要看一组帧之间的稳定性和覆盖情况。

   interface CapturePoseSample {
     timestamp: number;
     yaw: number;       // 水平方向角度
     pitch: number;     // 俯仰角
     motionDelta: number; // 与上一帧的位移变化，越大越不稳定
   }
   
   interface CoverageReport {
     stable: boolean;
     coveragePercent: number;
     missingAngles: string[];
     suggestion: string;
   }
   
   export class ThreeDgsCoverageGate {
     analyze(samples: CapturePoseSample[]): CoverageReport {
       if (samples.length < 12) {
         return {
           stable: false,
           coveragePercent: 0,
           missingAngles: ['front', 'left', 'right', 'back'],
           suggestion: '采集帧太少，先绕物体慢速拍一圈'
         };
       }
   
       const unstableCount = samples.filter(item => item.motionDelta > 18).length;
       const yawBuckets = this.buildYawBuckets(samples);
       const missingAngles = this.findMissingAngles(yawBuckets);
       const coveragePercent = Math.round((4 - missingAngles.length) / 4 * 100);
   
       if (unstableCount > samples.length * 0.25) {
         return {
           stable: false,
           coveragePercent,
           missingAngles,
           suggestion: '移动速度偏快，建议放慢手持速度后补采缺失角度'
         };
       }
   
       if (coveragePercent < 75) {
         return {
           stable: true,
           coveragePercent,
           missingAngles,
           suggestion: '角度覆盖不足，建议补拍：' + missingAngles.join('、')
         };
       }
   
       return {
         stable: true,
         coveragePercent,
         missingAngles: [],
         suggestion: '采集稳定，角度覆盖满足进入重建的最低要求'
       };
     }
   
     private buildYawBuckets(samples: CapturePoseSample[]): Record<string, number> {
       const buckets = { front: 0, left: 0, right: 0, back: 0 };
       for (const item of samples) {
         const yaw = ((item.yaw % 360) + 360) % 360;
         if (yaw >= 315 || yaw < 45) buckets.front += 1;
         else if (yaw >= 45 && yaw < 135) buckets.right += 1;
         else if (yaw >= 135 && yaw < 225) buckets.back += 1;
         else buckets.left += 1;
       }
       return buckets;
     }
   
     private findMissingAngles(buckets: Record<string, number>): string[] {
       return Object.entries(buckets)
         .filter(([, count]) => count < 3)
         .map(([name]) => name);
     }
   }

   这里我没有写成“拍够多少张就行”，因为帧数不是唯一标准。拍 80 张同一个角度，仍然不如 30 张覆盖完整的素材有价值。对 3DGS 来说，稳定移动和角度覆盖比单纯堆数量更重要。

   放到页面里怎么组织状态

   采集页不应该只有一个“开始重建”按钮。更稳的做法是把状态拆开：采集中、质量不足、需要补采、可以重建、重建中、重建完成。这样用户能看懂为什么按钮不可点，开发者也能把问题定位到具体阶段。

   type CaptureStage = 'collecting' | 'needMoreFrames' | 'needBetterQuality' | 'readyToReconstruct' | 'reconstructing' | 'done';
   
   interface CaptureGateState {
     stage: CaptureStage;
     canStartRecon: boolean;
     primaryTip: string;
     detailTips: string[];
   }
   
   export class ThreeDgsCaptureGateController {
     constructor(
       private frameGate: ThreeDgsFrameQualityGate,
       private coverageGate: ThreeDgsCoverageGate
     ) {}
   
     buildState(frames: FrameQualitySample[], poses: CapturePoseSample[]): CaptureGateState {
       const badFrames = frames
         .map(frame => this.frameGate.evaluate(frame))
         .filter(result => !result.usable);
   
       if (frames.length < 12) {
         return {
           stage: 'needMoreFrames',
           canStartRecon: false,
           primaryTip: '素材还不够，先慢速绕物体采集一圈',
           detailTips: ['至少覆盖正面、左右侧和背面', '移动速度保持稳定，不要突然转向']
         };
       }
   
       if (badFrames.length > frames.length * 0.2) {
         return {
           stage: 'needBetterQuality',
           canStartRecon: false,
           primaryTip: '部分素材质量不足，建议补拍后再重建',
           detailTips: Array.from(new Set(badFrames.map(item => item.message))).slice(0, 3)
         };
       }
   
       const coverage = this.coverageGate.analyze(poses);
       if (!coverage.stable || coverage.coveragePercent < 75) {
         return {
           stage: 'needBetterQuality',
           canStartRecon: false,
           primaryTip: coverage.suggestion,
           detailTips: coverage.missingAngles.map(angle => '缺少角度：' + angle)
         };
       }
   
       return {
         stage: 'readyToReconstruct',
         canStartRecon: true,
         primaryTip: '素材质量满足要求，可以开始生成 3DGS 结果',
         detailTips: ['采集覆盖完整', '移动速度稳定', '画面清晰度满足要求']
       };
     }
   }

   这层控制器的好处是可以复用。采集页可以直接用它控制按钮、提示文案和重建入口；测试里也可以用它喂不同素材，验证页面不会把低质量素材放过去。

   两种处理方式对比

   方案	优点	问题	我会怎么选
   不做门禁，直接重建	开发最快	失败后才暴露，用户等待成本高	只适合内部 Demo
   只看帧数	实现简单	不能识别低纹理、反光和模糊	不建议单独使用
   单帧质量 + 覆盖分析	能提前拦截多数失败素材	需要维护阈值和提示策略	正式功能优先选这个
   等底层重建返回错误再处理	接入成本低	错误原因晚，页面体验差	只能当兜底

   我的选择是第三种：单帧质量加覆盖分析。原因很简单，它不要求页面知道重建算法的全部细节，但能把最常见的失败提前挡住。开发成本可控，效果也能被测试验证。

   怎么验证这套门禁不是摆设

   我会准备四类测试数据：

   const lowTextureFrames: FrameQualitySample[] = [
     { frameId: 'wall-1', sharpness: 80, textureScore: 20, highlightRatio: 0.05, exposure: 55 },
     { frameId: 'wall-2', sharpness: 78, textureScore: 24, highlightRatio: 0.04, exposure: 58 }
   ];
   
   const reflectiveFrames: FrameQualitySample[] = [
     { frameId: 'metal-1', sharpness: 72, textureScore: 60, highlightRatio: 0.46, exposure: 70 },
     { frameId: 'metal-2', sharpness: 70, textureScore: 58, highlightRatio: 0.39, exposure: 68 }
   ];
   
   const stablePoses: CapturePoseSample[] = [
     { timestamp: 1, yaw: 0, pitch: 0, motionDelta: 6 },
     { timestamp: 2, yaw: 60, pitch: 2, motionDelta: 7 },
     { timestamp: 3, yaw: 120, pitch: 1, motionDelta: 8 },
     { timestamp: 4, yaw: 180, pitch: 0, motionDelta: 7 },
     { timestamp: 5, yaw: 240, pitch: -2, motionDelta: 6 },
     { timestamp: 6, yaw: 300, pitch: -1, motionDelta: 7 },
     { timestamp: 7, yaw: 20, pitch: 1, motionDelta: 6 },
     { timestamp: 8, yaw: 90, pitch: 1, motionDelta: 8 },
     { timestamp: 9, yaw: 160, pitch: 0, motionDelta: 7 },
     { timestamp: 10, yaw: 210, pitch: -1, motionDelta: 6 },
     { timestamp: 11, yaw: 280, pitch: -1, motionDelta: 8 },
     { timestamp: 12, yaw: 340, pitch: 0, motionDelta: 7 }
   ];

   验证时只看三个结论：

   • 低纹理素材必须被拦截；
   • 高反光素材必须给出明确提示；
   • 角度覆盖完整、移动稳定的数据才能打开重建入口。

   如果这三条过不了，页面就不能发布给用户。因为 3DGS 采集链路一旦放过坏素材，后面每一步都会被拖累。

   以后怎么避免同类问题

   我的建议是把采集门禁当成 3DGS 功能的第一层，不要等重建失败后再解释。页面上要让用户知道“为什么现在不能开始重建”，日志里要让开发者知道“是哪类素材导致失败”。

   还要注意一个边界：这套门禁不是底层重建能力本身，它只负责提前拦截明显不合格的输入。真正的重建、模型生成和三维展示，仍然要交给合适的空间重建能力、3D 资源处理链路和 ArkGraphics 3D 场景展示来完成。这样职责清楚，页面才不会越写越乱。