CameraScan for Android 是一个简化扫描识别流程的通用基础库。
CameraScan 本身并不提供具体的分析识别功能,只是将相机预览、扫描分析等过程进行抽象分离,从而简化扫描识别功能的实现,你只需将 CameraScan 作为基础库,然后实现具体的识别业务,便可快速实现各种扫描识别相关功能。
如果你之前有使用过 ZXingLite 、MLKit 或 WeChatQRCode,可能会对 CameraScan 比较眼熟。现已将 CameraScan 独立出来,便于后续统一维护。
以后 ZXingLite、MLKit、WeChatQRCode 发布的新版本都将使用 CameraScan 作为相机扫描基础库。
CameraScan + ViewfinderView +(ZXingLite、MLKit、WeChatQRCode 其中之一) = 完美搭配。
在Project的 build.gradle 或 setting.gradle 中添加远程仓库
repositories {
//...
mavenCentral()
}
在Module的 build.gradle 里面添加引入依赖项
implementation 'com.github.jenly1314:camera-scan:1.2.0'
使用 v1.1.x 以上版本时,要求 compileSdkVersion >= 34
使用 v1.0.x 以上版本时,要求 compileSdkVersion >= 33
1、通过继承 BaseCameraScanActivity 或者 BaseCameraScanFragment 或其子类,可快速实现扫描识别。 (适用于大多场景,自定义布局时需覆写 getLayoutId 方法)
2、在你项目的Activity或者Fragment中实例化一个 BaseCameraScan。(适用于想在扫描界面写交互逻辑,又因为项目 架构或其它原因,无法直接或间接继承 BaseCameraScanActivity 或 BaseCameraScanFragment 时使用)
3、继承 CameraScan 自己实现一个,可参照默认实现类 BaseCameraScan,其他步骤同方式2。(高级用法,谨慎使用)
CameraScan 作为相机扫描的(核心)基类;所有与相机扫描相关的都是基于此类来直接或间接进行控制的。
主要是相机相关的配置;如:摄像头的前置后置、相机预览相关、图像分析相关等配置。
CameraConfig中提供的可配置项:
CameraSelector.Builder
、Preview.Builder
、ImageAnalysis.Builder
;你可以直接库中内置实现的相机配置: CameraConfig 、AspectRatioCameraConfig 和 ResolutionCameraConfig。
你也可以自定义或覆写 CameraConfig 中的 options 方法,根据需要定制配置。
这里特别温馨提示:默认配置在未配置相机的目标分析图像大小时,会优先使用:横屏:640 480 竖屏:480 640;
根据这个图像质量顺便说下默认配置的优缺点:
基于上面的配置优缺点特性,CameraScan内部默认会通过 CameraConfigFactory 来获取适合当前设备的的相机配置:CameraConfig;如果内部默认配置不满足你的需求,你也可以根据具体需求去设置CameraScan的CameraConfig;
如:通过CameraConfig设置前置摄像头
方式一: 通过工厂类创建CameraConfig(推荐)
// 通过工厂类创建适合当前设备的CameraConfig
CameraConfig cameraConfig = CameraConfigFactory.createDefaultCameraConfig(this, CameraSelector.LENS_FACING_FRONT);
getCameraScan().setCameraConfig(cameraConfig);
方式二: 通过对象创建CameraConfig
// 此处的CameraConfig可以是CameraConfig的任意子类(其它CameraConfig相关配置修改方式与设置前置摄像头类似)
CameraConfig cameraConfig = new CameraConfig() {
@NonNull
@Override
public CameraSelector options(@NonNull CameraSelector.Builder builder) {
builder.requireLensFacing(CameraSelector.LENS_FACING_FRONT);
return super.options(builder);
}
};
getCameraScan().setCameraConfig(cameraConfig);
需要注意的是:
cameraScan.setCameraConfig(cameraConfig)
一般是在相机启动预览之前调用的,如果是在相机启动预览之后修改了CameraConfig的配置,则需重新调用cameraScan.startCamera()
后,CameraConfig相关配置才会生效。
Analyzer 为定义的分析器接口;主要用于分析相机预览的帧数据,从而得到具体的结果。一般实现某种扫描识别功能时,你只需自定义并实现一个 Analyzer 对应的功能即可。
BaseCameraScanActivity 和 BaseCameraScanFragment 作为扫描预览界面的基类,主要目的是便于快速实现扫描识别。
扫描预览界面内部持有 CameraScan,并处理了 CameraScan 的初始化(如:相机权限、相机预览、生命周期等细节)
CameraScan 里面包含部分支持链式调用的方法,即调用返回是 CameraScan 本身的一些配置建议在调用 startCamera() 方法之前调用。
如果是通过继承 BaseCameraScanActivity 或者 BaseCameraScanFragment 或其子类实现的相机扫描,可以在 initCameraScan() 方法中根据需要修改CameraScan相关配置。
示例:
// 根据需要修改CameraScan相关配置
cameraScan.setPlayBeep(true)//设置是否播放音效,默认为false
.setVibrate(true)//设置是否震动,默认为false
.setCameraConfig(CameraConfigFactory.createDefaultCameraConfig(this, CameraSelector.LENS_FACING_BACK))//设置相机配置信息
.setNeedTouchZoom(true)//支持多指触摸捏合缩放,默认为true
.setDarkLightLux(45f)//设置光线足够暗的阈值(单位:lux),需要通过{@link #bindFlashlightView(View)}绑定手电筒才有效
.setBrightLightLux(100f)//设置光线足够明亮的阈值(单位:lux),需要通过{@link #bindFlashlightView(View)}绑定手电筒才有效
.bindFlashlightView(ivFlashlight)//绑定手电筒,绑定后可根据光线传感器,动态显示或隐藏手电筒按钮
.setOnScanResultCallback(this)//设置扫描结果回调,需要自己处理或者需要连扫时,可设置回调,自己去处理相关逻辑
.setAnalyzeImage(true);//设置是否分析图片,默认为true。如果设置为false,相当于关闭了扫描识别功能
启动相机预览
// 启动预览(如果是通过直接或间接继承BaseCameraScanActivity或BaseCameraScanFragment实现的则无需调用startCamera)
getCameraScan().startCamera();
控制闪光灯
// 设置闪光灯(手电筒)是否开启,需在startCamera之后调用才有效
getCameraScan().enableTorch(torch);
设置分析器
// 设置分析器
cameraScan.setAnalyzer(analyzer);
如果是通过直接或间接继承 BaseCameraScanActivity 来实现的,可直接覆写
createAnalyzer
方法返回具体的分析器即可。
介绍完 CameraScan 相关配置后,下面就来说下界面和布局部分;
通过继承 BaseCameraScanActivity 可快速实现具体的扫描功能;( BaseCameraScanFragment 与之类似)
示例:
// 此处的泛型*表示分析得到的具体结果
class CameraScanActivity : BaseCameraScanActivity<*>() {
/**
* 初始化CameraScan
*/
override fun initCameraScan(cameraScan: CameraScan<*>) {
super.initCameraScan(cameraScan)
// TODO 根据需要初始化CameraScan相关配置
cameraScan.setPlayBeep(true)
}
/**
* 布局ID;通过覆写此方法可以自定义布局
*
* @return 布局ID
*/
override fun getLayoutId(): Int {
return super.getLayoutId()
}
override fun onScanResultCallback(result: AnalyzeResult<*>) {
// TODO 扫描结果回调;分析后得到的结果
}
override fun createAnalyzer(): Analyzer<*>? {
// TODO 创建分析器;由具体的分析器去实现分析检测功能
return null
}
}
一般在 ZXingLite 、MLKit 或 WeChatQRCode 对应的库中都有提供 BaseCameraScanActivity 的子类,可快速实现具体的分析识别功能。(比如:MLKit中的条码扫描有:BarcodeCameraScanActivity)
PreviewView 用来预览,布局内至少要保证有 PreviewView (必须的);如果是继承 BaseCameraScanActivity 或
BaseCameraScanFragment 或其子类实现的相机扫描;快速实现扫描功能;
需自定义布局时,通过覆写getLayoutId
方法即可;预览控件ID可覆写getPreviewViewId
方法自定义;
ivFlashlight 是布局内置的手电筒(非必须的),如果是继承 BaseCameraScanActivity 或 BaseCameraScanFragment,其内部已默认处理了手电筒点击开关事件;控件id可覆写getFlashlightId
方法自定义,默认为 ivFlashlight。返回0表示无需内置手电筒。您也可以自己去定义
更多CameraScan相关用法可查看 BaseCameraScanActivity 源码或参见下面的使用示例。
BaseCameraScanActivity和BaseCameraScanFragment使用的默认布局:
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent">
<androidx.camera.view.PreviewView
android:id="@+id/previewView"
android:layout_width="match_parent"
android:layout_height="match_parent" />
<!-- 只需保证有布局内有PreviewView即可,然后你可根据需要添加的控件 -->
<ImageView
android:id="@+id/ivFlashlight"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_gravity="center"
android:layout_marginTop="@dimen/camera_scan_flashlight_margin_top"
android:contentDescription="@null"
android:src="https://github.com/jenly1314/CameraScan/raw/master/@drawable/camera_scan_flashlight_selector" />
</FrameLayout>
自定义布局示例:(通过覆写getLayoutId
方法)
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent">
<androidx.camera.view.PreviewView
android:id="@+id/previewView"
android:layout_width="match_parent"
android:layout_height="match_parent" />
<!-- 只需保证有布局内有PreviewView即可,然后你可根据需要添加的控件 -->
<com.king.view.viewfinderview.ViewfinderView
android:id="@+id/viewfinderView"
android:layout_width="match_parent"
android:layout_height="match_parent" />
<ImageView
android:id="@+id/ivFlashlight"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_gravity="center"
android:layout_marginTop="@dimen/camera_scan_flashlight_margin_top"
android:contentDescription="@null"
android:src="https://github.com/jenly1314/CameraScan/raw/master/@drawable/camera_scan_flashlight_selector" />
</FrameLayout>
如上面的自定布局,使用了开源库:ViewfinderView;一般在实现扫码相关需求时,会经常用到。
页面完整示例:CameraScanActivity
更多使用详情,请查看app中的源码使用示例或直接查看API帮助文档
LogUtils
类,改用LogX 来统一管理日志CameraScan.setAutoStopAnalyze(boolean)
用于设置是否自动停止分析图像AdaptiveCameraConfig
自适应相机配置CameraConfigFactory.createDefaultCameraConfig
的默认实现如果您喜欢CameraScan,或感觉CameraScan帮助到了您,可以点右上角“Star”支持一下,您的支持就是我的动力,谢谢 :smiley:
您也可以扫描下面的二维码,请作者喝杯咖啡 :coffee: