在 iOS 上使用 ML Kit 掃描條碼

你可以使用 ML Kit 辨識條碼並解碼。

立即體驗

事前準備

  1. 在 Podfile 中加入下列 ML Kit pod:
    pod 'GoogleMLKit/BarcodeScanning', '3.2.0'
    
  2. 安裝或更新專案的 Pod 後,請使用其 .xcworkspace 開啟 Xcode 專案。Xcode 12.4 以上版本支援 ML Kit。

輸入圖片使用規範

  • 如要讓 ML Kit 準確讀取條碼,輸入圖片必須包含以充足像素資料代表的條碼。

    特定的像素資料要求取決於條碼類型和編碼的資料量,因為許多條碼都支援變數大小酬載。一般來說,條碼最小的最小尺寸應至少為 2 像素,2 維代碼的高度則至少為 2 像素。

    舉例來說,EAN-13 條碼是由 1、2、3 或 4 單位的長條和空間組成,因此 EAN-13 條碼圖片最好有寬度至少 2、4、6 和 8 像素的長條和空間。由於 EAN-13 條碼的總寬度為 95 個單位,條碼寬度至少必須為 190 像素。

    PDF417 等解碼器格式需要較大的像素尺寸,才能可靠地讀取 ML Kit。舉例來說,PDF417 程式碼的每列最多可包含 34 17 個單位寬的「字詞」,理想情況下為寬度至少為 1156 像素。

  • 影像失焦可能會影響掃描的準確度。如果您的應用程式未取得可接受的結果,請使用者重新拍攝圖片。

  • 以一般應用程式來說,建議提供解析度較高的圖片 (例如 1280x720 或 1920x1080),以便在遠距離相機的情況下掃描條碼。

    不過,如果應用程式需要延遲時間是關鍵的一環,您可以透過較低的解析度擷取圖片,進而提升效能,同時需要條碼佔滿輸入圖像的大部分。另請參閱「改善即時效能的提示」。

1. 設定條碼掃描器

如果您知道應該讀取哪些條碼格式,可以將條碼掃描器設定為僅掃描這些格式,以提升條碼掃描器的速度。

舉例來說,如果只要掃描 Aztec 代碼和 QR code,請建構 BarcodeScannerOptions 物件,如以下範例所示:

Swift

let format = .all
let barcodeOptions = BarcodeScannerOptions(formats: format)
  

支援的格式包括:

  • code128
  • code39
  • code93
  • codaBar
  • dataMatrix
  • EAN13
  • EAN8
  • ITF
  • qrCode
  • UPCA
  • 通用
  • PDF417
  • Aztec

Objective-C

MLKBarcodeScannerOptions *options =
  [[MLKBarcodeScannerOptions alloc]
   initWithFormats: MLKBarcodeFormatQRCode | MLKBarcodeFormatAztec];

支援的格式包括:

  • 代碼-128 (MLKBarcodeFormatCode128)
  • 代碼-39 (MLKBarcodeFormatCode39)
  • 代碼-93 (MLKBarcodeFormatCode93)
  • Codabar (MLKBarcodeFormatCodaBar)
  • 資料矩陣 (MLKBarcodeFormatDataMatrix)
  • EAN-13 (MLKBarcodeFormatEAN13)
  • EAN-8 (MLKBarcodeFormatEAN8)
  • ITF (MLKBarcodeFormatITF)
  • QR code (MLKBarcodeFormatQRCode)
  • UPC-A (MLKBarcodeFormatUPCA)
  • UPC-E (MLKBarcodeFormatUPCE)
  • PDF-417 (MLKBarcodeFormatPDF417)
  • 阿茲特克代碼 (MLKBarcodeFormatAztec)

2. 準備輸入圖片

如要掃描圖片中的條碼,請將圖片以 UIImageCMSampleBufferRef 的形式傳遞給 BarcodeScannerprocess()results(in:) 方法:

使用 UIImageCMSampleBuffer 建立 VisionImage 物件。

如果您使用 UIImage,請按照下列步驟操作:

  • 使用 UIImage 建立 VisionImage 物件。請務必指定正確的 .orientation

    Swift

    let image = VisionImage(image: UIImage)
    visionImage.orientation = image.imageOrientation

    Objective-C

    MLKVisionImage *visionImage = [[MLKVisionImage alloc] initWithImage:image];
    visionImage.orientation = image.imageOrientation;

如果您使用 CMSampleBuffer,請按照下列步驟操作:

  • 指定 CMSampleBuffer 中包含的圖片資料方向。

    如何取得圖像方向:

    Swift

    func imageOrientation(
      deviceOrientation: UIDeviceOrientation,
      cameraPosition: AVCaptureDevice.Position
    ) -> UIImage.Orientation {
      switch deviceOrientation {
      case .portrait:
        return cameraPosition == .front ? .leftMirrored : .right
      case .landscapeLeft:
        return cameraPosition == .front ? .downMirrored : .up
      case .portraitUpsideDown:
        return cameraPosition == .front ? .rightMirrored : .left
      case .landscapeRight:
        return cameraPosition == .front ? .upMirrored : .down
      case .faceDown, .faceUp, .unknown:
        return .up
      }
    }
          

    Objective-C

    - (UIImageOrientation)
      imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                             cameraPosition:(AVCaptureDevicePosition)cameraPosition {
      switch (deviceOrientation) {
        case UIDeviceOrientationPortrait:
          return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationLeftMirrored
                                                                : UIImageOrientationRight;
    
        case UIDeviceOrientationLandscapeLeft:
          return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationDownMirrored
                                                                : UIImageOrientationUp;
        case UIDeviceOrientationPortraitUpsideDown:
          return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationRightMirrored
                                                                : UIImageOrientationLeft;
        case UIDeviceOrientationLandscapeRight:
          return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationUpMirrored
                                                                : UIImageOrientationDown;
        case UIDeviceOrientationUnknown:
        case UIDeviceOrientationFaceUp:
        case UIDeviceOrientationFaceDown:
          return UIImageOrientationUp;
      }
    }
          
  • 使用 CMSampleBuffer 物件和方向建立 VisionImage 物件:

    Swift

    let image = VisionImage(buffer: sampleBuffer)
    image.orientation = imageOrientation(
      deviceOrientation: UIDevice.current.orientation,
      cameraPosition: cameraPosition)

    Objective-C

     MLKVisionImage *image = [[MLKVisionImage alloc] initWithBuffer:sampleBuffer];
     image.orientation =
       [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                    cameraPosition:cameraPosition];

