Three.js: [suggestion] add a rotateOnWorldAxis helper

[MichaelHazani]

I keep seeing global-rotation related problems and questions pop up, which makes sense, as three's "simple" rotation methods are local and grokking the quaternion math involved in conversions is nontrivial, especially for beginners.

Would the maintainers ( @mrdoob / @WestLangley / whoever's making feature decisions) be open to a helper method that simplifies rotating in world axis? To conform with the existing (local) rotateOnAxis, The API could be something like:

Object3D.rotateOnWorldAxis([Vector3], [radians])

and the implementation similar to the solution I provided here.

I think this would really benefit the community - I know I, for one, scratch my head every time I have to reimplement world rotation...

[WestLangley]

Related: https://github.com/mrdoob/three.js/pull/8438#issuecomment-199946343 and the discussion regarding world methods in https://github.com/mrdoob/three.js/issues/3211.

Also: This SO answer regarding rotating around a world axis.

Here is one version of the requested method:

THREE.Object3D.prototype.rotateOnWorldAxis = function() {

    // rotate object on axis in world space
    // axis is assumed to be normalized
    // assumes object does not have a rotated parent

    var q = new THREE.Quaternion();

    return function rotateOnWorldAxis( axis, angle ) {

        q.setFromAxisAngle( axis, angle );

        this.applyQuaternion( q );

        return this;

    }

}();

[MichaelHazani]

@WestLangley - thanks for the context. And yup, that's exactly the solution I propose in the SO answer I mentioned.

I understand your reasoning (particularly with regards to the dangers of decoupling matrix operations from rotations) and respect your decisions of course, but for what it's worth - I suspect this is one sorely needed helper that stumps a lot of people and would provide real value. The jump from "having all the core methods available" to actually implementing this kind of rotation may not be as trivial as it may seem to seasoned pros, and I'm sure it wouldn't be the first time an operation is abstracted in three in the interest of providing accessible functionality of some kind.

I am light years away from your amount of experience and proficiency but I've been working with 3D math and following the development of three for several years, and this technique is one I always keep in a gist somewhere because I don't know a single easy-to-find way to recall it. It's a very common use case, it doesn't mess up matrices, and - I think - would be very beneficial to newcomers and experts alike. It's needed frequently enough to justify a shorthand.

FWIW, I don't think it's an accident this request resurfaced, and I'm sure it will do so again in the future (which isn't in and of itself a justification for an API change, but it is an indication that such a change would be welcome by users.)

Seeing as you seemed to be on the fence in the most recent thread, I wanted to make my passionate plea for this:). Thanks for reading.

[WestLangley]

@mrdoob We can leave the method here for users to reference, or I can file a PR. Whatever you want.

[MichaelHazani]

if @mrdoob approves, I'm happy to take a stab at it if your ( @WestLangley ) plate is full.

[mrdoob]

Lets put it in 👍

[MichaelHazani]

Fantastic! @westlangley, mind if I go for it? I’d love to contribute something to the lib that gave me so much:). Definitely done by the weekend.

[MichaelHazani]

(Prob much sooner given that it’s a copy-paste job after your great example - just waiting for a work-free moment by my computer)

[WestLangley]

Sure. Please use the code pattern of rotateOnAxis() and include the docs.