<a
href=http://www.t-plan.com>T-Plan Home</a>

14 June 2018

Table Kit Plugin For T-Plan Robot Enterprise

Contents
1. Overview
2. Plugin installation
3. Usage
    3.1 GetTables Script
    3.2 GetCell Script
    3.3 ExportTable Script
4. Change Log

1. Overview

The Table Kit Plugin finds tables on the screen using graphical screen analysis. This includes:

Recognition of tables and their properties (row and column count, number of cells, location, width and height)
Exposing of cell properties (bounds, color, text)
Optional retrieval of text from individual table cells using the Tesseract OCR engine.

The plugin is primarily designed for test scripts written in the TPR language. To call the plugin scripts from Java either use the DefaultJavaTestScript.run() method or use the script instance approach described in the Java Test Script Basics document.

The table recognition algorithm has the following limitations:

All cells must have solid color background and must be separated by a grid line (border) of another color.

There must be at least one pixel distance (padding) between the cell content (text) and its border.

Should you have any questions or suggestions contact the T-Plan support. For the list of other plugins provided by T-Plan go here.

2. Plugin installation

To install the plugin download the appropriate archive from the following location:

Version 0.7 (T-Plan Robot 4.1.1 and higher): http://www.t-plan.ltd.uk/releases/robot/plugins/tablekit_v0.7.zip
Version 0.6 (T-Plan Robot 4.1.1 and higher): http://www.t-plan.ltd.uk/releases/robot/plugins/tablekit_v0.6.zip
Version 0.5 (T-Plan Robot 3.5.2 - 4.1): http://www.t-plan.ltd.uk/releases/robot/plugins/tablekit_v0.5.zip

For version differences see the Change Log.

OPTION 1:

IMPORTANT: As Java 9 broke support of dynamic JAR loading you must use this option if you are running Java 9 or higher.

Unzip the file to a location on your hard drive.
Add the tablekit.jar file to the class path of the Robot start command. For details see the Robot release notes.
Start or restart Robot. The test scripts will be exposed to Robot. When you create a Run command in your TPR script the property window will list the plugin scripts.

OPTION 2 (JAVA 8 AND LOWER):

Unzip the file to the plugins/ directory under the Robot installation directory. This will make Robot load the classes on the start up. Make sure to remove any older versions of the plugin.
Start or restart Robot. The test scripts will be exposed to Robot. When you create a Run command in your TPR script the property window will list the plugin scripts. The plugin will also add the table viewer to the Plugins menu of the Robot GUI:

OPTION 3 (JAVA 8 AND LOWER):

NOTE: This option will not install the table viewer into the menu. The viewer will be however available from the Properties window of the GetTables script. For the viewer screenshot see the Usage chapter below.

Unzip the file to a location on your hard drive.
If you plan on using the plugin in the TPR scripts put the following command to the beginning of each test script:

Include "<location>/tablekit.jar"

If you plan on using the plugin in Java test scripts put the tablekit.jar file onto the Java class path (see OPTION 1).

To uninstall the plugin simply delete the file and remove the Include references eventually.

3. Usage

The plugin contains three Java test scripts:

Script Name
Description

com.tplan.table.GetTables Recognize table(s) on the screen.

com.tplan.table.GetCell Retrieve information of a cell of the previously recognized table.

com.tplan.table.ExportTable Export previously recognized table to a text, CSV or MS Excel file.

The plugin scripts are to be called from TPR test scripts using the Run command. The command instances may be easily created using the Command Wizard tool. To edit an existing Run command right click it and select Properties in the context menu. The GetTable script also provides the table viewer:

A few examples showing typical usage:

EXAMPLE #1: Recognize a table and save text of its cell at the second row and third column to a variable called 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}"

EXAMPLE #2: Click cell at [row, column] = [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"

EXAMPLE #3: Verify whether the cells in the first column have the same color and set the SAMECOLOR variable to true or false accordingly.

// 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 } }

EXAMPLE #4: Recognize table(s) and save them to a MS Excel file.

// 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"

3.1 GetTables Script

DESCRIPTION

The com.tplan.table.GetTables script performs analysis of the screen in order to find a table or tables. The basic data of detected table(s) is exposed through the following variables:

Variable Name
Description

_TABLE_COUNT=<number>
Number of recognized tables.

_TABLE<n>_X=<X-coordinate>
_TABLE<n>_Y=<Y-coordinate>
_TABLE<n>_W=<width>
_TABLE<n>_H=<height>
The bounding rectangle of the n-th table where <n> is between one and
the number of tables.

_TABLE<n>_ROWS=<number>
_TABLE<n>_COLUMNS=<number>
_TABLE<n>_CELLS=<number>
Number or rows, columns and cells of the n-th table where <n> is between
one and the number of tables.

_TABLE<n>_TEXT=<number> Summary text recognized in the n-th table. This variable is populated only
if the OCR is on (tocr=true). The text is composed of the individual cells
in the reading mode with the tabulator (tab, \t) and new line (\n) serving as
the cell and row separators.

To get text of a single cell use GetCell.

