HarmonyOS APP开发：AR渲染与增强现实开发

📌 核心要点：从平面检测到3D模型放置，从光照估计到AR家具预览，掌握HarmonyOS AR开发全链路

一、背景与动机

你有没有在宜家APP上"试摆"过家具？打开摄像头，对准客厅地板，一个3D沙发就"放"在了你的房间里——还能绕着它走一圈，看看和窗帘搭不搭。这就是AR（增强现实）技术最典型的应用场景。

AR不是什么遥远的黑科技，它已经深入到我们生活的方方面面：导航APP的AR实景导航、教育APP的3D人体模型、电商APP的虚拟试妆试衣……可以说，AR正在重新定义人与数字世界的交互方式。

HarmonyOS从5.0开始就提供了AR开发能力，到了6.0更是大幅增强了AR Foundation框架，支持平面检测、锚点管理、光照估计、图像追踪等核心功能。对于开发者来说，这意味着你可以用ArkTS + 3D组件，在自己的APP中实现专业级的AR体验。

但AR开发的门槛确实不低。它涉及3D渲染、相机标定、空间计算等多个领域，光是理解"世界坐标系"和"相机坐标系"的关系就够喝一壶的。所以这篇文章，咱们从原理到实战，把AR开发的核心知识点讲清楚。

二、核心原理

2.1 AR技术原理

AR的核心任务只有一句话：把虚拟物体"放"到真实世界的正确位置上，并让它看起来像真的。

这句话拆开来，包含三个子问题：

1. 定位：设备在真实世界中的位置和朝向是什么？（6DoF追踪）
2. 理解：真实世界的结构是什么？（平面检测、深度估计）
3. 融合：虚拟物体如何与真实场景自然融合？（光照估计、遮挡处理）

graph TD
    A[摄像头输入]:::primary --> B[视觉惯性里程计<br>VIO]:::info
    B --> C[6DoF位姿估计<br>位置+朝向]:::warning
    C --> D[场景理解]:::info
    D --> E[平面检测]:::primary
    D --> F[深度估计]:::primary
    D --> G[图像追踪]:::primary
    
    C --> H[AR渲染管线]:::error
    E --> H
    F --> H
    G --> H
    H --> I[虚拟物体叠加<br>到相机画面]:::warning
    
    classDef primary fill:#4CAF50,stroke:#388E3C,color:#fff
    classDef warning fill:#FF9800,stroke:#F57C00,color:#fff
    classDef error fill:#F44336,stroke:#D32F2F,color:#fff
    classDef info fill:#2196F3,stroke:#1976D2,color:#fff

2.2 AR Foundation框架

HarmonyOS的AR开发基于AR Foundation框架，核心组件包括：

2.3 平面检测与锚点

平面检测是AR的基石。系统通过分析相机画面中的特征点，拟合出水平面或垂直面，这些平面就是虚拟物体的"落脚点"。

锚点（Anchor）则是AR中的"定位钉"。当你在某个平面上放置了一个虚拟物体，系统会创建一个锚点来固定它的位置。即使设备移动、追踪漂移，锚点也会通过校正算法保持虚拟物体的位置稳定。

graph LR
    A[屏幕触摸点<br>2D坐标]:::primary --> B[射线投射<br>ARRaycast]:::info
    B --> C{与平面相交?}:::warning
    C -->|是| D[获取交点<br>3D世界坐标]:::primary
    D --> E[创建锚点<br>ARAnchor]:::error
    E --> F[在锚点位置<br>放置3D模型]:::info
    
    classDef primary fill:#4CAF50,stroke:#388E3C,color:#fff
    classDef warning fill:#FF9800,stroke:#F57C00,color:#fff
    classDef error fill:#F44336,stroke:#D32F2F,color:#fff
    classDef info fill:#2196F3,stroke:#1976D2,color:#fff

2.4 AR光照估计

光照估计让虚拟物体"融入"真实场景的关键。如果虚拟沙发的光照和房间里的光照不一致，用户一眼就能看出"这是假的"。

HarmonyOS的AR光照估计提供以下参数：

• 环境光强度（Ambient Intensity）：整体光照亮度
• 环境光色温（Ambient Color Temperature）：光照的冷暖色调
• 主光源方向（Main Light Direction）：主要光源的照射方向
• 主光源强度（Main Light Intensity）：主光源的亮度

通过这些参数，我们可以动态调整虚拟物体的材质光照，让它与真实环境融为一体。

三、代码实战

3.1 基础用法：AR会话与平面检测

先搭建AR开发的基础框架——创建AR会话、启用平面检测：

