VisionSDK iOS 集成

适用于 iOS 的条形码和二维码扫描框架。VisionSDK 提供了手动和自动捕获模式来检测条形码和二维码。它还提供了离线（无互联网）和在线（通过 Restful API 标签扫描）模式的 OCR 以检测文本。

开发要求

• iOS 15.0+
• Swift: 5.7
• Xcode 版本: 13.0

安装

CocoaPods

CocoaPods 是 Cocoa 项目的依赖管理器。有关使用和安装说明，请访问其网站。要使用 CocoaPods 将 VisionSDK 集成到您的 Xcode 项目中，请在您的 Podfile 中指定它。

pod 'VisionSDK'

Swift 包管理器

Swift 包管理器 是一种用于自动分发 Swift 代码的工具，并集成到了 swift 编译器中。

一旦您设置了 Swift 包，将 VisionSDK 作为依赖项添加就很简单，只需将它添加到您的 Package.swift 中的 dependencies 值即可。

dependencies: [
    .package(url: "https://github.com/packagexlabs/vision-sdk.git", .upToNextMajor(from: "1.0.0"))
]

手动框架集成

• 在 Xcode 中，转到 "常规 > 构建阶段 > 链接框架和库"。
• 将 VisionSDK.xcframework 添加到您的项目中。
• 请确保将其标记为 "嵌入并签名"。
• 在源文件中写入导入语句。

import VisionSDK

使用

将 Privacy - Camera Usage Description 添加到 Info.plist 文件中

初始化

为了使用OCR API，您需要将Constants.apiKey设置为您的API密钥。同时，您还需要指定您拥有API密钥的API环境。请注意，这些设置必须在使用API调用之前进行。您可以在cloud.packagex.io生成自己的API密钥。您可以在这里找到说明指南。

Constants.apiKey = "your_api_key"
Constants.apiEnvironment = .staging

使用基础

import VisionSDK
import AVFoundation

final class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        setupScanner()
    }

    private func setupScanner() {
        switch AVCaptureDevice.authorizationStatus(for: .video) {
        case .authorized:
            setupScannerView()
        case .notDetermined:
            AVCaptureDevice.requestAccess(for: .video) { [weak self] granted in
                if granted {
                    DispatchQueue.main.async { [weak self] in
                        self?.setupScannerView()
                    }
                }
            }
        default:
            showAlert()
        }
    }

    private func setupScannerView() {
        let scannerView = CodeScannerView(frame: view.bounds)
        view.addSubview(scannerView)
        
        scannerView.configure(delegate: self, input: .init(focusImage: nil, focusImageRect: .zero, shouldDisplayFocusImage: true, shouldScanInFocusImageRect: true, imageTintColor: .white, selectionTintColor: .white, isTextIndicationOn: true, isBarCodeOrQRCodeIndicationOn: true, sessionPreset: .high, nthFrameToProcess: 10, captureMode: .auto, captureType: .single, codeDetectionConfidence: 0.8), scanMode: .autoBarCodeOrQRCode)
        
        scannerView.startRunning()
    }

    private func showAlert() {
        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
            let alert = UIAlertController(title: "Error", message: "Camera is required to use in this application", preferredStyle: .alert)
            alert.addAction(.init(title: "OK", style: .default))
            self?.present(alert, animated: true)
        }
    }
}

extension ViewController: CodeScannerViewDelegate {
    func codeScannerView(_ scannerView: CodeScannerView, didFailure error: CodeScannerError) {
        print(error)
    }
    
    func codeScannerView(_ scannerView: CodeScannerView, didSuccess codes: [String]) {
        print(codes)
    }
    
    // called when text, barcode, or qr code is detected in camera stream, Depends on configuration of scanner view e.g. isTextIndicationOn, isBarCodeOrQRCodeIndicationOn
    func codeScannerViewDidDetect(_ text: Bool, barCode: Bool, qrCode: Bool) {
    
    }
    
    // returns captured image with all barcodes detected in it
    func codeScannerView(_ scannerView: CodeScannerView, didCaptureOCRImage image: UIImage, withCroppedImge croppedImage: UIImage?, withbarCodes barcodes: [String]) {
    
    }
}

自定义

源代码方法

override func viewDidLoad() {
        super.viewDidLoad()

        let scannerView = CodeScannerView(frame: view.bounds)
        
        scannerView.setScanModeTo(.barcode)
        scannerView.setCaptureTypeTo(.multiple)
        scannerView.setCaptureModeTo(.manual)
        
}

