For people who don’t work with math and matrices a lot, it may not be immediately obvious how to “rotate a quaternion”.
It is not obvious that we have to use quat.setFromAxisAngle() in conjunction with quat.multiply() after searching for “threejs rotate around axis” on Google and see the Object3D.rotateOnAxis() method (and we might wonder why is this method not on the Quaternion class).
So this is how to “rotate” a quaternion:
// rotate around Z axis by 45 deg
const rotationToApply = new Quaternion().setFromAxisAngle({x: 0, y: 0, z: 1}, (45 / 180) * Math.PI)
quaternionToRotate.multiply(rotationToApply)
Non-math people might not be able to immediately figure this out. VS Code (with @types/three installed for type checking and auto-completion) does not provide the answer when trying to auto-complete quat.rotat.
Someone adept enough may try to autocomplete .axis and find .setFromAxisAngle, but they might not immediately realize they also need multiply() to “rotate”.
Is the Three.js team open to making Quaternion (and other classes like Euler) easier to use? For example:
quat.rotateOnAxis({x: 0, y: 0, z: 1}, angle)
quat.rotateX(angle)
quat.rotateY(angle)
quat.rotateZ(angle)
quat.rotateAxes(axis1, axis2) // applies the rotation from axis1 to axis2
// etc
Object3D.rotateOnAxis would then proxy to Quaternion.rotateOnAxis. Object3D.rotateOnAxisWorld/etc would need to remain in Object3D, because only the tree has the concept of hierarchy.