English 한국어 日本語 Tiếng Việt

アプリケーション開発ガイド

目次

1. エントリーポイント

すべての関数プロトタイプは以下の通りです。

#ifdef WIN32
#define TS_ANPR_ENTRY extern "C" __declspec(dllexport) const char* WINAPI
#else
#define TS_ANPR_ENTRY extern "C" const char*
#endif

長文にならないよう、以下は TS_ANPR_ENTRY と表記します。

1.1. anpr_initialize

ライブラリを初期化します。 ライブラリを使用するために、他の関数よりも先に一度呼び出す必要があります。

TS_ANPR_ENTRY anpr_initialize(const char* mode); // [IN] ライブラリの動作モード設定

パラメータ:

戻り値:

1.2. anpr_read_file

画像ファイルから車両ナンバーを認識します。

TS_ANPR_ENTRY anpr_read_file(
  const char* imgFileName,  // [IN] 入力画像ファイル名
  const char* outputFormat, // [IN] 出力データ形式
  const char* options);     // [IN] 機能オプション

パラメータ:

戻り値:

1.3. anpr_read_pixels

読み込まれた画像のメモリバッファから車両ナンバーを認識します。 TS-ANPR v2.3.0からはエンコードされた画像バッファも入力可能です。

TS_ANPR_ENTRY anpr_read_pixels(
  const unsigned char* pixels,  // [IN] 画像ピクセルの開始アドレス
  const unsigned long width,    // [IN] 画像の横ピクセル数
  const unsigned long height,   // [IN] 画像の縦ピクセル数
  const long stride,            // [IN] 画像1ラインあたりのバイト数
  const char* pixelFormat,      // [IN] 画像ピクセルフォーマット
  const char* outputFormat,     // [IN] 出力データ形式
  const char* options);         // [IN] 機能オプション

パラメータ:

戻り値: (anpr_read_fileと同じ) 備考: (anpr_read_fileと同じ)

  # Python例

  # ビデオフレームを入力
  ret, frame = capture.read()
  height = frame.shape[0]
  width = frame.shape[1]
  result = anpr_read_pixels(bytes(frame), width, height, 0, b'BGR', b'json', b'vms')
  if len(result) > 0:
      print(result.decode('utf8'))

  # ウェブサイトの画像を入力
  response = requests.get('https://example.com/image.jpg')
  if response.status_code == 200:
      result = anpr_read_pixels(response.content, 0, 0, 0, b'encoded', b'json', b'vms')
      if len(result) > 0:
          print(result.decode('utf8'))

2. オプション

2.1. ライセンス別サポートオプション一覧

文字 意味 対応ライセンス
v ナンバープレートの車両装着有無判定 全て
b ナンバープレートのバイク装着有無判定（ベトナムナンバープレート専用） 全て
m 複数台の車両ナンバープレートを全て認識（マルチ認識） オブジェクト認識, Pro, Server
s 360° 全方位の車両からナンバープレート認識（サラウンド認識） オブジェクト認識, Pro, Server
d オブジェクト認識（満車・空車用） 全て
r 認識されたオブジェクト（車両）のナンバープレート認識 全て
i 関心領域（RoI）設定 全て
x 非関心領域（RoU）設定 全て
a 最小ナンバープレートサイズ設定 全て

2.2. オプション選択ガイド

以下のフローチャートで「開始」から「選択完了」まで条件に従って進み、通過した緑色の丸の文字をまとめてオプション値として使用します。（文字の順序は関係ありません。） 例）進行経路が「開始」→「v」→「s」→「m」→「選択完了」の場合、オプション値は "vsm" となります。

