Contribution on Rotation Modes

Hi Dr. Stüvel,

my name is Damiano, I’m a software engineer and amateur 3D modeller, and of course I love Blender :slight_smile:

I’m working on adding a new rotation mode to objects and bones (and 3D cursor as well): swing-twist, with twist axis being any of X, Y and Z.
I think I have already done most of the work on the core functionalities, and I will work on improving the Python API side and how the rotation mode is visualized in the GUI.
But before doing that, I would like to know if the developers are interested in having this new rotation mode. I think that swing-twist would be more useful than euler, quaternions or axis-angle to use for character animation, because it has 3 components similarly to euler, but it is easier and more intuitive to use than axis-angle and quaternions.
Here (Fundamental flaws in Blender's constraint philosophy? - #5 by Hadriscus), Brecht says that it would be useful to have the swing-twist rotation mode, which is already available for drivers/constraints, in objects/bones.

If you think that this contribution would be accepted, I will keep working on it.

Keep up the great work on Blender!

Damiano Oriti


Hi Damiano,

Swing-Twist certainly has some benefits. I’m not intimately familiar with it, though. According to Baerlocher & Boulic: Parametrization and Range of Motion of the Ball-and-Socket Joint (2000) there are multiple possible parametrisations possible, each with their own singularities. Which one did you choose for your implementation, or is this something artists have control over? Are you basing your work on any scientific paper?


Hi Sybren,

actually, I did not introduce new code specifically for handling the math behind swing-twist, I have just reused the existing code that I think was contributed by Alexander Gravrilov for drivers and constraints. I used the existing code to convert from swing-twist to quaternion and vice versa, and with this I handle all conversions from-to the other rotation modes and mat3/mat4.
If the original code is robust enough, my code should work well, since it relies on that.
I’m not familiar with the existing paremetrisations either, but this weekend I can study that paper and Alexander’s code to give you a thorough answer on this, including the limitations of the current implementation. I think that this is the best thing to do anyway, because if there is any limitation in the current paremetrisation and implementation I would like to know before contributing it.

Artists can choose the same modes available for drivers and constraints, that is XZ-Swing and Y-twist, XY-Swing and Z-twist and YZ-Swing and X-twist.
As I wrote in the proposal thread here on devtalk, the advantages are:

  • 3 editable components
  • no need to be normalized, so easier to edit using the GUI than quaternions or axis-angle
  • where euler will give same final rotations for different angles, swing-twist gives different final rotations for different angles

Have a nice day,

1 Like

It all sounds quite good, thanks for putting in the effort! Would you mind if I make this thread public, so that it can be read by other interested people as well?


Sure, no problem :slight_smile:

Since you don’t provide any screenshots, I assume you want to represent it as 3 (pseudo-)angles. The main question in that case is the representation of the swing values.

The way the drivers output the swing values is a hack that applies a simple math function to raw quaternion values, with the only goal being that if rotation is purely about that primary axis, then the value shoud be equal to the real angle. The driver feature was mostly meant for driving corrective shape keys, so conceptial clarity wasn’t a priority. For representing actual rotation more thought is necessary.

The driver Swing+Twist representation is most similar to the axis-angle swing parameterization from the above article; with the difference that drivers don’t provide the invariant that e.g. Xswing^2 + Zswing^2 = true_swing^2, i.e. representation of the same angle of swing in all possible different directions doesn’t form a circle in the XZ space, but some weird curves. This likely needs to be fixed if we want to indroduce a proper rotation mode.

That however would mean a compatibility break for drivers (since you’d want them to return values compatible with transform channels), or introducing 3 new modes for drivers, marking the old swing+twist ones as ‘Legacy’.

Edit: Note that for swing angles below 90 degrees the difference between representations is very small.

Also here is some completely untested (actually buggy) code for conversions to/from a ‘proper’ swing angle representation: Pasteall/Obhd (C)


I would definitely be interested in trying it out as an animator.

At Dreamworks we worked around the gimbal problem with certain bones by providing a 4th degree of rotation called orbit. I believe the order went: orbit > swing > raise > twist (but I could be switching swing & raise… it’s been a few years). This was available on the upper arms, hands, feet, torso, and head.

I bring it up not to replicate it… but more to point out that animators can adapt to different rotation modes & workflows if they make sense and provide consistent and acceptable behavior. :slight_smile:


I would like to play with it as soon as a patch is available! Things I’d like to find out are:

  • Can animators intuit the way each axis will behave, when they change keyframe values one axis at a time in the graph editor?
  • Will it play nicely with the rotation gizmo when it is set to Gimbal?
  • In what cases will interpolating between two rotations result in unpredictability for animators?
1 Like

Hi Alexander, thank you for the precious input on the math and for the code sample :slight_smile:
As you said, if we don’t want to break compatibility, adding those 3 new modes for drivers would be necessary, and I think I should be able to do that. So, if you, Sybren and the other developers agree, I would do just that.

I will start by studying that paper that describes swing-twist in order to gain a better understanding on what are its pros and cons, then I will go back to the sample implementation that you provided to prepare a new demo for animators to try and tell us if this would be, indeed, a good addition for them.


Considering how swing + twist works, I have no reason to believe that it will be worse than existing modes, whereas I have reason to believe that it will be more intuitive to use and predictable.
Currently I have just played with my demo and it seems to work well, but I want to gain better understanding of it on a technical level, a proper implementation and more tests in order to give thorough answers to your questions.

Is this perhaps based on this research?

@DamianoOriti Could you provide us with Windows/Linux/macOS demo builds? I can help with that if you want.

Here you can download a Windows build and the patch for Linux users who want to build it themselves.

A few notes:

  • I would rather recheck all the code and fix the swing-twist implementation before giving it to animators to try, as Alexander pointed out that the existing code that this patch is based on is not a proper implementation of the swing-twist parametrization.
  • I read the paper that you suggested (very interesting, by the way) and I am preparing a proposal with advantages and limitations based on that.
  • Adding keyframes with ‘I’ key and selecting ‘Rot’ does not work, you should hover over the rotation property with the mouse and press ‘I’ there to add a keyframe.

This weekend I will update the first post with a more detailed proposal, and, if possible, I will recheck the code and try to fix the implementation.


Hi, if you mean the specific swing-twist parametrization, then I have to check what they are using and will let you know. If, on the other hand, you mean the skinning method, no, sadly this is a much more limited contribution, but hopefully useful.

I finally had some spare time to work again on this.

I used the code provided by @angavrilov to fix the issue related to the swing components not giving the correct swing angle. In the provided functions there were some bugs that should now be fixed.
I also fixed the issue of keyframes not being added for Swing-Twist when using ‘I’ and selecting a rotation Keying Set.

The updated patch can be downloaded from here.

After reading the paper linked by @sybren, I would say that the major benefits of Swing-Twist are:

  • The singularity being far from the limits of natural motions (for common characters at least).
  • Less singularities than Euler.
  • Compared to Quaternions and Axis-Angle, it has single twist component, no need to keep normalized, and less components to change.

Based on the feedback, if you all find it worthy to add this new rotation mode to Blender, I will keep working on it to fix bugs and add the versioning code for legacy Swing-Twist modes used in drivers.

1 Like

I will try to answer your questions:

  • From my tests, I would say that being able to handle swing and twist separately makes it more intuitive to reason about it and understand which components to change to get a specific orientation.
  • I just tried the rotation gizmo, but I am not convinced 100% that it is working as expected (maybe that’s because I rarely use it). If you have the chance to try it, please let me know if you find any strange behaviour.
  • One would incur in unpredictable behaviour when the swing is close to 180°, where there it the singularity. For legs, arms, etc., this should not be a problem I think.