Implement BoneConstraint3D with CopyTransform/ConvertTransform/Aim Modifiers

[TokageItLab]

BoneConstraint3D

A base class that allows two bones to be specified.

Note that interpolation by SkeletonModifier3D.influence for the entire skeleton is done for each SkeletonModifier3D.

However, constraint settings are often applied to multiple bones at the same time. Therefore, it prevents unnecessary interpolation by having the settings in an array so that the number of SkeletonModifier3Ds in the scene does not grow unnecessarily. For this reason, the BoneConstraint3D settings have the apply amount of modification to the bone for each element in the settings array.

AimModifier3D

This is a simple version of LookAtModifier3D that only allows bone to the target without advanced options such as angle limitation or time-based interpolation. The feature is simplified, but instead it is implemented with smooth tracking without euler,

• It depends on the quaternion constructor with arcs from the two Vector3s, so it is recommended that merge Fix looking at with 180 degree arc #100991 first.

CopyTransfromModifier3D

Apply the copied transform of the target bone to the apply bone with processing it with some masks and options.

There are 4 ways to apply the transform, depending on the combination of Relative and Additive options.

• Relative + Additive
  • Extract target pose relative to the rest and add it to the apply bone's pose.
• Relative + Not Additive
  • Extract target pose relative to the rest and add it to the apply bone's rest.
• Not Relative + Additive
  • Extract target pose absolutely and add it to the apply bone's pose.
• Not Relative + Not Additive
  • Extract target pose absolutely and the apply bone's pose is replaced with it.

ConvertTransfromModifier3D

Apply the copied transform of the target bone to the apply bone about the specific axis with remapping it with some options.

---

Compatibility with third-parties

I assume there is some compatibility, but cannot guarantee that the behavior is exactly the same in a particular situation (since Since it has not yet been tested/verified).

Blender

CopyXXX (for rotation with axis mask, rotation mode is roll only) -> CopyTransfromModifier3D
Transformation (for rotation, rotation mode is roll only) -> ConvertTransfromModifier3D
Track/LockedTrack -> AimModifier3D with using euler
DampedTrack ->AimModifier3D without using euler

VRMConstraint

https://github.com/vrm-c/vrm-specification/blob/master/specification/VRMC_node_constraint-1.0

RotationConstraint -> CopyTransfromModifier3D with only rotation with all axes without invert flags
RollConstraint -> ConvertTransfromModifier3D with rotation mode
AimConstraint -> AimModifier3D without using euler

[fire]

Do we have test scenes?

I'll look into those.

[TokageItLab]

@fire I used this model in quick check to show axes where everything is a sibling of root:

constraint_demo.zip

[TokageItLab]

@fire For now, since the feature freeze is nearing, I separated the PR only from the refactoring part, which will cause break compatibility; Since LookAtModifier is added in 4.4, if this PR is carried over to 4.5 it will occur.

• Move enum BoneAxis to SkeletonModifier from LookAtModifier #101148

[TokageItLab]

I will write a CI test later, because this module does not depend on external factors such as time, but purely mathematical transformations, so it is possible to check for them.

[aaronfranke]

For reference, see also this GDScript implementation of VRM constraints I made for godot-vrm: https://github.com/V-Sekai/godot-vrm/blob/master/addons/vrm/node_constraint/bone_node_constraint.gd

Also, I made an example model here: vrm-c/vrm-specification#444 Before merging this PR, we should write a draft PR to godot-vrm that uses this PR and test that it works correctly.

This PR looks much more comprehensive than what I wrote and seems to handle everything in VRM and more, awesome! Feel free to request a review from me once this PR is ready to go.

[TokageItLab]

I removed the use euler option from Copy/ConvertTransformModifier.

Since the bone pose only stores the quaternion, there is no guarantee that the euler will be stored in the next frame even if the SkeletonModifier sets the euler. Then I concluded that it would be difficult to accomplish converting euler rotation without a more fundamental implementation in the Skeleton3D class.

BTW, this is not a problem in cases where processing is performed on all three axes. Where this becomes a problem is when using ConvertTransformModifier to handle Rotation, or CopyTransformModifier to mask or invert on one or two axes. But it should still cover VRM compatibility. It lacks the compatibility of the constrains that Blender has that use Euler.

For now, to ensure mathematical correctness, they behave as if they were copying/cancelling a roll in a particular axis or inverting an element in a Quaternion. Perhaps similar to the roll+swing rotation mode in Blender.

It may seem somewhat less intuitive, but I have explained conceptually in the documentation how they work. Also, their mathematical validation is ensured by the added unit tests.

[fire]

Should we store in swing twist decomposed quaternion/basis?

I mentioned wanting to support cone, twist and polygon (kusudama)

[TokageItLab]

Should we store in swing twist decomposed qusternions/basis?

@fire I don't think Skeleton3D needs to retain that. However, it could be discussed whether or not these functions like get_roll_angle() should be made public.

[TokageItLab]

For consistency (Copy/ConvertModifier does not contain the word "Bone") and to account for the possibility of setting non-bone targets in the future, I renamed TrackBoneModifier3D to AimModifier3D as a more generic name. TrackModifier3D is another idea, but the word "track" has many homonyms, so the word "aim" was chosen to match with VRMConstraint.

There is a possibility of a little confusion with LookAtModifier3D, but AimModifier3D has BoneConstraint3D as its base class, so I assume that this is not a problem.

[TokageItLab]

Fixed several bugs discovered while applying Blender's constrained settings for actual use:

• Fixed a problem with inverse_lerp causing division by zero when target's range in ConvertTransformModifier is 0
• Fixed a problem with incorrect rest space in AimModifier (this PR includes Fix rest translation space in LookAtModifier3D #104217)
• Fixed an issue with incorrect conversion of AimModifier's without-euler mode

Twist without constraint:

Twist with constraint:

[TokageItLab]

Improved handling of zero division in ConvertTransformModifier. Also, "target bone" has been renamed to "reference bone".

While "target" in Aim is clear, the word "target" in Convert and Copy is a bit confusing (although Blender consistently calls it "target"). This rename would make Aim "target" to "reference", but I think it's still understandable.

If anyone has any other better names, suggestions are welcome.