图像操作API

图像操作API用于在执行中操作API，及自动化结果的验证，主要通过Image对象。此外虚拟控件也有相应的方法，根据图片实现判断。

Image对象

Image对象用于获得图片的属性信息，及针对图片的比较操作。

Image对象定义如下：

  1.     class Image {
  2.         width: number;
  3.         height: number;
  5.         clip(rect: {x: number, y: number, width: number, height: number}): Image;
  6.         drawImage(image: Image, x: number, y: number): Image;
  7.         getData(option?: {encoding: 'base64' | null}): Promise<Buffer | string>;
  9.         static fromData(bufferOrString: Buffer | string): Promise<Image>;
  10.         static fromFile(filePath: string): Promise<Image>;
  12.         static imageEqual(image1: Buffer | string | Image,
  13.             image2: Buffer | string | Image, 
  14.             options?: CompareOptions,
  15.             compareInfo?: ImageCompareInfo): Promise<boolean>;
  16.         static imageCompare(image1: Buffer | string | Image,
  17.             image2: Buffer | string | Image, 
  18.             options?: CompareOptions): Promise<ImageCompareResult>
  19.     }

获得一个Image对象的实例可以得到图片的属性，或将图片用于后继处理。

可以从Buffer、base64的字符串，或者一个文件路径生成Image实例，例如：

  1.    const { Image } = require('leanpro.visual');
  2.    const fs = require('fs');
  3.    (async function() {
  4.        let buf1 = fs.readFileSync('c:/temp/image1.png');
  5.        let image1 = await Image.fromData(buf1);
  6.        console.log(image1.width, image1.height);
  8.        let image2 = await Image.fromFile('c:/temp/image2.png');
  9.        console.log(image2.width, image2.height);
  10.    })()

上面例子分别从Buffer和文件中读取图片数据并打印宽度和高度。

注意：无法直接通过new Image()创建对象，需要通过fromData或者fromFile生成Image实例。另外Image对象现只支持PNG格式的图片。

实例成员：

  • clip 用于剪切图片，返回另一个图片。传入矩形框，按照矩形框剪切图片，如果传入数据不合法导致剪切的图片宽度或高度为0，返回为null;

  • drawImage 用于将两幅绘制图片绘制到一幅图片上。返回为新绘制的图片。

    例如：

    1.  this.screen1 = await model.getButton("Five").takeScreenshot();
    2.  this.screen2 = await model.getButton("Six").takeScreenshot();
    3.  let image1 = await Image.fromData(this.screen1);
    4.  let image2 = await Image.fromData(this.screen2);
    6.  image1 = image1.clip({ x: 10, y: 10, width: image1.width - 20, height: image1.height - 20 })
    7.  image2 = image2.clip({ x: 10, y: 10, width: image2.width - 20, height: image2.height - 20  })
    9.  let combinedImage = image1.drawImage(image2, image1.width + 5, 0);

    上面代码将两个按钮截屏剪切掉10像素的周围边缘，然后绘制到一张图片上，中间间隔5个像素。

    如果你想让两幅图片上下排列，你可以使用类似下面的代码：

    1. let combinedImage = image1.drawImage(image2, 0, image1.height + 5);

    您还可以使用为负值的x，y，以便第二个图像在第一个图像的另一侧绘制，例如，以下语句将在左侧绘制image2，在右侧绘制image1：

    1. let combinedImage = image1.drawImage(image2, -(image1.width + 5), 0);

  • getData返回图片的内容数据，可用于保存至文件，或添加到报表中。注意它返回的是Promise，所以在async函数中需要加await。

图片比较操作

在自动化过程中，为了验证结果的正确性，可以通过验证结果图片和期望图片的差异来判断执行结果是否正确。

图片判断主要有两种方式：

  • 比较图片差异，返回布尔值。
  • 将两幅图对应像素相减，产生结果图片，将差异点用色彩标出来，结果图片显示在报表中，可以由人工判断是否正确。

Image对象的imageEqual和imageCompare分别针对上面两种对比方式。

