Mengenali Teks dalam Gambar dengan ML Kit di iOS

Anda dapat menggunakan ML Kit untuk mengenali teks dalam gambar. ML Kit memiliki API tujuan umum yang cocok untuk mengenali teks dalam gambar, seperti teks rambu jalan, dan API yang dioptimalkan untuk mengenali teks dalam dokumen. API tujuan umum ini memiliki model di perangkat dan model berbasis cloud. Pengenalan teks dokumen hanya tersedia pada model berbasis cloud. Lihat ringkasan untuk mengetahui perbandingan antara model berbasis cloud dan model di perangkat.

Sebelum memulai

Jika Anda belum menambahkan Firebase ke aplikasi, lakukan dengan mengikuti langkah-langkahnya di panduan memulai.
Sertakan library ML Kit di Podfile Anda:
```
pod 'Firebase/MLVision', '6.25.0'
# If using an on-device API:
pod 'Firebase/MLVisionTextModel', '6.25.0'
```
Setelah menginstal atau mengupdate Pod project, pastikan untuk membuka project Xcode menggunakan .xcworkspace-nya.
Di aplikasi Anda, impor Firebase:
Swift
```
import Firebase
```
Objective-C
```
@import Firebase;
```
Jika ingin menggunakan model berbasis Cloud, dan belum mengaktifkan API berbasis Cloud untuk project Anda, lakukan sekarang:
1. Buka halaman ML Kit APIs pada Firebase console.
2. Jika belum mengupgrade project ke paket harga Blaze, klik Upgrade untuk melakukannya. (Anda akan diminta untuk mengupgrade hanya jika project tersebut tidak menggunakan paket Blaze.)
  
  Hanya project tingkat Blaze yang dapat menggunakan API berbasis Cloud.
3. Jika API berbasis Cloud belum diaktifkan, klik Aktifkan API berbasis Cloud.
Sebelum men-deploy aplikasi yang menggunakan Cloud API ke fase produksi, Anda harus mengambil beberapa langkah tambahan untuk mencegah dan mengurangi dampak akses API tanpa izin.

Jika hanya ingin menggunakan model di perangkat, Anda dapat melewati langkah ini.

Kini Anda siap untuk mulai mengenali teks dalam gambar.

Pedoman gambar input

Agar ML Kit dapat secara akurat mengenali teks, gambar input harus berisi teks yang diwakili oleh data piksel yang cukup. Idealnya, untuk teks Latin, setiap karakter harus berukuran setidaknya 16x16 piksel. Untuk teks China, Jepang, dan Korea (hanya didukung oleh API berbasis cloud), setiap karakter harus berukuran 24x24 piksel. Untuk semua bahasa, umumnya ukuran karakter yang lebih besar dari 24x24 piksel tidak meningkatkan akurasi.

Jadi, misalnya, gambar 640x480 piksel mungkin sudah cukup untuk memindai kartu nama yang menempati lebar penuh gambar. Untuk memindai dokumen yang dicetak pada kertas berukuran letter, gambar 720x1280 piksel mungkin diperlukan.
Fokus gambar yang buruk dapat menurunkan akurasi pengenalan teks. Jika tidak memperoleh hasil yang layak, coba minta pengguna untuk mengambil ulang gambar.
Jika mengenali teks dalam aplikasi real-time, Anda mungkin perlu mempertimbangkan dimensi keseluruhan gambar input. Gambar yang lebih kecil dapat diproses lebih cepat. Jadi, untuk mengurangi latensi, ambil gambar dengan resolusi lebih rendah (ingat persyaratan akurasi di atas) dan pastikan bahwa teks menempati gambar seluas mungkin. Lihat juga Tips untuk meningkatkan performa real-time.

Mengenali teks dalam gambar

Untuk mengenali teks dalam gambar menggunakan model berbasis cloud atau model di perangkat, jalankan pengenal teks seperti yang dijelaskan di bawah ini.

1. Jalankan pengenal teks

Teruskan gambar sebagai `UIImage` atau `CMSampleBufferRef` ke metode `process(_:completion:)` `VisionTextRecognizer`:

Dapatkan instance VisionTextRecognizer dengan memanggil onDeviceTextRecognizer atau cloudTextRecognizer:

Swift

Untuk menggunakan model di perangkat:

let vision = Vision.vision()
let textRecognizer = vision.onDeviceTextRecognizer()

Untuk menggunakan model cloud:

let vision = Vision.vision()
let textRecognizer = vision.cloudTextRecognizer()

// Or, to provide language hints to assist with language detection:
// See https://cloud.google.com/vision/docs/languages for supported languages
let options = VisionCloudTextRecognizerOptions()
options.languageHints = ["en", "hi"]
let textRecognizer = vision.cloudTextRecognizer(options: options)

Objective-C

Untuk menggunakan model di perangkat:

FIRVision *vision = [FIRVision vision];
FIRVisionTextRecognizer *textRecognizer = [vision onDeviceTextRecognizer];

Untuk menggunakan model cloud:

FIRVision *vision = [FIRVision vision];
FIRVisionTextRecognizer *textRecognizer = [vision cloudTextRecognizer];

// Or, to provide language hints to assist with language detection:
// See https://cloud.google.com/vision/docs/languages for supported languages
FIRVisionCloudTextRecognizerOptions *options =
        [[FIRVisionCloudTextRecognizerOptions alloc] init];
options.languageHints = @[@"en", @"hi"];
FIRVisionTextRecognizer *textRecognizer = [vision cloudTextRecognizerWithOptions:options];

Buat objek VisionImage menggunakan UIImage atau CMSampleBufferRef.

Untuk menggunakan UIImage:

Jika perlu, putar gambar sehingga properti imageOrientation-nya adalah .up.
Buat objek VisionImage menggunakan UIImage yang sudah diputar dengan benar. Jangan tentukan metadata rotasi apa pun—yang harus digunakan adalah nilai default, yaitu .topLeft.
Swift
```
let image = VisionImage(image: uiImage)
```
Objective-C
```
FIRVisionImage *image = [[FIRVisionImage alloc] initWithImage:uiImage];
```

Untuk menggunakan CMSampleBufferRef:

Buat objek VisionImageMetadata yang menentukan orientasi data gambar yang terdapat dalam buffering CMSampleBufferRef.

Untuk mendapatkan orientasi gambar:

Swift

func imageOrientation(
    deviceOrientation: UIDeviceOrientation,
    cameraPosition: AVCaptureDevice.Position
    ) -> VisionDetectorImageOrientation {
    switch deviceOrientation {
    case .portrait:
        return cameraPosition == .front ? .leftTop : .rightTop
    case .landscapeLeft:
        return cameraPosition == .front ? .bottomLeft : .topLeft
    case .portraitUpsideDown:
        return cameraPosition == .front ? .rightBottom : .leftBottom
    case .landscapeRight:
        return cameraPosition == .front ? .topRight : .bottomRight
    case .faceDown, .faceUp, .unknown:
        return .leftTop
    }
}

Objective-C

- (FIRVisionDetectorImageOrientation)
    imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                           cameraPosition:(AVCaptureDevicePosition)cameraPosition {
  switch (deviceOrientation) {
    case UIDeviceOrientationPortrait:
      if (cameraPosition == AVCaptureDevicePositionFront) {
        return FIRVisionDetectorImageOrientationLeftTop;
      } else {
        return FIRVisionDetectorImageOrientationRightTop;
      }
    case UIDeviceOrientationLandscapeLeft:
      if (cameraPosition == AVCaptureDevicePositionFront) {
        return FIRVisionDetectorImageOrientationBottomLeft;
      } else {
        return FIRVisionDetectorImageOrientationTopLeft;
      }
    case UIDeviceOrientationPortraitUpsideDown:
      if (cameraPosition == AVCaptureDevicePositionFront) {
        return FIRVisionDetectorImageOrientationRightBottom;
      } else {
        return FIRVisionDetectorImageOrientationLeftBottom;
      }
    case UIDeviceOrientationLandscapeRight:
      if (cameraPosition == AVCaptureDevicePositionFront) {
        return FIRVisionDetectorImageOrientationTopRight;
      } else {
        return FIRVisionDetectorImageOrientationBottomRight;
      }
    default:
      return FIRVisionDetectorImageOrientationTopLeft;
  }
}

