Merge pull request #39 from nut-tree/feature/38/split_image_processing_and_matching

Closes #38. Split image processing and matching

Author: s1hofmann

.github/ISSUE_TEMPLATE/enhancement.md

@@ -0,0 +1,13 @@
+---
+name: Enhancement
+about: Suggest a possible enhancement to the project
+---
+
+**Short overview**
+
+**Use case**
+
+**Detailed description**
+
+**Additional content**
+> Please provide any (mandatory) additional data for your enhancement

lib/provider/opencv/__mocks__/alpha_channel.png

@@ -0,0 +1,13 @@
+/**
+ * A DataSink should provide methods to store data
+ *
+ * @interface DataSink
+ */
+export interface DataSink {
+  /**
+   * store will write data to disk
+   * @param data Data to write
+   * @param path Absolute output file path
+   */
+  store(data: any, path: string): Promise<any>;
+}

lib/provider/opencv/data-sink.interface.ts

@@ -0,0 +1,12 @@
+/**
+ * A DataSource should provide methods to load data
+ *
+ * @interface DataSource
+ */
+export interface DataSource {
+  /**
+   * load will load image data from disk
+   * @param path Absolute path to output file
+   */
+  load(path: string): Promise<any>;
+}

lib/provider/opencv/data-source.interface.ts

@@ -1,7 +1,5 @@
-import { Image } from "../../image.class";
 import { MatchRequest } from "../../match-request.class";
 import { MatchResult } from "../../match-result.class";
-import { Region } from "../../region.class";
 
 /**
  * A Finder should provide an abstraction layer to perform
@@ -10,15 +8,6 @@ import { Region } from "../../region.class";
  * @interface FinderInterface
  */
 export interface FinderInterface {
-  /**
-   * loadImage should allow to load an image from filesystem
-   *
-   * @param {string} path The filesystem path to the image
-   * @returns {*} An image
-   * @memberof VisionProviderInterface
-   */
-  loadImage(path: string): any;
-
   /**
    * findMatch should provide an abstraction to search for an image needle
    * in another image haystack
@@ -38,35 +27,4 @@ export interface FinderInterface {
    * @memberof FinderInterface
    */
   findMatches(matchRequest: MatchRequest): Promise<MatchResult[]>;
-
-  /**
-   * fromImageWithAlphaChannel should provide a way to create a library specific
-   * image with alpha channel from an abstract Image object holding raw data and image dimension
-   *
-   * @param {Image} img The input Image
-   * @param {Region} [roi] An optional Region to specify a ROI
-   * @returns {Promise<any>} An image
-   * @memberof VisionProviderInterface
-   */
-  fromImageWithAlphaChannel(img: Image, roi?: Region): Promise<any>;
-
-  /**
-   * fromImageWithoutAlphaChannel should provide a way to create a library specific
-   * image without alpha channel from an abstract Image object holding raw data and image dimension
-   *
-   * @param {Image} img The input Image
-   * @param {Region} [roi] An optional Region to specify a ROI
-   * @returns {Promise<any>} An image
-   * @memberof VisionProviderInterface
-   */
-  fromImageWithoutAlphaChannel(img: Image, roi?: Region): Promise<any>;
-
-  /**
-   * rgbToGrayScale should provide a way to convert an image from RGB to grayscale
-   *
-   * @param {*} img Input image, RGB
-   * @returns {Promise<any>} Output image, grayscale
-   * @memberof VisionProviderInterface
-   */
-  rgbToGrayScale(img: any): Promise<any>;
 }

lib/provider/opencv/finder.interface.ts

@@ -0,0 +1,39 @@
+import { resolve } from "path";
+import { ImageProcessor } from "./image-processor.class";
+import { ImageReader } from "./image-reader.class";
+
+describe("ImageProcessor", () => {
+  it("should allow to create a cv.Mat from an Image with alpha channel, alpha channel is dropped", async () => {
+    // GIVEN
+    const imageReader = new ImageReader();
+    const imagePath = resolve(__dirname, "./__mocks__/alpha_channel.png");
+    const image = await imageReader.load(imagePath);
+
+    // WHEN
+    const mat = await ImageProcessor.fromImageWithAlphaChannel(image);
+
+    // THEN
+    expect(image.hasAlphaChannel).toBeTruthy();
+    expect(mat.channels).toEqual(3);
+    expect(mat.rows).toEqual(image.height);
+    expect(mat.cols).toEqual(image.width);
+    expect(mat.empty).toBeFalsy();
+  });
+
+  it("should allow to create a cv.Mat from an Image without alpha channel", async () => {
+    // GIVEN
+    const imageReader = new ImageReader();
+    const imagePath = resolve(__dirname, "./__mocks__/mouse.png");
+    const image = await imageReader.load(imagePath);
+
+    // WHEN
+    const mat = await ImageProcessor.fromImageWithoutAlphaChannel(image);
+
+    // THEN
+    expect(image.hasAlphaChannel).toBeFalsy();
+    expect(mat.channels).toEqual(3);
+    expect(mat.rows).toEqual(image.height);
+    expect(mat.cols).toEqual(image.width);
+    expect(mat.empty).toBeFalsy();
+  });
+});