import { ARSession, ARPlaneManager, ARAnchorManager, ARLightEstimation } from '@kit.ARFoundation'
import { camera } from '@kit.Multimedia'

// AR基础页面
@Entry
@Component
struct ARBasicPage {
  // AR会话
  private arSession: ARSession | null = null
  private arPlaneManager: ARPlaneManager | null = null
  private arAnchorManager: ARAnchorManager | null = null
  private arLightEstimation: ARLightEstimation | null = null
  
  // AR状态
  @State isSessionRunning: boolean = false
  @State detectedPlanes: Array<ARPlaneInfo> = []
  @State trackingState: string = '未初始化'
  @State lightIntensity: number = 0
  @State lightTemperature: number = 6500

  aboutToAppear() {
    this.initARSession()
  }

  aboutToDisappear() {
    this.releaseARSession()
  }

  build() {
    Stack() {
      // 相机预览（作为AR背景）
      XComponent({
        id: 'arCamera',
        type: XComponentType.SURFACE,
        libraryName: 'arengine'
      })
        .width('100%')
        .height('100%')
        .onLoad(() => {
          this.startARSession()
        })
      
      // 3D渲染层（虚拟物体叠加在相机画面上）
      Component3D({
        scene: $rawfile('ar_scene.json'),
        modelType: [ModelType.SURFACE]
      })
        .width('100%')
        .height('100%')
        .environment($rawfile('ar_environment.json'))
      
      // UI叠加层
      Column() {
        // 顶部状态栏
        Row() {
          Text(`追踪状态: ${this.trackingState}`)
            .fontSize(14)
            .fontColor('#FFFFFF')
            .padding(8)
            .backgroundColor('#80000000')
            .borderRadius(4)
          
          Text(`平面: ${this.detectedPlanes.length}`)
            .fontSize(14)
            .fontColor('#FFFFFF')
            .padding(8)
            .backgroundColor('#80000000')
            .borderRadius(4)
            .margin({ left: 8 })
        }
        .width('100%')
        .padding(16)
        
        Blank()
        
        // 底部光照信息
        Row() {
          Text(`光照强度: ${this.lightIntensity.toFixed(0)} lux`)
            .fontSize(12)
            .fontColor('#FFFFFF')
            .padding(6)
            .backgroundColor('#80000000')
            .borderRadius(4)
          
          Text(`色温: ${this.lightTemperature.toFixed(0)}K`)
            .fontSize(12)
            .fontColor('#FFFFFF')
            .padding(6)
            .backgroundColor('#80000000')
            .borderRadius(4)
            .margin({ left: 8 })
        }
        .width('100%')
        .padding(16)
        .justifyContent(FlexAlign.Center)
      }
      .width('100%')
      .height('100%')
    }
  }

  // 初始化AR会话
  private async initARSession() {
    try {
      // 创建AR会话配置
      const config: ARSessionConfig = {
        // 启用平面检测
        planeDetection: PlaneDetectionMode.HORIZONTAL | PlaneDetectionMode.VERTICAL,
        // 启用光照估计
        lightEstimation: true,
        // 启用深度估计
        depthEstimation: false,
        // 启用图像追踪
        imageTracking: false
      }
      
      // 创建AR会话
      this.arSession = new ARSession(config)
      
      // 创建平面检测管理器
      this.arPlaneManager = new ARPlaneManager(this.arSession)
      this.arPlaneManager.onPlaneDetected((plane: ARPlaneInfo) => {
        this.detectedPlanes.push(plane)
        console.info(`检测到新平面: ${plane.type}, 面积: ${plane.area.toFixed(2)}m²`)
      })
      this.arPlaneManager.onPlaneUpdated((plane: ARPlaneInfo) => {
        // 更新已有平面信息
        const idx = this.detectedPlanes.findIndex(p => p.id === plane.id)
        if (idx >= 0) {
          this.detectedPlanes[idx] = plane
        }
      })
      
      // 创建锚点管理器
      this.arAnchorManager = new ARAnchorManager(this.arSession)
      
      // 创建光照估计管理器
      this.arLightEstimation = new ARLightEstimation(this.arSession)
      this.arLightEstimation.onLightUpdated((light: ARLightInfo) => {
        this.lightIntensity = light.ambientIntensity
        this.lightTemperature = light.ambientColorTemperature
        // 更新3D场景中的光照
        this.updateSceneLighting(light)
      })
      
      console.info('AR会话初始化成功')
    } catch (error) {
      console.error(`AR初始化失败: ${error}`)
    }
  }

  // 启动AR会话
  private async startARSession() {
    if (!this.arSession) return
    try {
      await this.arSession.start()
      this.isSessionRunning = true
      this.trackingState = '追踪中'
      console.info('AR会话已启动')
    } catch (error) {
      console.error(`AR启动失败: ${error}`)
      this.trackingState = '启动失败'
    }
  }