界面构建方式

功能描述

静态属性

• videoDevice: AVCaptureDevice - 这是CodeScannerView正在使用的视频设备。对相机缩放、手电筒或其他基于设备的操作必须在此属性上执行。可以通过CodeScannerView.videoDevice语法访问

配置方法

scannerView.configure(delegate: VisionSDK.CodeScannerViewDelegate, input: VisionSDK.CodeScannerView.Input = .default, scanMode: VisionSDK.CodeScannerMode = .qrCode)

参数

• delegate - 应该是符合CodeScannerViewDelegate协议的类

• 输入 - 输入结构定义了扫描视图的属性。这些属性包括

  • focusImage: UIImage - 在视图中心显示的图像。如果没有提供，VisionSDK将使用默认图像。请注意，焦点矩形框会根据不同的扫描模式而变化。

  • focusImageRect: CGRECT - 焦点图像的自定义矩形。您可以提供您首选的矩形或使用 .zero 作为默认值。请注意，默认焦点矩形框会根据不同的扫描模式而变化。

  • shouldDisplayFocusImage: Bool - 如果您需要绘制焦点区域，请设置为 true。

  • shouldScanInFocusImageRect: Bool - 如果您只想检测焦点区域中可见的代码，请设置为 true。这将丢弃检测到焦点图像之外的代码。

  • imageTintColor: UIColor - 设置焦点图像的着色色。请注意，在 focusImage: UIImage 属性中提供的图像可能带有 .alwaysTemplate 的渲染模式加载。因此，您需要提供焦点图像的颜色。默认值是 UIColor.white

  • selectionTintColor: UIColor - 在检测到代码时，设置要使用的着色色。根据 scanMode 和 shouldScanInFocusImageRect 属性，当检测到代码时，显示的焦点图像可能会改变着色色。默认值是 UIColor.white

  • isTextIndicationOn: Bool - 如果您不想在实时相机流中检测文本，请设置为 false。如果设置为 false，codeScannerViewDidDetect(_ text: Bool, barCode: Bool, qrCode: Bool) 方法会将 text 参数发送为 false。

  • isBarCodeOrQRCodeIndicationOn: Bool - 如果您不想在实时相机流中检测条形码或二维码，请设置为 false。使用此属性可以在您想要根据代码检测执行手动捕获的情况中有所帮助。

  • sessionPreset: Session.Preset - 您可以根据要求设置会话预设。默认值是 .high。

  • nthFrameToProcess: Int - 这是在实时相机流中检测文本、条形码和二维码的 nth 帧的数量，如果通过 isTextIndicationOn 或 isBarCodeOrQRCodeIndicationOn 启用。处理每一帧可能在 CPU 使用率和电池消耗方面成本很高。默认值是 10，这意味着从通常的 30 fps 摄像机流中，每 10 帧 processing 一次。其值应在 1-30 之间。

  • captureMode - 定义是否应该自动捕捉代码。如果您想根据用户操作捕捉代码，请将其设置为 .manual。默认值是 .auto。如果不是这样，您将不得不手动使用 capturePhoto() 方法触发扫描。

  • captureType - 如果您想允许扫描多个结果，请将其设置为 .multiple。在 .manual 情况中，您将必须手动使用 capturePhoto() 方法触发扫描。

  • codeDetectionConfidence: Float - 您可以设置检测代码的最小置信度水平。低于给定值的将丢弃。值必须在 0-1 的范围内。默认值是 0.5。

• scanMode - 定义扫描模式。具有以下选项

  • .barCode - 在这种模式下仅检测条形码
  • .qrCode - 在这种模式下仅检测二维码
  • .ocr - 在 OCR API 调用中使用此模式来捕捉照片
  • .autoBarCodeOrQRCode - 检测条形码和二维码

scannerView.setScanModeTo(_ mode: VisionSDK.CodeScannerMode)

将扫描模式设置为所需的模式。

scannerView.setCaptureModeTo(_ mode: VisionSDK.CaptureMode)

将捕获模式设置为所需的模式。

scannerView.setCaptureTypeTo(_ type: VisionSDK.CaptureType)

将捕获类型设置为所需的类型。

scannerView.startRunning()

在它之前需要调用 configure() 方法。它启动相机会话和扫描。

scannerView.stopRunning()

停止相机会话和扫描。

scannerView.rescan()

使用此功能来恢复扫描。

scannerView.deConfigure()