lib/provider/opencv/image-processor.class.spec.ts

@@ -0,0 +1,47 @@
+import * as cv from "opencv4nodejs";
+import { Image } from "../../image.class";
+import { Region } from "../../region.class";
+
+export class ImageProcessor {
+  /**
+   * fromImageWithAlphaChannel should provide a way to create a library specific
+   * image with alpha channel from an abstract Image object holding raw data and image dimension
+   *
+   * @param {Image} img The input Image
+   * @param {Region} [roi] An optional Region to specify a ROI
+   * @returns {Promise<any>} An image
+   * @memberof VisionProviderInterface
+   */
+  public static async fromImageWithAlphaChannel(
+    img: Image,
+    roi?: Region,
+  ): Promise<cv.Mat> {
+    const mat = await new cv.Mat(img.data, img.height, img.width, cv.CV_8UC4).cvtColorAsync(cv.COLOR_BGRA2BGR);
+    if (roi) {
+      return mat.getRegion(new cv.Rect(roi.left, roi.top, roi.width, roi.height));
+    } else {
+      return mat;
+    }
+  }
+
+  /**
+   * fromImageWithoutAlphaChannel should provide a way to create a library specific
+   * image without alpha channel from an abstract Image object holding raw data and image dimension
+   *
+   * @param {Image} img The input Image
+   * @param {Region} [roi] An optional Region to specify a ROI
+   * @returns {Promise<any>} An image
+   * @memberof VisionProviderInterface
+   */
+  public static async fromImageWithoutAlphaChannel(
+    img: Image,
+    roi?: Region,
+  ): Promise<cv.Mat> {
+    const mat = new cv.Mat(img.data, img.height, img.width, cv.CV_8UC3);
+    if (roi) {
+      return mat.getRegion(new cv.Rect(roi.left, roi.top, roi.width, roi.height));
+    } else {
+      return mat;
+    }
+  }
+}

lib/provider/opencv/image-processor.class.ts

@@ -0,0 +1,29 @@
+import * as path from "path";
+import { ImageReader } from "./image-reader.class";
+
+describe("Image loader", () => {
+  it("should resolve to a non-empty Mat on successful load", async () => {
+    // GIVEN
+    const SUT = new ImageReader();
+    const imagePath = path.resolve(__dirname, "./__mocks__/mouse.png");
+
+    // WHEN
+    const result = await SUT.load(imagePath);
+
+    // THEN
+    expect(result.height).toBeGreaterThan(0);
+    expect(result.width).toBeGreaterThan(0);
+  });
+
+  it("loadImage should reject on unsuccessful load", async () => {
+    // GIVEN
+    const SUT = new ImageReader();
+    const imagePath = "./__mocks__/foo.png";
+
+    // WHEN
+    const call = SUT.load;
+
+    // THEN
+    await expect(call(imagePath)).rejects.toEqual(`Failed to load image from '${imagePath}'`);
+  });
+});

lib/provider/opencv/image-reader.class.spec.ts

@@ -0,0 +1,16 @@
+import * as cv from "opencv4nodejs";
+import { Image } from "../../image.class";
+import { DataSource } from "./data-source.interface";
+
+export class ImageReader implements DataSource {
+  public async load(path: string): Promise<Image> {
+    return new Promise<Image>(async (resolve, reject) => {
+      try {
+        const image = await cv.imreadAsync(path, cv.IMREAD_UNCHANGED);
+        resolve(new Image(image.cols, image.rows, image.getData(), image.channels));
+      } catch (e) {
+        reject(`Failed to load image from '${path}'`);
+      }
+    });
+  }
+}

lib/provider/opencv/image-reader.class.ts

@@ -0,0 +1,32 @@
+import { existsSync, unlinkSync } from "fs";
+import { resolve } from "path";
+import { ImageReader } from "./image-reader.class";
+import { ImageWriter } from "./image-writer.class";
+
+const INPUT_PATH = resolve(__dirname, "./__mocks__/mouse.png");
+const OUTPUT_PATH_PNG = resolve(__dirname, "./__mocks__/output.png");
+const OUTPUT_PATH_JPG = resolve(__dirname, "./__mocks__/output.jpg");
+
+beforeEach(() => {
+  for (const file of [OUTPUT_PATH_JPG, OUTPUT_PATH_PNG]) {
+    if (existsSync(file)) {
+      unlinkSync(file);
+    }
+  }
+});
+
+describe.each([[OUTPUT_PATH_PNG], [OUTPUT_PATH_JPG]])(
+  "Image writer", (outputPath) => {
+    test("should allow to store image data to disk", async () => {
+      // GIVEN
+      const imageReader = new ImageReader();
+      const image = await imageReader.load(INPUT_PATH);
+      const imageWriter = new ImageWriter();
+
+      // WHEN
+      await imageWriter.store(image, outputPath);
+
+      // THEN
+      expect(existsSync(outputPath)).toBeTruthy();
+    });
+  });