3. 取得 BarcodeScanner 的執行個體

取得 BarcodeScanner 的執行個體:

Swift

let barcodeScanner = BarcodeScanner.barcodeScanner()
// Or, to change the default settings:
// let barcodeScanner = BarcodeScanner.barcodeScanner(options: barcodeOptions)

Objective-C

MLKBarcodeScanner *barcodeScanner = [MLKBarcodeScanner barcodeScanner];
// Or, to change the default settings:
// MLKBarcodeScanner *barcodeScanner =
//     [MLKBarcodeScanner barcodeScannerWithOptions:options];

4. 處理圖片

接著,將圖片傳遞至 process() 方法:

Swift

barcodeScanner.process(visionImage) { features, error in
  guard error == nil, let features = features, !features.isEmpty else {
    // Error handling
    return
  }
  // Recognized barcodes
}

Objective-C

[barcodeScanner processImage:image
                  completion:^(NSArray<MLKBarcode *> *_Nullable barcodes,
                               NSError *_Nullable error) {
  if (error != nil) {
    // Error handling
    return;
  }
  if (barcodes.count > 0) {
    // Recognized barcodes
  }
}];

5. 從條碼取得資訊

如果條碼掃描作業成功,掃描器會傳回 Barcode 物件的陣列。每個 Barcode 物件都代表在圖片中偵測到的條碼。對於每個條碼,您可以在輸入圖片中取得其邊界座標,以及以條碼編碼的原始資料。此外,如果條碼掃描器可以判斷條碼編碼的資料類型,您就可以取得包含剖析資料的物件。

例如:

Swift

for barcode in barcodes {
  let corners = barcode.cornerPoints

  let displayValue = barcode.displayValue
  let rawValue = barcode.rawValue

  let valueType = barcode.valueType
  switch valueType {
  case .wiFi:
    let ssid = barcode.wifi?.ssid
    let password = barcode.wifi?.password
    let encryptionType = barcode.wifi?.type
  case .URL:
    let title = barcode.url!.title
    let url = barcode.url!.url
  default:
    // See API reference for all supported value types
  }
}

Objective-C

for (MLKBarcode *barcode in barcodes) {
   NSArray *corners = barcode.cornerPoints;

   NSString *displayValue = barcode.displayValue;
   NSString *rawValue = barcode.rawValue;

   MLKBarcodeValueType valueType = barcode.valueType;
   switch (valueType) {
     case MLKBarcodeValueTypeWiFi:
       ssid = barcode.wifi.ssid;
       password = barcode.wifi.password;
       encryptionType = barcode.wifi.type;
       break;
     case MLKBarcodeValueTypeURL:
       url = barcode.URL.url;
       title = barcode.URL.title;
       break;
     // ...
     default:
       break;
   }
 }

改善即時成效的訣竅

如要在即時應用程式中掃描條碼,請遵循下列準則,以便達到最佳影格速率:

  • 請勿以相機的原始解析度擷取輸入資料。在某些裝置上,以原生解析度擷取輸入內容會產生極大 (超過 1,000 萬像素) 的圖片,進而導致極低的延遲,且不利於準確率。而是只要求掃描條碼所需的相機尺寸 (通常不超過 200 萬像素)。

    但是,我們不建議使用 AVCaptureSessionPresetDefaultAVCaptureSessionPresetLowAVCaptureSessionPresetMedium 等已命名的擷取工作階段預設設定,因為這會對應到某些裝置上不適當的解析度。請改用特定預設設定,例如 AVCaptureSessionPreset1280x720

    如果掃描速度很重要,您可以進一步降低拍照解析度。不過請注意,條碼大小下限規定。

    嘗試從一系列串流影片影格中辨識條碼時,辨識器可能會產生影格間有不同的結果。請等到取得連續一系列的相同值,才能確信您傳回良好結果。

    ITF 和 CODE-39 不支援總和檢查碼數字。

  • 如要處理影片畫面,請使用偵測工具的 results(in:) 同步 API。從 AVCaptureVideoDataOutputSampleBufferDelegate captureOutput(_, didOutput:from:) 函式呼叫此方法,即可同步取得指定影片畫面的結果。將 AVCaptureVideoDataOutput alwaysDiscardsLateVideoFrames 保留為 true,藉此調節對偵測工具的呼叫次數。如果在偵測工具執行期間提供新的影片畫面,該影格將遭到捨棄。
  • 如果您使用偵測工具的輸出內容將輸入圖片上的圖形重疊,請先從 ML Kit 取得結果,然後再在單一步驟算繪影像和重疊。這樣一來,您只會在每個已處理的輸入影格轉譯一次螢幕介面。如需範例,請參閱 ML Kit 快速入門導覽課程範例中的 updatePreviewOverlayViewWithLastFrame