  // 释放AR会话
  private releaseARSession() {
    this.arSession?.stop()
    this.arSession?.release()
    this.isSessionRunning = false
  }

  // 更新场景光照
  private updateSceneLighting(light: ARLightInfo) {
    // 根据光照估计结果调整3D场景的环境光和主光源
    // 具体实现取决于3D引擎的API
    console.info(`光照更新 - 强度: ${light.ambientIntensity}, 色温: ${light.ambientColorTemperature}K`)
  }
}

// AR会话配置
interface ARSessionConfig {
  planeDetection: PlaneDetectionMode
  lightEstimation: boolean
  depthEstimation: boolean
  imageTracking: boolean
}

// 平面检测模式
enum PlaneDetectionMode {
  NONE = 0,
  HORIZONTAL = 1,
  VERTICAL = 2,
  HORIZONTAL_AND_VERTICAL = 3
}

// 平面信息
interface ARPlaneInfo {
  id: string
  type: string        // 'horizontal' | 'vertical'
  center: Vector3
  extent: Vector2     // 平面的长宽
  area: number        // 面积（平方米）
  normal: Vector3     // 法线方向
  vertices: Array<Vector3>
}

// 光照信息
interface ARLightInfo {
  ambientIntensity: number        // 环境光强度（lux）
  ambientColorTemperature: number // 色温（开尔文）
  mainLightDirection: Vector3     // 主光源方向
  mainLightIntensity: number      // 主光源强度
}

// 向量类型
interface Vector3 {
  x: number
  y: number
  z: number
}

interface Vector2 {
  x: number
  y: number
}

3.2 进阶用法：3D模型AR放置

检测到平面后，最核心的操作就是在平面上放置3D模型。这个过程涉及射线投射和锚点创建：

// AR模型放置管理器
class ARModelPlacer {
  private arSession: ARSession
  private arAnchorManager: ARAnchorManager
  private arPlaneManager: ARPlaneManager
  
  // 已放置的模型列表
  private placedModels: Array<PlacedModel> = []
  // 当前选中的模型
  private selectedModel: PlacedModel | null = null
  
  // 模型资源映射
  private modelResources: Map<string, ModelResource> = new Map()

  constructor(session: ARSession, anchorMgr: ARAnchorManager, planeMgr: ARPlaneManager) {
    this.arSession = session
    this.arAnchorManager = anchorMgr
    this.arPlaneManager = planeMgr
    this.loadModelResources()
  }

  // 加载模型资源
  private loadModelResources() {
    this.modelResources.set('sofa', {
      name: '沙发',
      resourcePath: 'models/sofa.glb',
      scale: 0.5,
      defaultRotation: { x: 0, y: 0, z: 0 }
    })
    this.modelResources.set('table', {
      name: '餐桌',
      resourcePath: 'models/table.glb',
      scale: 0.3,
      defaultRotation: { x: 0, y: 0, z: 0 }
    })
    this.modelResources.set('lamp', {
      name: '落地灯',
      resourcePath: 'models/lamp.glb',
      scale: 0.4,
      defaultRotation: { x: 0, y: 0, z: 0 }
    })
    this.modelResources.set('bookshelf', {
      name: '书架',
      resourcePath: 'models/bookshelf.glb',
      scale: 0.35,
      defaultRotation: { x: 0, y: 0, z: 0 }
    })
  }

  // 在屏幕触摸位置放置模型
  async placeModelAtTouch(screenX: number, screenY: number, modelType: string): Promise<boolean> {
    try {
      // 1. 从屏幕坐标发射射线
      const raycastHit = await this.arSession.raycast(screenX, screenY)
      
      if (!raycastHit || raycastHit.length === 0) {
        console.warn('射线未命中任何平面')
        return false
      }
      
      // 2. 取最近的命中点
      const hit = raycastHit[0]
      
      // 3. 在命中点创建锚点
      const anchor = await this.arAnchorManager.createAnchor(hit.pose)
      
      // 4. 加载并放置3D模型
      const resource = this.modelResources.get(modelType)
      if (!resource) {
        console.error(`未知模型类型: ${modelType}`)
        return false
      }
      
      const placedModel: PlacedModel = {
        id: `model_${Date.now()}`,
        type: modelType,
        anchor: anchor,
        position: { x: hit.pose.position.x, y: hit.pose.position.y, z: hit.pose.position.z },
        rotation: { ...resource.defaultRotation },
        scale: resource.scale,
        resource: resource
      }
      
      this.placedModels.push(placedModel)
      console.info(`模型已放置: ${resource.name} at (${hit.pose.position.x.toFixed(2)}, ${hit.pose.position.y.toFixed(2)}, ${hit.pose.position.z.toFixed(2)})`)
      
      return true
    } catch (error) {
      console.error(`放置模型失败: ${error}`)
      return false
    }
  }

