Options for more control over rounding

[jorenbroekema]

In my opinion the current precision option in the Color.toString() method is very unintuitive.

E.g. I can have rounding issues with a low precision if my value is high. For example, a precision of 1 is not a problem when my lightness is 1%, but it is a problem when it is 95% because it would be rounded to 100%.

It would be much more intuitive if precision would dictate the amount of digits after the decimal point.

In case you disagree, coz I can imagine there's a reason for the current behaviour, can we then perhaps add a different option e.g. "decimals" to specify the amount of decimals (under the hood it would probably just do Number.toFixed(decimals))?

I'm happy to contribute

[facelessuser]

It would be much more intuitive if precision would dictate the amount of digits after the decimal point.

What you are describing is more about requesting the setting of scale.

[facelessuser]

Precision is the number of digits and scale is the number of digits after the decimal point. Some would argue that precision should be the number of significant digits, but color.js also limits the scale to whatever is set for precision, but it does not currently allow a way to explicitly set and control the scale.

[jorenbroekema]

Yeah I can imagine that we'd want to keep precision as is, but a secondary decimals/scale option would be nice. Of course, the decimals/scale would be constrained by the precision, e.g. 12.3456 with { precision: 2, decimals: 3 } would output either 12.000 or 12 and not 12.346, I'm kinda impartial to whether the amount of decimals is respected in the case of 0s or if it's shortened to fewer decimals where possible, I'm personally leaning towards shortening where possible so the output would be 12.

Edit FWIW, the reason why I would lean towards shortening where possible, this is JS' behavior for parsing a float 🤷‍♂ kinda makes sense to me:

[DarioSoller]

I also stumbled over the precision and decimal behaviour, especially when mixing colors.

So for example having

