Transparent pixels with different RGB values fail on assertSimilarGD

[bennothommo]

An issue I've seen crop up from time to time when using this library is when transparent pixels between two images (ie. alpha = 127) have differing RGB values. When viewing the images, they are exactly the same, for example:

Both two images look exactly the same, but the top one has a transparent black background around the edge (RGB 0) and the bottom one has a transparent white background around the edge (RGB 255). Due to the RGB values being different, all these edge pixels are considered different, and thus the threshold of the test has to set to a threshold high enough to cover the percentage of the image that these pixels take up.

I have experimented applying a different colour difference calculation that takes the alpha channel into account when calculating the difference of the RGB channels and basically use a percentage of the RGB values depending on the opacity - for example, at 50% opacity, the RGB values are halved and thus the delta of difference is less, and at 0% opacity, the RGB values are considered to be 0 themselves, meaning not taken into account at all for difference. This started to go into the realm of determining differences based on opacity which might be outside of the scope for this library.

I'm interested to hear your thoughts on whether you would be amenable to a PR that includes such calculations, or if for now, a smaller scoped PR that just ignores RGB values when the pixel is transparent?

[meyfa]

I fully agree that this is an issue. I've run into this in the past as well when writing tests for PHP-SVG. It was an unfortunate design choice to not treat transparent pixels differently.

Any change to the calculations could be considered a breaking change and require a major version bump. There could be scenarios in which even fully transparent pixel colors matter. For instance, when converting to JPEG, the RGB color will be used as a background color. If someone is testing for this right now, their tests would be broken.

However, I do think this is the right path forward. Unfortunately, there are already 4 supported major versions of phpunit-assert-gd and they differ only in their support for PHP and PHPUnit, not their feature set. If any behavioral changes were made, this would have to be a new v5 and couldn't be backported to v1 - v4 unless it was behind a parameter or global flag.

For PHP-SVG, I would most prefer ignoring fully transparent pixel colors while keeping the behavior for any other pixels unchanged. However, if we wanted to add scaling like you propose later, we should try to design it such that there isn't another breaking change, and make this configurable. Since PHP 8.0 named arguments can be used. Therefore, I would propose:

<?php
public function testSomething()
{
    $this->assertSimilarGD('./tests/expected.png', './tests/actual.png', alpha: '<mode>');
}

where <mode> is one of the modes we want to support, such as:

• separate - the current behavior
• visible - compare RGB only for visible pixels
• scale - differences are halved for 50% alpha pixels, etc.
• ignore - completely ignore the alpha component, only compare RGB

The names are open to bikeshedding ;)

If we implemented visible, we would have to consider what happens when only one of the images has a fully transparent pixel but the other does not. Similarly, for scale we would need to decide which logic to apply for differing alpha values between the images.

Do you feel this is a reasonable path forward or does the new argument feel too clunky?

[bennothommo]

Thanks for your response @meyfa. I definitely agree that if we go ahead with something like this, it would be best done in a backwards-compatible way so you wouldn't have to release yet another major update.

I like your idea. As an alternative, we could potentially introduce a concept of a DifferenceCalculator (or other named) class that could be added an additional parameter to assertSimilarGd/assertNotSimilarGd, with in-built calculators for the modes that you specified above, but with the option for people to provide their own for increased flexibility.

eg.

interface DifferenceCalculator
{
    /**
     * Calculates the difference between two pixels at the given coordinates.
     * 
     * This method will be provided with two GDImage objects representing the images being compared, and co-ordinates
     * of the pixel being compared.
     * 
     * The method should return a float value between 0 and 1 inclusive, with 0 being an exact match and 1 being the
     * complete opposite.
     */
    public function calculate(\AssertGD\GDImage $imageA, \AssertGD\GDImage $imageB, int $pixelX, int $pixelY): float;
}

// Default behaviour

class RgbaSimilarity implements DifferenceCalculator
{
    public function calculate(\AssertGD\GDImage $imageA, \AssertGD\GDImage $imageB, int $pixelX, int $pixelY): float
    {
        $pixelA = $imageA->getPixel($pixelX, $pixelY);
        $pixelB = $imageB->getPixel($pixelX, $pixelY);

        $diffR = abs($pixelA['red'] - $pixelB['red']) / 255;
        $diffG = abs($pixelA['green'] - $pixelB['green']) / 255;
        $diffB = abs($pixelA['blue'] - $pixelB['blue']) / 255;
        $diffA = abs($pixelA['alpha'] - $pixelB['alpha']) / 127;

        return ($diffR + $diffG + $diffB + $diffA) / 4;
    }
}

Then, to use it, it would be a case of running:

$calculator = new RgbaSimilarity();
$this->assertSimilarGD('image1.jpg', 'image2.jpg', '', 0, $calculator); //  not specifying a calculator would use the default behaviour class above

[meyfa]

I like that idea! Would you like to send a pull request?