メインコンテンツまでスキップ

YotsukaD API ガイド

このページでは、EdgeOCRExtensions の YotsukaD API を使ってラベルを検出し、必要に応じて射影補正済み画像を取得する方法を説明します。

API リファレンス

詳細な API 仕様は Swift API リファレンス / Kotlin API リファレンス を参照してください。

YotsukaD API 概要​

  1. YotsukaD インスタンスを生成します。
  2. load() を 1 回だけ呼びます。
  3. 静止画なら UIImage、カメラなら CMSampleBuffer または ImageProxy を渡します。
  4. result.documents からスコア、四隅座標、補正済み画像（UIImage または Bitmap）を取得します。

1. 初期化してモデルをロードする​

import AVFoundation
import EVKit
import UIKit

func loadYotsukaD() -> YotsukaD {
  // 検出器を生成して以後のフレームで再利用する
  let detector = YotsukaD(
    modelPath: "",
    inputSize: (3, 640, 640),
    scoreThreshold: 0.25,
    numClasses: 3,
    useGPU: true
  )

  // 推論前にロード失敗を検知する
  guard detector.load() else {
    fatalError("Failed to load YotsukaD")
  }
 
  // ロード後の状態を確認する
  guard detector.isLoaded() else {
    fatalError("YotsukaD is not ready")
  }

  return detector
}
  • modelPath — SDK 組み込みモデルを使う場合は空文字列 "" を渡します。独自モデルを使う場合はファイルパスを指定します。
  • inputSize — モデルの入力サイズを (channels, height, width) の順で指定します。
  • scoreThreshold — 検出スコアの閾値です。誤検出が多い場合は値を上げてください。
  • numClasses — モデルが区別できるクラス数を指定します。
  • useGPU / useGpu — GPU を使用する場合は true を設定します。

2. カメラ入力を推論する​

import AVFoundation
import CoreGraphics
import EVKit

// スキャンオプションを設定する
let options = DocScanOptions(
  transformMode: .auto,
  centerOnly: false
)

// カメラのフレームをそのまま渡してリアルタイム推論する
let result = try detector.scan(
  sampleBuffer,
  viewBounds: viewBounds,
  cropRect: cropRect,
  rotation: .rotate0,
  options: options
)

カメラ入力では、プレビュー内の対象領域を cropRect で指定して scan(...) に渡します。どちらのプラットフォームでも、結果は result.documents から取得します。

  • cropRect は 0.0 から 1.0 の正規化座標です。
  • Swift では viewBounds（プレビューの表示領域）と rotation（入力フレームの向き）を追加で渡します。Kotlin では ImageProxy から回転情報を自動取得するため不要です。

書類サイズを自動で推定したい場合は transformMode: .auto または TransformMode.Auto を使います。

補正後画像を固定サイズで保存したい場合は .fixedSize(width:height:) または FixedSize(width, height) を使います。 中央の書類だけ拾いたい場合は centerOnly: true または centerOnly = true を使います。

3. 結果を使う​

for document in result.documents {
  print("score: \(document.score)")
  print("keypoints: \(document.keypoints)")

  // 補正済み画像がある場合は表示や保存に使う
  if let cropped = document.cropped {
    imageView.image = cropped
  }
}

result.documents に検出された書類の一覧が入ります。各 Document は以下のプロパティを持ちます。

  • score — 検出の信頼度（0.0〜1.0）
  • keypoints — 書類の四隅座標（正規化座標）
  • cropped — 射影補正済みの画像（Swift: PlatformImage? / Kotlin: Bitmap?）

documents が空の場合は対象が検出されていないため、撮影角度や cropRect の範囲を見直してください。

4. 静止画像を推論する（Swift のみ）​

カメラではなく静止画像や加工済み画像を扱う場合は、PlatformImage を scan(...) に渡します。

import EVKit

// スキャンオプションを設定する
let options = DocScanOptions(
  transformMode: .auto,
  centerOnly: false
)

// 画像全体を対象にして推論する
let result = try detector.scan(
  image,
  cropRect: CGRect(x: 0, y: 0, width: 1, height: 1),
  rotation: .rotate0,
  options: options
)

for document in result.documents {
  print("score: \(document.score)")
  print("keypoints: \(document.keypoints)")

  if let cropped = document.cropped {
    imageView.image = cropped
  }
}
  • cropRect に (0, 0, 1, 1) を渡すと画像全体が推論対象になります。
  • 特定領域だけを対象にしたい場合は正規化座標で範囲を指定してください。