flowchart TD

  start[/開始/]-->attach
  attach-->|不問|multi
  attach-->|装着のみ|v((v)):::opt

  v-->angle
  angle-->|傾きなしのみ|multi
  angle-->|360° 傾き問わず|s((s)):::opt
  s-->multi
  multi-->|はい|m((m)):::opt
  multi-->|いいえ|done[/選択完了/]
  m-->done

  start-->d((d)):::opt
  d-->angle2
  angle2-->|傾きなしのみ|multi2
  angle2-->|360° 傾き問わず|s2((s)):::opt
  s2-->multi2
  multi2-->|はい|m2((m)):::opt
  multi2-->|いいえ|read
  m2-->read

  read-->|はい|r((r)):::opt
  read-->|いいえ|done
  r-->done


  subgraph "ナンバー認識"
    attach
    v
    angle
    multi
    m
    s
  end

  subgraph "オブジェクト認識"
    read
    angle2
    multi2
    s2
    m2
    d
    r
  end

  classDef opt fill:#6F6,stroke:#CCC,stroke-width:4px,padding:10px,font-weight:bold

2.3. 関心領域 (RoI) / 関心領域 (RoU) の設定

関心領域 (RoI)

非関心領域(RoU)

注意: 関心領域（RoI）および非関心領域（RoU）のいずれも指定しない場合、画像全体に対してナンバープレート認識が行われます。 関心領域と非関心領域の両方を指定し、それらに重複部分がある場合は、非関心領域が優先されます。そのため、重複部分にあるナンバープレートはすべて無視されます。

# Python例
# 上記画像の各多角形領域の各頂点ピクセル座標が以下の通りの場合:
# RoI = [(810,64), (939,1182), (1486,1182), (1149,571), (879,124), (839,64)]
# RoI2 = [(771,67), (479,1182), (1793,1182), (801,67)]
# RoU = [(851,70), (923,134), (1753,1182), (1789,1182), (1789,250), (1176,87), (946,68)]

# 関心領域（RoI）を一つ設定
result = anpr_read_file(
  b'roi.jpg',    # 入力ファイル名
  b'text',       # 出力形式
  b'vi810,64,939,1182,1486,1182,1149,571,879,124,839,64') # 車両に取り付けられたナンバープレートのみを認識するためにvオプションを使用

# 関心領域（RoI）を二つ設定
result = anpr_read_file(
  b'roi.jpg',    # 入力ファイル名
  b'text',       # 出力形式
  b'vi810,64,939,1182,1486,1182,1149,571,879,124,839,64i771,67,479,1182,1793,1182,801,67')

# 関心領域（RoI）一つと非関心領域（RoU）一つを設定
result = anpr_read_file(
  b'roi.jpg',    # 入力ファイル名
  b'text',       # 出力形式
  b'vi810,64,939,1182,1486,1182,1149,571,879,124,839,64x851,70,923,134,1753,1182,1789,1182,1789,250,1176,87,946,68')

# 非関心領域（RoU）を一つ設定
result = anpr_read_file(
  b'roi.jpg',    # 入力ファイル名
  b'text',       # 出力形式
  b'vx851,70,923,134,1753,1182,1789,1182,1789,250,1176,87,946,68')

2.4. 最小ナンバープレートサイズの設定

3. 出力フォーマット

出力データは、optionsに dが含まれるオブジェクト認識と、含まれない車両ナンバープレート認識の 2 つの形式に分かれます。

3.1. 車両ナンバープレート認識結果

3.1.1. text

車両ナンバープレートのテキストのみを出力します。 ナンバープレートが複数ある場合は、改行文字 CR (0x0d)で区切ります。

香川900さ464
札幌330ほ5419

ナンバープレートが認識されなかった場合は、空のテキスト(NULL terminated string (0x00))を出力します。

エラーが返される場合は、以下のようなテキスト形式で出力されます。

error: (1) Invalid parameters
3.1.2. csv

車両ナンバープレートおよび属性情報を csv 形式で出力します。 認識されたナンバープレートごとに 1 行ずつ出力され、各カラムはカンマ（,）で区切られます。

香川900さ464,1217,2083,92,175,12.45,0.75,0.83,0.20,ev
札幌330ほ5419,1108,1317,67,217,12.45,0.76,0.89,0.10,

