KXABarcodeReader Programmer's Guide (iOS)

2019-08-05/2022-02-21

このページではバーコード認識(デコーダ)ソフトウェア「KXABarcodeReader Library iOS版」の使用方法を解説します。

iOS版KXABarcodeReader Libraryは静的ライブラリファイル (.a) とヘッダファイル (.h) で構成されます。

% tree
.
├── Headers
│   ├── KXABarcodeReader.h
│   ├── kxa_barcode_reader.h
│   └── kxa_barcode_symbologies.h
└── libkxabarcodereader.a

KXABarcodeReader Libraryを利用したいアプリのXcodeプロジェクトに、これら静的ライブラリとすべてのヘッダを追加してください(最新バージョンはXCFramework形式になっていますので、サンプルアプリのプロジェクトに同梱されているKXABarcodeReader.xcframeworkを追加するだけで自動的にこれらのファイルが使えるようになります)。

さらにターゲットの設定で、KXABarcodeReader Libraryが依存している Accelerate.framework とiconvライブラリ (libiconv.tdb) のリンクを指定してください。

KXABarcodeReaderのコア部分はC/C++で記述されていますが、iOS向けのAPIとしてはObjective-Cのクラスを使用します。

KXABarcodeReaderの仕組み

iOS AVFoundation フレームワークのキャプチャセッションで渡されるビデオフレーム (CMSampleBufferRef) のイメージ (CVImageBufferRef) をKXABarcodeReaderのデコードメソッドに与えることにより、画像に含まれるバーコードの値を文字列データとして得ることができます。

KXABarcodeReader iOS版でのバーコードの検出は、ビデオフレームをその中心からイメージの短辺サイズの正方形に切り取った領域内を対象とし、正方形の中央付近を通る水平線(スキャンライン)を基準に行われます。一度に複数のバーコードをデコードすることはできません。

KXABarcodeReaderはグローバルでスタティックな状態を持つので、複数のスレッドから非同期にAPIを呼び出すことはできません(同時並行デコード処理は不可能)。

Objective-Cクラス

バーコード読み取り機能を提供するObjective-Cクラス名は「KXABarcodeReader」です。 KXABarcodeReader.h ファイルで宣言されています。

次のようにバーコードリーダを利用するObjective-Cソースファイルにインポートしてください。

#import "KXABarcodeReader.h"

バーコードの種類を表す定数

KXABarcodeReaderがサポートするバーコードの種類を表す定数は kxa_barcode_symbologies.h に定義されています。次の8種類に分けられます。

  1. KXA_NW7 = NW-7 (CODABAR)
  2. KXA_ITF = Interleaved 2 of 5
  3. KXA_CODE39 = CODE39
  4. KXA_CODE128 = CODE128 (GS1-128)
  5. KXA_EAN13 = EAN-13/JAN-13, UPC-A
  6. KXA_EAN8 = EAN-8/JAN-8
  7. KXA_UPCE = UPC-E
  8. KXA_GS1DATABAR = GS1 DataBar

KXABarcodeReaderクラス

KXABarcodeReaderクラスには次のようなメソッドやプロパティがあります。

sharedInstance

sharedInstanceメソッドは、KXABarcodeReaderクラスの共有インスタンスを返します。 KXABarcodeReaderはグローバルでスタティックな状態を持つため、アプリ内で利用できるKXABarcodeReaderオブジェクトは1つだけです。あらかじめ生成された単一のインスタンスをアプリ全体で共有します。 alloc により新しいKXABarcodeReaderオブジェクトを生成することはできません。 sharedInstanceメソッドが返すオブジェクトを使ってください。

+ (KXABarcodeReader *)sharedInstance;

version

versionは、KXABarcodeReaderのバージョンと著作権を表す文字列 (NSString *) を保持している読み取り専用のプロパティです。

versionNumber

versionNumberは、KXABarcodeReaderのバージョンを表す8桁の数値 (Binary Coded Decimal) を保持している読み取り専用のプロパティです。

license

licenseは、ライブラリの使用許諾番号を表す文字列 (NSString *) を保持している読み取り専用のプロパティです。ライセンスを購入していない(アプリがライセンスファイルを含まない)場合、文字列は空です。

reset

resetメソッドは、KXABarcodeReaderオブジェクトの内部状態をリセットします。 プロパティの値はデフォルト値に戻ります。

- (void)reset;

types

typesは、読み取り(デコード)の対象としたいバーコードの種類を設定するためのプロパティです。バーコードの種類には前述の定数を指定します。複数の種類をデコード対象としたい場合は、ビット単位OR演算を使用します。

EAN-13(UPC-A), EAN-8, UPC-Eを読み取り対象とする例:

reader.types = KXA_EAN13
    | KXA_EAN8
    | KXA_UPCE;

