Rotate quaternion around plane normal

Question

How can one rotate a quaternion so that the rotation is around a plane normal?

A graphic/diagram I made below gives more detail about what exactly I am implying. Note that the tip of the quaternions in the diagram are that of the quaternions local, upwards direction, symbolizing roll (the quaternion's w component).

English describing the diagram:

The rotation is around plane normal (vector) N with amount θ. The global axes are X, Y, and Z (Y is up). The plane normal and quaternion are both in global space. Notice how the beginning and end of the operation does not use any reference to the global axes, only the plane.

The angle between the start quaternion (q) and end quaternion (q') and the plane is equal (a = a'). If you were to draw lines from the tips of the quaternions to the plane, the angles of intersection would be equal. In other words, the roll of the quaternions are preserved in relation to that of the plane.

---

EDIT 6/21/2020: Thanks to Theraot, this is possible simply by doing this in your favorite engine with quaternions:

quaternion qPrime = quaternion.AxisAngle(normal, θ) * q;

As Theraot states in his answer, order of multiplication does matter, and some engines may do the opposite operation compared to other engines. For Unity's Mathematics package, the above pseudo-code holds true. The formula for AxisAngle can be found by a simple google search. The following Gif shows it working while proving that all angle requirements I stated above are satisfied.

Answer 1

You can create a quaternion from an axis and the angle. Use this to create a quaternion to represent the rotation around the normal of the plane by the angle theta. Then compose that quaternion with your quaternion q, which will yield a new quaternion q' which is equivalent to rotating q round the normal of the plane by the angle theta.

You need to be aware of the direction of the normal and sign of the angle, which might result in rotating in the opposite direction.

Composing the rotations of the quaternions is just multiplication of the quaternions (and normalize the result). And, yes, the order matter.

---

I haven't internalized how to order my quaternions. And, you know, engines are not helping. Apparently the product of two unit quaternions a * b means rotating by b and then by a in Unreal Engine (documentation, documentation), but it means rotating by a and then by b in Unity (documentation). I believe Unreal is right. Thankfully there are only two ways it can be, try one way, and if it isn't, try the other way.

---

If you are going to implement your own quaternion operations, I suggest Developing a Math Engine in C++: Implementing Quaternions. Getting a quaternion form axis and angle, and quaternion multiplication are covered there.