(feat) Add PixelMatcher to CaptureSupport.

[hastebrot]

Problem

In TestFX 3 GuiTest created screenshots when errors occurred, i.e. when a Node for a mouse interaction wasn't found or an verifyThat() assertion failed. We need to port this functionality to TestFX 4 FxRobot and FxAssert.

Solution

Extend CaptureSupport which allows to capture nodes and regions (i.e. a desktop, screen, stage, scene, bounds) as an in-memory Image. It is possible to annotate captured images with rectangles (e.g. the area of missing nodes) and texts (e.g. the assertion error text).

interface CaptureSupport {
    // capture methods.
    Image captureNode(Node node);
    Image captureRegion(Rectangle2D region);

    // load and save methods.
    Image loadImage(Path path);
    void saveImage(Image image, Path path);

    // annotation and match methods.
    Image annotateImage(Shape shape, Image image);
    PixelMatcherResult matchImages(Image image0, Image image1, PixelMatcher matcher);
}

A PixelMatcher allows to match two images and return a match result.

interface PixelMatcher {
    PixelMatcherResult match(Image image0, Image image1);
    boolean matchColors(Color color0, Color color1);

    WritableImage createEmptyMatchImage(Image image0, Image image1);
    Color createMatchColor(Color color0, Color color1);
    Color createNonMatchColor(Color color0, Color color1);
}

class PixelMatcherResult {
    public PixelMatcherResult(Image matchImage, long matchPixels, long totalPixels) {}

    public Image getMatchImage() {}
    public long getTotalPixels() {}
    public long getMatchPixels() {}
    public long getNonMatchPixels() {}
    public double getMatchFactor() {}
    public double getNonMatchFactor() {}
}

Testing

PixelMatcherResult::getNonMatchPixels() varies between Java versions for the same Scene, e.g. Java 1.8.31 and 1.8.72.

---

Subtask of: #167

[hastebrot]

FxRobot and FxService need a method to describe screenshot captures.

interface CaptureBuilder {
    CaptureBuilder capture(Bounds bounds);
    CaptureBuilder annotateWith(Shape shape);

    CaptureBuilder saveTo(Path path);
    Image toImage();
}