各カラムの意味は以下の通りです。 | カラム | 意味 | 備考 |—–:|—————————|———————— | 1 | 車両ナンバー | text | 2 | ナンバープレート左上 x 座標 | area.x | 3 | ナンバープレート左上 y 座標 | area.y | 4 | ナンバープレート幅 | area.width | 5 | ナンバープレート高さ | area.height | 6 | ナンバープレート角度 | area.angle | 7 | 文字認識信頼度 | conf.ocr | 8 | ナンバープレート認識信頼度 | conf.plate | 9 | 文字認識所要時間（秒） | elapsed | 10(1) | 環境対応電気自動車かどうか | attr.ev

ナンバープレートが認識されなかった場合は、空のテキスト(NULL terminated string (0x00))を出力します。

エラーが返される場合は、以下のようなテキスト形式で出力されます。

error,1,Invalid parameters

3.1.3. json

車両ナンバープレートおよび属性情報を json 形式で出力します。

[
  {
    // 1枚目のナンバープレート
    text: "香川900さ464", // 車両ナンバー
    area: {
      // ナンバープレート領域（ピクセル単位）
      x: 1217, // 左上 x座標
      y: 2083, // 左上 y座標
      width: 92, // 幅
      height: 175, // 高さ
      angle: 12.45, // 傾き（度）
    },
    attrs: {
      // ナンバープレート属性
      ev: true, // 環境対応電気自動車かどうか
    },
    ev: true, // 非推奨（attrs.evに移行、将来のバージョンで削除予定）
    conf: {
      // 信頼度（範囲: 0 ~ 1）
      ocr: 0.75, // 文字認識信頼度
      plate: 0.84, // ナンバープレート認識信頼度
    },
    elapsed: 0.27, //  所要時間（秒単位）
  },
  {
    // 2枚目のナンバープレート
    text: "札幌330ほ5419",
    area: {
      x: 1108,
      y: 1317,
      width: 67,
      height: 217,
      angle: 12.45,
    },
    attrs: {
      ev: false,
    },
    ev: false,
    conf: {
      ocr: 0.76,
      plate: 0.89,
    },
    elapsed: 0.14,
  },
];

ナンバープレートが認識されなかった場合は、以下のように空データを出力します。

[];

エラーが返される場合は、以下のような json 形式で出力されます。

{
  "error": {
    "code": 1,
    "message": "Invalid parameters"
  }
}

3.1.4. yaml

車両ナンバープレートおよび属性情報を yaml 形式で出力します。

- text: 香川900さ464 # 1枚目のナンバープレート、車両ナンバー
  area: # ナンバープレート領域（ピクセル単位）
    x: 1217 # 左上 x座標
    y: 2083 # 左上 x座標
    width: 92 # 幅
    height: 175 # 高さ
    angle: 12.45 # 傾き（度）
  conf: # 信頼度（範囲: 0 ~ 1）
    ocr: 0.75 # 文字認識信頼度
    plate: 0.83 # ナンバープレート認識信頼度
  attrs: # ナンバープレート属性
    ev: true # 環境対応電気自動車かどうか
  ev: true # 非推奨（attrs.evに移行、将来のバージョンで削除予定）
  elapsed: 0.20 # 所要時間（秒）
- text: 札幌330ほ5419 # 2枚目のナンバープレート
  area:
    x: 1108
    y: 1317
    width: 67
    height: 217
    angle: 12.45
  conf:
    ocr: 0.76
    plate: 0.89
  ev: false
  elapsed: 0.10

ナンバープレートが認識されなかった場合は、以下のように空データを出力します。

エラーが返される場合は、以下のような yaml 形式で出力されます。

error
  code: 1
  message: Invalid parameters

3.1.5. xml

車両ナンバープレートおよび属性情報を xml 形式で出力します。