  // 移动已放置的模型
  async moveModel(modelId: string, screenX: number, screenY: number): Promise<boolean> {
    const model = this.placedModels.find(m => m.id === modelId)
    if (!model) return false
    
    try {
      const raycastHit = await this.arSession.raycast(screenX, screenY)
      if (!raycastHit || raycastHit.length === 0) return false
      
      const hit = raycastHit[0]
      
      // 更新锚点位置
      await this.arAnchorManager.updateAnchor(model.anchor, hit.pose)
      model.position = { x: hit.pose.position.x, y: hit.pose.position.y, z: hit.pose.position.z }
      
      return true
    } catch (error) {
      console.error(`移动模型失败: ${error}`)
      return false
    }
  }

  // 旋转模型
  rotateModel(modelId: string, angleDegrees: number) {
    const model = this.placedModels.find(m => m.id === modelId)
    if (!model) return
    model.rotation.y += angleDegrees
  }

  // 缩放模型
  scaleModel(modelId: string, scaleFactor: number) {
    const model = this.placedModels.find(m => m.id === modelId)
    if (!model) return
    model.scale = Math.max(0.1, Math.min(2.0, model.scale * scaleFactor))
  }

  // 删除模型
  async removeModel(modelId: string) {
    const idx = this.placedModels.findIndex(m => m.id === modelId)
    if (idx < 0) return
    
    const model = this.placedModels[idx]
    // 移除锚点
    await this.arAnchorManager.removeAnchor(model.anchor)
    this.placedModels.splice(idx, 1)
  }

  // 获取所有已放置的模型
  getPlacedModels(): Array<PlacedModel> {
    return this.placedModels
  }

  // 选中模型（用于拖拽和旋转操作）
  selectModelAtTouch(screenX: number, screenY: number): PlacedModel | null {
    // 遍历已放置模型，检查触摸点是否在模型的投影范围内
    for (const model of this.placedModels) {
      const screenPos = this.arSession.worldToScreen(model.position)
      const dx = screenX - screenPos.x
      const dy = screenY - screenPos.y
      const hitRadius = 50 * model.scale  // 投影半径（像素）
      if (dx * dx + dy * dy < hitRadius * hitRadius) {
        this.selectedModel = model
        return model
      }
    }
    this.selectedModel = null
    return null
  }
}

// 已放置的模型数据
interface PlacedModel {
  id: string
  type: string
  anchor: ARAnchor
  position: Vector3
  rotation: Vector3
  scale: number
  resource: ModelResource
}

// 模型资源数据
interface ModelResource {
  name: string
  resourcePath: string
  scale: number
  defaultRotation: Vector3
}

// 锚点接口
interface ARAnchor {
  id: string
  pose: ARPose
}

// AR位姿
interface ARPose {
  position: Vector3
  rotation: Quaternion
}

// 四元数
interface Quaternion {
  x: number
  y: number
  z: number
  w: number
}

3.3 完整示例：AR家具预览应用

下面是一个完整的AR家具预览应用，包含模型选择、放置、移动、旋转、删除等全部功能：

// AR家具预览应用
@Entry
@Component
struct ARFurniturePreviewPage {
  // AR组件
  private arSession: ARSession | null = null
  private modelPlacer: ARModelPlacer | null = null
  
  // UI状态
  @State currentModel: string = 'sofa'
  @State isPlacingMode: boolean = true
  @State placedCount: number = 0
  @State showHelp: boolean = true
  @State trackingState: string = '初始化中...'
  @State lightInfo: string = '--'
  
  // 手势状态
  private lastTouchX: number = 0
  private lastTouchY: number = 0
  private isDragging: boolean = false
  private selectedModelId: string = ''

  // 可选家具列表
  private furnitureList: Array<FurnitureItem> = [
    { type: 'sofa', name: '沙发', icon: '🛋️', description: '三人位布艺沙发' },
    { type: 'table', name: '餐桌', icon: '🪑', description: '实木圆形餐桌' },
    { type: 'lamp', name: '落地灯', icon: '💡', description: '北欧风格落地灯' },
    { type: 'bookshelf', name: '书架', icon: '📚', description: '五层开放式书架' }
  ]

  aboutToAppear() {
    this.initAR()
  }

  aboutToDisappear() {
    this.arSession?.stop()
    this.arSession?.release()
  }