デフォルト値は KXA_UNKNOWN_BARCODE_TYPE (読み取り対象なし)です。

rotation

rotationプロパティには、decodeメソッドへの入力イメージとなるビデオフレームが回転している場合、それを正位置に戻す補正を行うための回転角を設定します。 decodeメソッドはrotationプロパティで指定された角度だけ入力イメージを回転させてから解析処理を行います。 rotationの値として整数値nを渡すと入力イメージを n × 90° 回転させます。 通常0、1、2、3いずれかの整数値を与えます。

デフォルト値はゼロ (0) です。

decode

decodeは、引数として与えられたビデオフレームの輝度情報配列部分を解析、デコードするメソッドです。バーコードの検出に成功すれば、そのデータを文字列として返します。デコードできなかった場合は空の文字列を返します。

※ライセンス未購入の試用状態では戻り値であるバーコード文字列の一部が伏せ字(アスタリスク「*」)になります。

- (NSString *)decode:(CVImageBufferRef)imageBuffer;

deocodeメソッドは、AVFoundationキャプチャセッションのデリゲートメソッド captureOutput:didOutputSampleBuffer:fromConnection: で渡ってくるCMSampleBufferから取得したCVImageBufferRefを利用することを前提にしています。

type

typeプロパティには、直前のdecodeメソッド呼び出しでバーコードの検出に成功している場合、読み取ったバーコードの種類(バーコードの種類を表す定数のいずれか)が格納されています。バーコードが検出されていない場合、値は不定です。

text

textプロパティには、直前のdecodeメソッド呼び出しでバーコードの検出に成功している場合、読み取ったバーコードデータ(文字列)が格納されています。バーコードが検出されていない場合、値は不定です。

Swiftからの利用

SwiftはObjective-Cとの相互運用が可能ですので、KXABarcodeReader LibraryはSwiftベースのプロジェクトにも利用できます。アップルの公式ドキュメント「Imported C and Objective-C APIs」に従って、ブリッジヘッダを作成してください。

API呼び出し手順

アプリに組み込む際の処理手順、APIをどのような順番で呼び出せばよいかを説明します。

ビューがロードされるタイミングで、バーコードリーダオブジェクト(BarcodeReaderの共有インスタンス)を取得します。

#import "KXABarcodeReader.h"
…

- (void)viewDidLoad {
    [super viewDidLoad];

    self.barcodeReader = [KXABarcodeReader sharedInstance];

…

バーコード読み取り用のビューを表示し、カメラのプレビュー動作を開始する手前のタイミングで、バーコードリーダオブジェクトの内部状態をリセットし、読み取りに必要なパラメータを設定します。

[self.barcodeReader reset];
self.barcodeReader.rotation = 3;
self.barcodeReader.types = KXA_GS1DATABAR;

キャプチャセッションのデリゲートメソッドで得られるビデオフレームのデータを使ってデコード処理を行います。

- (void)captureOutput:(AVCaptureOutput*)captureOutput
didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
       fromConnection:(AVCaptureConnection*)connection
{
    // イメージバッファを取得する。
    CVImageBufferRef imageBuffer;
    imageBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);

    // イメージバッファをロックする。
    CVPixelBufferLockBaseAddress(imageBuffer, 0);

    if ([[self.barcodeReader decode:imageBuffer] length]) {
        // 文字列が空でなければバーコードの検出に成功している。
        NSLog(@"Type: %d", self.barcodeReader.type);
    }

    // イメージバッファをアンロックする。
    CVPixelBufferUnlockBaseAddress(imageBuffer, 0);
}

初回のデリゲートメソッド呼び出し(単一のビデオフレーム、1度のデコード処理)で正常にバーコードを読み取れるとは限りません。正常に読み取りが完了するまで、デリゲートの呼び出しを連続して受け付けるようにします。バーコードの検出に成功したらキャプチャセッションを終了して構いません。

再び読み取りを行うには、バーコードリーダオブジェクトの内部状態をリセットするところから始めます。

ビデオフレームの設定

入力イメージのフレームサイズ(画素数)は 1920 × 1080 ピクセル以下に設定してください。

適切な画素数は用途によって異なります。 EAN-13(UPC-A), EAN-8, UPC-E は 640 × 480 ピクセル程度でも読み取り可能です。 非常に長い可変長バーコード(CODE128に多い)や、サイズが小さいGS1 DataBarの場合、解像度を上げないと読み取れません。バーコード検出処理負荷との兼ね合いで 1280 × 720 ピクセル程度が実用的かと思われます。

適用業務と、実際に使用するiOSデバイスのカメラの機能に応じて最適な画素数を割り出してください(むやみに画素数を上げても処理が重くなるだけで良い結果はえられません)。

お問い合わせ先

KXABarcodeReader Libraryについてのお問い合わせは、次の連絡先にお願いいたします。