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.)

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
===============================================================================