# LenzEngineLibrary_Android

**Repository Path**: ppz_bj/lenz-engine-library_-android

## Basic Information

- **Project Name**: LenzEngineLibrary_Android
- **Description**: Partner access with LenzEngineLibrary
- **Primary Language**: Android
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2020-10-30
- **Last Updated**: 2022-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

  # **朗镜通拍照SDK**



##### 2022.01.24修订  

##### (最新版本在sdk目录) 

##### 最新版本:1.4.2.1

      

```
1.4.2.1更新日志

1.修正问题,优化使用性
```

------------


## 产品简介
       朗镜通拍照 Android SDK 是一套基于 Android 5.0以上版本设备的应用程序接口.
    可使用该套SDK开发适用于Android系统移动设备拍照执行门店类应用.
    通过调用朗镜通拍照接口,可调用普通拍照,拼接拍照功能.


------------

- ## 需要权限

\<uses-permission android:name="android.permission.VIBRATE" />

\<uses-permission android:name="android.permission.CAMERA" />

\<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

**另需要授予动态权限:写入,相机(WRITE_EXTERNAL_STORAGE,CAMERA)**

------------

- ## build.gradle配置
    
    需在引用module中build.gradle,添加配置
```
    defaultConfig {
        ndk {
            abiFilters 'armeabi-v7a'
        }
    }

    aaptOptions {
        noCompress "tflite"
    }
```



------------

- ## 集成引入

    

以下提供两种集成方式 
     


 ### 1.本地aar集成引入

  sdk目录中aar下载,导入需要集成module的libs目录下     

  需在引用module中build.gradle,配置本地aar路径及引用 

       repositories {
             flatDir {
                 dirs 'libs'
             }
         }  
  

>     implementation 'com.android.support:recyclerview-v7:28.0.0'  
> 
>     implementation 'com.github.bumptech.glide:glide:4.8.0'
>   
>     implementation 'com.google.code.gson:gson:2.7'  
>
>     implementation 'com.squareup.okhttp3:okhttp:3.7.0'
>   
>     implementation(name: 'lenzEngineLibrary-release-version', ext: 'aar')    
  

**注:lenzEngineLibrary-release-version为lenzEngineLibrary版本号,需要替换aar版本名称**   
    例: implementation(name: 'lenzEngineLibrary-release-1.3.1', ext: 'aar'),示例版本可能非最新版本,请查看最新版本进行接入       
                 
   ### 2.maven集成引入

   需在引用module中build.gradle,配置maven及引用
      
       repositories {
           maven {
               url 'https://github.com/trax-china-android/LenzEngineAndroid/raw/maven'
            }
         }  


>        implementation 'com.android.support:recyclerview-v7:28.0.0'   
> 
>        implementation 'com.github.bumptech.glide:glide:4.8.0'
>       
>        implementation 'com.google.code.gson:gson:2.7'  
>
>        implementation 'com.squareup.okhttp3:okhttp:3.7.0'
>
>        implementation 'com.trax.lenzengine:lenzengine:version@aar'

   **注:version为lenzEngineLibrary版本号,需要替换aar版本号**    
   例: implementation 'com.trax.lenzengine:lenzengine:1.3.1@aar',示例版本可能非最新版本,请查看最新版本进行接入      
    
   ***请勿使用 implementation 'com.trax.lenzengine:lenzengine:+@aar' 引用方式***
  
------------

- ## 混淆规则

    -dontwarn com.lenztechretail.lenzenginelibrary.\*\*  
    
    -keep class com.lenztechretail.lenzenginelibrary.\*\*{\*;}  
    
    -keep interface com.lenztechretail.lenzenginelibrary.\*\*{\*;}

------------

- ## 关于NDK
 需要安装NDK  android-ndk-r14b 以上

   - CPU:
  不支持X86

 **注:本SDK所有方法不支持子线程内调用**

------------

  

## 1. 朗镜通 SDK 初始化

