HSBType closeTo working correctly?

[weymann]

I've no expertise in color conversions and maybe I'm just too stupid to handle this corrrectly.

Rationale
I want to introduce the DIRIGERA binding which provides support of color bulbs and color LED strips. I want to use HSBType closeTo comparison in order to check if a command is close to the current state.

• If it's close - don't change device settings
• If not - change device settings

Observation
After manual testing I stumbled over the following values and wrote it into a test

        HSBType colorState = HSBType.valueOf("63,1,33");
        HSBType compareState = HSBType.valueOf("63,100,0");
        System.out.println("Color " + colorState + " Compare " + compareState + " close? "
                + colorState.closeTo(compareState, 0.01));

Output:

Color 63,1,33 Compare 63,100,0 close? true

Hue - fine
Saturation - far away
Brightness - far away
Comparison done with 1% max allowed difference and result is true?

Made some more tests checking each H, S and B value

        HSBType colorState = HSBType.valueOf("100,50,100");
        for (int i = 0; i < 101; i++) {
            HSBType compareState = HSBType.valueOf("100,50," + i);
            boolean close = compareState.closeTo(colorState, 0.01);
            System.out.println("Color " + colorState + " Compare " + compareState + " close? " + close);
        }

Brightness is changed from 0 to 100 with 1% deviation expected.
Result:

Color 100,50,100 Compare 100,50,0 close? false
...
Color 100,50,100 Compare 100,50,53 close? false
Color 100,50,100 Compare 100,50,54 close? true
...
Color 100,50,100 Compare 100,50,100 close? true

Nearly half of the values are close with 1% deviation?

I think you see the pattern. Just play with the values in the loop and see the results:
Changing the Saturation value with allowed difference of 18% nearly all values are closeTo true

Code

        HSBType colorState = HSBType.valueOf("100,50,100");
        for (int i = 0; i < 101; i++) {
            HSBType compareState = HSBType.valueOf("100," + i + ",100");
            boolean close = compareState.closeTo(colorState, 0.18);
            System.out.println("Color " + colorState + " Compare " + compareState + " close? " + close);
        }

Log

Color 100,50,100 Compare 100,0,100 close? false
...
Color 100,50,100 Compare 100,3,100 close? true
...
Color 100,50,100 Compare 100,95,100 close? true
Color 100,50,100 Compare 100,96,100 close? false
...
Color 100,50,100 Compare 100,100,100 close? false

Sidenote
Sorry for the german screenshot. But you can see searching all java files from addons the closeTo function is only used in test code and not in production code which I can use as reference.

[andrewfg]

@weymann the HSBType.closeTo() method only compares the color -- not the brightness (see source code below). More specifically it compares if the two XY coordinates are close to each other on the CIE Color Space. In other words it is comparing only the HS part and not the B.

Furthermore the maxPercentage relates to the maximum delta percentage in XY color space values -- not in percentage of the H or B inputs. (note: the XY scale is 0.0 <= n <= 1.0)

Finally it is worth noting that H values wrap around at 360 degrees -- so a color with H = 359.9 will be close to a color with H = 0.1

   public boolean closeTo(HSBType other, double maxPercentage) throws IllegalArgumentException {
        if (maxPercentage <= 0.0 || maxPercentage > 1.0) {
            throw new IllegalArgumentException("'maxPercentage' out of bounds, allowed range 0..1");
        }
        double[] exp = ColorUtil.hsbToXY(this);
        double[] act = ColorUtil.hsbToXY(other);
        return ((Math.abs(exp[0] - act[0]) < maxPercentage) && (Math.abs(exp[1] - act[1]) < maxPercentage));
    }

---

EDIT: so for your use case I would suggest

private boolean closeToExtended(HSBType other, double maxXYPercentage, double maxBPercentage) {
  return this.closeTo(other, maxXYPercentage) && Math.abs(this.getBrightness().doubleValue() - other.getBrightness().doubleValue()) < maxBPercentage;

}