NOTE: The parameter of scale is obsoleted since v0.5. It is accepted on the command line to preserve compatibility with the previous releases but its value is ignored. The command will identify the best scaling factor on its own.

SYNOPSIS (TPR SCRIPTS)
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>]

SYNOPSIS (JAVA SCRIPTS)
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" >] );

* Red color indicates obligatory parameters

OPTIONS
cw=<pixels>

- Minimum cell width in pixels. Defaults to 15.

ch=<pixels>

- Minimum cell height in pixels. Defaults to 10.

minrows=<number>

- Minimum required number of table rows. Tables that don't meet this criteria will be omitted. Defaults to 2 rows.

mincols=<number>

- Minimum required number of table columns. Tables that don't meet this criteria will be omitted. Defaults to 2 columns.

spacing=<spacing>

- Maximum spacing (grid thickness) between two neighboring cells. Defaults to 4 pixels.

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

- The rectangular area of the desktop to limit the table recognition to. The syntax and functionality is equal to the cmparea parameter of the CompareTo command. If you omit this parameter the whole remote desktop will be processed. The area coordinates have format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (for example. "x:225") or as a percentage ("x:23%").

If any of x, y, width or height are omitted, T-Plan Robot will use the full screen values to determine the missing parameters (x:0, y:0, w:<screen_width>, h:<screen_height>). For example, "cmparea=y:50%,height:50%" will process bottom half of the screen.

tocr=<true|false>

- The value of "true" will perform Tesseract OCR for each recognized cell to retrieve its text. The text may be then obtained through a call of the GetCell script. The parameter defaults to false (do not perform OCR).

WARNING: This OCR mode may take long, especially for large tables. It is suitable only if you plan on iterating over texts of all cells or export the table to a file. Should you need to retrieve text of a single cell or a few cells it is more efficient to skip the OCR in GetTables and perform single cell OCR using the tocr parameter of GetCell.

language=<lang_code>

- A valid 3-character language code of a properly installed Tesseract language data file. The parameter is used only if OCR is on (tocr=true). If the parameter is omitted it defaults to "eng" (English). See the Tesseract OCR comparison method for details.

fixocr=<true|false>

- The value of true will make an attempt to fix some known Tesseract OCR accuracy errors such as:

Abundant spaces in numbers ("3. 14" instead of "3.14")
Digits confused for characters where the cell value appears to be a number, such as recognition of capital 'O' instead of the zero digit '0' ("2.O5" instead of "2.05")
Slash confused for another character in date values ("29|10|2013" instead of "29/10/2013")

The default value is true (do fix). Set it off if the command fixes texts that are not supposed to be fixed, such as strings similar to numbers or dates (product codes, special char and digit sequences...)

RETURNS
The command returns 0 (zero) when at least one table is found and no error is experienced. Otherwise it returns 1 (one) when no tables get recognized or 2 (two) when the OCR fails to execute for an I/O error, typically when Tesseract is not installed or misconfigured. The failure is also logged into the execution log.

EXAMPLES

See the Usage chapter.

3.`2` GetCell Script

DESCRIPTION

The com.tplan.table.GetCell script retrieves properties of a table cell recognized previously through GetTables. The data is exposed to the script in form of variables:

Variable Name
Description

_TABLE_CELL_X=<X-coordinate>
_TABLE_CELL_Y=<Y-coordinate>
_TABLE_CELL_W=<width>
_TABLE_CELL_H=<height>
The bounding rectangle of the cell.

_TABLE_CELL_ROWSPAN=<number>
_TABLE_CELL_COLSPAN=<number>
The cell row span and cell span.

_TABLE_CELL_TEXT=<number> The cell text. This variable is populated only if the OCR is on (tocr=true) or if OCR
has been performed before either by GetTables or by a call of GetCell for the same
cell row and column number.

_TABLE_CELL_BLANK=<true|false> Indicates whether the cell is blank or not. This is verified independently from OCR
through testing whether the cell area is made of a single color.

_TABLE_CELL_COLOR=<color> The cell background color in the HTML notation. For example, white is "ffffff" while
black is "000000".

NOTE: The parameter of scale is obsoleted since v0.5. It is accepted on the command line to preserve compatibility with the previous releases but its value is ignored. The command will identify the best scaling factor on its own.

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

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

* Red color indicates obligatory parameters

OPTIONS
row=<number>

- The cell row number. When omitted it defaults to the first row (1).

column=<number>

- The cell column number. When omitted it defaults to the first column (1).

table=<number>

- The table number. It makes sense only if GetTables recognizes more than one table. When omitted it defaults to the first table (1).

tocr=<true|false>

- The value of "true" will perform Tesseract OCR to retrieve the cell text unless the cell is blank (solid color). The parameter defaults to false (do not perform OCR).

language=<lang_code>

- A valid 3-character language code of a properly installed Tesseract language data file. The parameter is used only if OCR is on (tocr=true). If the parameter is omitted it defaults to "eng" (English). See the Tesseract OCR comparison method for details.

fixocr=<true|false>

- The value of true will make an attempt to fix some known Tesseract OCR accuracy errors such as:

Abundant spaces in numbers ("3. 14" instead of "3.14")
Digits confused for characters where the cell value appears to be a number, such as recognition of capital 'O' instead of the zero digit '0' ("2.O5" instead of "2.05")
Slash confused for another character in date values ("29|10|2013" instead of "29/10/2013")

RETURNS
The command returns 0 (zero) on success. When it fails it returns 1 (one) when the cell is not available or 2 (two) when the OCR fails to execute for an I/O error, typically when Tesseract is not installed or misconfigured. The failure is also logged into the execution log.

EXAMPLES
See the Usage chapter.

3.3 ExportTable Script

DESCRIPTION

The com.tplan.table.ExportTable script exports table(s) recognized previously through GetTables to a text, CSV or MS Excel file. The format is decided from the file extension:

.txt - text file

Cells will be separated by tabulators (tabs, \t)
Rows will be separated by new lines (\n)
Tables will be separated by two blank lines.

.csv - CSV file

The file will be IETF RFC 4180 compliant.
Tables they will be separated by two blank lines.

.xls, .xlsx - MS Excel. The supported formats are Microsoft Excel 97/2000/XP (.xls) and MS Excel 2007 XML documents (.xlsx).

There will be one sheet per table. Each sheet be named by the table number ("1", "2", ...)
The table will start from the top left sheet corner (the "A1" cell). It will be bordered by a solid black line.
The cells will contain the recognized text provided that OCR has been performed. No other cell attributes will be applied to the Excel table (color, text alignment, font size/style...). Should you need any extra functionality int his area ask the T-Plan support.

If the file has no or unrecognized extension the script will append .xls to the file name and it will default to Microsoft Excel 97/2000/XP.

To ensure that the file contains all cell texts call the GetTables script with the OCR on (tocr=true). A typical sequence of commands to recognize table(s) and store them to a MS Excel file is:

// 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"

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

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

* Red color indicates obligatory parameters

OPTIONS
file=<target_file>

- The target file to save the tables to (mandatory). The format will be judged from the extension (.txt, .csv, .xls or .xlsx). If the file has no recognized extension the script will default to the Microsoft Excel 97/2000/XP (.xls) format and it will append the .xls extension to the file name.

The specified file may be absolute or relative. Relative paths will be resolved against the user home folder.

tables=<number(s)>

- The table number or a semicolon or comma separated list of table numbers (optional). When omitted the script exports all tables recognized by the most recent GetTables call.

RETURNS
The command returns 0 (zero) on success. It returns 1 (one) when it fails for an I/O error or if the table list is invalid. The failure is also logged into the execution log.

EXAMPLES
See the Usage chapter.

4. Change Log

Version 0.7 released on 14 June 2018

Table recognition logic updated to improve accuracy where one or more columns fail to recognize thanks to a custom content
Minor viewer enhancements

Version 0.6 released on 15 November 2016

New version for Robot 4.1.1 and higher (the 0.5 version fails to open the viewer for the Local Desktop connection due to a change in the Robot framework)

Version 0.5 released on 19 June 2014

First public release with the initial set of GetTables, GetCell and ExportTable scripts.

Script Name	Description
`com.tplan.table.GetTables`	Recognize table(s) on the screen.
`com.tplan.table.GetCell`	Retrieve information of a cell of the previously recognized table.
`com.tplan.table.ExportTable`	Export previously recognized table to a text, CSV or MS Excel file.

Variable Name	Description
_TABLE_COUNT=<number>	Number of recognized tables.
_TABLE<n>_X=<X-coordinate> _TABLE<n>_Y=<Y-coordinate> _TABLE<n>_W=<width> _TABLE<n>_H=<height>	The bounding rectangle of the n-th table where <n> is between one and the number of tables.
_TABLE<n>_ROWS=<number> _TABLE<n>_COLUMNS=<number> _TABLE<n>_CELLS=<number>	Number or rows, columns and cells of the n-th table where <n> is between one and the number of tables.
_TABLE<n>_TEXT=<number>	Summary text recognized in the n-th table. This variable is populated only if the OCR is on (tocr=true). The text is composed of the individual cells in the reading mode with the tabulator (tab, \t) and new line (\n) serving as the cell and row separators. To get text of a single cell use GetCell.

Variable Name	Description
_TABLE_CELL_X=<X-coordinate> _TABLE_CELL_Y=<Y-coordinate> _TABLE_CELL_W=<width> _TABLE_CELL_H=<height>	The bounding rectangle of the cell.
_TABLE_CELL_ROWSPAN=<number> _TABLE_CELL_COLSPAN=<number>	The cell row span and cell span.
_TABLE_CELL_TEXT=<number>	The cell text. This variable is populated only if the OCR is on (tocr=true) or if OCR has been performed before either by GetTables or by a call of GetCell for the same cell row and column number.
_TABLE_CELL_BLANK=<true\|false>	Indicates whether the cell is blank or not. This is verified independently from OCR through testing whether the cell area is made of a single color.
_TABLE_CELL_COLOR=<color>	The cell background color in the HTML notation. For example, white is "ffffff" while black is "000000".