删除扫描视图的所有配置并停止扫描。

scannerView.capturePhoto()

当您在扫描多个代码、手动捕获或 OCR 模式时，使用此方法来触发代码扫描或照片捕获。

委托方法

func codeScannerView(_ scannerView: VisionSDK.CodeScannerView, didSuccess codes: [String])

此方法在扫描成功后返回扫描到的代码。

func codeScannerViewDidDetect(_ text: Bool, barCode: Bool, qrCode: Bool)

当相机流中检测到文本、条码或二维码时调用此方法。值取决于在配置扫描视图时是否启用了文本或代码指示。

func codeScannerView(_ scannerView: CodeScannerView, didCaptureOCRImage image: UIImage, withCroppedImge croppedImage: UIImage?, withbarCodes barcodes: [String])

在OCR模式下调用capturePhoto()方法时调用此方法。它返回来自相机流的捕获图像、其中检测到的所有代码以及如果捕获图像中检测到文档的可选裁剪文档图像。

func codeScannerView(_ scannerView: VisionSDK.CodeScannerView, didFailure error: VisionSDK.CodeScannerError)

在任何初始化或捕获代码的阶段发生错误且未检测到任何代码时调用此方法。

OCR方法

func callScanAPIWith(_ image: UIImage, andBarcodes barcodes: [String], andApiKey apiKey: String? = nil, andToken token: String? = nil, andLocationId locationId: String? = nil, andOptions options: [String: String], withImageResizing shouldResizeImage: Bool = true, _ completion: @escaping ((_ data: Data?, _ response: URLResponse?, _ error: NSError?)-> Void))

在VisionAPIManager的共享实例上调用此方法。可以使用VisionAPIManager.shared语法访问它。此方法接收捕获的图像和API密钥或AuthToken作为参数。从PackageX平台API返回OCR响应响应。

VisionSDK Android集成

VisionSDK Android集成是Android上的一个条码和二维码扫描框架，提供了在手动和自动捕获模式下简单高效地检测条码和二维码的方式。它还包括文本检测（使用Restful API的标签扫描）模式的OCR（光学字符识别）功能。

VisionSDK Android集成的关键特性包括

• 支持多种查看类型（矩形、正方形、全屏）的扫描窗口
• 扫描窗口大小、形状和边框样式的自定义选项
• 捕获图像和OCR API功能

安装

Vision SDK 存放在 JitPack.io

首先将 JitPack 添加到根项目

maven { url "https://jitpack.io" }

然后，将以下依赖项添加到项目的 build.gradle 文件中

implementation 'com.github.packagexlabs:vision-sdk-android:v1.0'

用法

初始化

为了使用OCR API，您需要将Constants.apiKey设置为您的API密钥。同时，您还需要指定您拥有API密钥的API环境。请注意，这些设置必须在使用API调用之前进行。您可以在cloud.packagex.io生成自己的API密钥。您可以在这里找到说明指南。

首先初始化 SDK

有两种身份验证方式

1. 通过 API 密钥
2. 通过 Token

VisionSDK.getInstance().initialise(
    authentication = //TODO authentication,
    environment = //TODO environment
)

VisionSDK.getInstance().initialise(
    apiKey = Authentication.BearerToken(/*Yoru token here*/),
    environment = Environment.STAGING
)

基本用法

要开始扫描条形码和 QR 码，请使用 startScanning 方法并指定视图类型

private fun startScanning() {

    //setting the scanning window configuration
    binding.customScannerView.startScanning(
        viewType = screenState.scanningWindow,
        scanningMode = screenState.scanningMode,
        detectionMode = screenState.detectionMode,
        scannerCallbacks = this
    )
}

视图类型

有两种扫描窗口类型

1. 默认的 ViewType.WINDOW 展示用于 QR 检测模式的正方形窗口和条形码的矩形窗口
2. ViewType.FULLSCREEN 全屏

扫描模式

扫描模式有两种类型

1. 自动模式会根据检测模式自动检测任何条形码或二维码
2. 手动模式需要在调用Capture后才检测条形码或二维码

检测模式

检测模式用于指定要检测的代码类型

1. QrAndBarcode共同检测条形码和二维码
2. Barcode仅检测条形码
3. QR仅检测二维码
4. OCR进行OCR检测。此模式将调用OCR API

回调

还有扫描回调，我们在开始扫描时需要提供它。这是一个接口，它将根据检测模式提供不同的回调。