由于操作系统、分辨率、颜色设置都可能影响图片的显示，同样的控件在不同的环境设置下可能显示不同，所以在比较截屏图片时，一般会设置比较容忍度。在容忍度阈值内认为两幅图片是相同的。容忍度有如下的分类：

  • 颜色容忍度：针对两幅图片的两个对应像素点，如果它们的RGB颜色按照特定的距离算法在一定的范围内认为是相同的。

  • 像素容忍度：针对两幅图整体而言，如果不同的像素点数量在一定的范围内，则认为两幅图是相同的。像素容忍度还可以根据百分比来设定，即不同的点占图片所有像素的百分比。

  • imageEqual

    imageEqual用来比较两幅图片的差异，返回布尔值的Promise，如果是true表示相同，false表示不同。如果您只想知道两个图像是否不同，请使用此API。 如果您想知道获取显示差异所在位置的结果图像，请使用另一个API imageCompare。

    它的函数签名：

    1.   imageEqual(image1: Buffer | string | Image,
    2.               image2: Buffer | string | Image, 
    3.               options?: CompareOptions,
    4.               compareInfo?: ImageCompareInfo): Promise<boolean>;
    • image1、image2可以是Buffer、base64的字符串，或者一个Image实例。

    • options用来指定图片比较的参数，它有如下的参数设置：

      1. interface CompareOptions {
      2.         colorTolerance?: number,        //default to 0.1
      3.         pixelNumberTolerance?: number,  //no default value
      4.         pixelPercentTolerance?: number, //default 1, means 1% 
      5.         ignoreExtraPart?: boolean       //default to false
      6.     }

      其中:

      • colorTolerance：颜色容忍度，缺省为0.1。一般不用修改。
      • pixelNumberTolerance：像素数量容忍度，没有缺省值。
      • pixelPercentTolerance：像素百分比容忍度，缺省为1，即1%。例如，两幅图片分别有10000像素，如果允许少于150个像素不同的情况下认为图片相同，则设置为1.5。
      • ignoreExtraPart：是否忽略非重叠部分，缺省为false。两幅比较图片可以是不同尺寸，比较时左上角对齐，超出部分会当成是不同的点。如果设成true，则会忽略超出部分。

      当pixelNumberTolerance和pixelPercentTolerance有一个超出了设定值（或缺省值）比较就会返回false。如果只需要使用其中一个设定，可以将另一个设定设为比较大的值。例如只需要pixelNumberTolerance，并忽略pixelPercentTolerance，可以把pixelPercentTolerance设成100。

    • 除了返回值表示是否相同外，有时需要知道详细的信息，例如像素尺寸，有多少点不同，不同的点的百分比等，这时可以通过传出compareInfo对象获得相关信息。

      compareInfo的类型：

      1. interface ImageCompareInfo {
      2.         image1: {
      3.             width: number,
      4.             height: number
      5.         },
      6.         image2: {
      7.             width: number,
      8.             height: number
      9.         }
      10.         diffPixels: number,
      11.         diffPercentage: number
      12.     }

      使用时，如果compareInfo传入一个空的对象，调用imageEqual后compareInfo会填充如上结构的数据。

      下面是调用样例:

      1. (async function() {
      2.     try {
      3.         let pngSource = await Image.fromFile(__dirname + '/../source.png');
      4.         let pngTargt = await Image.fromFile(__dirname + '/../target.png');
      6.         let compareInfo = {};
      7.         let isEqual = await Image.imageEqual(pngSource, pngTargt, 
      8.             {pixelNumberTolerance: 300, ignoreExtraPart: true}, compareInfo);
      9.         console.log('isEqual', isEqual, JSON.stringify(compareInfo, null, 2));
      10.     } catch(err) {
      11.         console.log(err)
      12.     }
      14. })()

      执行时它传入两个图片，比较是否相同，同时会忽略没有重叠部分。如果不同的像素点超过300个，则返回false，同时它返回了compareInfo的详细数据。打印的内容如下：

      1.     isEqual false {
      2.     "image1": {
      3.         "width": 375,
      4.         "height": 266
      5.     },
      6.     "image2": {
      7.         "width": 402,
      8.         "height": 224
      9.     },
      10.     "diffPixels": 3502,
      11.     "diffPercentage": 3.3100814760203408
      12.     }

  • imageCompare

    impageCompare，比较两者图片，返回详细信息的数据，特别是两幅图片差异部分的图片。如果您想获得显示差异所在位置的结果图像，请使用此API。

    它有如下的签名：

    1.   imageCompare(image1: Buffer | string | Image,
    2.               image2: Buffer | string | Image, 
    3.               options?: CompareOptions): Promise<ImageCompareResult>
    • image1、image2可以是Buffer、base64的string，或者一个Image实例。
    • options 的设置与imageEqual的options设置相同。此外，如果ignoreExtraPart是false，对生成的差分图片有影响。如果ignoreExtraPart为false，图片非重叠部分会设置为红色，否则非重叠不设置颜色。

    返回值是名为ImpageCompareResult的结构：

    1.   interface ImageCompareResult {
    2.           equal: boolean,
    3.           info: ImageCompareInfo,
    4.           diffImage: Image
    5.       }

    其中:

    • equal表示是否根据容忍度设置认为图片相同。
    • info的结构与imageEqual的compareInfo结构相同，包括像素尺寸，有多少点不同，不同的点的百分比等。
    • diffImage是返回的差分图片的Image对象，相同的像素点以缺省白色表示，不同的点显示为红色。图像中原有的图案会以浅色显示在目标图片中，方便定位差异部分所在的位置。