Kemudian, buat objek metadata:

Swift

let cameraPosition = AVCaptureDevice.Position.back  // Set to the capture device you used.
let metadata = VisionImageMetadata()
metadata.orientation = imageOrientation(
    deviceOrientation: UIDevice.current.orientation,
    cameraPosition: cameraPosition
)

Objective-C

FIRVisionImageMetadata *metadata = [[FIRVisionImageMetadata alloc] init];
AVCaptureDevicePosition cameraPosition =
    AVCaptureDevicePositionBack;  // Set to the capture device you used.
metadata.orientation =
    [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                 cameraPosition:cameraPosition];

Buat objek VisionImage menggunakan objek CMSampleBufferRef dan metadata rotasi:

Swift

let image = VisionImage(buffer: sampleBuffer)
image.metadata = metadata

Objective-C

FIRVisionImage *image = [[FIRVisionImage alloc] initWithBuffer:sampleBuffer];
image.metadata = metadata;

Lalu, teruskan gambar ke metode process(_:completion:):

Swift

textRecognizer.process(visionImage) { result, error in
  guard error == nil, let result = result else {
    // ...
    return
  }

  // Recognized text
}

Objective-C

[textRecognizer processImage:image
                  completion:^(FIRVisionText *_Nullable result,
                               NSError *_Nullable error) {
  if (error != nil || result == nil) {
    // ...
    return;
  }

  // Recognized text
}];

2. Ekstrak teks dari blok teks yang dikenali

Jika operasi pengenalan teks berhasil, objek [`VisionText`]] [VisionText] akan ditampilkan. Objek `VisionText` berisi teks lengkap yang dikenali dalam gambar, serta berisi nol objek [`VisionTextBlock`][VisionTextBlock] atau lebih. Setiap `VisionTextBlock` mewakili blok teks persegi panjang, yang berisi nol objek [`VisionTextLine`][VisionTextLine] atau lebih. Setiap objek `VisionTextLine` berisi nol objek [`VisionTextEements`][VisionTextEements] atau lebih, yang mewakili kata dan entity seperti kata (tanggal, angka, dan sebagainya). Untuk setiap objek `VisionTextBlock`, `VisionTextLine`, dan `VisionTextElement`, Anda bisa mendapatkan teks yang dikenali di area dan koordinat pembatas area tersebut. Contoh:

Swift

let resultText = result.text
for block in result.blocks {
    let blockText = block.text
    let blockConfidence = block.confidence
    let blockLanguages = block.recognizedLanguages
    let blockCornerPoints = block.cornerPoints
    let blockFrame = block.frame
    for line in block.lines {
        let lineText = line.text
        let lineConfidence = line.confidence
        let lineLanguages = line.recognizedLanguages
        let lineCornerPoints = line.cornerPoints
        let lineFrame = line.frame
        for element in line.elements {
            let elementText = element.text
            let elementConfidence = element.confidence
            let elementLanguages = element.recognizedLanguages
            let elementCornerPoints = element.cornerPoints
            let elementFrame = element.frame
        }
    }
}

Objective-C

NSString *resultText = result.text;
for (FIRVisionTextBlock *block in result.blocks) {
  NSString *blockText = block.text;
  NSNumber *blockConfidence = block.confidence;
  NSArray<FIRVisionTextRecognizedLanguage *> *blockLanguages = block.recognizedLanguages;
  NSArray<NSValue *> *blockCornerPoints = block.cornerPoints;
  CGRect blockFrame = block.frame;
  for (FIRVisionTextLine *line in block.lines) {
    NSString *lineText = line.text;
    NSNumber *lineConfidence = line.confidence;
    NSArray<FIRVisionTextRecognizedLanguage *> *lineLanguages = line.recognizedLanguages;
    NSArray<NSValue *> *lineCornerPoints = line.cornerPoints;
    CGRect lineFrame = line.frame;
    for (FIRVisionTextElement *element in line.elements) {
      NSString *elementText = element.text;
      NSNumber *elementConfidence = element.confidence;
      NSArray<FIRVisionTextRecognizedLanguage *> *elementLanguages = element.recognizedLanguages;
      NSArray<NSValue *> *elementCornerPoints = element.cornerPoints;
      CGRect elementFrame = element.frame;
    }
  }
}