1. onBarcodeDetected当在单模式下检测到条形码或二维码时
2. onImageCaptured在OCR模式下捕获图像时
3. onMultipleBarcodesDetected在多模式下检测到多个条形码时
4. onFailure在手动模式下抛出异常或无法检测到任何条形码/二维码时

常见异常类

如果在特定时间窗口内没有检测到条形码或二维码，则SDK将抛出异常。存在自定义异常。

1. 在手动模式中无条码检测时返回 BarCodeNotDetected
2. 在手动模式中未检测到QR码时返回 QRCodeNotDetected

自定义扫描窗口

要自定义扫描窗口的外观和行为，您可以使用 setScanningWindowConfiguration 方法，并传递一个包含您所需设置的配置对象。

例如

由于 ViewType.RECTANGLE 和 ViewType.SQUARE 有窗口，您可以根据需要配置扫描窗口。还可以设置扫描窗口的半径以及垂直起点。

//Setting the Barcode and QR code scanning window sizes
binding.customScannerView.setScanningWindowConfiguration(
  Configuration(
      barcodeWindow = ScanWindow(
          width = ((binding.root.width * 0.9).toFloat()),
          height = ((binding.root.width * 0.4).toFloat()),
          radius = 10f,
          verticalStartingPosition = (binding.root.height / 2) - ((binding.root.width * 0.4).toFloat())
      ), qrCodeWindow = ScanWindow(
          width = ((binding.root.width * 0.7).toFloat()),
          height = ((binding.root.width * 0.7).toFloat()),
          radius = 10f,

          //you can set the vertical position of the scanning window
          verticalStartingPosition = (binding.root.height / 2) - ((binding.root.width * 0.5).toFloat())
      )
  )
)

示例

以下是一些使用上述配置初始化扫描器的示例

将手动在矩形区域内检测条码

binding.customScannerView.startScanning(
    viewType = ViewType.WINDOW,
    scanningMode = ScanningMode.Manual,
    detectionMode = DetectionMode.Barcode,
    this
)

将全屏用于QR码检测并将自动捕获条码

binding.customScannerView.startScanning(
    viewType = ViewType.FULLSCRREN,
    scanningMode = ScanningMode.Auto,
    detectionMode = DetectionMode.QR,
    this
)

监听条码和文本检测

对于条码和指示器，您可以观察不同的实时数据

1. customScannerView.barcodeIndicators 会在检测到新的条码或QR码时发布新的值。您可以使用格式字段来区分条码和QR码，例如 TWO_DIMENSIONAL_FORMATS.contains(it.format)
2. customScannerView.textIndicator 会在屏幕上检测到文本时发布新的值

手动触发捕获

如上所述，我们有一个手动模式。对于手动模式触发，你可以调用customScannerView.capture()，根据模式，它会返回不同的回调

如果检测模式是

1. DetectionMode.Barcode，则在检测到条码的情况下将触发onBarcodeDetected回调，如果在指定时间内未检测到条码，将抛出异常QRCodeNotDetected。
2. DetectionMode.QR将返回QR码或抛出异常BarCodeNotDetected
3. DetectionMode.OCR将捕获图像以及当前条码，并在onImageCaptured中返回

请确保在调用捕获时，扫描模式应为手动

捕获图像和OCR API

上述实时数据选项外，SDK还提供捕获图像和调用OCR API的选项。

捕获图像

当模式为OCR时，你可以捕获一个图像。在OCR模式中，当调用capture时，回调将返回一个图像。

customScannerView.captureImage()

回调

fun onImageCaptured(bitmap: Bitmap, value: MutableList<Barcode>?) {
    //Image along with the barcodes
}

在回调中，它将返回图像位图以及当前帧中的条码列表。

进行OCR调用

对于 OCR API调用，您需要设置环境，存在多个环境，还需要API密钥。您可以通过调用makeOCRApiCall在位图上进行OCR分析。需要提供位图和条码。如果没有条码，则提供一个空列表。

下面是一个示例

customScannerView.makeOCRApiCall(
    bitmap = bitmap,
    barcodeList = list,
    onScanResult = object : OCRResult {
        override fun onOCRResponse(ocrResponse: OCRResponse?) {
            //Successful result
        }

        override fun onOCRResponseFailed(throwable: Throwable?) {
            //Some issue occurred
        }
    })

在回调中，将返回成功或错误。它从PackageX平台API返回OCR响应响应。

许可

版权所有2022 PackageX Labs。

是根据MIT许可证许可的。