方法调用:
`LenzEngine.getInstance().initialize(String companyId)` 

在应用启动 Application onCreate()中执行调用

参数说明: 
companyId:企业 id ---(companyId获取请咨询对应相关项目经理)

***测试环境切换  openDebugEnvModel(),需在应用启动 Application onCreate()中执行调用,且在initialize()前配置调用,不调用此方法即默认为线上正式环境-----(正式使用时,请务必使用线上正式环境及其companyId)***

示例:LenzEngine.getInstance().openDebugEnvModel().initialize(testCompanyId)



## 2. 获取企业任务模型列表

方法调用:

`LenzEngine.getInstance().getLenzTaskInfo(LenzGetTaskListCallBack lenzGetTaskListCallBack)`


参数说明:

LenzGetTaskListCallBack网络回调

LenzGetTaskListCallBack包括两个实现方法

1.onSuccess(List`<`LenzTaskInfoBean`>` lenzTaskInfoBean) 数据成功返回回调方法

2.onFailure(Exception exception)  网络请求异常返回回调方法

------------
	下为 LenzTaskInfoBean 变量及描述简述

LenzTaskInfoBean:{

String taskId, //企业模型任务

String taskName, //企业模型任务描述

String questionId,//模型任务唯一问题 id

String questionName,//模型任务唯一问题描述

}



## 3.普通相机调用     

方法调用:

`LenzEngine.getInstance().startCamera(Context context` 
`, LenzTaskInfoBean lenzTaskInfoBean`
`, List<String> businessDataIds`
`, LenzCameraClickListener lenzCameraClickListener)`



重载方法:

`LenzEngine.getInstance().startCamera(Context context` 
`, LenzTaskInfoBean lenzTaskInfoBean`
`, List<String> businessDataIds`
`, int index`
`, int countLimit` 
`, LenzCameraClickListener lenzCameraClickListener)`



参数说明:

context 上下文引用(必须是 Activity context)

lenzTaskInfoBean 为已选择匹配的活动任务模型实例(入参为null,可进行离线相机调用)

businessDataIds 对接企业的唯一批次ID集合(对接企业方提供)

index  当前已保留拍照数量

countLimit  最大拍照数量限制

lenzCameraClickListener 拍照回调  



LenzCameraClickListener 包括一个实现方法

		1.notifyImgPath(String imgPath,String imgId) 拍照成功返回图片路径及图片Id(实际就是图片名)回调方法,用于图片展示及数据处理,删除等,同时此数据源包装集合后期用于最后图片上传入参使用

*最大拍照数量限制图示（传入参数index与countLimit则会显示以下效果,拍照数量以及缩略图----进入相机拍照成功后显示）*