这两个图片比较API中，imageEqual是imageCompare的封装，为了更直观的返回两个图片是否相等的判断结果。如果只想知道是否相等就用imageEqual，如果除了是否相等外，还想知道更详细的就用imageCompare。

示例

下面是比较两个图片并生成差分图片的样例：

  1.       (async function() {
  2.         try {
  3.             let pngSource = await Image.fromFile(__dirname + '/../image1.png');
  4.             let pngTargt = await Image.fromFile(__dirname + '/../image2.png');
  6.             let result = await Image.imageCompare(pngSource, pngTargt, {pixelNumberTolerance: 300});
  7.             let diffImage = result.diffImage;
  8.             console.log('resultMeta', JSON.stringify(result.info, null, 2));
  9.             let imageData = await diffImage.getData();
  10.             fs.writeFileSync(__dirname + '/../diff.png', imageData)
  12.         } catch(err) {
  13.             console.log(err)
  14.         }
  15.       })()

该样例打印出差异信息，并把结果图片保存成文件”diff.png”。

假如我们有下面两幅图片：

image1 (375 266)image2 (402 224)
图像操作API - 图1图像操作API - 图2

根据参数的不同，可以生成下面的差分图片：

ignoreExtraPart = trueignoreExtraPart = false
图像操作API - 图3图像操作API - 图4

左边是ignoreExtraPart = true的情况，超出部分也标记为红色，右边是ignoreExtraPart = false，忽略了超出部分。

控件与模型图片比较

Windows自动化中一个常见的场景是，将运行时控件的截屏与模型中的保存的对象截屏相比较。这可以通过调用测试对象的modelImage方法获得测试对象的截屏png图片，以base64字符串数据返回。如果模型中该对象没有对应的截屏图片，则返回null。

下面的样例从对象模型中获取按钮对象，同时拿到控件截屏和模型中的截屏，并做对比，将对比信息打印出来，同时将差分图片保存到目录中。

  1. const { Image } = require('leanpro.visual');
  2. const { AppModel } = require('leanpro.win');
  3. const fs = require('fs');
  5. const model = AppModel.loadModel(__dirname + "\\test.tmodel");
  7. (async function () {
  8.     let five = model.getButton("Five");
  9.     let controlImage = await five.takeScreenshot();
  10.     let modelImage = await five.modelImage();
  11.     let result = await Image.imageCompare(modelImage, controlImage);
  12.     fs.writeFileSync(__dirname + '/diff.png', await result.diffImage.getData());
  13.     //print the diff information
  14.     console.log(result.info)
  15. })();

虚拟控件上的图片操作

虚拟控件的图片相关操作有：

  • findSnapshot
  • matchSnapshot

请参见虚拟控件API获得相关帮助。