  build() {
    Stack() {
      // AR相机预览 + 3D渲染层
      Stack() {
        XComponent({
          id: 'arCameraPreview',
          type: XComponentType.SURFACE,
          libraryName: 'arengine'
        })
          .width('100%')
          .height('100%')
          .onLoad(() => {
            this.startAR()
          })
        
        // 3D场景层
        Component3D({
          scene: $rawfile('furniture_ar_scene.json'),
          modelType: [ModelType.SURFACE]
        })
          .width('100%')
          .height('100%')
      }
      
      // UI叠加层
      Column() {
        // 顶部状态栏
        this.TopBar()
        
        // 帮助提示
        if (this.showHelp) {
          this.HelpTip()
        }
        
        Blank()
        
        // 底部控制面板
        this.BottomPanel()
      }
      .width('100%')
      .height('100%')
    }
    .onTouch((event: TouchEvent) => {
      this.handleARTouch(event)
    })
  }

  // 顶部状态栏
  @Builder TopBar() {
    Row() {
      // 返回按钮
      Text('←')
        .fontSize(24)
        .fontColor('#FFFFFF')
        .padding(8)
        .onClick(() => {
          // 返回上一页
        })
      
      // 追踪状态
      Text(this.trackingState)
        .fontSize(12)
        .fontColor('#FFFFFF')
        .padding({ left: 8, right: 8, top: 4, bottom: 4 })
        .backgroundColor('#80000000')
        .borderRadius(12)
      
      Blank()
      
      // 光照信息
      Text(this.lightInfo)
        .fontSize(11)
        .fontColor('#AAAAAA')
      
      // 已放置数量
      Text(`${this.placedCount}件`)
        .fontSize(12)
        .fontColor('#FFFFFF')
        .padding({ left: 8, right: 8, top: 4, bottom: 4 })
        .backgroundColor('#80000000')
        .borderRadius(12)
    }
    .width('100%')
    .padding({ left: 8, right: 16, top: 8 })
  }

  // 帮助提示
  @Builder HelpTip() {
    Column() {
      Text('📱 对准地面或桌面，点击屏幕放置家具')
        .fontSize(14)
        .fontColor('#FFFFFF')
        .padding(12)
        .backgroundColor('#B0404040')
        .borderRadius(8)
    }
    .width('100%')
    .padding(16)
    .alignItems(HorizontalAlign.Center)
    .onClick(() => {
      this.showHelp = false
    })
  }

  // 底部控制面板
  @Builder BottomPanel() {
    Column() {
      // 操作按钮行（选中模型时显示）
      if (!this.isPlacingMode && this.selectedModelId) {
        Row() {
          Button('旋转')
            .fontSize(12)
            .padding({ left: 12, right: 12, top: 6, bottom: 6 })
            .backgroundColor('#FF9800')
            .fontColor('#FFFFFF')
            .onClick(() => {
              this.modelPlacer?.rotateModel(this.selectedModelId, 45)
            })
          
          Button('放大')
            .fontSize(12)
            .padding({ left: 12, right: 12, top: 6, bottom: 6 })
            .backgroundColor('#4CAF50')
            .fontColor('#FFFFFF')
            .onClick(() => {
              this.modelPlacer?.scaleModel(this.selectedModelId, 1.2)
            })
          
          Button('缩小')
            .fontSize(12)
            .padding({ left: 12, right: 12, top: 6, bottom: 6 })
            .backgroundColor('#2196F3')
            .fontColor('#FFFFFF')
            .onClick(() => {
              this.modelPlacer?.scaleModel(this.selectedModelId, 0.8)
            })
          
          Button('删除')
            .fontSize(12)
            .padding({ left: 12, right: 12, top: 6, bottom: 6 })
            .backgroundColor('#F44336')
            .fontColor('#FFFFFF')
            .onClick(() => {
              this.modelPlacer?.removeModel(this.selectedModelId)
              this.placedCount--
              this.isPlacingMode = true
              this.selectedModelId = ''
            })
        }
        .width('100%')
        .justifyContent(FlexAlign.SpaceEvenly)
        .padding({ top: 8, bottom: 8 })
      }
      
      // 家具选择列表
      Row() {
        ForEach(this.furnitureList, (item: FurnitureItem) => {
          Column() {
            Text(item.icon).fontSize(28)
            Text(item.name).fontSize(11).fontColor('#FFFFFF').margin({ top: 2 })
          }
          .width(72)
          .height(72)
          .borderRadius(12)
          .justifyContent(FlexAlign.Center)
          .backgroundColor(this.currentModel === item.type ? '#2196F3' : '#40404040')
          .border(this.currentModel === item.type ? 2 : 0, '#2196F3')
          .onClick(() => {
            this.currentModel = item.type
            this.isPlacingMode = true
            this.selectedModelId = ''
          })
        })
      }
      .width('100%')
      .justifyContent(FlexAlign.SpaceEvenly)
      .padding({ top: 8, bottom: 8 })
      
      // 模式切换
      Row() {
        Text(this.isPlacingMode ? '📌 放置模式' : '✋ 编辑模式')
          .fontSize(13)
          .fontColor('#FFFFFF')
          .padding({ left: 16, right: 16, top: 6, bottom: 6 })
          .backgroundColor(this.isPlacingMode ? '#4CAF50' : '#FF9800')
          .borderRadius(16)
          .onClick(() => {
            this.isPlacingMode = !this.isPlacingMode
          })
        
        Text('🗑️ 清空全部')
          .fontSize(13)
          .fontColor('#FFFFFF')
          .padding({ left: 16, right: 16, top: 6, bottom: 6 })
          .backgroundColor('#F44336')
          .borderRadius(16)
          .margin({ left: 12 })
          .onClick(() => {
            this.clearAllModels()
          })
      }
      .width('100%')
      .justifyContent(FlexAlign.Center)
      .padding({ top: 4, bottom: 16 })
    }
    .width('100%')
    .backgroundColor('#B0000000')
    .borderRadius({ topLeft: 16, topRight: 16 })
  }