<?xml version="1.0" encoding="utf-8"?>
<data>
  <!-- 1枚目のナンバープレート
    text: 車両ナンバー
    ev: 非推奨（attrs.evに移行、将来のバージョンで削除予定）
    elapsed: 所要時間（秒）
  -->
  <license-plate text="香川900さ464" ev="true" elapsed="0.20">
    <!-- ナンバープレート属性
      ev: 環境対応電気自動車かどうか
    -->
    <attrs ev="true"/>
    <!-- ナンバープレート領域（ピクセル単位）
      x: 左上 x座標
      y: 左上 y座標
      width: 幅
      height: 高さ
      angle: 傾き（度）
    -->
    <area x="1217" y="2083" width="92" height="175" angle="12.45"/>
    <!-- 信頼度（範囲: 0 ~ 1）
      ocr: 文字認識信頼度
      plate: ナンバープレート認識信頼度
    -->
    <conf ocr="0.75" plate="0.83"/>
  </license-plate>
  <!-- 2枚目のナンバープレート -->
  <license-plate text="札幌330ほ5419" ev="false" elapsed="0.11">
    <attrs ev="false"/>
    <area x="1108" y="1317" width="67" height="217"/>
    <conf ocr="0.76" plate="0.89"/>
  </license-plate>
</data>

ナンバープレートが認識されなかった場合は、以下のように空データを出力します。

<?xml version="1.0" encoding="utf-8"?>
<data />

エラーが返される場合は、以下のような xml 形式で出力されます。

<?xml version="1.0" encoding="utf-8"?>
<error code="1" message="Invalid parameters" />

3.2. オブジェクト認識結果

画像から事前に学習したオブジェクトを検出します。 特徴的なのは、360° 魚眼レンズカメラで撮影された元画像において、歪んだ形状のオブジェクトも認識できる点です。 現在サポートしているオブジェクトの一覧は以下の通りです。 | class | 名前
|————–|———————————- | car | 車両 | motorcycle | オートバイ

3.2.1. csv, text

オブジェクト認識結果を cvs 形式のテキストで出力します。 出力形式を textに指定した場合も、csv 形式で出力されます。

認識されたオブジェクトごとに 1 行ずつ出力され、各カラムはカンマ（,）で区切られます。

car,2171,2281,396,521,0.9679,0.2886,山梨88せ5059,2420,2295,110,81,147.5933,0.9005,0.7864,0.3913,ev
car,264,2266,433,543,0.9706,0.2886,京都11に211,315,2281,103,81,211.3135,0.9160,0.8299,0.4189,
car,777,0,579,403,0.9716,0.2886 // ナンバープレート情報がない場合

各カラムの意味は以下の通りです。 | カラム | 意味 | 備考 |—–:|———————————–|———————— | 1 | 種類 | class | 2 | オブジェクト左上 x 座標 | area.x | 3 | オブジェクト左上 y 座標 | area.y | 4 | 幅 | area.width | 5 | 高さ | area.height | 6 | 信頼度 | conf | 7 | 所要時間（秒） | elapsed | 8(1) | 車両ナンバー | licensePlate.text | 9 | ナンバープレート x 座標 | licensePlate.area.x | 10 | ナンバープレート y 座標 | licensePlate.area.y | 11 | ナンバープレート幅 | licensePlate.area.width | 12 | ナンバープレート高さ | licensePlate.area.height | 13 | ナンバープレート角度 | licensePlate.area.angle | 14 | 文字認識信頼度 | licensePlate.conf.ocr | 15 | ナンバープレート認識信頼度 | licensePlate.conf.plate | 16 | 文字認識所要時間（秒）| licensePlate.elapsed | 17(2) | 環境対応電気自動車かどうか | licensePlate.attrs.ev

オブジェクトが認識されなかった場合は、空のテキスト(NULL terminated string (0x00))を出力します。

エラーが返される場合は、以下のようなテキスト形式で出力されます。

error,1,Invalid parameters
3.2.2. json