Tips untuk meningkatkan performa real-time

Jika ingin menggunakan model di perangkat untuk mengenali teks dalam aplikasi real-time, ikuti pedoman berikut ini untuk mencapai kecepatan frame terbaik:

Batasi panggilan ke pengenal teks. Jika frame video baru tersedia saat pengenal teks sedang berjalan, hapus frame tersebut.
Jika Anda menggunakan output pengenal teks untuk menempatkan grafis pada gambar input, pertama-tama dapatkan hasilnya dari ML Kit, lalu render gambar dan tempatkan grafis dalam satu langkah. Dengan demikian, Anda hanya merender ke permukaan tampilan sekali untuk setiap frame input. Lihat class previewOverlayView dan FIRDetectionOverlayView dalam aplikasi contoh untuk mendapatkan gambaran.
Pertimbangkan untuk mengambil gambar dengan resolusi lebih rendah. Namun, perhatikan juga persyaratan dimensi gambar API ini.

Langkah berikutnya

Sebelum men-deploy aplikasi yang menggunakan Cloud API ke fase produksi, Anda harus mengambil beberapa langkah tambahan untuk mencegah dan mengurangi dampak akses API tanpa izin.

Mengenali teks dalam gambar dokumen

Untuk mengenali teks dokumen, konfigurasi dan jalankan pengenal teks dokumen berbasis cloud seperti yang dijelaskan di bawah ini.

API pengenalan teks dokumen, yang dijelaskan di bawah ini, menyediakan antarmuka yang ditujukan untuk memudahkan Anda bekerja dengan gambar dokumen. Namun, jika lebih menyukai antarmuka yang disediakan oleh API teks jarang, Anda dapat menggunakannya untuk memindai dokumen dengan mengonfigurasi pengenal teks cloud untuk menggunakan model teks padat.

Untuk menggunakan API pengenalan teks dokumen:

1. Jalankan pengenal teks

Teruskan gambar sebagai UIImage atau CMSampleBufferRef ke metode process(_:completion:) VisionDocumentTextRecognizer :

Dapatkan instance VisionDocumentTextRecognizer dengan memanggil cloudDocumentTextRecognizer:

Swift

let vision = Vision.vision()
let textRecognizer = vision.cloudDocumentTextRecognizer()

// Or, to provide language hints to assist with language detection:
// See https://cloud.google.com/vision/docs/languages for supported languages
let options = VisionCloudDocumentTextRecognizerOptions()
options.languageHints = ["en", "hi"]
let textRecognizer = vision.cloudDocumentTextRecognizer(options: options)

Objective-C

FIRVision *vision = [FIRVision vision];
FIRVisionDocumentTextRecognizer *textRecognizer = [vision cloudDocumentTextRecognizer];

// Or, to provide language hints to assist with language detection:
// See https://cloud.google.com/vision/docs/languages for supported languages
FIRVisionCloudDocumentTextRecognizerOptions *options =
        [[FIRVisionCloudDocumentTextRecognizerOptions alloc] init];
options.languageHints = @[@"en", @"hi"];
FIRVisionDocumentTextRecognizer *textRecognizer = [vision cloudDocumentTextRecognizerWithOptions:options];

Buat objek VisionImage menggunakan UIImage atau CMSampleBufferRef.

Untuk menggunakan UIImage:

