Example of "colour.RGB_to_XYZ" has value outside [0, 1].

[shanest]

In the docstring for RGB_to_XYZ, it's noted that values should be in [0,1]:
https://github.com/colour-science/colour/blob/master/colour/models/rgb/rgb_colourspace.py#L871

But in example_models.py, the one example of using this function provides a value > 1:
https://github.com/colour-science/colour/blob/master/colour/examples/models/examples_models.py#L71

This seems inconsistent and caused me some confusion: I wanted to confirm the presumed ranges for RGB values after seeing this example, and so had to do some detection. Perhaps the example should be fixed.

[KelSolaar]

Hi @shanest,

This is a very good point and something we should improve, so basically there are a few things at play here:

• The documentation is not exact in the sense that you can have RGB high dynamic range values that will go beyond 1, and you might also have out of gamut RGB values that will be negative and must be kept in order to not clip your data. We need to find a good way to convey that.
• Colour science in general is very inconsistent in the way it deals with representation, some algorithms are working with percentages usually in domain [0, 100], e.g. colour.spectral_to_XYZ, or colour.colorimetry.lightness_Glasser1958, some others are working with scalars typically in domain [0, 1] and Munsell value using [0, 10]. We have discussed about it in About a common computations domain. #125 but I still think it needs improvements beyond the metadata stuff.

@MichaelMauderer : Any new thoughts about this?

[nick-shaw]

Input *RGB* colourspace array is in domain [0, 1] suggests "constrained to the range 0-1" but really it means it is normalised to that range. Values outside that range are still valid and meaningful. An sRGB value >1 represents a luminance higher than the peak white of an sRGB display, and while it cannot be shown on that display, it is meaningful to use in HDR calculations.

[MichaelMauderer]

I agree that the terminology might be confusing and we have to clarify somewhat. I also remember we agonised about the terminology here quite a bit in the past...
Nick nicely explains the problem here. Maybe replacing "domain" with "normalised to" or "normal domain" might already help a great deal.

I think in the long term it makes a lot of sense to be consistent across the API. But getting there without adding confusion and problems along the way is tricky. These changes can go undetected easily and start so subtly (or not so subtly) break code.

Would it a good idea to actually have a parameter that indicates the "domain" of the values going into a function? That would allow us to document the current behaviour through the default value for that parameter, but also shift the default in a future release. The parameter could start None or some "default guard", triggering the current behaviour and then at some point starts giving a deprecation warning in anticipation of a behaviour change.

At the same time, we could have a flag that enables/disables warnings for out of "normal range" values, making it easier to spot mistakes (and add explanation in cases like this about what's going on)

[KelSolaar]

These changes can go undetected easily and start so subtly (or not so subtly) break code.

Yes absolutely.

I think in the long term it makes a lot of sense to be consistent across the API.

I was thinking about it again and it is really hard to settle on what is consistent. As an example, the various Lightness and CIE Lab* functions output Lightness as a percentage, and somebody would be super confused if we were to divide their output by 100. I was looking Bruce Lindbloom calculator by curiosity and he does not really have a solution for this precise problem either:

Using XYZ = [1, 1, 1]

Notice how CIE XYZ, CIE xyY and RGB are expressed as numbers but the others are percentage. He has however Scale checkboxes and this is really what it is about here. I think I remember that this is the term I originally cherry picked for the metadata branch to represent this but we are currently using extent
because we have start and end to do a linear conversion.

PS: I noticed that the Fairchild (201*) Luminance and Lightness definitions docstrings need update.

[MichaelMauderer]

You are right. It would also be problematic to break with common conventions and definitions.

Maybe we should try to get an overview of all the different approaches in use right now.

[KelSolaar]

@MichaelMauderer : There is actually a non-up-to-date spreadsheet here: https://docs.google.com/spreadsheets/d/1lYQgMcwCrToc5A76r2VYkRS5NQtu4BmPviQzzd6p1QM/edit?usp=sharing

[KelSolaar]

So trying a few things:

Original

Input RGB colourspace array is in domain [0, 1].

A

Input RGB colourspace array is in normal domain [0, 1].

B

Input RGB colourspace array is normalised to domain [0, 1].

C

Input RGB colourspace array is an array of scalar values relative to 1.
Input RGB colourspace array is an array of percentage values relative to 100.
Input RGB colourspace array is an array of scalar values relative to 10.

@MichaelMauderer , @nick-shaw : Any other forms or comments appreciated :)

[KelSolaar]

We have settled on B.