目录

识别平面语义(ArkTS)

本章节给出了关键开发步骤,完整代码可以参考示例代码。

约束与限制

从5.1.0(18)开始,识别平面语义能力支持部分Phone、部分Tablet设备。请参考硬件要求判断设备是否支持平面及物体语义特性(ARENGINE_FEATURE_TYPE_SEMANTIC)。

接口说明

获取平面语义信息可以通过ARPlane平面对象获取,以下接口为平面相关接口。详细接口和说明,请参考AR Engine API参考。

接口名 描述
ARTrackable.getPose 获取追踪目标的位姿信息。
ARTrackable.getAnchors 获取绑定到输入可跟踪对象的锚点对象。
ARPose.getMatrix 将位姿数据转换为一个4x4的矩阵。
ARPlane.getPolygonXZ 获取检测到的平面2D顶点数组。
ARPlane.getSubsumedBy 获取平面的父平面(当平面与另一个平面合并时会生成父平面)。
ARPlane.isPoseInExtents 检查给定位姿是否在平面的边界矩形内。
ARPlane.isPoseInPolygon 检查给定位姿是否在平面的边界多边形内。

开发步骤

AR Engine仅输出识别到的平面数据。为便于用户观察,可使用AGP(Ark Graphics Platform)渲染引擎或者XComponent绘制识别的平面。关于AGP的介绍可以查看ArkGraphics 3D简介和AGP引擎。

对于使用ArkTS的任何AR应用,首先需要创建一个AR会话ARViewContext,用于管理AR Engine的系统状态。AR会话ARViewContext的创建可以参考管理AR会话章节。

识别平面语义之前需要先检测识别环境中的平面,如何检测识别环境中的平面请参考检测环境中的平面。

[h2]导入模块

识别平面语义能力所需要导入的模块如下:

import { arEngine, ARView, arViewController } from '@kit.AREngine';
import {Camera, CustomGeometry, Geometry, Image, Material, MaterialType, Node, PrimitiveTopology,
  Scene, SceneResourceFactory, Shader, ShaderMaterial} from '@kit.ArkGraphics3D';
import { BusinessError } from '@kit.BasicServicesKit';

[h2]定义变量

定义变量planeLabel接收平面类型标签信息。

let arSession: arEngine.ARSession;
let planeLabel: arEngine.ARSemanticPlaneLabel;

[h2]显示平面语义信息

首先初始化AR会话和AR场景,可以参考初始化AR会话和AR场景章节。

更改semanticMode为ARSemanticMode.PLANE,启用平面语义识别能力。

在设备界面上显示识别到平面的信息,使用重复调用函数方法在设备界面上实时更新识别到的平面语义信息。

@Builder
export function ARTargetBuilder() {
  ARTarget()
}
// ...

@Component
struct ARTarget {
  @State arContext?: arViewController.ARViewContext = undefined;
  @State targetPlaneLabel: arEngine.ARSemanticPlaneLabel = planeLabel;
  private intervalId: number = -1;
  private delayInterval: number = 33;
  private params: arEngine.ARConfig = { type: arEngine.ARType.WORLD };
  // ...

  build() {
    NavDestination() {
      RelativeContainer() {
        if (this.arContext) {
          ARView({ context: this.arContext })
            .height('100%')
            .width('100%')
            .alignRules({
              center: { anchor: '__container__', align: VerticalAlign.Center },
              middle: { anchor: '__container__', align: HorizontalAlign.Center }
            })

          Column() {
            Text(`Label: ${convertSemanticLabel(this.targetPlaneLabel)}`)
              .infoStyles()
          }
          .alignItems(HorizontalAlign.Center)
          .alignRules({
            bottom: { anchor: '__container__', align: VerticalAlign.Bottom },
            middle: { anchor: '__container__', align: HorizontalAlign.Center }
          })
        }
      }
    }
    .onAppear(() => {
      this.initARView();
      this.intervalId = setInterval(async () => {
        this.targetPlaneLabel = planeLabel;
        // ...
      }, this.delayInterval);
    })
    .onWillDisappear(() => {
      // ...
    })
    .onShown(() => {
      this.resumeARView();
    })
    .onHidden(() => {
      this.pauseARView();
    })
    // ...
    .hideTitleBar(true)
    .hideBackButton(true)
    .hideToolBar(true)
  }

