TBS Web AR JsApi 说明


本文档接口使用仅针对TBS AR内测申请通过的开发者,其他开发者会因为权限问题无法使用,当前外部可通过邮件tbs@tencent.com申请,后期会全面开放使用,敬请期待。

一、TBS JS库引用

<script src="http://res.imtt.qq.com/tbs/tbsar.js "></script>

添加以上语句的页面可在集成了TBS的应用上(微信、手Q、空间等)调用TBS JSAPI接口

二、AR 相关接口

1、tbs.event.onAREngineStatusChanged(callback)
接口说明:注册AR模块初始化过程中的事件监听,需要在执行tbs.ar.initAREngine前注册,否则有部分事件会监听不到。
param {Function} callback (event) 初始化AREngine过程中事件回调函数
{Object} event json格式对象
{String} status ‘READY’引擎初始化成功,’DOWNLOADING’插件下载中,’DOWNLOAD_START’插件开始下载,’FAILED’引擎初始化失败
{Number} progress 插件下载过程中,下载进度
{Number} size 开始下载插件时,插件需要下载的byte
{Number} code 引擎初始化失败错误码
{String} message 初始化失败描述

tbs.event.onAREngineStatusChanged(function(event)
{
var logString = '';
if (event.status === 'READY')
logString = "engine ready";
else if (event.status === 'DOWNLOADING')
logString
= "engine downloading: " + event.progress;
else if (event.status === 'DOWNLOAD_START')
logString
= "engine need download: " + event.size + "byte";
else if (event.status === 'FAILED')
logString
= "engine load failed: " + event.code + ";" + event.message;
//do something
})

2、tbs.ar.initAREngine(callback)
接口说明:初始化AR模块,异步执行,结果已回调的形式通知页面。
param {Function} callback (result) 初始化回调
{Object} result json格式对象
{Boolean} success true初始化成功;false初始化失败
{Number} errorCode 失败情况下错误码
{String} message 失败情况下错误描述

tbs.ar.initAREngine(function(result)
{
if (result && result.success){
//success do something
}else{
//failed
}
});

3、tbs.ar.addARMarkerWithURL(target, callback)
接口说明:添加需要识别的目标对象,需要指定name和待训练的图片,识别引擎训练训练图片后,开始识别图片中的对象。name是唯一标识符,removeMarker时候需要用到。

param1 {Object} target
json对象,描述需要添加的marker信息
{String} name 唯一标识符
{String} url 图片地址,识别引擎训练这个图片,后续对图片里的目标进行识别
param2 {Function} callback (result) 添加成功与否的回调通知
{Object} result json对象,描述是否添加成功
{Boolean} success true添加成功,false添加失败
{Number} errorCode 失败情况下的错误码
{String} message 失败情况下的错误描述

var markers = [
{
name: 'mark1',
url: 'http://res.imtt.qq.com/image/10-0.jpg'
},
{
name: 'mark2',
url: 'http://res.imtt.qq.com/image/bmw.jpg'
},
{
name: 'mark3',
url: 'http://res.imtt.qq.com/qqbrowser_x5/kakaxi.jpg'
}
];
function addMarker(idx) {
tbs.ar.addARMarkerWithURL(markers[idx], function(result) {
if(result && result.success){
//success
}else{
//failed
}
});
}
addMarker(0);

4、tbs.ar.registerARRecognitionTarget(target, callback)
接口说明:注册云端识别,需要指定唯一的name(后台提交marker图片后返回的accesskey,当当前后台还为完善,可以联系tbs@tencent.com手动提交),name在移除的时候需要用到。类别为空的情况下,表示识别后台所有支持的类别。

param 1 {Object} target 需要识别对象的json描述
{String} name 唯一标识符
{String} targetCategory 类别,如’car’,’flower’ 可不填
param 2 {Function} callback (result) 云端识别对象添加成功与否回调
{Object} result 成功或失败json描述
{Boolean} success true成功,false失败
{Number} errorCode 失败情况下错误码
{String} message 失败情况下错误原因描述

