Lookup Table's Lut.getColor() should use Math.floor instead of Math.round

[dcriado]

Describe the bug

In Lut.getColor(), once the input value is converted into an alpha between 0 and 1, alpha is multiplied by the number of colors to assign it an index, and then rounded to the nearest integer using Math.round.

I think this might be wrong, as alpha should be rounded to the nearest integer below, using Math.floor.

Otherwise, values that fall under a color i but are closer to its border with the color i+1 will eventually be assigned the color i+1.

Here is the referred line in the source code:

three.js/examples/jsm/math/Lut.js

Line 108 in cd4f4e7

let colorPosition = Math.round( alpha * this.n );

To Reproduce

See code snippet below.

Code

import { Lut, ColorMapKeywords } from 'three/examples/jsm/math/Lut';

const colormap = ColorMapKeywords.rainbow;
const lut = Lut( colormap, 6 );
    
lut.setMax( 100.0 );
lut.setMin( 0.0 );
    
// This value gets a correct color
// alpha = 0.7
// alpha * nrColors = 4.2
// getColor picks this.lut[4]
const a = 70;
const colorA = lut.getColor( a );

// This value gets a wrong color
// alpha = 0.6
// alpha * nrColors = 3.6
// getColor picks this.lut[4] instead of this.lut[3]
const b = 60;
const colorB = lut.getColor( b );

Screenshots

Maybe this schematic helps to illustrate my point:

Platform:

• Device: Desktop
• OS: Linux
• Browser: Firefox
• Three.js version: r137

[Mugen87]

Your proposed change makes sense to me. However, while debugging this case I've stumbled across the following.

When setting up the lookup table like above:

const lut = Lut( colormap, 6 );

The internal color array (the lut property) has actually seven entries although n is six. According to the code in getColor() the last entry is actually never selected. Is that an error, too?

[dcriado]

Definitely something is odd when setting up the lookup table:

Expand to see cases from n=1 to n=10.

I was setting an example with n=6 because I am currently using n=12 and I wanted to simplify my case.

The thing is that Lut(colormap, 12) does return 12 colors. But n=6 does not! My apologies for not checking this beforehand.

I will look into the method setColorMap to see what is causing these discrepancies.

three.js/examples/jsm/math/Lut.js

Line 47 in cd4f4e7

setColorMap( colormap, count = 32 ) {

[scurest]

three.js/examples/js/math/Lut.js

Lines 46 to 60 in f6e6fa1

	const step = 1.0 / this.n;
	this.lut.length = 0;
	for ( let i = 0; i <= 1; i += step ) {
	for ( let j = 0; j < this.map.length - 1; j ++ ) {
	if ( i >= this.map[ j ][ 0 ] && i < this.map[ j + 1 ][ 0 ] ) {
	const min = this.map[ j ][ 0 ];
	const max = this.map[ j + 1 ][ 0 ];
	const minColor = new THREE.Color( this.map[ j ][ 1 ] );
	const maxColor = new THREE.Color( this.map[ j + 1 ][ 1 ] );
	const color = minColor.lerp( maxColor, ( i - min ) / ( max - min ) );
	this.lut.push( color );

For some n, i will be exactly 1 at the end of the loop, but some will only be close to 1

> a = 1/6
> a+a+a+a+a+a
< 0.9999999999999999
> a = 1/5
> a+a+a+a+a
< 1.0

If i >= 1 at the end, then the second condition in the if is never true, so an element isn't pushed to lut on the last i=1.0 iteration. But if i<1 at the end, the last iteration does push an element.

That's why lut is only sometimes different by 1.

[scurest]

Thinking more about it:

There are two obvious ways to do this. One is to divide the interval into n equal pieces and store the sample at the midpoint of each piece in lut[k]. In this case you would use the floor just like OP said, floor(n*alpha). You would also use lut[n-1] instead of lut[n] (which the current code does).

(Pink dots are the sample locations, gray crosses are where it switches from one bucket to the next).

---

The other way is to sample at the points 0, 1/n, 2/n, ..., (n-1)/n, 1. This creates n+1 segments (note the first and last are half the size of the others).

The current code is sampling at these points, right? So it should be doing this. Since the lut[k] bucket holds the color sampled at the point k/n, you would want to use the k bucket when alpha is closer to k/n than to (k-1)/n or (k+1)/n. That's the range [k/n - 1/2n, k/n + 1/2n), or multiplying by n, the range [k - 1/2, k + 1/2). This makes round correct.

However if this is the intent of the current code, there are two problems. There should always be n+1 buckets in lut, and the lut[n] bucket should be used (it should not use lut[n-1] instead).

AFAICT combined these mean the only visible problem is when sampling near alpha=1, sometimes the color at 1-1/n is returned when the color at 1 should be.

[scurest]

Well now that I think about it, of those two ways, only the first one makes sense for updateCanvas since pixels are equal-sized.

I don't really understand the canvas code. It uses this.n for the height? Is the purpose to visualize the contents of this.lut? But then why does it do its own lerping loop instead of reading this.lut?

[Mugen87]

The method seems to require a rewrite, too. However let's solve the sampling bugs first in #23589 before working on the next topic.

[scurest]

Well I was thinking depending on what the goal for writing to a canvas is, it might affect which sampling method you would want to use.

[sngazm]

Sorry to rehash a discussion that has ended. I was confused trying to use Lut for data visualization in my project and came across this issue.

After reading the documentation, the behavior I expected was to divide a given range evenly into count number of sections and assign a color to each section.

However, it appears that count + 1 sections are actually generated, with the first and last sections having a narrower range than the others.
(Just like the second image uploaded by @scurest ).

I want to visualize a lot of data in groups of 3 or 5 smaller numbers, so I want each section to be equally divided. For what purpose is this spec'd out?