Discussion: Color Class Methods

[WestLangley]

Description

Color classes often have methods such as lighten(), darken(), saturate(), desaturate().

Such methods are guaranteed to result in another valid color.

three.js, on the other hand, includes some Color methods that are more appropriate for a Vector class, and they do not necessarily result in a valid color.

Many of these methods are not used often, it appears, but I assume there would be little support for removing them.

So in that context, it is reasonable to discuss if clamping should be added to any of the following Color methods to ensure the color components remain in the [ 0, 1 ] range.

method	clamping	example use case
offsetHSL( h, s, l )	calls setHSL, which clamps	used in many examples
add( color )	needs clamp	_color.multiply( _diffuseColor ).add( material.emissive )
addColors( color1, color2 )	needs clamp	not used in the library
addScalar( s )	needs clamp	multiplyScalar( 0.5 ).addScalar( 0.5 )
sub( color )	maxes with zero only	not used in the library
multiply( color )	OK, only darkens	_color.multiply( _diffuseColor ).add( material.emissive )
multiplyScalar( s )	guaranteed OK if 0 < s < 1	.multiplyScalar( 0.5 ).addScalar( 0.5 ) )
setScalar( scalar )	OK if 0 < scalar < 1	color.setScalar( 0.1 + 0.9 * Math.random() )

Comments requested.

Solution

Clamp to ensure valid colors are returned.

Alternatives

Do nothing, using the argument that three.js does not validate inputs.

Additional context

No response

[WestLangley]

color.lerpColors( color1, color2, 0.5 ) is fine. There is nothing wrong with this method.

color.addColors( color1, color2 ).multiplyScalar( 0.5 ) will produce an unexpected result if clamping is added.

This shows why addColors() is not an appropriate method. It is arguably better to remove it than to patch it by clamping.

Similar arguments can be made for the other methods that generate invalid colors.

I am not a fan of removing methods, but TBH, these methods should never have been added in the first place.

[gkjohnson]

Is it still the case that rgb can only be assigned values [0, 1]? It may have been the case when the values were specified as sRGB but they are now linear colors. It's often the case when doing calculations that you'll wind up with color outside the [0, 1] range and that should be considered valid. Eg averaging colors, calculating lighting and intensity, losslessly converting between color spaces, etc. I'm not sure if I agree that these functions should enforce clamping.

[WestLangley]

Of course, the output of a shader can have RGB values greater than 1. Those values represent luminance (cd / $m^2$), and are rendered to a texture, for example.

The Color class is also RGB-valued, but represents a color within a color space. It is unit-less, and in [ 0, 1 ] when in-gamut.

You are correct, that when converting between color spaces you can get RGB values outside of [ 0, 1 ], and that, indeed, is a reason not to clamp values. Proper gamut-mapping would be required to bring those values into the valid range.

Related: CSS Color Module Level 4

[gkjohnson]

The Color class is also RGB-valued, but represents a color within a color space. It is unit-less, and in [ 0, 1 ] when in-gamut.

If trying to emulate color operations on the CPU that are being done on the GPU or doing something like performing CPU ray tracing for light maps, probes, etc I would be expecting to use the Color class and have done so in the past when working on this kind work. Though I do understand the use for things like materials is to define a color within a color space rather than capture any kind of intensity.

Is using the the Color class to calculate an "average" color something you consider invalid?

[WestLangley]

Correct. The color class is not intended to represent luminance values. It is designed to represent a color.

TBH, I have likely performed similar calculations on the CPU to validate GPU operations. I think Vector3 would be the proper javascript class to use in that case.

Is using the Color class to calculate an "average" color something you consider invalid?

No. Please see my second post above.

[boytchev]

Sometimes I use color components outside their default range to get effects that are otherwise harder to achieve (e.g. neon colors or negative lights). Although physically unnatural and not conforming to any color model, such colors may have their own aesthetic merits.

Would it be feasible to make colors use internally xyz and set rgb as synonyms of xyz (with getter/setter)? This will make THREE.Color and THREE.Vector3 compatible.

Then THREE.Color may be stripped off by all math methods (e.g. color*scalar), and be enriched by color methods (e.g. darken). So users that need to work with colors as colors may use THREE.Color's methods; and users that want to do some math magic with colors may use THREE.Vector3 instead.

[donmccurdy]

I do like the idea of reorganizing or trimming methods available for THREE.Color, and — maybe especially — of making explicit which methods assume a closed domain [0, 1] or some particular meaning of 1.0. A ColorUtils class could be helpful.

However, I do not think I agree on the goals and reasoning suggested. Particularly, the distinctions below may be incorrect or artificially limiting:

The color class is not intended to represent luminance values. It is designed to represent a color.

The Color class is also RGB-valued, but represents a color within a color space. It is unit-less, and in [ 0, 1 ] when in-gamut.

RGB is a relative encoding of three stimulus values. Relative is important, and relative to what depends on context. One part of that is color space. But additionally, consider these (non-exhaustive) contexts:

1. For output to a canvas or display, RGB values encode a relationship to the display medium, typically [0, 1]
2. For diffuse reflectance color, RGB values encode a fraction, within theoretical limits reflectance, [0, 1]
3. For emissive color, RGB encodes a relationship to a unit of measurement, [0, ∞]

