SDK接口调用

相机接口

具体返回格式见 数据接口

操作步骤:

  1. 身份验证:调用 [[AipOcrService shardService] authWithAK:SK 或其他验证方法;
  2. 初始化对应的ViewController,设置对应的block。
    如 身份证本地扫描识别:
UIViewController * vc =
    [AipCaptureCardVC ViewControllerWithCardType:CardTypeLocalIdCardFont andImageHandler:^(UIImage *image) {
    // 成功扫描出身份证
     [[AipOcrService shardService] detectIdCardFrontFromImage:image
                                                  withOptions:nil
                                               successHandler:^(id result){
    // 在成功回调中,保存图片到系统相册
     UIImageWriteToSavedPhotosAlbum(image, nil, nil, (__bridge void *)self);
     // 打印出识别结果
     NSLog(@"%@", result);
    }
                                                  failHandler:_failHandler];
    }];
    // 展示ViewController
    [self presentViewController:vc animated:YES completion:nil];
  1. 在合适的地方启动ViewController: 如[self presentViewController:vc animated:YES completion:nil]

数据接口

该调用方法传入需要识别的UIImage,异步识别,识别完成之后,回调返回识别结果。

主要类为AipOcrService类,使用单例[AipOcrService sharedService]来调用相关接口即可。

操作步骤:

  1. 身份验证:调用 [[AipOcrService shardService] authWithAK:SK 或其他验证方法;

  2. 调用相应接口

    • 通用文字识别(基础版、不含位置信息) detectTextBasicFromImage
    • 通用文字识别(含位置信息) detectTextFromImage
    • 通用文字识别(高精度、不含位置信息)detectTextAccurateBasicFromImage
    • 通用文字识别(高精度、含位置信息)detectTextAccurateFromImage
    • 通用文字识别 (含生僻字)detectTextEnhancedFromImage
    • 网图识别 detectWebImageFromImage
    • 身份证正面识别detectIdCardFrontFromImage
    • 身份证背面识别detectIdCardBackFromImage
    • 银行卡识别detectBankCardFromImage
    • 驾驶证识别 detectDrivingLicenseFromImage
    • 行驶证识别 detectVehicleLicenseFromImage
    • 车牌识别 detectPlateNumberFromImage
    • 营业执照识别 detectBusinessLicenseFromImage
    • 通用票据识别 detectReceiptFromImage

所有回调函数均在后台线程中被调用,如需在主线程中操作,请使用[[NSOperationQueue mainQueue] addOperationWithBlock]patch到主线程中,示例参考demo工程。

以下以通用文字识别调用为例,其他接口的参数与返回可参考API文档

NSDictionary *options = @{@"language_type": @"CHN_ENG", @"detect_direction": @"true"};
[[AipOcrService shardService] detectTextFromImage:finalImage withOptions:options successHandler:^(id result) {
    // 成功识别的后续逻辑
} failHandler:^(NSError *err) {
    // 失败的后续逻辑
}];

options参数详情

参数 是否必选 类型 可选值范围 说明
image(已由参数替代) true string - 图像数据,base64编码,要求base64编码后大小不超过1M,最短边至少15px,最长边最大2048px,支持jpg/png/bmp格式
recognize_granularity false string big、small 是否定位单字符位置,big:不定位单字符位置,默认值;small:定位单字符位置
mask false string - 表示mask区域的黑白灰度图片,白色代表选中, base64编码
language_type false string CHN_ENG、ENG、POR、FRE、GER、ITA、SPA、RUS、JAP 识别语言类型,默认为CHN_ENG。可选值包括:
- CHN_ENG:中英文混合;
- ENG:英文;
- POR:葡萄牙语;
- FRE:法语;
- GER:德语;
- ITA:意大利语;
- SPA:西班牙语;
- RUS:俄语;
- JAP:日语
detect_direction false boolean true、false 是否检测图像朝向,默认不检测,即:false。朝向是指输入图像是正常方向、逆时针旋转90/180/270度。可选值包括:
- true:检测朝向;
- false:不检测朝向。
detect_language false string true、false 是否检测语言,默认不检测。当前支持(中文、英语、日语、韩语)
classify_dimension false string lottery 分类维度(根据OCR结果进行分类),逗号分隔,当前只支持lottery。
lottery:彩票分类,设置detect_direction有助于提升精度
vertexes_location false string true、false 是否返回文字外接多边形顶点位置,不支持单字位置。默认为false
  • 结果返回
字段 必选 类型 说明
direction int32 图像方向,当detect_direction=true时存在。
- -1:未定义,
- 0:正向,
- 1: 逆时针90度,
- 2:逆时针180度,
- 3:逆时针270度
log_id uint64 唯一的log id,用于问题定位
words_result array() 定位和识别结果数组
words_result_num uint32 识别结果数,表示words_result的元素个数
+vertexes_location array() 当前为四个顶点: 左上,右上,右下,左下。当vertexes_location=true时存在
++x uint32 水平坐标(坐标0点为左上角)
++y uint32 垂直坐标(坐标0点为左上角)
+location array() 位置数组(坐标0点为左上角)
++left uint32 表示定位位置的长方形左上顶点的水平坐标
++top uint32 表示定位位置的长方形左上顶点的垂直坐标
++width uint32 表示定位位置的长方形的宽度
++height uint32 表示定位位置的长方形的高度
+words string 识别结果字符串
+chars array() 单字符结果,recognize_granularity=small时存在
++location array() 位置数组(坐标0点为左上角)
+++left uint32 表示定位位置的长方形左上顶点的水平坐标
+++top uint32 表示定位位置的长方形左上顶点的垂直坐标
+++width uint32 表示定位定位位置的长方形的宽度
+++height uint32 表示位置的长方形的高度
++char string 单字符识别结果
// 示例
{
    direction : 2,
    log_id : 676709620,
    words_result : [ {
            location : {
                height : 20;
                left : 86;
                top : 387;
                width : 22;
            };
            words : "N";
        },
    ],
    words_result_num : 1;
}

身份证质量控制

身份证本地质量控制已包含在[AipCaptureCardVC ViewControllerWithCardType:CardTypeLocalIdCardFont ....]之中。

相关的使用方法已在AipOcrSdk工程中开源,用户可根据自己的需要自行修改。

  • 初始化
[[AipOcrService shardService]getTokenSuccessHandler:^(NSString *token) {
    //*获取到身份证质量控制token*//
} failHandler:^(NSError *error) {

}];
// 利用获取到的token 完成 IdcardQualityAdaptor的初始化
IdcardQualityAdaptor *idcard = [[IdcardQualityAdaptor alloc]init];

[idcard initWithToken:token];
  • 检测图片
- (IdcardQualityModel *)process:(UIImage *)image width:(int)width height:(int)height channel:(int)channel cardType:(idcard_quality::IdCardType)type;

options参数

参数 类型 说明
image(已由image参数代替) String 图像数据,支持本地图像文件路径,图像文件二进制数据,要求base64编码后大小不超过1M,最短边至少15px,最长边最大2048px,支持jpg/png/bmp格式 长宽比应与身份证规格(1.6 : 1)接近。当身份证 (1)正方向完整位于输入图像内,占比80%-90% (2)正面姓名,号码,反面失效期 清晰,无反光 (3)无明显倾斜 时接口返回IDCARD_NORMAL, 其他情况返回细分错误码用于引导用户扫描到符合要求的图像。
Width,height,channel Int Uiimage的宽、高 、channel (RGB彩图设置为3)
type idcard_quality::IdCardType IDCARD_FRONT_SIDE为检测身份证头像面,IDCARD_BACK_SIDE为检测国徽面
IdcardQualityModel 中ImageStatusType属性 Int IDCARD_NORMAL = 0 图像包含占比合适,清晰,无反光的身份证 IDCARD_WRONG_LOCATION = 1 图像不包含占比合适的身份证。可能的情况包括非身份证,过于倾斜等 IDCARD_BLURRED = 2 图像包含占比合适的身份证,但关键字段模糊 IDCARD_OVER_EXPOSURE = 3 图像包含占比合适的身份证,但关键字段反光 IDCARD_REVERSED_SIDE = 4 输入图像与输入参数设置的身份证国徽/人脸面不匹配 IDCARD_MOVING = 5 连续输入算法的两帧之间差异过大,可能是镜头或身份证在晃动 IDCARD_TOO_SMALL = 6 图像包含身份证,但占比过小
  • 释放资源
- (void)releaseIdcardQuality;

特殊配置

截图分辨率系数

该系数影响到拍摄照片之后截取的图片大小

在AipOcrSdk/AipOcrSdk/View/AipCutImageView.m 中

//截图的分辨率系数 开发者可自行配置
static CGFloat const scale = 1.0;

图片放大/缩小系数

在AipOcrSdk/AipOcrSdk/View/AipCutImageView.m 中

//捏合操作最大/最小系数
static CGFloat const pinchMaxscale = 10.0;
static CGFloat const pinchMinscale = 0.5;