SQABasic "ImageUtilities" Library
MODULE DESCRIPTION:
Utilities for working with images and screen coordinates in SQA Robot.
Currently, the image capture mechanism requires the use of rtcmpi.exe--which
is installed with TeamTest and other Testing bundles of Rational Software.
However, the installation of only the Robot testing Agent does not install
the needed tools for the capture and export mechanism used. So this will
not work if ONLY the Agent is installed.
Image capture may also fail if the user has turned off logging
to TestManager via the Robot Tools setting. You may have to enable
TestManager logging for the capture to successfully execute.
Function CreateImageDiff also needs the installation of ImageMagick to succeed.
See ImageMagick and the ImageMagick compare tool doc for extra info.
Declarations
Constants
Global Variables
User-Defined Types
Routine Details
User Dependencies:
(stuff the developer's library/script $INCLUDES at compile time.)
(Note: The order of items may matter and may be different for your code.)
- '$INCLUDE: "ImageUtilities_X.sbh"
- '$INCLUDE: "ImageUtilities.SBH"
Internal Dependencies:
(stuff this library needs at compile time.)
Exported Declarations
Function IsValidRectangle BasicLib ImageUtilities
Function ValidateContainedRectangle BasicLib ImageUtilities
Function GetRectangleFromString BasicLib ImageUtilities
Function GetMaskFromString BasicLib ImageUtilities
Function CaptureScreenShotToVPImg BasicLib ImageUtilities
Function ExportVPImgToImageFile BasicLib ImageUtilities
Function CreateImageDiff BasicLib ImageUtilities
Constants
(none)
Globals
(none)
User-Defined Types
(none)
Routine Details
function IsValidRectangle( rect as SQARectangle ) as integer
DESCRIPTION:
Check whether a SQARectangle specifies a valid rectangle.
A rectangle is valid if and only if:
rect.left < rect.right AND rect.top < rect.bottom
PARAMETERS:
rect SQARectangle to be checked.
RETURNS:
-1 (True) if rect is a valid rectangle specification.
0 (False) if rect is not a valid rectangle specification.
ERRORS:
(none)
Orig Author: Yuesong Wang
Orig Date: JUL 24, 2002
History:
JUL 24, 2002 Original Release
function ValidateContainedRectangle( _
containedRect as SQARectangle, _
containerRect as SQARectangle ) as integer
DESCRIPTION:
Validate coordinates of a rectangle contained in another rectangle.
If the coordinates of the contained rect are outside the range of the
container rect, they are changed to the nearest boundary values so that
the new coords of the contained rect are fully within the container
rect.
PARAMETERS:
containedRect Coords of the contained rectangle. Might be forced to
the boundary value of containerRect.
containerRect Coords of the container rectangle.
RETURNS:
-1 (True) if containedRect is validated/fitted with containerRect.
0 (False) if either rect is an invalid rectangle specification.
containedRect will not be changed in this case.
ERRORS:
(none)
Orig Author: Yuesong Wang
Orig Date: JUL 24, 2002
History:
JUL 24, 2002 Original Release
Function GetRectangleFromString( _
rectStr As String, _
rect As SQARectangle ) as integer
DESCRIPTION:
Convert a string expression to a rectangle.
PARAMETERS:
rectStr String expression that represents a rectangle. The format must
be stricly "x1,y1 to x2,y2", where (x1,y1) is the top-left of
the rectangle and (x2,y2) is the bottom-right. This is the
format of the ScreenRect and ClientRect properties that can be
retrieved via SQAGetProperyAsString().
rect SQARectangle that receives coordinates converted from recStr.
RETURNS:
-1 (True) on successful converstion. The converted rect must also pass
the validation by IsValidRectangle.
0 (False) on failure or any error (e.g. invalid rectStr, invalid rect).
ERRORS:
(none)
Orig Author: Yuesong Wang
Orig Date: JUL 24, 2002
History:
JUL 24, 2002 Original Release
Function GetMaskFromString( _
rWidth As integer, _
rHeight As integer, _
maskStr As String, _
rect as SQARectangle ) as integer
DESCRIPTION:
Convert a string expression to a mask.
A mask is a rectangle contained within a container rectangle. The
coordinates of the mask is relative to that of the container rectangle.
That means the coords of the mask are always in the range of
(0,0,width,height).
PARAMETERS:
rWidth Width of the container rectangle of the mask.
rHeight Height of the container rectangel of the mask.
maskStr String expression that specifies a mask area of a rectangle.
The expression can contain either absolute coordinates or
percentages ("x1,y1,x2,y2" or "x1%,y1%,x2%,y2%"). Note that the
size of the container rectangle implies the boundary value of
this parameter, i.e. (0,0) and (0%,0%) are the minimum, and
(width, height) and (100%,100%) are the maximum. Values
exceeding the minimun/maximum are forced to the nearest boundary
value. Absolute and percent values can be mixed, e.g.
"0,0,50%,50%" is valid.
rect SQARectangle that receives the mask coordinates with respect to
the container rectangle.
EXAMPLES:
rWidth rHeight maskString rect (left, top, right, bottom)
----------------------------------------------------------------------
100 50 "0,0,10,20" (0,0,10,20) -- coords spec
100 50 "25%,10%,50%,20%" (25,5,50,10) -- percetn spec
100 50 "10,10%,50%,20" (10,5,50,20) -- mixed spec
100 50 "50,25,100,100" (50,25,100,50) -- partially out-of-bound
spec is forced to fit
(same for %)
100 50 "150,100,200,150" undefined -- Completely out-of-bound
spec causes function to
return false
RETURNS:
-1 (True) on successful converstion. The converted rect must also pass
the validation by IsValidRectangle.
0 (False) on failure or any error (e.g. invalid maskStr).
ERRORS:
(none)
Orig Author: Yuesong Wang
Orig Date: JUL 24, 2002
History:
JUL 24, 2002 Original Release
function CaptureScreenShotToVPImg( rect as SQARectangle ) as string
DESCRIPTION:
Capture screen shot of a rectangular area to a .img file.
RegionVP function is called with the specified coordinates. This
generates a .img file in the "vp" directory of the runtime log folder
which is obtained with SQAGetLogDir.
Note that if the specified area exceeds the boundary of the screen,
only the portion that is displayed on the screen will be captured. If
the specified area is completely outside the screen, the fucntion will
no capture nothing and return "".
NOTE: We use Robot's Image Comparator tool to capture the screenshot.
The routine may fail to execute properly if the user has turned off logging
to TestManager via the Robot Tools setting. You may have to enable
TestManager logging for the routine to successfully execute.
PARAMETERS:
rect SQARectangle that represents the specified area.
RETURNS:
Full path to the .img file. "" if failed (e.g. rect out-of-bound).
ERRORS:
(none)
Orig Author: Yuesong Wang
Orig Date: JUL 17, 2002
History:
JUL 17, 2002 Original Release
JUL 24, 2002 (YWANG) Changed to take SQARectangle parameter.
Added boundary check for rect.
APR 23, 2004 (CANAGL/BOLAWL) Enabled TM Agent use.
DEC 09, 2005 (BOLAWL) Updated VPName to < 20 chars (new RR limitation). RJL
JAN 20, 2006 (CANAGL) Added more CaptureScreenShot documentation.
function ExportVPImgToImageFile( _
vpimgfilepath as string, _
imagefilepath as string ) as integer
DESCRIPTION:
Export a .img file generated by image vp to a .bmp or .jpg file.
Rational Test Image Comparator tool is used (via its GUI) to export the
VP generated .img file.
PARAMETERS:
vpimgfilepath Full path to the VP .img file
imagefilepath Full path to the target image file. Extension must be
.bmp or .jpg
RETURNS:
-1 (true) on success
0 (false) on failure (e.g. imagefilepath is not bmp or jpg)
ERRORS:
(none)
Orig Author: Yuesong Wang
Orig Date: JUL 16, 2002
History:
JUL 16, 2002 Original Release
JAN 30, 2003 (CANAGL) Removed some English-specific Text=Save text.
APR 23, 2004 (CANAGL) Fixed an export path bug.
DEC 09, 2005 (BOLAWL) Updated VPNames to < 20 chars (new RR limitation). RJL
Function CreateImageDiff( bench as string, actual as string, diff as String ) as Integer
DESCRIPTION:
Create a new image that graphically shows the differences between the
supplied bench and actual.
Currently, this function only supports the use of the ImageMagick 'compare'
tool. ImageMagick must be installed for this function to succeed.
Future releases may allow for alternate tool support.
See ImageMagick and the ImageMagick compare tool doc for extra info.
PARAMETERS:
bench the full path to the benchmark image to use in the compare image creation.
actual the full path to the test 'actual' image to use in the compare image creation.
diff the full path to the output diff image to be created.
RETURNS:
-1 on success
0 bench or actual do not exist
1 Required Tool support not installed or available (ImageMagick)
2 failure in Shell execution
3 Shell execution did not complete (still running?)
4 compared image sizes do not match (diff may not be generated)
ERRORS:
(none)
Orig Author: Carl Nagle
Orig Date: MAY 25, 2005
History:
MAY 25, 2005 Original Release
Copyright (2002,2003) Claritas Inc.
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License Version 2 as published by the Free
Software Foundation. This license version can be viewed in its entirety at:
http://www.opensource.org/licenses/gpl-license.php
THIS CODE IS PROVIDED "AS IS". THERE ARE NO REPRESENTATIONS OR WARRANTIES,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
FITNESS FOR ANY PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
ANYONE BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING IN CONNECTION
WITH THE CODE OR ITS USE.
You should have received a copy of the GNU General Public License along with
this program; if not, write to:
the Free Software Foundation, Inc.,
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
===============================================================================