Godot: Wrong definition and formula for Color.contrasted()

[hazarek]

Doc description;

Color.contrasted()
Returns the most contrasting color.

Opposite color(complementary color) do not mean that the contrast is high. The contrast of the two hue is measured by relative luminance.

I don't know what this formula calculates (it looks like complementary colors) but it's certainly not contrast.
https://github.com/godotengine/godot/blob/27763b67bb63139319bf611590c40e48663e72d6/core/color.cpp#L220

void Color::contrast() {
    r = Math::fmod(r + 0.5, 1.0);
    g = Math::fmod(g + 0.5, 1.0);
    b = Math::fmod(b + 0.5, 1.0);
}

A Python library for computing contrast ratios, as required by WCAG 2.0.
https://github.com/gsnedders/wcag-contrast-ratio

I found this so maybe it would be useful.
https://gamedev.stackexchange.com/questions/38536/given-a-rgb-color-x-how-to-find-the-most-contrasting-color-y

[Ev1lbl0w]

I made a visualization of the color changes from those methods and the formula from the linked Stackexchange post, to aid with discussion:

From what I can see, .contrasted() does not make complementary colors; .inverted() does.

[hazarek]

"most contrasting color" this sentence is ridiculous. Most of the internet is filled with false information.
You can get the opposite of a color with any color model. But you cannot get the most contrast color. A color has more than one pair at the same contrast ratio. Contrast ratio measurement algorithm is available in the repository I shared above.

I think the name and formula should change from Color.contrasted() to Color.inverted().
The formula is very simple for HSV (Hue + 180) % 360

[Ev1lbl0w]

Godot already has the inverted method which effectively swaps the color to it's complementary. And I agree: I'm not seeing the usefulness of the contrast method. From what I've seen the code hasn't been changed since the _dawn of Godot_ (the first commit), so it might indeed be something laying around and long forgotten :stuck_out_tongue:

[hazarek]

Godot already has the inverted method which effectively swaps the color to it's complementary.

I have not noticed, sorry. Formulas and descriptions need to be approached more scientifically. I reviewed Godot's color methods now. Godot's descriptions do not give confidence.

[clayjohn]

@hazarek some of the descriptions indeed need work. The focus in the past was on getting _something_ in the class reference for each method. However, many methods lack clarity or depth.

If you understand how the method descriptions can be improved, please make suggestions here or, preferably, in a PR

[Calinou]

PS: Replacing or removing the constrated() method should be debated in a proposal.

[hazarek]

PS: Replacing or removing the constrated() method should be debated in a proposal.

The discussion has already been done here and it's over.