Using RGB values authored for one context in another would be a mistake. Even for the display-referred color and the diffuse reflectance, they are not the same thing, even if their limits are both [0, 1], as 1.0 means something else.

RGB values in our rendering pipeline (e.g. luminance) are still tristimulus values encoded with a color space: having primaries, white point, and a linear transfer function. I think we'd be adding unnecessary confusion by trying say they are not color. I would also not equate “in gamut“ and “valid”. Validity has meaning only in context.

As far as the methods though, I am open to ideas, but I would not privilege the display-referred case in that choice, please! :)

[WestLangley]

@donmccurdy I think you are conflating the vec3 output of a shader with the JavaScript Color class.

A few comments, in no particular order:

1. In the shader, we call it a color for convenience, but it is a vec3 and has physical units -- luminance for example. It is also unbounded, if it is not tone mapped.

2. In the shader, after tone mapping, the output is a code value, nominally in [ 0, 1 ].

3. On the JavaScript side, Color represents a color, and it is unit-less. It can only represent unit-less properties -- diffuse reflectance, for example..

4. In the case of emission, it is material.emissiveIntensity that has the physical light units; material.emissive is a color.

5. If I read CSS Color Module Level 4 correctly, it says colors outside the intended range are not invalid, but are clamped when accessed -- or used in a function. That may be a solution to my concerns stated in my original post: clamp the inputs, not the output.

6. You are correct about not equating “in gamut“ and “valid”. :-)

7. And yes, as I suggested here, I think our design would benefit by adding a colorSpace property to the color class.

[donmccurdy]

The RGB color model is a vec3 encoding of stimulus. Whether it is unitless or has physical units, is bounded or unbounded, is tone mapped or not, does not (I think) affect whether we may use the RGB color model. It's all RGB stimulus. Even at the display, it is still just stimulus, imperfectly modeling (and hoping to evoke) a perceptual concept, color, that does not truly exist outside of our heads.

By the CSS Color Module Level 4 definitions, diffuse reflectance in a PBR material is not color, either. While it is unitless, it is not “a definition ... of the human visual perception of a light or a physical object illuminated with light.” But for our purposes, diffuse reflectance and environment lighting are stored in RGB textures, those textures are associated with known color spaces, and we need to work with them as such. I think we may need a broader view of color than CSS provides, to communicate much about physically-based rendering.

That said, if we want to be very precise with our terms, I do agree with you, and would go even further — none of this is really color, and terms like "RGB coordinates" or "tristimulus" would be more descriptive and accurate. I'm not sure that is practical... but I think neither is splitting the uses of RGB stimulus in half and calling only one half color, if that makes sense? 😅

Just hypothetically ... if THREE.Color were renamed THREE.RGB, might we agree that it need not be unitless?

[WestLangley]

Thank you for your reply!

Yes, (unbounded) HDR environment lighting is stored in textures, and the stored data represents luminance.

Sorry, but it is not clear to me what the output from a shader -- or what is stored in a texture -- has to do with the three.js Color class. Perhaps I am not understanding what you are trying to convey...

I simply stated, in my original post, that the Color class has valid data in [0, 1], and IMHO, some of the methods included in the class were inappropriate.

three.js/src/math/Color.js

Lines 217 to 226 in d9a24af

	/**
	* Sets this color from RGB values.
	*
	* @param {number} r - Red channel value between `0.0` and `1.0`.
	* @param {number} g - Green channel value between `0.0` and `1.0`.
	* @param {number} b - Blue channel value between `0.0` and `1.0`.
	* @param {string} [colorSpace=ColorManagement.workingColorSpace] - The color space.
	* @return {Color} A reference to this color.
	*/
	setRGB( r, g, b, colorSpace = ColorManagement.workingColorSpace ) {

//

This post was prompted by a line of code I saw recently, similar to the following:

material.color.set( 100, 50, 0, colorSpace );

That is out-of-range for ColorManagement, so I felt it was important to discuss exactly what the Color class represents.

three.js/src/math/Color.js

Lines 226 to 232 in d9a24af

	setRGB( r, g, b, colorSpace = ColorManagement.workingColorSpace ) {
	this.r = r;
	this.g = g;
	this.b = b;
	ColorManagement.colorSpaceToWorking( this, colorSpace );

[donmccurdy]

Sorry, but it is not clear to me what the output from a shader -- or what is stored in a texture -- has to do with the three.js Color class.

In terms of what we currently need to do internally within the three.js library, yes, almost all operations in the open domain working color space are done in shaders. But in user application-space, I don't think that division of usage is so simple. Any operation we might do to RGB values on the GPU should be possible on the CPU, ideally, for tasks like light baking on CPU. I feel that THREE.Color is the correct representation of RGB stimulus values, regardless of open or closed domain, pre- or post-tone mapping.

The color grading methods you mention in the OP are a great example — the set of color grading methods suitable for closed-domain RGB values are just a subset of the grading methods that a production-quality color grading API would offer, and it's common to apply some grading before tone mapping.

Certainly configuring MeshStandardMaterial#color with RGB values outside [0, 1] should still be considered invalid, no disagreement there, I just wouldn't extend that to the THREE.Color class in general.

That is out-of-range for ColorManagement...

I think that's something we can decide. Admittedly I'd much prefer to avoid gamut mapping in THREE.ColorManagement, but clamped or unclamped conversions are still useful. We could technically support “Extended sRGB” without major changes (though I do have major reservations about that).