Jika perlu, putar gambar sehingga properti imageOrientation-nya adalah .up.
Buat objek VisionImage menggunakan UIImage yang sudah diputar dengan benar. Jangan tentukan metadata rotasi apa pun—yang harus digunakan adalah nilai default, yaitu .topLeft.
Swift
```
let image = VisionImage(image: uiImage)
```
Objective-C
```
FIRVisionImage *image = [[FIRVisionImage alloc] initWithImage:uiImage];
```

Untuk menggunakan CMSampleBufferRef:

Buat objek VisionImageMetadata yang menentukan orientasi data gambar yang terdapat dalam buffering CMSampleBufferRef.

Untuk mendapatkan orientasi gambar:

Swift

func imageOrientation(
    deviceOrientation: UIDeviceOrientation,
    cameraPosition: AVCaptureDevice.Position
    ) -> VisionDetectorImageOrientation {
    switch deviceOrientation {
    case .portrait:
        return cameraPosition == .front ? .leftTop : .rightTop
    case .landscapeLeft:
        return cameraPosition == .front ? .bottomLeft : .topLeft
    case .portraitUpsideDown:
        return cameraPosition == .front ? .rightBottom : .leftBottom
    case .landscapeRight:
        return cameraPosition == .front ? .topRight : .bottomRight
    case .faceDown, .faceUp, .unknown:
        return .leftTop
    }
}

Objective-C

- (FIRVisionDetectorImageOrientation)
    imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                           cameraPosition:(AVCaptureDevicePosition)cameraPosition {
  switch (deviceOrientation) {
    case UIDeviceOrientationPortrait:
      if (cameraPosition == AVCaptureDevicePositionFront) {
        return FIRVisionDetectorImageOrientationLeftTop;
      } else {
        return FIRVisionDetectorImageOrientationRightTop;
      }
    case UIDeviceOrientationLandscapeLeft:
      if (cameraPosition == AVCaptureDevicePositionFront) {
        return FIRVisionDetectorImageOrientationBottomLeft;
      } else {
        return FIRVisionDetectorImageOrientationTopLeft;
      }
    case UIDeviceOrientationPortraitUpsideDown:
      if (cameraPosition == AVCaptureDevicePositionFront) {
        return FIRVisionDetectorImageOrientationRightBottom;
      } else {
        return FIRVisionDetectorImageOrientationLeftBottom;
      }
    case UIDeviceOrientationLandscapeRight:
      if (cameraPosition == AVCaptureDevicePositionFront) {
        return FIRVisionDetectorImageOrientationTopRight;
      } else {
        return FIRVisionDetectorImageOrientationBottomRight;
      }
    default:
      return FIRVisionDetectorImageOrientationTopLeft;
  }
}

Kemudian, buat objek metadata:

Swift

let cameraPosition = AVCaptureDevice.Position.back  // Set to the capture device you used.
let metadata = VisionImageMetadata()
metadata.orientation = imageOrientation(
    deviceOrientation: UIDevice.current.orientation,
    cameraPosition: cameraPosition
)

Objective-C

FIRVisionImageMetadata *metadata = [[FIRVisionImageMetadata alloc] init];
AVCaptureDevicePosition cameraPosition =
    AVCaptureDevicePositionBack;  // Set to the capture device you used.
metadata.orientation =
    [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                 cameraPosition:cameraPosition];

Buat objek VisionImage menggunakan objek CMSampleBufferRef dan metadata rotasi:

Swift

let image = VisionImage(buffer: sampleBuffer)
image.metadata = metadata

Objective-C

FIRVisionImage *image = [[FIRVisionImage alloc] initWithBuffer:sampleBuffer];
image.metadata = metadata;

Lalu, teruskan gambar ke metode process(_:completion:):

Swift

textRecognizer.process(visionImage) { result, error in
  guard error == nil, let result = result else {
    // ...
    return
  }

  // Recognized text
}

Objective-C

[textRecognizer processImage:image
                  completion:^(FIRVisionDocumentText *_Nullable result,
                               NSError *_Nullable error) {
  if (error != nil || result == nil) {
    // ...
    return;
  }

    // Recognized text
}];

