TableKit

T-Plan Robot Enterprise用 Table Kitプラグイン

目次:

1. 概要
2. プラグインのインストール
3. 使用方法
3.1 GetTablesスクリプト
3.2 GetCellスクリプト
3.3 FindCellスクリプト
3.4 ExportTableスクリプト
4. 変更履歴

1. 概要

Table Kitプラグインは、画面のグラフィカルな解析によって表(テーブル)を検出します。具体的には次のことを行います:

• 表とそのプロパティ(行数・列数、セル数、位置、幅と高さ)の認識

• セルのプロパティ(範囲、色、テキスト)の取得

• Tesseract OCRエンジンを使用した、個々のテーブルセルからのテキストの任意の取得

このプラグインは主に TPR言語で書かれたテストスクリプト向けに設計されています。Javaからプラグインスクリプトを呼び出すには、 DefaultJavaTestScript.run() メソッドを使用するか、 Java Test Script Basics 文書に記載されているスクリプトインスタンス方式を使用してください。

テーブル認識アルゴリズムにはいくつかの制限事項があります。ご利用の前にご確認ください。

1. すべてのセルは単色の背景を持ち、別の色のグリッド線(境界線)で区切られている必要があります。

   

2. セルの内容(テキスト)とその境界線の間には、少なくとも1ピクセルの距離(パディング)が必要です。つまり、テキストが境界線に接してはいけません。

   

3. アルゴリズムがセルの集合が表を構成しているかどうかを評価する際、同じサイズのセルで構成された規則的な表を優先します。このため、複数の標準セルにまたがる結合セルが、別の表として認識されてしまうことがあります。

ご質問やご提案がございましたら、 T-Planサポートまでご連絡ください。T-Planが提供するその他のプラグインの一覧は こちらをご覧ください。

2. プラグインのインストール

プラグインをインストールするには、以下の場所から適切なアーカイブをダウンロードしてください:

• バージョン0.8(T-Plan Robot 7以降): https://downloads.t-plan.com/releases/robot/plugins/tablekit_v0.8.zip

• バージョン0.7(T-Plan Robot 4.1.1以降): https://downloads.t-plan.com/releases/robot/plugins/tablekit_v0.7.zip

• バージョン0.5(T-Plan Robot 3.5.2 - 4.1): https://downloads.t-plan.com/releases/robot/plugins/tablekit_v0.5.zip

バージョン間の違いについては 変更履歴を参照してください。

オプション1:

1. ファイルをハードドライブ上の任意の場所に解凍します。

2. tablekit.jarファイルをRobot起動コマンドのクラスパスに追加します。詳細はRobotの リリースノートを参照してください。

3. Robotを起動または再起動します。テストスクリプトがRobotに公開されます。TPRスクリプトでRunコマンドを作成すると、プロパティウィンドウにプラグインスクリプトが一覧表示されます。

オプション2(Macアプリでは使用不可):

1. ファイルをRobotインストールディレクトリ配下のplugins/ディレクトリに解凍します。これによりRobotは起動時にクラスをロードするようになります。プラグインの古いバージョンが残っていないことを確認してください。
   重要: Macアプリを実行している場合はこれを行わないでください。アプリの署名が無効になってしまいます。代わりにオプション3を使用してください。

2. Robotを起動または再起動します。テストスクリプトがRobotに公開されます。TPRスクリプトでRunコマンドを作成すると、プロパティウィンドウにプラグインスクリプトが一覧表示されます。また、このプラグインはテーブルビューアを、Robot GUIの[プラグイン]メニューに追加します:
   
   

オプション3:

注: このオプションでは、テーブルビューアはメニューにインストールされません。ただし、ビューアはプロパティ ウィンドウのGetTablesスクリプトから利用できます。ビューアのスクリーンショットは、以下の使用方法の章を参照してください。

1. ファイルをハードドライブ上の任意の場所に解凍します。

2. TPRスクリプトでプラグインを使用する場合は、各テストスクリプトの先頭に以下のコマンドを記述してください:
   Include "<location>/tablekit.jar"

3. Javaテストスクリプトでプラグインを使用する場合は、tablekit.jarファイルをJavaのクラスパスに置いてください(オプション1を参照)。

