iOS_SDK
简介
本文档描述货架拼接iOS SDK如何使用。
系统支持
系统:iOS 9.0 以上
硬件:armv7 arm64 (Starndard architectures) (暂不支持模拟器)
Release Notes
时间 | 版本 | 说明 |
---|---|---|
2021.03.09 | 3.0.1 | 新增光线检测功能 |
2020.12.30 | 3.0.0 | 新增图片拼接功能 |
2020.11.12 | 2.0.0 | 新增支持排面统计占比 |
2019.08.30 | 1.0.0 | 第一版,视频拼接 |
集成说明
货架拼接SDK全部为源代码,包括体验APP的UI部分和Http接口、重合度算法接口的定义和使用。没有打包动态库和静态库。用户拷贝相关功能代码至项目中即可,并修改相应文件名以避免符号冲突。
体验APP使用
SDK的工程结构如下:
${SDK_ROOT}
├─ EasyDLStitch // Demo工程文件
├─ images // 资源文件
├─ RES // 配置文件
获取鉴权
- 进入EasyDL零售版的百度智能云控制台应用列表页面,如下图所示:
- 如果还未创建应用,请点击「创建应用」按钮进行创建。创建应用后,参考鉴权参考文档,使用API Key(AK)和Secret Key(SK)获取access_token
下载SDK包后,填写ak、sk等信息。在RES/conf.json相应位置填入:
{
"ak": "Mz0zhObvEZ6lnG1K3renXXXX", // API Key的值
"sk": "188fRHYvLPmlPrNCDpBnkhL3ydXXXXX", // Secret Key的值
"apiUrl": "https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/detection/XXXX" // 定制商品检测服务API
}
视频拼接参数设置
体验APP中对视频截取帧的频率为1秒1帧,由于每个视频的帧数不能大于60,所以体验APP不能拼接长度大于60s的视频。开发者可根据实际情况调整截帧的频率,并相应限制视频长度。调整频率方法为修改easydl-stitch-ios/ViewController/StitchViewController.m中:
static int frameInterval = 1;//截帧间隔(秒)
并在合适的地方提示视频长度限制:
UIAlertController *actionSheet = [UIAlertController alertControllerWithTitle:@"选择对象(视频长度不能超过60s)" message:nil preferredStyle:UIAlertControllerStyleActionSheet];
图片拼接参数设置
体验APP中提供了图片拼接的摄像头代码和获取图片重合度算法的c++代码。通过调节摄像头和算法的参数,获取最佳的拍摄效果和拼接效果。修改easydl-stitch-ios/ViewController/ImagePickerViewController.mm:
// 以下为用户自定义配置
#define kThreshold 75 // 判断重合的阈值,0~100之间
#define kStrategy "phash" // 重合算法,类型:["ahash","phash","dhash"]
#define kThetaZ 60 // 手机倾斜Z轴角度阈值
#define kThetaXY 20 // 手机倾斜XY轴角度阈值
#define kOverLapControl true // 是否与遮罩重合才可以拍照
#define kOrientationControl true // 是否手机持握方向符合要求才可以拍照
#define kSkipFrames 3 // 跳过视频帧比对的数量,比如每3帧比对一次
#define kBrightnessLow -3 // 光线强度暗度阈值,-99~99之间
#define kBrightnessHigh 5 // 光线强度亮度阈值,-99~99之间
#define kBrightnessControl false // 是否光线符合要求才可以拍照
参数说明:
- 获取重合度有"ahash","phash","dhash"三种算法,返回0~100之间的数值,越大表示重合度越高。不同算法返回的数值有区别,需相应调整阈值
- 手机倾斜XY轴指左右倾斜,Z轴是前后倾斜,当倾斜角度过大会影响拼接效果
- 设置只有手机倾斜角度、待拍摄图片与上一张图片重合度、环境光线亮度等条件符合要求才拍摄图片,保证拍摄效果
- 相机默认为每秒30帧,修改kSkipFrames的值调节做重合度对比的速度,避免卡顿或拍摄状态切换过快
拼接API调用流程
- 创建任务:开始拼接整个流程
- 加货架图:上传图片
- 开始任务:启动货架拼接离线任务
- 查询任务:查询拼接任务的状态和结果
其他:
- 取消任务:取消正在进行或者等待的任务
- 任务列表: 查询所有状态的任务列表
- 终止任务:终止正在进行或者等待的任务
API接口说明
以下接口为SDK调用货架拼接API的方法。货架拼接API接口的返回值及其他信息参见文档货架拼接API调用方法。
创建拼接任务
- (void)createSpliceTaskWithConfig:(NSDictionary *)config
successHandler:(SuccessBlock)successHandler
failHandler:(FailureBlock)failHandler;
其中config为参数,后面两个回调block。参数取值及描述:
参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
---|---|---|---|---|
api_url | 是 | string | 商品检测服务的url | 无 |
row_image_nums | 是 | array[number] | 各行待拼接货架图片的数量,array长度为货架图片的行数,array[i]为第i行的货架图片数量 | 行数不大于3,行内图片数量不大于60 |
detection_threshold | 否 | float | 商品检测服务的阈值 | 默认值为商品检测服务的阈值,取值范围[0,1] |
nms_iou_threshold | 否 | float | 检测框矫准去重的阈值 | 默认值为0.45, 取值范围[0.2,0.8] |
上传图片
- (void)uploadImageWithConfig:(NSDictionary *)config
successHandler:(SuccessBlock)successHandler
failHandler:(FailureBlock)failHandler ;
其中config为参数,后面两个回调block。参数取值及描述:
参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
---|---|---|---|---|
task_id | 是 | string | 货架拼接任务id | 无 |
row | 是 | number | 图片对应行的index | 取值从0开始,需小于创建任务参数row_image_nums的长度 |
column | 是 | number | 图片在行内所在的index | 取值从0开始,需小于创建任务参数row_image_nums[row]的取值 |
image | 是 | string | 上传图片的base64编码 |
启动拼接任务
-(void)startSpliceTaskWithConfig:(NSDictionary *)config
successHandler:(SuccessBlock)successHandler
failHandler:(FailureBlock)failHandler;
其中config为参数,后面两个回调block。参数取值及描述:
参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
---|---|---|---|---|
task_id | 是 | string | 货架拼接任务id | 无 |
查询任务状态
-(void)queryTaskResultWithConfig:(NSDictionary *)config
successHandler:(SuccessBlock)successHandler
failHandler:(FailureBlock)failHandler;
其中config为参数,后面两个回调block。参数取值及描述:
参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
---|---|---|---|---|
task_id | 是 | string | 货架拼接任务id | 无 |
查询任务列表
-(void)listTaskWithConfig:(NSDictionary *)config
successHandler:(SuccessBlock)successHandler
failHandler:(FailureBlock)failHandler;
其中config为参数,后面两个回调block。参数取值及描述:
参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
---|---|---|---|---|
task_ids | 否 | array[string] | 只返回指定id的任务信息 | 无 |
begin_time | 否 | number | 只返回begin_time以后创建的任务信息 | 时间戳 |
end_time | 否 | number | 只返回end_time之前创建的任务信息 | 时间戳 |
终止任务
-(void)terminateTaskWithConfig:(NSDictionary *)config
successHandler:(SuccessBlock)successHandler
failHandler:(FailureBlock)failHandler;
其中config为参数,后面两个回调block。参数取值及描述:
参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
---|---|---|---|---|
task_id | 是 | string | 货架拼接任务id | 无 |
错误码
以下为SDK使用的错误码,API接口错误码参见货架拼接API错误码。
错误码 | 说明 |
---|---|
200002 | 模型配置错误,请检查传入的配置文件是否有效 |
100006 | API ,AK/SK 换取token失败 |
100007 | API, 请求 API 失败 |