  // 初始化AR
  private async initAR() {
    try {
      const config: ARSessionConfig = {
        planeDetection: PlaneDetectionMode.HORIZONTAL | PlaneDetectionMode.VERTICAL,
        lightEstimation: true,
        depthEstimation: false,
        imageTracking: false
      }
      
      this.arSession = new ARSession(config)
      const planeManager = new ARPlaneManager(this.arSession)
      const anchorManager = new ARAnchorManager(this.arSession)
      
      this.modelPlacer = new ARModelPlacer(this.arSession, anchorManager, planeManager)
      
      // 监听追踪状态
      this.arSession.onTrackingStateChanged((state: string) => {
        this.trackingState = state === 'TRACKING' ? '✅ 追踪正常' : 
                             state === 'LIMITED' ? '⚠️ 追踪受限' : '❌ 追踪丢失'
      })
      
      // 监听光照变化
      const lightEstimation = new ARLightEstimation(this.arSession)
      lightEstimation.onLightUpdated((light: ARLightInfo) => {
        this.lightInfo = `${light.ambientIntensity.toFixed(0)} lux / ${light.ambientColorTemperature.toFixed(0)}K`
        this.updateModelLighting(light)
      })
      
    } catch (error) {
      console.error(`AR初始化失败: ${error}`)
      this.trackingState = '❌ 初始化失败'
    }
  }

  // 启动AR
  private async startAR() {
    if (!this.arSession) return
    try {
      await this.arSession.start()
      this.trackingState = '⏳ 扫描环境中...'
    } catch (error) {
      console.error(`AR启动失败: ${error}`)
    }
  }

  // 处理AR触摸事件
  private handleARTouch(event: TouchEvent) {
    const touch = event.touches[0]
    
    if (event.type === TouchType.Down) {
      this.lastTouchX = touch.x
      this.lastTouchY = touch.y
      this.isDragging = false
      
      if (this.isPlacingMode) {
        // 放置模式：点击放置模型
        this.placeModelAtPoint(touch.x, touch.y)
      } else {
        // 编辑模式：选中模型
        const model = this.modelPlacer?.selectModelAtTouch(touch.x, touch.y)
        if (model) {
          this.selectedModelId = model.id
        }
      }
    } else if (event.type === TouchType.Move) {
      const dx = touch.x - this.lastTouchX
      const dy = touch.y - this.lastTouchY
      
      if (Math.abs(dx) > 5 || Math.abs(dy) > 5) {
        this.isDragging = true
      }
      
      // 编辑模式下拖拽移动模型
      if (!this.isPlacingMode && this.selectedModelId && this.isDragging) {
        this.modelPlacer?.moveModel(this.selectedModelId, touch.x, touch.y)
      }
      
      this.lastTouchX = touch.x
      this.lastTouchY = touch.y
    } else if (event.type === TouchType.Up) {
      this.isDragging = false
    }
  }

  // 在指定位置放置模型
  private async placeModelAtPoint(x: number, y: number) {
    if (!this.modelPlacer) return
    const success = await this.modelPlacer.placeModelAtTouch(x, y, this.currentModel)
    if (success) {
      this.placedCount++
      // 放置成功后自动切换到编辑模式
      const models = this.modelPlacer.getPlacedModels()
      if (models.length > 0) {
        this.selectedModelId = models[models.length - 1].id
        this.isPlacingMode = false
      }
    }
  }