プラグインをアンインストールするには、ファイルを削除し、必要に応じてIncludeの参照も削除してください。

3. 使用方法

このプラグインには3つのJavaテストスクリプトが含まれています:

プラグインスクリプトは、Runコマンドを使用してTPRテストスクリプトから呼び出します。コマンドのインスタンスはコマンドウィザードツールを使って簡単に作成できます。既存のRunコマンドを編集するには、右クリックしてコンテキストメニューの[プロパティ]を選択してください。GetTablesスクリプトにはテーブルビューアも用意されています:
典型的な使用例をいくつか示します:

例1:

表を認識し、2行目・3列目のセルのテキストをTEXTという名前の変数に保存します:

// Presume that tablekit.jar is in the script folder 
Include "tablekit.jar" 

// Recognize table(s) on the screen 
Run "com.tplan.table.GetTables" 
if ({_EXIT_CODE} > 0) { 
    Exit 1 desc="No tables were found." 
} 


// Get details of the cell at row=2 and column=3 and perform OCR 
Run "com.tplan.table.GetCell" row="2" column="3" tocr="true" 
if ({_EXIT_CODE} > 0) { 
    Exit 2 desc="Failed to retrieve cell at [2,3]. See the log for details." 
} 

// Save the cell text to the TEXT variable 
Var TEXT= "{_TABLE_CELL_TEXT}"

例2:

[行, 列] = [3,5] のセルをクリックします。

// Recognize table(s) on the screen 
Run "com.tplan.table.GetTables" 
if ({_EXIT_CODE} > 0) { 
    Exit 1 desc="No tables were found." 
} 

// Get coordinates of the cell at [3,5] 
Run "com.tplan.table.GetCell" row="3" column="5" 
if ({_EXIT_CODE} > 0) { 
    Exit 2 desc="Failed to retrieve cell at [3,5]. See the log for details." 
} 

// Click at the cell coordinates plus 5 pixels in each direction 
Mouse click to="x:{_TABLE_CELL_X}+5,y:{_TABLE_CELL_Y}+5"

例3:

最初の列のセルがすべて同じ色かどうかを確認し、SAMECOLOR変数をtrueまたはfalseに設定します。

// Declare the _TABLE1_ROWS variable to suppress compiler warnings in for() 
Var _TABLE1_ROWS =0 

// Recognize table(s) on the screen 
Run "com.tplan.table.GetTables" 
if ({_EXIT_CODE} > 0) { 
    Exit 1 desc="No tables were found." 
} 

// Get color of the first cell 
Run "com.tplan.table.GetCell" 
if ({_EXIT_CODE} > 0) { 
    Exit 2 desc="Failed to retrieve cell at [1,1]. See the log for details." 
} 
Var COLOR ={_TABLE_CELL_COLOR} 

// Iterate over the rest of cells in the first column and test 
// whether their color is the same 
Var SAMECOLOR =true 
for (i=2; {i}<{_TABLE1_ROWS}+1; i={i}+1) { 
    Run "com.tplan.table.GetCell" row={i} column=1 
    if ("{_TABLE_CELL_COLOR}" != "{COLOR}") { 
        // Not the same color 
        Var SAMECOLOR =false 
        break 
    } 
}

例4:

表を認識し、MS Excelファイルに保存します。

// Recognize tables and perform OCR to retrieve text of all cells 
Run "com.tplan.table.GetTables" tocr="true"
if ({_EXIT_CODE} > 0) { 
    Exit 1 desc="No tables were found." 
} 

// Export the tables to MS Excel 
Run "com.tplan.table.ExportTable" file="C:\test.xlsx"

例5:

"Price:"というラベルの付いたセルを検索し、その隣のセルから値を読み取ります。

// Recognize tables and perform OCR to retrieve text of all cells 
Run "com.tplan.table.GetTables" tocr="true"
if ({_EXIT_CODE} > 0) { 
    Exit 1 desc="No tables were found." 
} 

// Find a cell labeled "Price:" 
Run "com.tplan.table.FindCell" text="Price:"
if ({_EXIT_CODE} > 0) { 
    Exit 2 desc="The 'Price:' cell was not found" 
}