  private pauseARView(): void {
    // ...
  }

  private resumeARView(): void {
    // ...
  }

  private initARView(): void {
    Scene.load().then(async (scene) => {
      let context = new arViewController.ARViewContext();
      context.scene = scene;
      context.callback = new ARViewCallbackImpl();
      context.config = {
        type: arEngine.ARType.WORLD,
        planeFindingMode: arEngine.ARPlaneFindingMode.HORIZONTAL_AND_VERTICAL,
        powerMode: this.params?.powerMode,
        semanticMode: arEngine.ARSemanticMode.PLANE,
        poseMode: this.params?.poseMode,
        depthMode: this.params?.depthMode,
        meshMode: this.params?.meshMode,
      };
      context.init().then(() => {
        this.arContext = context;
        logger.info(`Succeeded in initing ARView.`);
      }).catch((err: BusinessError) => {
        logger.error(`Failed to init context. Code is ${err.code}, message is ${err.message}`);
      });
      // ...
    }).catch((err: BusinessError) => {
      logger.error(`Failed to load scene. Code is ${err.code}, message is ${err.message}`);
    });
  }
}

[h2]获取语义信息

调用ARViewCallback,使用其中的onFrameUpdate方法进行帧数据更新,在设备界面上显示识别到的平面类型。

增加获取语义信息的方法plane.label,获取每一帧识别到的平面语义信息。

class ARViewCallbackImpl extends arViewController.ARViewCallback {
  // ...
  onAnchorAdd(ctx: arViewController.ARViewContext, node: Node, anchor: arEngine.ARAnchor): void {
  }

  onAnchorUpdate(ctx: arViewController.ARViewContext, node: Node, anchor: arEngine.ARAnchor): void {
  }

  onFrameUpdate(ctx: arViewController.ARViewContext, sysBootTs: number): void {
    if (!ctx.session) {
      // ...
      return;
    }
    arSession = ctx.session;

    let frame = arSession.getFrame();
    let camera = frame.getCamera();
    if (!camera) {
      // ...
    } else {
      // 更新帧数据。
      let trackables: arEngine.ARTrackable[] = arSession.getAllTrackables(arEngine.ARTrackableType.PLANE);
      for (let i = 0; i < trackables.length; ++i) {
        let plane: arEngine.ARPlane = trackables[i] as arEngine.ARPlane;
        // ...
        planeLabel = plane.label;
        // ...
      }
    }
    // ...
  }
}

[h2]识别平面语义的自定义方法

自定义方法获取顶点数据getVertices、创建索引generateMeshIndex、创建mesh数据generateMeshInput,可参考检测平面的自定义方法。

arrayBufferFloat32ToNumber可以参考数据类型转换说明。

平面语义标签转换convertSemanticLabel可参考如下。

export function convertSemanticLabel(obj: number): string {
  let res: string = '';
  if (obj === 0) {
    res = 'UNKNOWN';
  } else if (obj === 1) {
    res = 'WALL';
  } else if (obj === 2) {
    res = 'FLOOR';
  } else if (obj === 3) {
    res = 'SEAT';
  } else if (obj === 4) {
    res = 'TABLE';
  } else if (obj === 5) {
    res = 'CEILING';
  } else if (obj === 6) {
    res = 'DOOR';
  } else if (obj === 7) {
    res = 'WINDOW';
  } else if (obj === 8) {
    res = 'BED';
  } else if (obj === 9) {
    res = 'PLANE SPACE';
  } else if (obj === 10) {
    res = 'CUBE VOLUME';
  } else if (obj === 11) {
    res = 'CUBE SPACE';
  }
  return res;
}