  // 更新模型光照
  private updateModelLighting(light: ARLightInfo) {
    // 根据环境光照调整3D模型的材质参数
    // 1. 调整环境光颜色（基于色温）
    const colorTemp = light.ambientColorTemperature
    // 色温转RGB的简化算法
    let r = 1.0, g = 1.0, b = 1.0
    if (colorTemp < 6500) {
      // 暖色调
      r = 1.0
      g = 0.8 + (colorTemp / 6500) * 0.2
      b = 0.6 + (colorTemp / 6500) * 0.4
    } else {
      // 冷色调
      r = 0.8 + (10000 - colorTemp) / 3500 * 0.2
      g = 0.9 + (10000 - colorTemp) / 3500 * 0.1
      b = 1.0
    }
    
    // 2. 调整光照强度
    const intensityScale = Math.min(light.ambientIntensity / 1000, 2.0)
    
    console.info(`光照更新 - 色温RGB: (${r.toFixed(2)}, ${g.toFixed(2)}, ${b.toFixed(2)}), 强度系数: ${intensityScale.toFixed(2)}`)
  }

  // 清空所有模型
  private async clearAllModels() {
    if (!this.modelPlacer) return
    const models = this.modelPlacer.getPlacedModels()
    for (const model of models) {
      await this.modelPlacer.removeModel(model.id)
    }
    this.placedCount = 0
    this.selectedModelId = ''
    this.isPlacingMode = true
  }
}

// 家具项
interface FurnitureItem {
  type: string
  name: string
  icon: string
  description: string
}

四、踩坑与注意事项

坑点1：AR会话的生命周期管理

AR会话是非常消耗资源的（CPU、GPU、相机），务必在页面不可见时暂停会话，页面销毁时释放会话：

// 页面生命周期中正确管理AR会话
onPageShow() {
  this.arSession?.resume()  // 页面可见时恢复
}

onPageHide() {
  this.arSession?.pause()   // 页面不可见时暂停
}

aboutToDisappear() {
  this.arSession?.stop()    // 页面销毁时停止
  this.arSession?.release() // 释放资源
}

如果不这样做，用户切换到其他APP再回来时，AR追踪可能已经丢失，甚至相机画面卡死。

坑点2：平面检测的延迟与误检

平面检测不是瞬间完成的，通常需要1-3秒的扫描才能检测到一个平面。在UI上给用户明确的引导——比如显示"请缓慢移动手机扫描地面"的提示，而不是让用户对着空气乱点。

另外，平面检测有时会产生误检——比如把一面白墙检测成多个碎片化的平面。建议合并距离相近的平面，并设置最小面积阈值过滤掉小碎片：

// 过滤小面积平面
private filterPlanes(planes: Array<ARPlaneInfo>): Array<ARPlaneInfo> {
  const MIN_AREA = 0.25  // 最小0.25平方米
  return planes.filter(p => p.area >= MIN_AREA)
}

坑点3：锚点漂移与稳定性

AR追踪不是完美的，长时间运行后锚点位置会发生漂移。解决方案是定期重新创建锚点——当检测到追踪状态从LIMITED恢复到TRACKING时，重新在关键位置创建锚点：

// 追踪恢复时重新校正锚点
this.arSession.onTrackingStateChanged((state: string) => {
  if (state === 'TRACKING') {
    // 追踪恢复，校正已放置模型的位置
    this.recalibrateAnchors()
  }
})

坑点4：3D模型的缩放与真实感

3D模型的缩放必须与真实尺寸对应，否则AR体验会非常违和。一个1.8米长的沙发在AR中看起来只有0.5米，用户立刻就会觉得"假"。建议在模型资源中标注真实尺寸，放置时按1:1比例缩放：

// 模型资源中标注真实尺寸
interface ModelResource {
  name: string
  resourcePath: string
  realWorldSize: Vector3  // 真实尺寸（米）
  scale: number           // 模型单位到米的换算系数
}

坑点5：光照估计的不稳定性

光照估计值会随相机画面变化而波动，如果直接用估计值更新材质，虚拟物体的光照会忽明忽暗。必须对光照参数做平滑处理：

// 光照参数平滑
private smoothLight: SmoothLight = { intensity: 500, temperature: 6500 }
private smoothFactor: number = 0.1  // 平滑系数

private updateModelLighting(light: ARLightInfo) {
  // 指数移动平均平滑
  this.smoothLight.intensity += (light.ambientIntensity - this.smoothLight.intensity) * this.smoothFactor
  this.smoothLight.temperature += (light.ambientColorTemperature - this.smoothLight.temperature) * this.smoothFactor
  
  // 使用平滑后的值更新材质
  this.applyLightToScene(this.smoothLight)
}