// Use variables produced by FindCell to get value in the cell in the next column.
Run "com.tplan.table.GetCell" table="{_TABLE_CELL_TABLE}" row="{_TABLE_CELL_ROW}" column="{_TABLE_CELL_COL}+1"

// Log the cell value.
Log "The price is: {_TABLE_CELL_TEXT}"

3.1 GetTablesスクリプト

説明

com.tplan.table.GetTablesスクリプトは、表を検出するために画面を解析します。検出された表の基本データは、以下の変数を通じて公開されます:

注: scaleパラメータはv0.5以降で廃止されました。以前のリリースとの互換性を保つためコマンドラインでは受け付けますが、値は無視されます。コマンドは最適な拡大率を自動的に判定します。

構文(TPRスクリプト)

Run com.tplan.table.GetTables [cw=<width_in_pixels>] [ch=<height_in_pixels>] [minrows=<number>] [mincols=<number>] [spacing=<spacing_in_pixels>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]] [tocr=<true|false>] [language=<3-char_lang_code>] [fixocr=<true|false>]

構文(Javaスクリプト)

run("com.tplan.table.GetTables" [, "cw", "<pixels>"] [, "ch", "<pixels>"] [, "minrows", "<number>"] [, "mincols", "<number>"] [, "spacing", "<pixels>"] [, "cmparea", "[x:<x>][,y:<y>][,w:<width>][,h:<height>]"] [, "tocr", < "false" | "true" >] [, "language", "<lang_code>"] [, "fixocr", < "false" | "true" >] );

※ 赤色は必須パラメータを示します

オプション

cw=<pixels>

- 最小セル幅(ピクセル単位)。デフォルトは15です。

ch=<pixels>

- 最小セル高さ(ピクセル単位)。デフォルトは10です。

minrows=<number>

- 表の最小行数です。この条件を満たさない表は除外されます。デフォルトは2行です。

mincols=<number>

- 表の最小列数です。この条件を満たさない表は除外されます。デフォルトは2列です。

spacing=<spacing>

- 隣接する2つのセル間の最大間隔(グリッドの太さ)です。デフォルトは4ピクセルです。

cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]

- 表の認識を限定するデスクトップの矩形領域です。構文と機能はcmpareaパラメータと同じです。これは CompareTo コマンドのパラメータです。このパラメータを省略した場合、リモートデスクトップ全体が処理対象になります。領域の座標は 'x:<x>,y:<y>,w:<width>,h:<height>' の形式で指定し、各座標はピクセル(例: "x:225")またはパーセント("x:23%")で指定できます。 x、y、width、heightのいずれかが省略された場合、T-Plan Robotは画面全体の値を使用して不足しているパラメータを決定します(x:0, y:0, w:<画面幅>, h:<画面高さ>)。例えば、"cmparea=y:50%,height:50%" は画面の下半分を処理します。

tocr=<true|false>

- "true" を指定すると、認識された各セルに対してTesseract OCRを実行し、テキストを取得します。取得したテキストは GetCell スクリプトの呼び出しで取得できます。このパラメータのデフォルトはfalse(OCRを実行しない)です。 警告: このOCRモードは、特に大きな表では時間がかかることがあります。すべてのセルのテキストを反復処理する場合や表をファイルにエクスポートする場合にのみ適しています。単一または少数のセルのテキストのみが必要な場合は、GetTablesでのOCRを省略し、tocrパラメータを使用して GetCellで単一セルのOCRを実行する方が効率的です。

language=<lang_code>

- 正しくインストールされたTesseract言語データファイルの、有効な3文字の言語コードです。このパラメータは、OCRが有効な場合(tocr=true)にのみ使用されます。省略した場合のデフォルトは"eng"(英語)です。詳細は Tesseract OCR の比較メソッドを参照してください。

fixocr=<true|false>

- "true" を指定すると、既知のTesseract OCR精度エラーの一部を修正しようと試みます。例:

• 
  

  • 数値中の余分なスペース("3.14"が"3. 14"になる)

  • セルの値が数値であるべき箇所で数字が文字と誤認識される、例えばゼロの数字'0'の代わりに大文字の'O'が認識される("2.05"が"2.O5"になる)

  • 日付の値でスラッシュが別の文字と誤認識される("29/10/2013"が"29|10|2013"になる)