オブジェクト認識結果を json 形式で出力します。

 [
  {                           // 1つ目のオブジェクト
    "class": "car",           // オブジェクト種別
    "area": {                 // オブジェクト領域（ピクセル単位）
      "x": 2171,              // 左上 x座標
      "y": 2281,              // 左上 y座標
      "width": 396,           // 幅
      "height": 521           // 高さ
    },
    "conf": 0.9679,           // オブジェクト認識信頼度（範囲: 0 ~ 1）
    "elapsed": 0.2513,        // 所要時間（秒）
    "licensePlate": [         // ナンバープレート
      {
        "text": "山梨88せ5059"    // 車両ナンバー
        "area": {             // ナンバープレート領域（ピクセル単位）
          "x": 2420,          // 左上 x座標
          "y": 2295           // 左上 y座標
          "width": 110,       // 幅
          "height": 81,       // 高さ
          "angle": 147.5933   // 傾き（度）
        },
        "attrs": {            // ナンバープレート属性
          "ev": true          // 環境対応電気自動車かどうか
        },
        "conf": {             // 信頼度（範囲: 0 ~ 1）
          "ocr": 0.9005,      // 文字認識信頼度
          "plate": 0.7864     // ナンバープレート認識信頼度
        },
        "elapsed": 0.3525,    // 所要時間（秒）
      }
    ]
  },
  {                           // 2つ目のオブジェクト
    "class": "car",
    "area": {
      "x": 264,
      "y": 2266,
      "width": 433,
      "height": 543
    },
    "conf": 0.9706,
    "elapsed": 0.2513,
    "licensePlate": [
      {
        "text": "京都11に211"
        "area": {
          "x": 315,
          "y": 2281,
          "width": 103,
          "height": 81,
          "angle": 211.3135
        },
        "attrs": {
          "ev": false
        },
        "conf": {
          "ocr": 0.916,
          "plate": 0.8299
        },
        "elapsed": 0.4402
      }
    ]
  },
  {                           // 3つ目のオブジェクト（ナンバープレート情報がない場合）
    "class": "car",
    "area": {
      "x": 777,
      "y": 0
      "height": 403,
      "width": 579,
    },
    "conf": 0.9716,
    "elapsed": 0.2513
  }
]

オブジェクトが認識されなかった場合は、以下のように空データを出力します。

[];

エラーが返される場合は、以下のような json 形式で出力されます。

{
  "error": {
    "code": 1,
    "message": "Invalid parameters"
  }
}
3.2.3. yaml

オブジェクト認識結果を yaml 形式で出力します。

- class: car # 1つ目のオブジェクト、オブジェクト種別
  area: # オブジェクト領域（ピクセル単位）
    x: 2171 # 左上 x座標
    y: 2281 # 左上 y座標
    width: 396 # 幅
    height: 521 # 高さ
  conf: 0.9678 # オブジェクト認識信頼度（範囲: 0 ~ 1）
  elapsed: 0.3190 # 所要時間（秒）
  licensePlate: # ナンバープレート
    - text: 山梨88せ5059 # 車両ナンバー
      area: # ナンバープレート領域（ピクセル単位）
        x: 2420 # 左上 x座標
        y: 2295 # 左上 y座標
        width: 110 # 幅
        height: 81 # 高さ
        angle: 147.5933 # 傾き（度）
      attrs: # ナンバープレート属性
        ev: true # 環境対応電気自動車かどうか
      conf: # 信頼度（範囲: 0 ~ 1）
        ocr: 0.9005 # 文字認識信頼度
        plate: 0.7864 # ナンバープレート認識信頼度
      elapsed: 0.3226 # 所要時間（秒）
- class: car # 2つ目のオブジェクト
  area:
    x: 264
    y: 2266
    width: 433
    height: 543
  conf: 0.9706
  elapsed: 0.3191
  licensePlate:
    - text: 京都11に211
      area:
        x: 315
        y: 2281
        width: 103
        height: 81
        angle: 211.3135
      conf:
        ocr: 0.916
        plate: 0.8299
      attrs:
        ev: false
      elapsed: 0.5527