[andrewfg]

PS apropos your DIRIGERA project: it may well be that the API is anyway separated into two sub-channel commands -- namely the 'color' and the 'brightness'. This is certainly the case of the Philips Hue and several other bindings in OH. This means that you have to split the HS to the API color sub-channel and the B to the API brightness sub-channel. Furthermore the API color sub-channel is probably rendered either as an RGB triplet or as an XY doublet. In both cases the RGB triplet or XY doublet describes the color at maximum brightness and the B part sub-channel attenuates that. Specifically do not fall into the trap of multiplying the RGB triplet by the B brightness, or you will be effectively scaling the brightness twice, which results in a very non linear performance, and an absolute mess over round trips.

PPS when your code is on GitHub please send me a link and I shall be happy to coach you. => EDIT: I found it..

[weymann]

HSBType.closeTo() method only compares the color -- not the brightness (see source code below). More specifically it compares if the two XY coordinates are close to each other on the CIE Color Space. In other words it is comparing only the HS part and not the B.

That would be great. TRADFRI bulbs/LEDs needs to split up Color / Temperature and Brightness API calls. Would be perfect to have a color matching function!

Just Unit Test show different. Brightness is affecting XY values using unit testing on OH 4.3.x baseline

Test code

    @Test
    void test() {
        HSBType colorState = HSBType.valueOf("100,50,100");
        for (int i = 1; i < 101; i++) {
            HSBType compareState = HSBType.valueOf("100,50," + i);
            boolean close = compareState.closeTo(colorState, 0.01);
            System.out.println("Color " + colorState + " Compare " + compareState + " close? " + close);
            System.out.println("Color XY   " + ColorUtil.hsbToXY(colorState)[0] + " " + ColorUtil.hsbToXY(colorState)[1]
                    + ColorUtil.hsbToXY(colorState)[2]);
            System.out.println("Compare XY " + ColorUtil.hsbToXY(compareState)[0] + " "
                    + ColorUtil.hsbToXY(compareState)[1] + " " + ColorUtil.hsbToXY(compareState)[2]);
            System.out.println("###");
        }
    }

Log Snippet

Color 100,50,100 Compare 100,50,1 close? false
Color XY   0.2976771874773136 0.51737018653883660.7927534058941139
Compare XY 0.3191818298851971 0.4147860758888785 6.822983746093411E-4
###
...
Color 100,50,100 Compare 100,50,53 close? false
Color XY   0.2976771874773136 0.51737018653883660.7927534058941139
Compare XY 0.2999331840332822 0.5071350599622351 0.1941539860502492
###
Color 100,50,100 Compare 100,50,54 close? true
Color XY   0.2976771874773136 0.51737018653883660.7927534058941139
Compare XY 0.29985049766495686 0.5075194958799395 0.2021501438928547
###
...
Color 100,50,100 Compare 100,50,100 close? true
Color XY   0.2976771874773136 0.51737018653883660.7927534058941139
Compare XY 0.2976771874773136 0.5173701865388366 0.7927534058941139
###

[weymann]

PS apropos your DIRIGERA project: it may well be that the API is anyway separated into two sub-channel commands -- namely the 'color' and the 'brightness'.

I had already fruitful discussion in community ff whre split according to HUE binding is done with separation of ON/OFF switch, brightness, temperature and color channel is done

[andrewfg]

split according to HUE binding is done with separation of ON/OFF switch, brightness, temperature and color channel is done

I think you did not understand what I was saying. I was not referring to the split within OH (where I also had a huge discussion about it) but rather the split of commands within the Dirigera API..

[andrewfg]

Unit Test show different. Brightness is affecting XY values

I will look at it tomorrow..

[andrewfg]

^
Ok. It is indeed correct that the B input does effect the XY values. It is also correct that closeTo does only compare the XY values. Both these statements are true and correct.

So your use case could/should compare the HS100 values (via closeTo) AND the xxB values.