デフォルト値はtrue(修正する)です。製品コード、特殊文字と数字の並びなど、数値や日付に似ているが修正すべきでない文字列をコマンドが修正してしまう場合は、この設定をオフにしてください。

戻り値

このコマンドは、少なくとも1つの表が見つかりエラーが発生しなかった場合は0(ゼロ)を返します。表が1つも認識されなかった場合は1(1)を、I/Oエラー(通常はTesseractが未インストールまたは設定不備)によりOCRの実行に失敗した場合は2(2)を返します。失敗は 実行ログにも記録されます。

使用例

使用方法 の章を参照してください。

3.2 GetCellスクリプト

説明

com.tplan.table.GetCellスクリプトは、以前に GetTablesで認識されたテーブルセルのプロパティを取得します。データは変数の形でスクリプトに公開されます:

注: scaleパラメータはv0.5以降で廃止されました。以前のリリースとの互換性を保つためコマンドラインでは受け付けますが、値は無視されます。コマンドは最適な拡大率を自動的に判定します。

構文(TPRスクリプト)

Run com.tplan.table.GetCell [row=<number>] [column=<number>] [table=<number>] [tocr=<true|false>] [language=<3-char_lang_code>] [fixocr=<true|false>]

構文(Javaスクリプト)

run("com.tplan.table.GetCell" [, "row", "<number>"] [, "column", "<number>"] [, "table", "<number>"] [, "tocr", < "false" | "true" >] [, "language", "<lang_code>"] [, "fixocr", < "false" | "true" >] );

※ 赤色は必須パラメータを示します

オプション

row=<number>

- セルの行番号です。省略した場合は最初の行(1)がデフォルトになります。

column=<number>

- セルの列番号です。省略した場合は最初の列(1)がデフォルトになります。

table=<number>

- 表の番号です。これは GetTables が複数の表を認識した場合にのみ意味を持ちます。省略した場合は最初の表(1)がデフォルトになります。

tocr=<true|false>

- "true" を指定すると、セルが空(単色)でない限りTesseract OCRを実行してセルのテキストを取得します。このパラメータのデフォルトはfalse(OCRを実行しない)です。

language=<lang_code>

- 正しくインストールされたTesseract言語データファイルの、有効な3文字の言語コードです。このパラメータは、OCRが有効な場合(tocr=true)にのみ使用されます。省略した場合のデフォルトは"eng"(英語)です。詳細は Tesseract OCR の比較メソッドを参照してください。

fixocr=<true|false>

- "true" を指定すると、既知のTesseract OCR精度エラーの一部を修正しようと試みます。例:

• 
  

  • 数値中の余分なスペース("3.14"が"3. 14"になる)

  • セルの値が数値であるべき箇所で数字が文字と誤認識される、例えばゼロの数字'0'の代わりに大文字の'O'が認識される("2.05"が"2.O5"になる)

  • 日付の値でスラッシュが別の文字と誤認識される("29/10/2013"が"29|10|2013"になる)

デフォルト値はtrue(修正する)です。製品コード、特殊文字と数字の並びなど、数値や日付に似ているが修正すべきでない文字列をコマンドが修正してしまう場合は、この設定をオフにしてください。

戻り値

このコマンドは、成功した場合は0(ゼロ)を返します。失敗した場合は、セルが利用できないときは1(1)を、I/Oエラー(通常はTesseractが未インストールまたは設定不備)によりOCRの実行に失敗したときは2(2)を返します。 失敗は 実行ログにも記録されます。

使用例

の使用方法の章を参照してください。

3.2 FindCellスクリプト

説明

com.tplan.table.FindCellスクリプトは、以前に GetTablesで認識された1つまたは複数の表から、テキストによりセルを検索します。v0.8以降でサポートされています。

検索は、完全一致("text"パラメータ)または正規表現("pattern")で行うことができます。"tables"、"columns"、"rows"のいずれかで範囲を限定しない限り、すべての表とセルが対象になります。これらのパラメータはいずれも、単一の数値またはカンマ区切りの数値リストを受け付けます。