![avatar](https://lenz-prod-app.oss-cn-beijing.aliyuncs.com/androidOther/SdkRes/sdk_limit_max.png)

*注(异常入参,限制失效):*

*Ⅰ.当countLimit<index,缩略不显示,且数量限制失效*

*Ⅱ.当countLimit<1, 缩略不显示,且数量限制失效*

*Ⅲ.当index<0, 缩略不显示,且数量限制失效*



###  相机可选其他配置

    1.setTiltModel(true)设置是否开启倾斜校验,默认为 false
     
    2.setBlurryModel(true)设置是否开启模糊校验,默认为 false
     
    3.setTiltValue(4)设置倾斜校验算法阈值,默认值为4,入参为 double 类型(阈值越小算法校验越严格)
     
    4.setBlurryValue(0.45)设置模糊校验算法阈值,默认值为0.45,入参为double类型(阈值越大算法校验越严格)

    5.setRemakeModel(true)设置是否开启翻拍检测,默认为 false  //翻拍图片命名中具有r1(翻拍标记)
         
    6.setCompressLevel(1)设置拍照图片质量等级,默认值为 2,可选参数为 0,1,2,3,4,5,入参为int类型

			a.0:为相机拍照原图(即选择策略为当前相机拍照最高相机参数)
	
			b.1:为相机参数 4k(即选择策略为当前相机参数优选 3840*2160)
	
			c.2:为相机参数 1080p(即选择策略为当前相机参数优选 1920*1080)
	 
			d.3:为相机参数 720p(即选择策略为当前相机参数优选 1280*720)
	
			e.4:为相机参数 540p(即选择策略为当前相机参数优选 960*540)
	
			f.5:为相机参数 480p(即选择策略为当前相机参数优选 800*480)


***注:***
***Ⅰ.由于 Android 手机相机参数碎片化,当指定等级无法获取时,将向上优取相机参数***
***Ⅱ.入参为非可选参数时均作原图(0)入参处理***

所有相机可选参数均在调用 startCamera方法前进行配置

例:
LenzEngine.getInstance().setCompressLevel(3).setTiltModel(true).startCamera(context, lenzTaskInfoBean, businessDataIds, index, countLimit, lenzCameraClickListener);

 



## 4.拼接详情及拼接相机调用
 拼接基础调用方法调用:

`LenzEngine.getInstance().openStitchDetail(Context context, LenzTaskInfoBean lenzTaskInfoBean, List<String> businessDataIds`
`, LenzStitchClickListener lenzStitchClickListener)`



参数说明:

context 上下文引用(必须是 Activity context)

lenzTaskInfoBean 为已选择匹配的活动任务模型实例(入参为null,可进行离线相机调用)

businessDataIds 对接企业的唯一批次ID集合

lenzStitchClickListener 为拼接拍照及完成拼接回调监听


LenzStitchClickListener 包括三个实现方法

			1.notifyImgPath(String imgPath,String imgId) 拍照成功返回图片路径及图片ID(实际就是图片名)回调方法
	
			2.notifyStitchImgs(List<String> imgPaths) 最终拼接完成所有图片路径集合,可用于图片预览展示(接入企业方不可删除 ---待图片答卷上传成功后,可根据此数据源进行资源删除释放)
	
			3.notifyStitchInfo(List<LenzStitchInfoBean> lenzStitchInfoBeans,boolean completeClick) 最终拼接完成后所有拼接信息集合(接入企业方根据其需要决定使用与否,此回调可查看具体图片所在拼接组列信息)

completeClick 为拼接拍照详情页面,完成Button点击事件回调参数.
点击完成返回true,其余退出拼接拍照详情页面方式均返回false, 此回调参数视接入企业方需要决定使用与否
***(关闭销毁拼接拍照详情页面,均会回调notifyStitchImgs(imgPaths)及notifyStitchInfo(lenzStitchInfoBeans,completeClick))***

	下为 LenzStitchInfoBean变量及描述简述,相关变量均可通过getXXX()获取

LenzStitchInfoBean:{  

​		int orientation; //当前组拼接方向,1:从左到右,2:从右到左  

​		List<ImageBean> images; //当前组货架ImageBean集合  

}

ImageBean:{  

​		int column;  //当前图片列数(从1开始)  

​		int row;    //当前图片行数(从1开始)  

​		String imageName;  //当前图片名  

​		String imagePath;  //当前图片路径  

   int status;  //当前图片是否开启拼接算法校验 1:开启,0:关闭(首张拼接状态为关闭) 

}


### 拼接相机参数可选配置

			1.setCompressLevel(1)设置拍照图片质量等级,默认值为 2,可选参数为 0,1,2,3,4,5 (参数介绍同普通相机)
	
			2.setTiltModel(true)设置是否开启倾斜校验,默认为 false
	
			3.setBlurryModel(true)设置是否开启模糊校验,默认为 false
	
			4.setTiltValue(4)设置倾斜校验算法阈值,默认值为4,入参为 double 类型(阈值越小算法校验越严格)
	
			5.setBlurryValue(0.45)设置模糊校验算法阈值,默认值为0.45,入参为double类型(阈值越大算法校验越严格)

                    6.setRemakeModel(true)设置是否开启翻拍检测(仅拼接首张检测),默认为 false //翻拍图片命名中具有r1(翻拍标记)



可选参数均在调用 openStitchDetail方法前进行配置



------------
 


> ***SDK新对接标准,均使用后端API上传*** 
> 
> ***5.图片上传 6.检查企业答卷是否已存在 不再需要企业方进行调用***


## 5.图片上传

#### 图片上传是否使用SDK上传,请咨询相关对接项目经理


方法调用:

`LenzEngine.getInstance().uploadImgs (Context context`
`, LenzTaskInfoBean lenzTaskInfoBean`
`, List<String> businessDataIds`
`, List<String> imgs`
`, LenzUploadListener lenzUploadListener)`



参数说明:

imgs 为普通相机拍照最终处理(即已包括被删除的数据源处理)待上传图片路径集合

lenzTaskInfoBean 为已选择匹配的活动任务模型实例

businessDataIds 对接企业的唯一批次ID集合

lenzUploadListener 为上传回调监听



LenzUploadListener 包括四个实现方法

			1.onLenzPrepare(String responseId)    图片上传前回调方法  responseId可用于检查答卷是否已上传
	
			2.onLenzUploadFinish(String responseId)   图片全部上传完成回调方法
	
			3.onLenzUploadProgress(String responseId, int current,int total,int currentProgress)    图片上传进度回调方法
	
					responseId 为执行任务上传唯一id,作为上传任务关联绑定使用(暂不用处理,预留参数)
	
					a. current:为当前正在上传图片序列数
	
					b. total:为需要上传总图片数量
	
					c. currentProgress:为当前上传图片进度
	
			4. onLenzUploadImgError(String responseId,Exception exception) 图片上传错误回调方法


##  6.检查企业答卷是否已存在

#### 注:校验执行任务(答卷)是否已上传,入参responseId(图片上传回调方法返回该参数)

方法调用:

`LenzEngine.getInstance().checkResponseExist(String responseId`
`, LenzCheckResponseIdExistCallback lenzCheckResponseIdExistCallback)`

参数说明:
responseId 为上传图片回调方法 onLenzPrepare(String responseId)回调参数

LenzCheckResponseIdExistCallback  包含两个回调方法

onSuccess(boolean isExist)     false: 不存在    true:存在

onFailure(LenzException exception)   exception:异常错误


------------


#### 错误码：

UPLOADING_EXCEPTION = 0; 当前已有任务上传中  
SDK_EXCEPTION = 1000;    SDK内部错误  
SERVER_EXCEPTION = 2000; 服务端错误  
ALIYUN_EXCEPTION = 3000; OSS云端错误

------------

#### SDK接入示例Demo：

[SDK-Demo工程](https://gitee.com/ppz_bj/lenz-engine-library_-android/tree/feature%2FlenzEngineDemo/) 

------------


## Issue(常见问题)

###  1.翻拍检测无效
        
       I.首先确定是否已进行build.gradle noCompress "tflite" 相关配置,请查询文档build.gradle配置节点说明
       Ⅱ.请确认拍照取景为翻拍图片
       Ⅲ.鉴于翻拍识别准确性误差,可能会存在误判,即翻拍图片未检测为翻拍(可对电脑显示器图片进行近距离拍照进行验证翻拍识别是否接入成功)
       
###  2.相机弹窗提示
        
       Package not found(OpenCV Manager package was not found...)
       请参照文档build.gradle配置节点部分,进行abiFilters配置

###  3.上传异常返回/Web--ERR_CLEARTEXT_NOT_PERMITTED
        
       errorCode(错误码): 3000  
       errorMsg: cloudClientError_CLEARTEXT communication to files.ppznet.com not permitted by network security policy....
       
       此异常为OSS云端抛出异常,解决方法如下:
       https://github.com/aliyun/aliyun-oss-android-sdk/issues/194

       Web异常---net::ERR_CLEARTEXT_NOT_PERMITTED
       解决方法同上