Appearance
ezxrCloudARWorld 算法插件
云定位-3DoF 算法是基于大空间云定位服务，通过相机画面识别场景并定位设备的观察位置，综合利用 3DoF（imu）算法，同步并更新渲染相机的位姿，实现手机与虚拟内容的交互的能力。
云定位-6DoF 算法是基于大空间云定位服务，通过相机画面识别场景并定位设备的观察位置，综合利用 6DoF 算法，同步并更新渲染相机的位姿，实现手机与虚拟内容的交互的能力。
插件申请和示例代码
为了快速对插件进行基础的了解和认识，请直接下载示例 Demo，使用微信小程序开发工具打开，修改 AppId 为已申请插件授权的 AppID，替换绑定了上述 AppID 的内容资源，然后在真机扫码预览效果。
插件权限申请
- 首先要在小程序管理后台的“设置-第三方服务-插件管理”中添加插件，通过 AppID** [wx5289d5cc5c5c77f9]** 查找插件并添加。
- 或者在微信小程序开发者工具中，导入示例 Demo 以后，等开发工具提示需要插件权限时，点击『申请』
内容资源替换
- 第一步，在洞见 AR-World 小程序能力平台创建 6DoF 跟踪 - 大场景（视觉定位）内容
- 第二步，参考接入示例接入
示例 Demo
更新日志
20240625 v1.4.1
新增定位平滑功能
20230814 v1.3.8
优化视觉定位先验功能
20230714 v1.3.7
增加算法启动和成功运行状态回调接口，优化 3DoF 相关
20230714 v1.3.6
增加算法启动和成功运行状态回调接口
20230615 v1.3.5
修复了云定位异常问题
20230612 v1.3.4
修复一些已知问题
20230507 v1.3.2
修复一些 bug
20230307 v1.3.0
支持 unity 和 threejs Web 双编辑器
支持洞见 AR-World 小程序能力平台配置
拍照功能使用说明
3.1 插件申明
javascript
"plugins": {
"ezxrARSession": {
"version": "1.4.1",
"provider": "wx5289d5cc5c5c77f9"
}
},3.2 提供方法
插件对外提供 ARSession 组件和 AREzxr 方法库。 如果需求中仅关注云定位/云识别状态，不需要相机的实时 pose，可以不处理虚拟相机 pose 数据。
【ARSession组件】
| 方法名称 | 方法说明 | 入参与返回 | 最低支持版本 |
|---|---|---|---|
| fnStart | 算法启动 | trackerType：跟踪类型，1-3dof，11-6dof； locationType：定位类型，填3； trackerOption：跟踪参数 renderer: 渲染引擎上下文 onStarted: 算法启动完成回调, >=1.3.6版 onRecogSuccess: 算法成功运行回调, >=1.3.6版本
| 1.3.0 onStarted onRecogSuccess 需要>=1.3.6版本 |
| fnSetOnFirstLocated | 第一次定位成功回调 | 返回：locType,result | 1.3.0 |
| fnSetOnLocated | 定位回调 | 返回：locType,result | 1.3.0 |
| fnSetMotionChanged | 设置 motion 回调 | 入参：function(res){} | 1.3.0 |
【AREzxr方法库】
| 方法名称 | 方法说明 | 入参与返回 | 最低支持版本 |
|---|---|---|---|
| checkARSupport | 查询是否支持 AR | 返回：arSupport, camFov | 1.3.0 |
| fnGetTrackType | 查询当前设备使用的跟踪算法 | 返回： 1 : 3DoF 跟踪算法 11: 6DoF 跟踪算法 1 12: 6DoF 跟踪算法 2 | 1.3.0 |
| fnWxRequestRes | 获取内容平台配置 | 入参如下： cid：内容平台 cid（同内容id） key：内容平台环境，development（测试）/production（线上） 返回如下： contentId：内容ID contentName：内容名 contentPackageUrl：内容包资源链接 contentType：内容类别，2-6dof大场景；4-3dof大场景 algorithmType：3-3dof，4-6dof editorType： 1-web 编辑器 2-unity 编辑器 mapInfo：{ mapResources：[ resourceType：7-geo， 10-nav resourceUrl：对应地址 ] } | 1.3.0 |
| PoseUpdate | 获取 GL 坐标 pose | 算法更新。 | 1.3.0 |
fnGetGlobalGLPose | 获取 ezxrGL 坐标 pose | 获取算法坐标。 返回:{ ezxrPose,pose,timestamp,spaceUncertainty,timeUncertainty} | 1.3.0 |
| fnTakephoto | 拍照 | 返回：临时存储路径 | 1.3.0 |
TIP
arSupport 为 false 时，该设备无法体验，应该交互上提示用户
6DoF 跟踪中，12 效果会好于 11，建议对于 11 的状态给予交互上的提示
3.3 接入示例
3.3.1 引用算法
javascript
const plugin = requirePlugin('ezxrARSession')
// 在page或component的json文件中添加
"usingComponents": {
"ezxr-arsession": "plugin://ezxrARSession/ARSession",
}
// 在page或component的wxml文件中添加
<ezxr-arsession id="ezxr-arsession"></ezxr-arsession>3.3.2 内容拉取和渲染引擎
插件 demo 内容渲染可选 threejs-miniprogram 或 易现自研渲染引擎(Insight) ；对应 threejs web 编辑器和 unity 编辑器。
如选择 threejs-miniprogram 渲染引擎，可在内容平台使用 Web 编辑器制作资源后发布。
如选择 Insight 渲染引擎，当前需要依赖易现内部创作工具进行资源导出，开发者可提供定制美术资源，易现进行导出后使用。
javascript
// 从洞见 AR-World 小程序能力平台拉取内容资源
this.ezxr = new plugin.AREzxr();
const response = await this.ezxr.fnWxRequestRes(7911, 'development');// 此处7911为创建内容的cid
// contentType 2-6dof大场景 4-3dof大场景
if (response.contentType === 2 || response.contentType === 4) {
let rootPath;
// editorType 1-web编辑器 2-unity编辑器
if (response.editorType === 1) rootPath = '/threejs/pages/Entrance/index?';
else if (response.editorType === 2) rootPath = '/Insight/pages/Entrance/index?';
else return console.error('response with invalid editorType');
wx.navigateTo({
url: rootPath + 'contentPackageUrl=' + response.contentPackageUrl + '&algorithmType=' + response.algorithmType,
});
} else {
return console.error('response with invalid contentType');
}
// 跳转对应编辑器页面
onLoad: function (options) {
this.data.isAndroid = wx.getSystemInfoSync().platform === 'android';
// 内容资源
if (options.contentPackageUrl) {
this.setData({
contentZipUrl: options.contentPackageUrl,
});
}
else {
console.error("Entrance with empty content url");
}
// 根据创建内容类型初始化算法类型
if (options.algorithmType) {
if(options.algorithmType == 3) {
this.data.tracker = 1; // 3dof
}
if(options.algorithmType == 4) {
this.data.tracker = 11; // 6dof
}
}
else {
console.error("Entrance with empty algorithmType");
}
},3.3.3 启动算法
要求先启动内容后再启动算法。
javascript
/**
* 生命周期函数--监听页面初次渲染完成
*/
onReady: async function () {
// 第一步：获取设备支持&获取内容配置
this.ezxr = new plugin.AREzxr();
const ins = await this.ezxr.checkARSupport();
console.log('ARSupport', ins);
if (ins.arSupport) {
this.setData({
camFov: ins.camFov, //需要传递给渲染引擎
});
} else {
console.error('ar support is false');
return;
}
// 第二步：启动内容
this.setData({
initContent: true, // 触发加载并渲染内容
});
const content = this.selectComponent('#ezxr-arcontent');
this.arContentCpt = content;
},
/**
* 内容加载完成回调
*/
onContentInited: async function (params) {
// 第三步：启动算法
this.setData({ initSession: true, });
const session = this.selectComponent('#ezxr-arsession');
this.arSessionCpt = session;
console.log('arSessionCpt', plugin, this.arSessionCpt);
//定位结果回调
this.arSessionCpt.fnSetOnLocated(res => {
console.log('location result: ', res);
});
//第一次定位成功回调
this.arSessionCpt.fnSetOnFirstLocated(res => {
console.log('location result first: ', res);
});
//如不需要，可不设置motion回调
// this.arSessionCpt.fnSetMotionChanged(res => {
// console.log('motion changed: ', res);
// });
// 需要确保在渲染引擎初始化成功之后
const renderer = this.arContentCpt.fnGetRenderer();
// 算法启动回调, 此时背景画面渲染已开启;
const onStarted = () => {
console.log("Tracker onStarted");
this.setData({
initLoading: false,
});
let tracktype = this.ezxr.fnGetTrackType();
console.log('Entrance index current tracktype', tracktype);
};
// 算法初始化完成回调, 此时平面检测成功, 算法pose开始更新;
const onRecogSuccess = () => {
console.log("Tracker onCompleted");
this.setData({
state: true
});
// 开启云定位
this.ezxr.fnSetRequestLocStatus(true);
};
this.trackerOption = {
renderer: wcengine,
onStarted: onStarted,
onRecogSuccess: onRecogSuccess,
};
this.locationOption = {
isRecogOnce: false,
};
await this.arSessionCpt.fnStart(
this.data.tracker, // =1或11，3dof为 1,6dof为 11。
this.data.location, // =3
this.trackerOption,
this.locationOption
);
},3.3.4 渲染更新
javascript
const plugin = requirePlugin('ezxrARSession');
this.arEzxr = new plugin.AREzxr();
// 更新算法pose
this.arEzxr.PoseUpdate();
const poseStatus = this.arEzxr.fnGetGlobalGLPose();//获取算法pose
if (!poseStatus) {
console.warn("pose is null when updating cam pose");
return;
}
this.contentCpt.fnSetCameraPose(poseStatus.ezxrPose);// unity 编辑器
this.contentCpt.fnSetCameraPose(poseStatus.pose);// web 编辑器3.3.5 拍照
使用拍照组件 poster 组件，具体生成海报需求可自行在此组件修改，或者参考此组件实现。
组件引入和方法调用：
javascript
"ezxr-takephoto":"../../Components/poster/poster"
<ezxr-takephoto id="ezxr-takephoto" bind:takePhoto="takePhoto"></ezxr-takephoto>
takePhoto() {
const ezxrTakePhotoCpt = this.selectComponent('#ezxr-takephoto');
ezxrTakePhotoCpt.takePhoto(this.arContentCpt.arEzxr, this.arContentCpt);
},生成海报大小可调：
3.4 注意事项
使用算法插件页面不支持后台使用；如果中途跳转其他页面再次返回算法插件页面，内容显示将出现异常；