const color = new Color('#ffffff');
const mixColor = new Color('#000f39');
new Color(color.mix(mixColor, 0.0625, { space: 'srgb' }).toString({ precision: 10 })

results in: rgb(93.75% 94.11764706% 95.14705882%)
So the precision currently does have an influence on the decimals.

Also with mixing colors in the HEX format I noticed, that when I have a mix color calculation, that with precision 4 is #c2c5d0 , for precision 2 this will be #c2c4cf and for precision 1 this will be #ccc and for precision 0 this even is #fff, which also came to a surprise for me.

I hope this helps in the discussion, in order to find a good solution, that works for everyone?

[facelessuser]

Normally, when libraries give access to scale an precision it would work more like: { precision: 5, scale: 3 }: 12.12345678 -> 12.123. Number of digits 5 where the scale is 3. precision and scale usually have specific meaning. I'm not sure exactly what color.js is willing to do in this area and specifically what kind of allowance of control they want to give, but I'll let others chime in.

[LeaVerou]

I think scale is very confusing in this context, I would expect scale to be around changing the range itself. I think decimals is a more natural name for this, and I agree it’s useful too. That’s why Intl.NumberFormat supports both. I believe we use Intl.NumberFormat under the hood so this should be an easy fix. I can’t remember how that API handles it if both are specified, if it errors we need to prevent that.

[facelessuser]

I think scale is very confusing in this context, I would expect scale to be around changing the range itself. I think decimals is a more natural name for this, and I agree it’s useful too.

That's fine, I'm using more common terminology, but I do see "decimal" is used as an option in Intl.NumberFormat.

[facelessuser]

I don't see that we are using NumberFormat. Precision is calculated here: https://github.com/color-js/color.js/blob/main/src/util.js#L65C1-L77C1. Anyway, a different approach can certainly be used. I think the approach just needs to be well defined.

[facelessuser]

I think there are probably a number of confusing things. When we talk about precision, we are normally talking about significant digits, but that is not what Color.js returns. Precision in Color.js simply means the number of digits, not significant digits. So very, very small numbers such as 0.000000001, with a precision of 5, would simply yield 0, not 1.0000e-9. Also, it can be noted we trim trailing zeros so 100 is just 100, not 100.00.

It seems Color.js, as it is coded currently, is not concerned about significant digits, so really, really small values are just 0, and there isn't any effort to ensure that the precision of trailing zeros.

I imagine a fractional decimal option could be added, but we would need to define what that means. I imagine we could have it simply be that first the number is rounded to the specified fractional decimal and then our current precision is applied. So as long as precision supports the the full decimal number range of your fractional decimal count, you could apply that and the precision. So with {precision: 5, decimal: 2}: 100.023456 -> 100.02 and 0.0123456 -> 0.01.

[jorenbroekema]

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#digit_options

This is an interesting read.

It seems that "precision" in ColorJS corresponds with maximumSignificantDigits, there seems to be no minimum/maximum fraction digits, and there's also no minimumSignificantDigits (trailing 0s after the decimal point are stripped from what I can tell) at least from the code https://github.com/color-js/color.js/blob/main/src/util.js#L65 that seems to be the case, it doesn't seem to use Intl API directly though.

If I'm not mistaken, serializeNumber util https://github.com/color-js/color.js/blob/main/src/util.js#L32 could essentially be replaced in its current state by:

return Intl.NumberFormat('en-US', {
  useGrouping: false,
  maximumSignificantDigits: precision,
}).format(n);

To summarize minimum/maximum Fraction/Significant digits, the fraction digits either constrains or enforces a higher precision after the decimal point of a number, and the significant digits either constrains or enforces a higher precision of the number in its totality, so that means the digits before and after the decimal point. While significant digits are indeed more related to precision and fraction digits more to accuracy, there is a bit more nuance to this, and I'll try to explain why it's so confusing to translate precision directly to maximumSignificantDigits.

What's fundamentally confusing about using the term "precision" here is that this happens to be also be a mathematical term that behaves differently compared to ColorJS' precision option.

Examples:

• 100 has a precision of -2 in math, 1000 a precision of -3. But, in ColorJS, 100 has a precision of 2, 101 would be rounded to 100. This is not what I would expect
• 12.3 has a precision of 1 in math (1 digit after decimal point), 123.4567 has a precision of 4. But, in ColorJS, 12.3 would count as a precision of 3, and 123.4567 would only be achievable with a precision of 7.

Another way to look at it is through this table, implied precision in numbers meaning what type of increment would be significant for the number.
Then the "resolved" precision (the mathematical term) can be summarized as the amount of digits after the decimal, or if it's a whole number, it's the amount of trailing zeros * -1, because a trailing zero makes it less precise.

number	implied precision in numbers	precision
12.3450	0.0001	4
12.34	0.01	2
12.3	0.1	1
12	1	0
120	10	-1
123	1	0
123000	1000	-3

I think to avoid all this confusion, the best course of action is changing the precision option to match the mathematical term in behaviour.
You can reach that pretty easily by just setting both the minimum and maximum fraction digits to the precision value using Intl.NumberFormat. You would have to create a small wrapper around it for negative precision values (if you want to support that, that is). What it would do when using a negative precision, is format the number using 0 precision first (so no fraction digits) and then converting digits before the decimal point to 0, depending on the negative precision. 1234 with -2 would be 1200. so 2 digits left of the decimal point are converted to be a trailing 0.

Let me know if this all makes sense.
I'd be very happy to get a PR started and see how many tests I end up breaking with it and see what the impact of such a "breaking change" would be if we align the precision option with the mathematical definition.

Also happy to hear alternatives of course. Just giving my point of view after reading up on Intl's NumberFormat options and digging into the mathematical perspective of it all.

[facelessuser]

I don't personally agree with this "math" definition, but would generally lean towards the scientific use in engineering etc.: https://simple.wikipedia.org/wiki/Arithmetic_precision.

This may be because I am an engineer, but this makes more sense to me.

[facelessuser]

This is probably what is compatible with what we have now:

Intl.NumberFormat(
  'en-US',
  {
    useGrouping: false,
    maximumSignificantDigits: precision,
    maximumFractionDigits: precision,
    roundingPriority: 'lessPrecision'
  }
).format(n)

If you gave control over maximumFractionDigits, you could limit the fractional part as well in a similar manner to what I described earlier.

This would give a backwards compatible approach that can better control fractional parts. I'm not sure how I feel about completely upending precision handling for a completely new approach, but others may disagree. That's just my personal opinion though, the project may want to go in a different direction.

[lloydk]

This is probably what is compatible with what we have now:

Intl.NumberFormat(
  'en-US',
  {
    useGrouping: false,
    maximumSignificantDigits: precision,
    maximumFractionDigits: precision,
    roundingPriority: 'lessPrecision'
  }
).format(n)

I think you might need to add roundingMode: "halfCeil".

In The serialization section of CSS Color Module Level 4 there are a bunch of places where it is specified that:

Values must be rounded towards +∞

And if you follow that link you'll eventually get to:

Unless otherwise specified, in the CSS specifications rounding to the nearest integer requires rounding in the direction of +∞ when the fractional portion is exactly 0.5. (For example, 1.5 rounds to 2, while -1.5 rounds to -1.)

[lloydk]

It seems that "precision" in ColorJS corresponds with maximumSignificantDigits, there seems to be no minimum/maximum fraction digits, and there's also no minimumSignificantDigits (trailing 0s after the decimal point are stripped from what I can tell) at least from the code https://github.com/color-js/color.js/blob/main/src/util.js#L65 that seems to be the case, it doesn't seem to use Intl API directly though.

In The serialization section of CSS Color Module Level 4 there are a bunch of places where it is specified that:

Trailing fractional zeroes in any component values must be omitted; if the fractional part consists of all zeroes, the decimal point must also be omitted.

[facelessuser]

I think you might need to add roundingMode: "halfCeil".

Good call.