- class: car # 3つ目のオブジェクト（ナンバープレート情報がない場合）
  area:
    x: 777
    y: 0
    width: 579
    height: 403
  conf: 0.9716
  elapsed: 0.3191

オブジェクトが認識されなかった場合は、以下のように空データを出力します。

エラーが返される場合は、以下のような yaml 形式で出力されます。

error
  code: 1
  message: Invalid parameters
3.2.4. xml

オブジェクト認識結果を xml 形式で出力します。

<?xml version="1.0" encoding="utf-8"?>
<data>
  <!-- 1つ目のオブジェクト
    class: オブジェクト種別
    conf: オブジェクト認識信頼度（範囲: 0 ~ 1）
    elapsed: 所要時間（秒）
  -->
  <object class="car" conf="0.9679" elapsed="0.3287">
    <!-- オブジェクト領域（ピクセル単位）
      x: 左上 x座標
      y: 左上 y座標
      width: 幅
      height: 高さ
    -->
    <area x="2171" y="2281" width="396" height="521"/>

    <!-- ナンバープレート
      text: 車両ナンバー
      elapsed: 所要時間（秒）
    -->
    <license-plate text="山梨88せ5059" elapsed="0.3961">

      <!-- ナンバープレート属性
        ev: 環境対応電気自動車かどうか
      -->
      <attrs ev="true"/>

      <!-- ナンバープレート領域（ピクセル単位）
        x: 左上 x座標
        y: 左上 y座標
        width: 幅
        height: 高さ
        angle: 傾き（度）
      -->
      <area x="2420" y="2295" width="110" height="81" angle="147.5933"/>

      <!-- 信頼度（範囲: 0 ~ 1）
        ocr: 文字認識信頼度
        plate: ナンバープレート認識信頼度
      -->
      <conf ocr="0.9005" plate="0.7864"/>
    </license-plate>
  </object>

  <!-- 2つ目のオブジェクト -->
  <object class="car" conf="0.9706" elapsed="0.3287">
    <area x="264" y="2266" width="433" height="543"/>
    <license-plate text="京都11に211" elapsed="0.4364">
      <attrs ev="false"/>
      <area x="315" y="2281" width="103" height="81" angle="211.3135"/>
      <conf ocr="0.9160" plate="0.8299"/>
    </license-plate>
  </object>

  <!-- 3つ目のオブジェクト（ナンバープレート情報がない場合） -->
  <object class="car" conf="0.9716" elapsed="0.3287">
    <area x="777" y="0" width="579" height="403"/>
  </object>
</data>

オブジェクトが認識されなかった場合は、以下のように空データを出力します。

<?xml version="1.0" encoding="utf-8"?>
<data />

エラーが返される場合は、以下のような xml 形式で出力されます。

<?xml version="1.0" encoding="utf-8"?>
<error code="1" message="Invalid parameters" />

4. エラーコード表

全エラー一覧は以下の表の通りです。

code message 説明
1 Invalid parameters 関数呼び出しの引数が正しくない場合
2 File not found 入力画像ファイルが存在しない場合
3 Invalid image 入力画像メモリが形式に合っていない場合
4 Unsupported image format 入力画像がサポートされていない形式の場合
100 License expired ライセンスが期限切れの場合
101 Corrupted library ライブラリ構成ファイルの一部が存在しないか、破損している場合
102 Not initialized エンジンが初期化されていない状態
103 Too many workers ライブラリ呼び出しスレッド数が上限（最大 256 個）を超えた場合
104 Resource exhausted これ以上リソースを割り当てできない場合
105 License not installed ライセンスがインストールされていない状態（無料トライアルライセンスがインストールされていない場合に発生）
106 USB dongle I/O error USB ライセンスドングルの読み取りに失敗した場合
107 License required 該当機能を利用するためのライセンスがない場合
108 Unsupported platform サポートされていない環境で実行された場合
200 Unknown その他の未定義エラー