坑点6：射线检测的坐标系转换

屏幕坐标和3D世界坐标的转换是AR开发中最容易出错的地方。屏幕坐标的原点在左上角，Y轴向下；而3D世界坐标的原点在设备初始位置，Y轴向上。在调用raycast之前，务必确认坐标系统一。

坑点7：多模型放置的性能问题

每放置一个3D模型，GPU的渲染负担就增加一份。当模型数量超过10个时，低端设备可能出现帧率下降。建议限制同时放置的模型数量，并对远处的模型做LOD（Level of Detail）降级：

// 根据距离调整模型精度
private adjustLOD(cameraPos: Vector3, models: Array<PlacedModel>) {
  for (const model of models) {
    const dist = this.distance(cameraPos, model.position)
    if (dist > 5.0) {
      // 远距离：使用低精度模型
      this.switchToLowPoly(model)
    } else {
      // 近距离：使用高精度模型
      this.switchToHighPoly(model)
    }
  }
}

五、HarmonyOS 6适配说明

API差异

行为变更

• 平面检测语义增强：6.0的平面检测结果包含语义标签（地面、桌面、墙面），可以直接根据标签决定放置逻辑，不再需要手动判断平面朝向
• 光照估计精度提升：6.0使用HDR环境光探针替代简单的强度/色温估计，虚拟物体的环境反射更加真实
• 追踪稳定性改善：6.0优化了VIO算法，追踪漂移减少约40%，长时间运行的AR体验更稳定

适配代码

// HarmonyOS 6适配：语义平面检测
private async placeModelOnSemanticPlane(screenX: number, screenY: number, modelType: string) {
  const raycastHit = await this.arSession.raycast(screenX, screenY)
  if (!raycastHit || raycastHit.length === 0) return false

  const hit = raycastHit[0]
  
  // 6.0新增：利用语义标签验证放置位置
  if (hit.semanticLabel) {
    // 沙发只能放在地面
    if (modelType === 'sofa' && hit.semanticLabel !== 'FLOOR') {
      console.warn('沙发只能放在地面上')
      return false
    }
    // 书架只能靠墙
    if (modelType === 'bookshelf' && hit.semanticLabel !== 'WALL') {
      console.warn('书架需要靠墙放置')
      return false
    }
  }
  
  // 创建锚点并放置模型
  const anchor = await this.arAnchorManager.createAnchor(hit.pose)
  // ... 放置逻辑
  return true
}

// HarmonyOS 6适配：HDR环境光
private updateHDRLighting(probeData: AREnvironmentProbe) {
  // 6.0支持HDR环境光探针
  // 使用探针数据更新3D场景的环境贴图
  this.updateEnvironmentMap(probeData.cubemap)
  // PBR材质自动根据环境贴图计算反射
  console.info('HDR环境光已更新')
}

// HarmonyOS 6适配：地理锚点（户外AR）
private async createGeoAnchor(latitude: number, longitude: number, altitude: number) {
  // 6.0新增：基于GPS坐标创建锚点
  const geoAnchor = await this.arAnchorManager.createGeoAnchor({
    latitude: latitude,
    longitude: longitude,
    altitude: altitude
  })
  console.info(`地理锚点已创建: (${latitude}, ${longitude}, ${altitude})`)
  return geoAnchor
}

六、总结

AR开发是移动端技术栈中门槛最高的方向之一，它横跨了3D渲染、计算机视觉、空间计算三大领域。但正是因为门槛高，掌握AR开发的开发者才格外稀缺——这恰恰是你的机会。

在HarmonyOS上做AR开发，核心要记住三点：

第一，追踪是基础。没有稳定的6DoF追踪，一切都是空中楼阁。在开发AR功能之前，先确保追踪状态正常，再考虑放置模型、光照估计等上层功能。

第二，真实感是目标。AR的核心价值在于"虚实融合"，如果虚拟物体看起来不像真的，整个AR体验就失败了。光照估计、阴影、遮挡处理，每一个细节都在为真实感服务。

第三，性能是底线。AR应用同时运行相机、VIO算法、3D渲染，对硬件的压力极大。务必做好性能优化——限制模型数量、使用LOD、异步加载资源、及时释放不用的锚点。

AR技术正在从"新奇"走向"实用"，从"炫技"走向"刚需"。当用户习惯了在手机上预览家具、试穿衣服、实景导航，AR就不再是可选项，而是必备功能。现在开始学习AR开发，正是最好的时机。