# AREngine_Codelab_Clientdemo_ArkTS

**Repository Path**: harmonyos_codelabs/arengine_codelab_clientdemo_arkts

## Basic Information

- **Project Name**: AREngine_Codelab_Clientdemo_ArkTS
- **Description**: 本示例展示了AREngine提供的平面检测，运动跟踪，环境跟踪和碰撞检测能力。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-21
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于AR引擎实现空间感知能力（ArkTS）

## 介绍

AR Engine（以下统称AR引擎）助力应用融合虚拟世界与现实世界，打造全新的视觉体验和交互方式。

本示例展示了AR引擎提供的平面检测，运动跟踪和环境跟踪能力。

- 运动跟踪能力，可以实时获取设备在空间中任意时刻的位姿。
- 环境跟踪能力，可以跟踪设备周围的平面，辅助开发者实现虚拟物体以场景化的方式逼真地融入现实物理世界。

## 效果预览

### ARViewScene效果预览

|           **应用首页**            |             **识别平面**             |            **显示模型**            |             **调整模型**             |
|:-----------------------------:|:--------------------------------:|:------------------------------:|:--------------------------------:|
| ![](screenshots/homePage.png) | ![](screenshots/detectPlane.png) | ![](screenshots/showModel.png) | ![](screenshots/adjustModel.png) |

1. 在手机的主屏幕，点击“ARSampleArktsForCodelab”，启动应用，在主界面可见“ARViewScene”按钮。
2. 点击“ARViewScene”按钮，拉起AR引擎的平面识别界面，对准地面，桌面，墙面等平面缓慢移动扫描。
3. 当识别出平面后，屏幕中心置自动放置一个3D模型。
4. 可以通过底部的滑块调整3D模型的左右、前后位置及旋转。

## 使用说明

开发者使用DevEco Studio打开本工程，签名后直接在真机设备上运行即可。

## 工程目录

```cpp
├──entry/src/main
├──module.json5                                     // 模块的配置文件
├──ets                                              // ets代码区
│  ├──entryability
│  │  └──EntryAbility.ets                           // 程序入口类
│  ├──pages
│  │  ├──ARViewScene.ets                            // ARViewScene界面
│  │  └──Selector.ets                               // 主界面
│  └──utils                                          // Util工具类
└──resources                                         // 资源文件目录
```

## 相关权限

1. 获取相机权限：ohos.permission.CAMERA。
2. 获取加速度传感器权限：ohos.permission.ACCELEROMETER。
3. 获取陀螺仪传感器权限：ohos.permission.GYROSCOPE。

## 约束与限制

1. AR Engine现阶段支持机型参考如下：
- Mate系列：Mate 60系列及之后的Mate机型。
- Pura系列：Pura 70系列及之后的Pura机型。
- 部分Nova机型：如Nova 12 Ultra、Nova 14 Pro、Nova 14 Ultra，具体范围以API查询返回结果为准。
- 部分Pocket机型：如 Pocket 2，具体范围以API查询返回结果为准。
- 部分MatePad机型：如MatePad Pro 13.2 2025，具体范围以API查询返回结果为准。

开发者可通过接口调用判断当前设备是否支持AR Engine。接口的调用参考方式如下：

```javascript
import { arViewController, ARView } from '@kit.AREngine';
import { BusinessError } from '@kit.BasicServicesKit';
@Component
struct ARTest {
  @State arContext?: arViewController.ARViewContext = undefined;
  build() {
    NavDestination() {
      RelativeContainer() {
        if (this.arContext) {
          ARView({ context: this.arContext })
        }
      }
    }
    .onAppear(() => {
      this.initARView()
    })
    .onWillDisappear(() => {
      this.arContext?.destroy();
    })
  }

  private initARView(): void {
    let context = new arViewController.ARViewContext()
    context.init().then(() => {
      this.arContext = context;
      console.info(`Succeeded in initializing ARView.`);
    }).catch((err: BusinessError) => {
      console.error(`Failed to init context. Code is ${err.code}, message is ${err.message}`);
    });
  }
}
```
若对应接口返回错误码为801，则表示AR Engine不支持当前设备。

2. 本实例支持的DevEco Studio版本：推荐DevEco Studio 5.1.0 Release及以上。
3. 本实例为Stage模型，支持的HarmonyOS SDK版本：推荐HarmonyOS 5.1.0 Release SDK及以上。

## 更新日志

### 1.0.0版本更新功能介绍

1. ARViewScene能力上线。<br>
   ARView场景能力上线，开发者可在识别的平面上放置3D模型进行场景布置。

## 相关文档

[AREngine开发指南](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ar-engine-kit-guide)

[AREngine API参考](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ar-engine-api)