Where are Blender 2.79 and later rigid body constraint angular limits documented?

Question

Summary I can find no documentation on the frame of reference for defining the rigid body HINGE constraint Z axis rotational limits. Blender defaults these to lower = -45 deg and upper = +45 deg. Online docs provide no detail and YouTube videos invariably skip over this aspect of constraint set-up.

Can someone direct me to documentation or provide insight into how the HINGE and other RB constraints angular limits are defined. i.e. with respect to what are the limit angles defined?

Detail I need to understand the Blender set up for these constraints well, as I need to prototype before exporting into my own game engine, which also uses Bullet Physics.

I've tried a Blender demo set-up with 2 bodies, one static/passive and the other active and a HINGE between the two and just when I think I've got it, for instance assuming:

• The angles are defined looking down the constraint's local Z axis, towards the origin.
• With the limiting angles defined relative to the XZ plane.
• With +ve angles being above the XZ plane and -ve below.

But as soon as I start playing with the angles, my hypothesis falls apart.

I can even manage to provide limits that cause the joint to act against gravity in an unrealistic way.

Given the lack of online guidance on this (including Blender stack exchange) I'm starting to think that this is not a well understood area. I assume the same will apply when I come to look at the other constraint types too, especially the GENERIC constraint. So any help or direction will be gratefully appreciated.

Answer 1

OK, so I didn't find any Blender specific documentation for this and ended up looking at the python code for:

bpy.ops.rigidbody.constraint_add()
bpy.context.object.rigid_body_constraint.type = 'HINGE'
bpy.context.object.rigid_body_constraint.object1 = bpy.data.objects["ObjectA"]
bpy.context.object.rigid_body_constraint.object2 = bpy.data.objects["ObjectB"]
bpy.context.object.rigid_body_constraint.use_limit_ang_z = True
bpy.context.object.rigid_body_constraint.limit_ang_z_lower = -0.785398
bpy.context.object.rigid_body_constraint.limit_ang_z_upper = 0.785398

and the Blender and Bullet C code.

Observations:

1. Adding a Blender HINGE constraint, ultimately calls the Bullet function to create a HINGE constraint and not a GENERIC as previously suspected.
2. Looking at the Bullet create function and reading Bullet forum posts, the constraint is set up relative to the frame (local transform) of the second Object passed to the function. You can override this behaviour and set up the constraint relative to the transform of the first object, using a boolean flag. Blender sticks with the default, so the constraint transform is relative to Object 2.
3. Looking into the "set angular limit" function, there is a normalisation of the limit range mid point between -2PI and 2PI, so excessively large limit angles just get pulled back into the range -360 to 360 degrees.

What this means in plain terms is:

• Limit angle "zero" is local x axis of objectB
• +ve Upper Limit is in anticlockwise direction, when looking along the constraint's local +ve Z axis from the origin
• -ve Lower Limit is in clockwise direction, when looking along the constraint's local +ve Z axis from the origin
• The orientation of the constraint's local X and Y axis doesn't affect the joint's rotational range.

This is probably hard to visualise, so I've included a picture with 3 scenarios.

• Top left is the starting set-up. Note the direction of the central constraint local Z axis.
• Bottom left has the constraint local transform rotated 180 degrees around the local X axis, so the local Z axis now points towards the view. Upper and lower limits now flip.
• Finally the image on the right is the same as the top left but Object B (2) to rotated downwards by 45 degrees and the limits move relative to this.

Ultimately, what was confusing me, was the fact that the limit angle range "zero" is defined by object 2 and not the orientation of the constraint itself. I assume a similar set-up will apply to the other Bullet constraints, notwithstanding the axes of rotation may be different.

Cheers.