开发接口

一、运行流程

图像识别AR组件流程示意图：

34

1.1 初始化AR渲染组件

方法：

this.selectComponent(selector).getInstance(options);

参数：

​ selector: string wxml中组件元素id

​ options: Object 实例化参数

属性 类型 必填 说明
cloudKey string 是 云识别Key，在太虚开发者管理后台中获取
onCreate function 是 组件构建完成事件回调函数，构建完成后才能使用组件接口
onFind function 否 识别成功回调函数
onLoadComplete function 否 模型加载完成回调函数

返回：

​ VoidARMarker对象

​ VoidARMarker是组件核心接口，提供了THREE JS微信小程序适配版本核心渲染以及云识别和图像跟踪等功能。

样例：

  onLoad() {
    wx.showLoading({
      title: '程序初始化中...',
    });
    var that = this;
    this.arviewer = this.selectComponent('#arviewer').getInstance({
      cloudKey:"xxxxxxxx",
      onCreate(){
        wx.hideLoading();
      },
      onFind(res){
        
      },
      onLoadComplete(){
        
      }
    });
  },

1.2 初始化组件扩展

组件扩展，是对模型渲染组件的功能扩展。

目前实现了“模型加载”、“模型点击”、“模型控制”和“陀螺仪跟踪”4个扩展功能，在项目中可以根据实际需要添加相应的扩展。

组件扩展需在组件onCreate事件后，才可以添加，例如：

//获取插件
var plugin = requirePlugin("voidar")
....
var that = this;
this.arviewer = this.selectComponent('#arviewer').getInstance({
      onCreate(){
        that.addExtension();
      }
});
...
//添加初始化扩展
addExtension:function(){
    var arviewer = this.arviewer;
    var THREE = arviewer.THREE;
    ...
}

1.3 打开AR相机

AR相机，在插件初始化完成后自动开启。

1.4 图像云识别

图像云识别，在相机获取图像帧数据后自动启动。

AR功能的开关可以通过 enableAR(boolean b,boolean camera) 接口控制。

参数：

​ 第一个参数: 云识别功能开关；

​ 第二个参数: 相机功能开关（可选，在关闭云识别功能下，独立控制相机是否开启，默认值为false)；

样例：

//开启AR功能（开启相机，开启图像识别）
this.arviewer.enableAR(true);
//关闭AR识别，关闭相机
this.arviewer.enableAR(false);
//只停止识别，相机开启
this.arviewer.enableAR(false,true);

1.5 显示AR内容

在onFind识别成功事件后显示AR内容。

如果AR内容为小程序AR编辑器中制作的模型，插件将自动加载内容并显示；

如果内容是通过开发者后台设置的自定义参数，通过获取metadata值后，内容由开发者呈现。

样例：

this.arviewer = this.selectComponent('#arviewer').getInstance({
....    
//识别成功，如果内容资源是编辑器生成的模型，自动加载显示；如果内容为自定义数据，通过res.metadata获取值后，内容由开发者呈现
//res.metadata也可以作为编辑器生成的模型的扩展数据。
onFind(res){
    //模型是否需要实时加载，应用运行期间已经加载的模型会自动缓存
    if (res.needLoad){
        wx.showLoading({
            title: '已识别，加载中',
        })
    }
}
....
});

1.6 退出AR

当小程序触发onUnload，AR内容销毁。

样例：

onUnload:function(){
    if(this.arviewer){
      this.arviewer.deinit();
      this.arviewer = null;
    }
}

二、类API

2.1 VoidARMarker类

  • VoidARMarker类 属性

    名称 类型 说明
    THREE Object THREE JS的THREE对象
    camera THREE.Camera 渲染相机
    scene THREE.Scene 渲染场景
    renderer THREE.WebGLRenderer webgl渲染器
    sunLight THREE.DirectionalLight 方向光
    ambientLight THREE.AmbientLight 环境光

    VoidARMarker类模型相关接口

    注：需要在onCreate事件后，按照下面代码获取到示例才可使用。

    this.arviewer = this.selectComponent('#arviewer').getInstance(...)

  • VoidARMarker类 方法

    • 添加模型

      addModel(THREE.Object3D model, boolean autoSize)

      参数：

      ​ model : 模型对象

      ​ autoSize: 是否自动调整相机位姿，让模型在屏幕中间显示，默认值为false

      返回：

      ​ 无

    • 获取模型

      getModel(string|number key)

      参数：

      ​ 当key值类型为数字时，按照“索引值”查询模型；当值为string时，将按照“模型名称”查询。

      返回：

      ​ THREE.Object3D

    • 删除模型

      removeModel(string|number key)

      参数：

      ​ 当key值类型为数字时，按照“索引值”查询模型；当值为string时，将按照“模型名称”查询。

      返回：

      ​ 无

    • 删除所有模型

      removeAllModel()

      参数：无

      返回：无

    • 反初始化，资源释放

      deinit()

      参数：无

      返回：无

  • VoidARMarker类 事件

    名称 说明
    onCreate 组件构建完成
    onUpdate 帧循环事件，多用于插件扩展中
    onCameraReady 获取到相机图像数据

2.2 动画控制接口

动画控制功能通过扩展THREE.Object3D类实现，增加了以下方法：

  • 播放模型动画

    playAnimation(string|number animKey, int loop, function onAnimFinished)

    参数：

    ​ animKey: 名称或者索引值

    ​ loop: 循环方式，支持单次和循环 （可选）

    ​ onAnimFinished: 动画播放完成回调（可选）

    返回：

    ​ 无

  • 停止播放模型动画

    stopAnimation()

    参数：无

    返回：无

  • 切换到下一个动画

    nextAnimation()

    参数：无

    返回：无