このスクリプトはセルのテキストを扱うため、OCRのセットアップと動作が必要です。例えば"tocr=true"パラメータでGetTablesを実行するなどして、テキストが既に認識されている場合は、OCRパラメータの指定有無に関わらずそのテキストをそのまま使用します。テキストがまだ取得されていない場合は、その場でOCRを実行します。これを利用してスクリプトのパフォーマンスを改善できます。例えば、画面上に大きな表があり、最初の列にある"Total:"というセルだけを探したいとします。GetTablesで全体をOCRするのは時間のかかる処理になり得ます。これを省略し、検索範囲を最初の列("column=1")に限定してFindCellスクリプトにOCRを任せることができます。

見つかったセルのデータは、変数の形でスクリプトに公開されます:

構文(TPRスクリプト)

Run com.tplan.table.FindCell [text=<text>] [pattern=<regular_expression>] [rows=<numbers>] [columns=<numbers>] [tables=<numbers>] [language=<3-char_lang_code>] [fixocr=<true|false>]

構文(Javaスクリプト)

run("com.tplan.table.FindCell", "text"|"pattern", "text_or_regular_expression" [, "rows", "<number(s)>"] [, "columns", "<number(s)>"] [, "tables", "<number(s)>"] [, "language", "<lang_code>"] [, "fixocr", < "false" | "true" >] );

※ 赤色は必須パラメータを示します。"text"または"pattern"のいずれかを指定する必要があります。

オプション

text=<text>

- 検索する完全一致のセルテキストです。

pattern=<regular_expression>

- java.util.regex.Pattern準拠の正規表現で、セルのテキストと照合します。例えば、"Price"で始まるセルを探すには "Price.*" という式を使用します。

tables=<number(s)>

- 検索対象を限定する表番号、またはカンマ区切りの表番号リストです。このパラメータを省略した場合、すべての表を対象に検索が行われます。

rows=<number(s)>

- 検索対象を限定する行番号、またはカンマ区切りの行番号リストです。このパラメータを省略した場合、すべての行を対象に検索が行われます。

columns=<number(s)>

- 検索対象を限定する列番号、またはカンマ区切りの列番号リストです。このパラメータを省略した場合、すべての列を対象に検索が行われます。

language=<lang_code>

- 正しくインストールされたTesseract言語データファイルの、有効な3文字の言語コードです。このパラメータは、セルのテキストがまだOCRによって認識されていない場合にのみ使用されます。省略した場合のデフォルトは"eng"(英語)です。詳細は Tesseract OCR の比較メソッドを参照してください。

fixocr=<true|false>

- "true" を指定すると、既知のTesseract OCR精度エラーの一部を修正しようと試みます。例:

• 
  

  • 数値中の余分なスペース("3.14"が"3. 14"になる)

  • セルの値が数値であるべき箇所で数字が文字と誤認識される、例えばゼロの数字'0'の代わりに大文字の'O'が認識される("2.05"が"2.O5"になる)

  • 日付の値でスラッシュが別の文字と誤認識される("29/10/2013"が"29|10|2013"になる)

デフォルト値はtrue(修正する)です。製品コード、特殊文字と数字の並びなど、数値や日付に似ているが修正すべきでない文字列をコマンドが修正してしまう場合は、この設定をオフにしてください。

戻り値

このコマンドは、少なくとも1つのセルが見つかった場合は0(ゼロ)を返します。失敗した場合は、セルが1つも見つからないときは1(1)を、I/Oエラーによる OCR実行の失敗、または入力パラメータがGetTablesの結果と一致しないときは2(2)を返します。 失敗は 実行ログにも記録されます。

使用例

の使用方法の章を参照してください。

3.4 ExportTableスクリプト

説明

com.tplan.table.ExportTableスクリプトは、以前に GetTables で認識された表を、テキスト、CSVまたはMS Excelファイルにエクスポートします。形式はファイルの拡張子から判定されます:

.txt - テキストファイル

• 
  

  • セルはタブ(\t)で区切られます

  • 行は改行(\n)で区切られます

  • 表は2行の空行で区切られます。

.csv - CSVファイル

• このファイルは IETF RFC 4180 準拠です。

• 表は2行の空行で区切られます。

.xls, .xlsx - MS Excel。サポートされている形式はMicrosoft Excel 97/2000/XP(.xls)、およびMS Excel 2007 XMLドキュメント(.xlsx)です。

