绘本识别
绘本识别
绘本识别模块主要是识别儿童绘本、教材，提供对应绘本教材的音频和内容。
Android SDK接入步骤
1.集成图灵AI平台的Android SDK，具体步骤可参考集成指南，可在Demo中绘本识别部分参考绘本识别接口的调用；
2.集成翻页键检测库（可选，可以用其他的翻页检测库）。图灵提供翻页检测库，有需要可以下载翻页检测Android SDK，具体使用说明可以参考翻页检测文档；
3.参考绘本接入指南，确定摄像头ID参数和场景参数，分别对应BookRequestConfig中的cameraId、type；
4.使用绘本识别接口上传图片得到识别结果，然后播放和显示绘本识别内容。
SDK接口使用步骤
第一步：初始化SDK， 获取userData；
第二步：获取TuringOSClient实例；
第三步：创建绘本识别参数，cameraID和type为必须参数，cameraID为摄像头标定结果，type为场景确认参数（具体可参考绘本接入指南)；
第四步：上传图片识别，filePath为图片路径，获取识别结果。
//第一步：初始化SDK，获取userData
SdkInitializer.init(deviceID, context, apiKey, secert, sdkInitializerListener);
//第二步：获取TuringOSClient实例
client = TuringOSClient.getInstance(mContext, userData);
//第三步：创建绘本识别参数，mTuringCameraID为摄像头标定的结果，mTuringType为场景参数，不同的设备使用场景需要不同的mTuringType值，具体参考绘本接入指南
BookRequestConfig.Builder builder = new BookRequestConfig.Builder();
builder.cameraID(mTuringCameraID)
.enableUseQa(true)
.enableDebug(true)
.type(mTuringType)
.enableInnerUrlFlag(true)
.phoneModel(android.os.Build.MODEL);
bookRequestConfig = builder.build();
//第四步：上传图片识别，filePath为图片路径
client.actionBook(filePath, bookRequestConfig, booklistener);
相关参数说明
BookRequestConfig
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| cameraId | int | Y | - | 在图灵后台注册的摄像头编号，包含摄像头标定参数以及硬件平台信息 |
| bookId | long | N | - | 绘本模型ID，封面识别不需要此参数，内页识别则需要把封面识别结果中的 bookId 传入 |
| innerUrlFlag | Boolean | N | - | 是否需要内页音频压缩包 false：表示不需要（默认） true：表示需要，封面识别成功后会返回压缩件下载url |
| debug | Boolean | N | - | 是否开启调试模式： false：表示不开启（默认） true：表示开启 注意：APIKey 正式量产（状态为正式状态）， 不支持 Debug 模式 |
| useQa | Boolean | N | - | 开启QA模式：false（default），使用需要管理平台开通对应题库 |
| type | int | Y | - | 0：标准版绘本机器人 1：标准版手机支架 2：标准版绘本台灯 3：升级版绘本机器人 4：升级版绘本台灯 5：指读版绘本机器人 6：指读版绘本台灯 9：纯指读版绘本机器人 10：纯指读版绘本台灯 11：标准版卡⽚识别 12：指读版卡⽚识别 场景确认参数，不同的场景可用的值不同，具体可参考绘本接入指南 |
| phoneModel | String | N | - | 手机型号（支架必填，非支架不需要） type=1时，改参数必填 |
| languageOrder | Integer | N | - | 语言顺序 1.中文优先 2.英文优先 默认1 |
| textFlag | Integer | N | - | 是否返回热区文本,默认0(需要联系图灵商务或者项目进行开通): textFlag=0：不返回 textFlag=1：返回热区文本 textFlag=2：返回热区文本+翻译文本 |
| accessModel | Integer | N | - | 访问模型 1:公有库+私有库 2:公有库 3:私有库 默认1 |
| modelOrder | Integer | N | - | 优先级顺序 1:公有库优先 2:私有库优先 默认2 |
| osState | String | 否 | clean | 清除休眠状态： 1. 固定传"clean" 2. 非休眠状态不可使用，否则返回1009的operateState码 |
| ext | Map | N | - | 其他输入，扩展参数 |
参数创建
BookRequestConfig.Builder builder = new BookRequestConfig.Builder();
builder.cameraID(1)
.enableUseQa(true)
.enableDebug(true)
.type(1);
绘本输出
封面识别成功返回示例：
{
"code":200,
"globalId":"98411492145000000",
"message":"success",
"nlpResponse":{
"intent":{
"code":1000056,
"operateState":2000,
"parameters":{
"msg":"cover recognition succeeded",
"intentCode":200,
"titleData":{
"cover":"http://universe-file-limit.tuling123.com/201912171915/9eeeaea4b6aa0cf34230ceb609e0c0f3/book_image/7b15cb80fe334d5e959c4ecc14b1a0be.jpg",
"bookVersion":3,
"zipUrl":"http://universe-file-limit.tuling123.com/201912171915/dbb3f754afe5a5038b9abea9c03f82b0/robot_story/12948/12948.zip",
"nameUrl":"http://universe-file-limit.tuling123.com/201912171915/14a7698950461761f5994c2214d6bee8/title/12948.mp3",
"name":"狼来了",
"bookName":"7b15cb80fe334d5e959c4ecc14b1a0be",
"bookId":12948
},
"commandUrl":"http://universe-file-limit.tuling123.com/201912171915/b5c3cdc000982ee3e55c579a8b71d13d/hint/success-1.mp3",
"debugData":{
"imgOriginalUrl":"http://turing-platform-openapi.oss-cn-beijing.aliyuncs.com/openapi/image/0b6c2dd6687a4c8cb73a3ca49ed9b3ca_69412281_98411492145000000_834c386edc924aacb366def72581a2f9.png",
"imgProcessedUrl":"http://turing-universe.oss-cn-beijing.aliyuncs.com/recognition_img/img224/180.0_35.0_250.0_560.0_320_240_crop_/7f01feb9-70af-4feb-9fcf-b02737309168.jpg"
}
}
},
"results":[
{
"groupType":0,
"resultType":"text",
"values":{
"text":"我要和你一起读故事了"
}
}
]
}
}
内页识别成功返回示例：
{
"code":200,
"globalId":"113607374688678001",
"message":"success",
"nlpResponse":{
"intent":{
"code":1000056,
"operateState":2000,
"parameters":{
"innerData":{
"pageUrl":"http://universe-file-limit.tuling123.com/202006101620/60f5821e936a55e6efadd1d8b393d3ab/robot_story/37353/37353-6.mp3",
"pageNum":6,
"bookId":37353
},
"msg":"inner page recognition succeeded",
"intentCode":207,
"hotZone":{
"pieceIndex":1423,
"pieceContent":"Excuse me. Where is the London Eye? It's next to the film museum near the Thames. ",
"pieceUrl":"http://universe-file-limit.tuling123.com/202006101620/fb6b6f4f04edd2e0ab066dae9cf5b33d/robot_story/37353/37353-6-1423.mp3"
},
"funcData":{
"finger":1,
"ocr":0
},
"debugData":{
"imgOriginalUrl":"http://turing-platform-openapi.oss-cn-beijing.aliyuncs.com/openapi/image/c8162cf54ada46bf883c0c19c8eba0de_356563768_113607374688678001_b3cb0572dbe1437aa0cefc2768516fe5.jpg",
"imgProcessedUrl":"http://turing-universe.oss-cn-beijing.aliyuncs.com/recognition_img/im224Finger/180.0_35.0_260.0_420.0_240_320_crop_/f25ceaa0-9c0d-486c-a895-5d481a052722.jpg"
}
}
}
}
}
参数说明：
intent-operateState
| operateState | 说明 |
|---|---|
| 1010 | 上传状态错误 |
| 1110 | 上传状态正确 |
| 1120 | 上传状态重复 |
| 1200 | 休眠状态 |
| 2000 | 绘本识别正常 |
| 3000 | 文本类问题数据输出，开启文本输入 |
| 3100 | 回答问题结束状态， 不再处理非图片类型请求 |
| 3200 | 回答问题状态(所有类型)-继续回答问题 |
| 3240 | 图片类问题-回答问题时被判断为无效的输入(不参与答题,前端可忽略该输出) |
| 3300 | 音频类问题数据输出，开启音频输入(注意音频类型!) |
| 3400 | 图片类问题数据输出。 |
| 1001 | 绘本图片识别异常，有intentCode |
| 1005 | 图片内容大小非法(取值范围:[1,200]kb) |
| 1006 | 图片内容处理异常 |
| 1007 | 请求Type非法 |
| 1008 | 请求中无图片信息 |
| 1009 | 错误输入(非法使用唤醒功能) |
intent-parameters
| 参数 | 类型 | 说明 |
|---|---|---|
| intentCode | int | 绘本状态 |
| msg | String | 返回信息（英文） |
| commandUrl | String | 提示语音 |
| titleData | TitleData | 封面识别返回信息 |
| innerData | InnerData | 内页识别返回信息 |
| debugData | DebugData | 调试信息 |
| funcData | FuncData | 功能参数，支持OCR和指读结果 |
| hotZone | HotZone | 点读热区信息 |
| success | boolean | 问答状态，用户回答是否正确 |
| sleepSec | int | 休眠状态，距离下次可请求绘本识别时间 |
| ext | map | 附加输出信息 |
| answerTimeoutSec | int | 问答状态，上传已读题目状态或回答题目时返回问题剩余可回答时间 |
| questionTimeoutSec | int | 问答状态，等待用户确认题目播放状态时间，有效期内图片问题不能作答，文本与音频类型可以回答 |
| backEvent | boolean | 问答状态事件回溯：如果上下文中的题目因为未读受保护而导致最近一次识别事件没有请求新题，纪录该次事件的时间。规定时间内用于用户上传状态readQuestion=FALSE/CANCEL则事件回溯。 |
| qParam | map | 问答状态，题目问题其他参数。 |
| aParam | map | 问答状态，题目答案其他参数 |
- qParam-evalAnswerData：音频类问答测评内容。
- aParam ：音频类评测结果输出。
TitleData
| 参数 | 类型 | 说明 |
|---|---|---|
| name | String | 绘本名称 |
| zipUrl | String | 绘本压缩包的url |
| bookVersion | Integer | 绘本版本，音频版本，判断是否需要更新 |
| nameUrl | String | 绘本名称的url |
| bookName | String | 绘本模型标识 |
| author | String | 绘本作者名称（版本2.0.0新增字段） |
| publisher | String | 出版社名称（版本2.0.0新增字段） |
| cover | String | 封面图片的url（版本2.0.0新增字段） |
| bookId | Long | 绘本Id |
InnerData
| 参数 | 类型 | 说明 |
|---|---|---|
| bookId | Long | 绘本Id |
| pageNum | Integer | 绘本页数 |
| url | String | 绘本内页音频 |
| pageUrl | String | 绘本内页音频（版本2.0.0新增字段） |
FuncData
| 参数 | 类型 | 说明 |
|---|---|---|
| ocr | int | 0:普通;1:ocr |
| finger | int | 0:无指读;1:可支持指读 |
HotZone
| 类型 | 参数 | 介绍 |
|---|---|---|
| int | pieceIndex | 热区索引 |
| String | pieceUrl | 热区在线的音频链接 |
| String | pieceContent | 热区文本 |
| String | transContent | 热区文本对应的中文文本 |
ext
| 参数 | 类型 | 说明 |
|---|---|---|
| evalFlag | int | 口语评测标志位（0不可测评，1可测评） |
| multiAudios | Array | 自定义热区多音频内容 |
| bookEvalFlag | boolean | 是否支持口语评测（需要后台开启输出口语评测标志位权限，封面识别时输出） bookEvalFlag=true：该书支持口语评测 bookEvalFlag=false：该书不支持口语评测 |
| bookSupportQa | array | 当前识别书本内包含的QA类型，AUDIO(音频), TEXT(文本), IMAGE(图片) |
- evalFlag：指读热区识别成功之后，evalFlag为1标识改热区文字支持口语评测，为0表示不支持口语评测。
- bookSupportQa：表示当前绘本支持的问答题目类型。
MultiAudio
| 参数 | 类型 | 说明 |
|---|---|---|
| text | String | 热区文本 |
| url | String | 热区音频文件URL或音频ID: URL有效时间为10分钟（自己上传的URL除外） |
| textKey | String | 音频名称 textKey=0：中文 textKey=1：英文 textKey=2：粤语 textKey=3：讲解 textKey=4：视频 |
DebugData
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| imgOriginalUrl | String | Y | - | 原图片链接 |
| imgProcessedUrl | String | Y | - | 算法处理后的图片链接 |
intentCode说明
| intentCode | 说明 |
|---|---|
| 200 | 识别绘本封面成功 |
| 201 | 识别绘本内页成功 |
| 202 | 绘本扉页识别成功 |
| 203 | 绘本无文本内页识别成功 |
| 204 | 绘本无意义内页识别成功 |
| 205 | 封面识别成功，热区识别成功 |
| 206 | 封面识别成功，热区识别失败 |
| 207 | 内页识别成功，热区识别成功 |
| 208 | 内页识别成功，热区识别失败 |
| 300 | 绘本封面识别失败 |
| 301 | 绘本内页识别失败 |
| 302 | 非缺省参数未找到 |
| 303 | 摄像头ID信息未找到 |
| 304 | 图片无法打开 |
| 305 | 图片尺寸异常 |
| 306 | 绘本内容未录入 |
| 307 | 当前绘本页音频缺失 |
| 308 | 未开通OCR功能 |
| 309 | 未开通指读功能 |
| 310 | 暂不支持该功能 |
| 311 | 此绘本为私有绘本 |
| 312 | 非法bookId |
| 400 | 封面算法识别超时 |
| 401 | 内页算法识别超时 |
| 402 | 绘本算法未知异常 |
一、封面识别和卡片识别
/**
*
*
* @param filePath 需要识别的图片文件路径
* @param bookRequestConfig BookRequestConfig
* @param listener
*/
public void actionBook(String filePath, BookRequestConfig bookRequestConfig, TuringOSClientListener listener)
/**
*
* @param data JEPG格式图片的byte[]数据
* @param bookRequestConfig
* @param listener
*/
public void actionBook(byte[] data, BookRequestConfig bookRequestConfig, TuringOSClientListener listener)
//调用
turingOSClient.actionBook(filePath, bookRequestConfig);
二、内页识别
在封面识别成功之后回返回bookID，将该bookID作为参数传入进行内页识别；
注意：bookID不影响换书场景，只需要在每次封面识别成功之后，记录并传入bookID即可。
/**
*
* @param fileName
* @param bookID 封面识别成功之后会在返回的结果中给出bookID
* @param bookRequestConfig
*/
public void actionBook(String fileName, long bookID, BookRequestConfig bookRequestConfig)
/**
*
* @param data JEPG格式图片的byte[]数据
* @param bookID
* @param bookRequestConfig
* @param listener
*/
public void actionBook(byte[] data, long bookID, BookRequestConfig bookRequestConfig)
//调用
turingOSClient.actionBook(filePath, bookID, bookRequestConfig);
三、指读识别
当封面识别成功之后会在FuncData中返回ocr和finger字段，具体表示如下
FuncData
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| ocr | int | Y | - | 0:普通;1:ocr |
| finger | int | Y | - | 0:无指读;1:可支持指读 |
实现指读识别的步骤：
第一步：成功识别绘本的封面，获取返回值中的FuncData--->finger字段，当finger字段等于1时，表示该绘本支持指读功能；
第二步：正常识别内页并上传带指读的图片，关注返回的intentCode的值，当intentCode等于207时，标志指读识别成功，并在HotZone中返回指读热区的信息，此时设备可以根据返回的指读信息，播放指读音频，显示指读内容。
四、指读内容口语评测
在指读成功识别之后，返回的 ext 字段evalFlag中附带口语评测的标志位，可根据标志位是否为1，直接调用口语评测接口 startEAWithRecorder 接口实现口语评测功能。
备注：
- 口语评测标志位需要联系商务开通，否则不会返回该字段；
- 通过该方式调用的口语评测与问答交互中的口语评测不属于同一个功能。该方式仅给出口语评测的标识，然后开发者自行调用口语评测接口实现。
绘本休眠
一、云端限流
由于设备在绘本模式使用过程中，设备受到翻页检测触发会不断的进行请求，云端已经对绘本请求做了限流。具体表现为下面输出参数intentCode=1200，即触发了云端限流。
具体返回示例如下：
{
"code":200,
"globalId":"116456280610447001",
"message":"success",
"nlpResponse":{
"intent":{
"code":1000056,
"operateState":1200
},
"results":[
{
"groupType":0,
"resultType":"text",
"values":{
"text":"休眠中，请3秒后再试试吧。"
}
}
]
}
}
-
当接受到请求识别返回的intentCode=1200时，说明触发了云端的限流开关。
-
此时图灵云端返回信息中会告知休眠状态和提醒距离下次自动唤醒的时间，该时间会随着无效请求进入休眠次数不断叠加。
- 云端唤醒：增加传参osState=clean可以唤醒休眠状态，或者等待提示的时间之后将会重新获得识别机会。
二、本地休眠
为避免触发云端限流和资源浪费，设备端可以自行实现本地休眠机制，对外Demo中的休眠流程如下图：
内容播放
SDK提供音频播放器
/**
*
* @param url 播放音频链接
* @param _playListener 播放状态接口
*/
public void playUrl(String url, PlayListener _playListener)
BookResPlayer bookResPlayer = new BookResPlayer(mContext);
bookResPlayer.playUrl(url, ContentPlayListener);