Quaternion.setFromUnitVectors precision issues

[nkallen]

Related issue: #21477

Description

Quaternion.setFromUnitVectors uses the dot product and Number.EPSILON to test if two vectors are antiparallel. I think Number.EPSILON is too precise -- it basically means any floating point operations on the input vectors will fail the antiparallel test. The dot product introduces its own numerical error. Number.EPSILON is typically used to determine if two float numbers are effectively identical within floating point resolution, not that they are within a reasonable geometrical tolerance (i.e., after a small number of operations such as addition, multiplication, etc).

There are perhaps other ways of testing this (like not using dot product) and a more reasonable epsilon (2 * 10 * Number.EPSILON) or we can take other geometry libraries as a reference (1e-11 radians is angular precision in Parasolid for example; however we don't want to involve cosines here).

But just like as an example of how Number.EPSILON probably should not be used:

console.log(1-((1+1.111)-1.111) < Number.EPSILON) // false

Reproduction steps

Please see attached code

Code

const Z = new THREE.Vector3(0,0,1);
const a = new THREE.Vector3(0, 2.2204460492503128e-16, -0.9999999999999996);
const q = new THREE.Quaternion().setFromUnitVectors(Z, a);

console.log(new THREE.Vector3(0,0,1).applyQuaternion(q));
Vector3 {x: 0, y: 0.7999999999999998, z: 0.6000000000000001} // this seems implausible to me

Live example

• jsfiddle-latest-release WebGLRenderer

Screenshots

No response

Version

r175

Device

No response

Browser

No response

OS

No response

[WestLangley]

Number.EPSILON is not the right constant to be used here.

I'd restore it to the value I set previously -- or a marginally less-conservative tolerance (i.e., smaller value) if your testing justifies it.

FYI, here are two other implementations:

https://github.com/toji/gl-matrix/blob/1f872b805677dbc006a07ee901f8fdb39fc35c4d/src/quat.js#L699

https://github.com/aforsythe/IlmBase/blob/2281d385361eab29972abb7ba992f89d33cb9780/Imath/ImathQuat.h#L703

[nkallen]

Hi, yes, I do think Number.EPSILON is the wrong choice (it's not motivated by considerations of the limits of floating-point math).

If I may politely suggest: In the short term, set it back to a plausible value (1e-6 is fine, I won't really complain, but it should probably be smaller as I'll explain below).

In the long term, it might be a good idea to review all uses of numerical tolerance in the core math classes, ideally with an expert (but maybe o3 is knowledgable enough), and set a consistent policy, just like you guys did with color spaces last year.

One consistent policy I'm familiar with from Parasolid is to use two GEOMETRIC tolerances: they use a positional tolerance of 1e-8 units and an angular tolerance of 1e-11 (note: these are too tight for threejs). Then every function doing a floating-point comparison needs to compare positions or angles and not just unitless numbers.

For example, here the antiparallel test would test either an angle Math.acos(vectora.dot(vectorb)) or a distance vectora.clone().add(vectorb).length(). In practice, you don't want to use trigonometric functions OR square roots, so you would really do vectora.clone().add(vectorb).lengthSq() < THREE.Constants.POSITIONAL_TOLERANCE_SQUARED. This is not the only way to do things, it but it avoids subtracting two similar numbers and it avoids trig functions and square roots.

Please note: I'm not a specialist on this topic. Best to consult an expert.

Now, simply using the dot product as the original code wouldn't really work in the above approach since it's neither a distance nor an angle. But if you did want to use the dot product, note that the dot product is basically like distance squared, so if you had a positional tolerance of 1e-6, the dot product tolerance might be 1e-12. (I think in practice 1e-12 will be too small though, because the dot introduces error with antiparallel vectors (x - (x + eps)). So I would choose 1e-10 or 1e-8 or something based on gut)

Now REALISTICALLY, if you don't want to be rigorous about this stuff, you can use 1e-6 everywhere and very very rarely will anyone be worse off. Finally, as mentioned above, 1e-8 (which Parasolid uses) is a tolerance intended for manufacturing and not computer graphics; a positional tolerance of 1e-6 is more than acceptable for visualization. Do note that you need to use different tolerances on the gpu which is only doing 32-bit fp math.

[Mugen87]

After checking multiple resources, I had a chat with Gemini about this topic which suggests 1e-7 as a robust epsilon for geometric comparisons. Should we go with that?

[nkallen]

1e-7 is definitely fine for my use case

[WestLangley]

I had a chat with Gemini about this topic which suggests 1e-7 as a robust epsilon for geometric comparisons.

Actually, the proper value is use-case-specific. Granted, it is somewhat subjective as to what that value should be in this case.

I would probably go with 1e-8, based on the previously-reported use cases.

@nkallen @Mugen87

[Mugen87]

I doubt the difference between 1e-7 and 1e-8 matters so 1e-8 is okay with me as well.

[nkallen]

Thanks for fixing this. Just wanted to say that I have a few critical 3rd party dependencies and of them threejs is by far the best maintained.