• 1つの表につき1つのシートが作成されます。各シートには表の番号("1"、"2"、...)が名前として付けられます。

• 表はシート左上隅("A1"セル)から始まります。黒の実線で囲まれます。

• セルには、OCRが実行されている場合に認識されたテキストが含まれます。それ以外のセル属性(色、テキストの配置、フォントサイズ・スタイルなど)はExcelの表には適用されません。この点で追加の機能が必要な場合は、T-Planサポートにお問い合わせください。

ファイルに拡張子がない、または認識されない拡張子の場合、スクリプトはファイル名に.xlsを付加し、Microsoft Excel 97/2000/XPをデフォルトとして使用します。 ファイルにすべてのセルのテキストを含めるには、OCRを有効にして GetTables スクリプトを実行してください(tocr=true)。表を認識してMS Excelファイルに保存する典型的なコマンドの流れは次のとおりです:

// Recognize tables and perform OCR to retrieve text of all cells
Run "com.tplan.table.GetTables" tocr="true"
if ({_EXIT_CODE} > 0) {
Exit 1 desc="No tables were found."
}

// Export the tables to MS Excel
Run "com.tplan.table.ExportTable" file="C:\test.xlsx"

構文(TPRスクリプト)

Run com.tplan.table.ExportTable [file=<target_file>] [tables=<number(s)>]

構文(Javaスクリプト)

run("com.tplan.table.ExportTable", "file", "<target_file>" [, "tables", "<number(s)>"]);

※ 赤色は必須パラメータを示します

オプション

file=<target_file>

- 表の保存先ファイルです(必須)。形式は拡張子(.txt、.csv、.xlsまたは.xlsx)から判定されます。認識可能な拡張子がない場合、スクリプトはMicrosoft Excel 97/2000/XP(.xls)形式をデフォルトとし、ファイル名に.xls拡張子を付加します。 指定するファイルは絶対パスまたは相対パスで指定できます。相対パスはユーザーのホームフォルダを基準に解決されます。

tables=<number(s)>

- 表の番号、またはセミコロンかカンマ区切りの表番号リストです(任意)。省略した場合、直前の GetTables 呼び出しで認識されたすべての表がエクスポートされます。

戻り値

このコマンドは、成功した場合は0(ゼロ)を返します。I/Oエラーが発生した場合、または表のリストが不正な場合は1(1)を返します。失敗は実行ログにも記録されます。

使用例

の使用方法の章を参照してください。

4. 変更履歴

バージョン0.8(2024年4月26日リリース)

1. v0.7では、水平線と垂直線の始点・終点座標を厳密に一致させて判定していました。このため、セルの角の1か所以上に異なる色のピクセルがあるテーブルセルを検出できませんでした。この判定は許容範囲のある方式(±1ピクセル)に変更されました。

2. TableKitビューアから実行するとTesseract OCRがNullPointerExceptionで失敗する問題がありました。これはRobot側のTesseract OCRモジュールの変更が原因でした。TableKitのコードを更新し、すべての最近のRobotバージョンと後方互換になるようにしました。

3. Excelへのエクスポートを修正しました。以前はRobot 5.xで最後に同梱していたレガシーなPOIライブラリに依存していたため失敗していました。

4. TableKitビューアのデザインを刷新しました。パラメータはツールバーから左下のパネルに移動しました。"tolerance"パラメータが追加されました。ツールバーには新たに2つのボタン、「ズームイン」と「ズームアウト」が追加されました。

5. FindCellという新しいスクリプトが導入されました。

6. GetCellの"row"、"table"、"column"パラメータは、コンパイル時にまだ存在しない変数を使った呼び出しをサポートするため、STRING型として再定義されました。

バージョン0.7(2018年6月14日リリース)

1. 独自のコンテンツが原因で1つ以上の列の認識に失敗するケースの精度を改善するため、表認識ロジックを更新しました

2. ビューアの軽微な機能改善

バージョン0.6(2016年11月15日リリース)

Robot 4.1.1以降向けの新バージョン(0.5バージョンはRobotフレームワークの変更により、ローカルデスクトップ接続でビューアを開くことができません)

バージョン0.5(2014年6月19日リリース)

最初の公開リリースで、初期セットとして GetTables、 GetCell 、 ExportTable スクリプトを含みます。