2. Ekstrak teks dari blok teks yang dikenali

Jika operasi pengenalan teks berhasil, objek VisionDocumentText akan ditampilkan. Objek VisionDocumentText berisi teks lengkap yang dikenali dalam gambar, dan hierarki objek yang mencerminkan struktur dokumen yang dikenali:

Untuk setiap objek VisionDocumentTextBlock, VisionDocumentTextParagraph, VisionDocumentTextWord, dan VisionDocumentTextSymbol, Anda bisa mendapatkan teks yang dikenali di area dan koordinat pembatas area tersebut.

Contoh:

Swift

let resultText = result.text
for block in result.blocks {
    let blockText = block.text
    let blockConfidence = block.confidence
    let blockRecognizedLanguages = block.recognizedLanguages
    let blockBreak = block.recognizedBreak
    let blockCornerPoints = block.cornerPoints
    let blockFrame = block.frame
    for paragraph in block.paragraphs {
        let paragraphText = paragraph.text
        let paragraphConfidence = paragraph.confidence
        let paragraphRecognizedLanguages = paragraph.recognizedLanguages
        let paragraphBreak = paragraph.recognizedBreak
        let paragraphCornerPoints = paragraph.cornerPoints
        let paragraphFrame = paragraph.frame
        for word in paragraph.words {
            let wordText = word.text
            let wordConfidence = word.confidence
            let wordRecognizedLanguages = word.recognizedLanguages
            let wordBreak = word.recognizedBreak
            let wordCornerPoints = word.cornerPoints
            let wordFrame = word.frame
            for symbol in word.symbols {
                let symbolText = symbol.text
                let symbolConfidence = symbol.confidence
                let symbolRecognizedLanguages = symbol.recognizedLanguages
                let symbolBreak = symbol.recognizedBreak
                let symbolCornerPoints = symbol.cornerPoints
                let symbolFrame = symbol.frame
            }
        }
    }
}

Objective-C

NSString *resultText = result.text;
for (FIRVisionDocumentTextBlock *block in result.blocks) {
  NSString *blockText = block.text;
  NSNumber *blockConfidence = block.confidence;
  NSArray<FIRVisionTextRecognizedLanguage *> *blockRecognizedLanguages = block.recognizedLanguages;
  FIRVisionTextRecognizedBreak *blockBreak = block.recognizedBreak;
  CGRect blockFrame = block.frame;
  for (FIRVisionDocumentTextParagraph *paragraph in block.paragraphs) {
    NSString *paragraphText = paragraph.text;
    NSNumber *paragraphConfidence = paragraph.confidence;
    NSArray<FIRVisionTextRecognizedLanguage *> *paragraphRecognizedLanguages = paragraph.recognizedLanguages;
    FIRVisionTextRecognizedBreak *paragraphBreak = paragraph.recognizedBreak;
    CGRect paragraphFrame = paragraph.frame;
    for (FIRVisionDocumentTextWord *word in paragraph.words) {
      NSString *wordText = word.text;
      NSNumber *wordConfidence = word.confidence;
      NSArray<FIRVisionTextRecognizedLanguage *> *wordRecognizedLanguages = word.recognizedLanguages;
      FIRVisionTextRecognizedBreak *wordBreak = word.recognizedBreak;
      CGRect wordFrame = word.frame;
      for (FIRVisionDocumentTextSymbol *symbol in word.symbols) {
        NSString *symbolText = symbol.text;
        NSNumber *symbolConfidence = symbol.confidence;
        NSArray<FIRVisionTextRecognizedLanguage *> *symbolRecognizedLanguages = symbol.recognizedLanguages;
        FIRVisionTextRecognizedBreak *symbolBreak = symbol.recognizedBreak;
        CGRect symbolFrame = symbol.frame;
      }
    }
  }
}

Langkah berikutnya

Sebelum men-deploy aplikasi yang menggunakan Cloud API ke lingkungan production, Anda harus mengambil beberapa langkah tambahan untuk mencegah dan mengurangi dampak akses API tanpa izin.