var targets = [
{
name: "target1",
targetCategory:[]
}
]
tbs.ar.registerARRecognitionTarget(targets[0],function cbk(result){
if(result && result.success){
//success
}else{
//failed
}
});

5、tbs.event.onARFrameUpload(callback)
接口说明:注册云端识别上传与结果事件监听,每次上传数据帧到后台都会响应UPLOADING事件,收到后台结果后相应DONE事件
param {Function} callback (event) 上传事件通知回调
{Object} event json格式对象
{String} status ‘UPLOADING’开始上传;’DONE’完成

tbs.event.onARFrameUpload(function(result){
if(result.status == 'UPLOADING'){
//uploading
}else if(result.status == 'DONE"){
//done
}
});

6、tbs.event.onARRecoginitionResult(callback)
接口说明:云端识别和单marker识别事件监听。 单marker识别有两个事件:TRACKING|LOST,即跟踪中和丢失 云端识别有一个事件:’DETECTED’
param {Function} callback (result) 监听函数
{Object} result json格式对象
{String} status ’DETECTED’云端识别成功,’TRACKING’单marker识别跟踪中,’LOST’单marker识别丢失
{String} category 识别到的类别,如’car’/’flower’
{Array} detail 注意,这里是json对象。描述云端识别到的对象的详细信息
{String} name 单marker识别对应的marker name
{Array} transformMatrix float类型的数组,长度16.目标的空间矩阵
{Array} corners float类型的数组,长度为8,在横屏模式下目标的四个顶点坐标,顺序是左下、左上、右上、右下,但是前端使用的时候普遍是竖屏模式,所以前端开发需要进行坐标转换。(如果想获取3D投影矩阵,可以通过getARCameraStatus接口获取,后面会介绍)

Alt text

tbs.event.onARRecoginitionResult(function(event)
{
var logString = '';
if (event.status === 'TRACKING')
{
//单marker识别跟踪中
}
else if (event.status === 'LOST') {
//单marker识别目标丢失
}
else if(event.status === 'DETECTED'){
//云端识别成功
}
});

7、tbs.ar.removeARMarker(target)
接口说明:移除识别目标,停止该目标的识别
param {Object} target target是json对象
{String} name 唯一标识符,需要与addARMarkerWithURL一致

var markers = [
{
name: 'mark1',
url: 'http://res.imtt.qq.com/qqbrowser_x5/10-0.jpg'
},
{
name: 'mark2',
url: 'http://res.imtt.qq.com/qqbrowser_x5/bmw.jpg'
},
{
name: 'mark3',
url: 'http://res.imtt.qq.com/qqbrowser_x5/kakaxi.jpg'
}
];
function removeMarker(idx) {
tbs.ar.removeARMarker(markers[idx]);
}
removeMarker(0);

8、tbs.ar.cleanARMarker()
接口说明:一次性移除之前添加的所有marker对象,停止识别工作

tbs.ar.cleanARMarker();

9、tbs.ar.getARCameraStatus()
接口说明:获取相机参数信息,返回json格式字符串,包含相机是否打开,采集的宽高(width,height)和初始化矩阵的信息

json={"on":true,"width":640,"height":480,"projectMatrix":[2.5340938568115234,0,0,0,0,3.325188398361206,0,0,-0.08572866022586823,-0.10817166417837143,-1.0004000663757324,-1,0,0,-2.0004000663757324,0]}

三、Demo示例
Android手机(IOS不支持)微信\手Q\空间等集成了TBS应用扫描如下二维码进入测试连接,本地Marker识别可扫描BruceQ(线上版本已支持),云端marker识别(6月底最新版本支持,人脸识别和SLAM技术处于开发中。
具体示例操作如下:
1、微信扫一扫二维码

Alt text

2、页面打开会自动下载ar插件,然后点击本地marker按钮,然后对准对应的marker图片即可出现图片识别到的信息和细线框包围位置。

Alt text

图片资源如下:

Alt text

Alt text

其他demo效果可以查看以下视频连接
识别示例
识别+跟随