Allow customizing the inertia tensor in user code

[aaronfranke]

This PR is a revival of #1114 and half of #945

Describe the project you are working on

I am working on the ability to represent complex physics objects in Godot.

Describe the problem or limitation you are having in your project

This chair cannot have its inertia properly described without access to the full 3x3 matrix inertia tensor (or changing the orientation). An object as simple as a chair does not seem like a niche use case to me, it seems very common.

Currently the only way for this object to have remotely close to the correct inertia would be to let Godot calculate a tensor, but this would not be very accurate if the collision shapes do not match up perfectly, and they would not be very precise if the chair's material was not uniformly dense.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The proposal is to expose the inertia tensor to the user, so advanced users can set up their own custom inertia tensors to improve the accuracy of advanced physics simulations.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

The engine's internal physics system already uses an inertia tensor matrix, but it's not exposed to the user.

I have a compiles-but-completely-broken branch here: https://github.com/aaronfranke/godot/tree/rigid-body-intertia-tensor-mass-dist maybe someone can figure out what's wrong.

Here is what it would look like in the inspector, a matrix for inertia instead of a vector:

EDIT: Actually, instead of the inertia tensor, I think it would be better to expose the inertia orientation as an Euler Vector3 or Quaternion. I think it's more intuitive to work with and also it aligns with the updated glTF physics specs.

If this enhancement will not be used often, can it be worked around with a few lines of script?

It will not be used very often, but it is important for the small percentage of users who want to put in the work to have accurate physics simulations. It can't be worked around, this is about exposing.

Is there a reason why this should be core and not an add-on in the asset library?

Physics is a core feature, and this is about exposing something in physics currently hidden from the user.

[aaronfranke]

An alternative implementation would be to expose an inertia orientation property (can be Euler angles or Quaternion) to rotate the Vector3 principle axis inertia to have different principle axes. EDIT: Actually, I prefer this, I think it's more intuitive to work with and also it aligns with the updated glTF physics specs.

Note that these 2 different formats are not trivial to interchange with each other, because the inertia tensor is NOT a rotation Basis. The inertia tensor is a symmetric matrix with only 6 unique numbers, the 3 principle axis inertia values and the 3 coupling values between the axes. Due to this being non-trivial to work with, it might be desired to implement both options, provide both orientation and tensor, which would be redundant properties.

[perococco]

I have the same issue, but I wanted to solve it in another way. I started the discussion #7600 and it has been closed since setting a custom inertia tensor solves the issue.

I have been told to add the detail of how I wanted to solve it to this issue for completeness:

So my idea was :

1. Add a Mass Mode with 2 choices

   1. Uniform (the default choice)
   2. Non Uniform

   In Uniform mode, we have the current behaviour of Godot and the field Mass is visible and editable. In Non Uniform the Mass is not editable (and "not visible" or "visible with filled with computed mass" ? )

2. On each collision shape and a field Mass.

3. On the core engine, the computation of the mass_properties must be updated in the case of the Non Uniform mode.

   1. The total mass must be computed
   2. The computation of center of mass and the inertia tensor must use the mass of the CollisionShape3D instead of its volume.

In the editor it will be something like in this video:

godot.mp4

[erikscott128]

I made a discussion post about this (#7909) in which I proposed that the off-diagonal elements of the inertia tensor be an additional Vector3 such that it represents the second half of a tensor in Voigt Form. This will prevent users from creating invalid (non-symmetric) inertia tensors and will not alter the current implementation (ie, the Vector3 representing the diagonal entries can remain).

For my intended use case (vehicle dynamics) computing and inputting the off-diagonal products of inertia is a preferred method over determining the rotation matrix required to transform to the principle axes. CAD applications are likely to be the source of this information for users, and most are happy to report the full inertia matrix. I believe solidworks will report the principle axes as well, but it appears that Fusion360 does not.

[snietfeld]

My use case is also related to vehicle dynamics. Preferred solution is to be able to simply set the full inertia tensor, but any of the proposed solutions would be fine.

[erikscott128]

It seems there's some renewed interest in this considering it has been mentioned in #13419. It seems the gLTF standard is to define the inertia in the principle axes, which are defined relative the the object's axes by a Basis. This is an acceptable solution and can be worked with. However, I have the following concerns:

• The inertia tensor would now be defined using 12 parameters (3 principle inertia values, and 9 basis values)
• The basis values would somehow have to be kept orthogonal. Not doing so which would lead to odd behavior
• Establishing a principle axis basis is good for objects with constant mass properties, but not for those with variable mass properties (eg, a vehicle that burns fuel or picks up/drops off passengers, cargo, etc).

In my opinion, the number of parameters exposed to the user in the Godot editor and through GDScript should reflect the appropriate number of degrees of freedom of the thing we're trying to define. In the case of an inertia tensor, this is 6. Exposing the inertia tensor directly provides what appear to be 9 to the uninitiated. A basis+inertia vector is worse in providing 12 as described above. @aaronfranke 's proposal of defining the principle axis orientation using Euler angles reduces this back to the desired 6, which is appropriate. The Voigt form I suggested would do this as well, but in a different way.

For my application (vehicle dynamics with time-variable mass properties), it is easiest to compute the moments and products of inertia directly. This will have to be done for every time step (for the case of fuel burn) or whenever any mass is added to or removed from the vehicle. So, for whatever method is ultimately chosen, it would be good if there were several methods to provide the information to the physics back-end to support multiple use cases. Some proposed method definitions are

• func set_inertia_voigt(inertia: Vector3, inertia_prod: Vector3) -> void
• func set_inertia_euler(inertia: Vector3, euler: Vector3) -> void
• func set_inertia_quart(inertia: Vector3, quart: Quaternion) -> void

All of these would perform the required calculations to format the inertia properly for the back end physics implementation.

Speaking of the physics implementation, I've opened up the source code myself and had a poke around. It appears Godot likes to do all of its physics calculations in the inertial (global) frame (I'm used to implementing it in the body-attached frame). GodotBody3D gets the inertia from the set_param method. The 3-element inertia vector is "inverted" (element-by-element) and assumes the principle axes of inertia are the identity matrix (ie,, aligned with the body-attached frame). The principle axes are transformed to the inertial (global) frame, and the inverted inertia vector is turned into a diagonal matrix before being transformed to the inertial frame to become the full inertia tensor. The principal_inertia_axes_local is already a member variable, so the structure is already in place to implement this in a way consistent with gLTF physics, and I see no reason why this couldn't be easily implemented.

Jolt seems to work a bit differently. Jolt has a MassProperties object which contains the entire local inertia tensor as a member variable mInertia. The inertia vector specified by Godot is simply written to the diagonal entries. To me, this is considerably easier to work with. If information is provided in the gLTF standard way (3 inertias+basis), this can be easily transformed back to the body-attached frame.

[erikscott128]

I forked the repo and started having a go at implementing it myself. Implementation in Jolt was basically trivial and I already appear to have it working without issue. Godot's native 3D physics is more difficult and I'm still working it. I would like to eliminate having to compute the principle axes entirely as that would improve performance and significantly clean things up. However, it appears joints require the principle axes in their implementation.

[erikscott128]

Success! I have added a "Product of Inertia" property to the editor and implemented the it into both GodotPhysics3D and JoltPhysics. This uses the Voigt order I proposed above, so the format for the Vector3 is (Iyz, Ixz, Ixy).

Initial testing in both GodotPhysics3D and Jolt revealed only minor numerical differences between them.

I'm not going to detail all of the changes here (you can check my fork of the repo if you're interested). The core of the changes lie in the GodotBody3D and JoltBody3D classes. Jolt was basically trivial. The set_param method was modified to accept the product of inertia vector (this required an additional entry in the BodyParameter enum in PhysicsServer3D). The _calculate_mass_properties method was modified so that the inertia in Jolt's MassProperties object is fully defined.

...
	// If using custom inertia, set products of inertia
	if (!calculate_inertia) {
		mass_properties.mInertia(1, 2) = -(float)product_of_inertia.x;  // Iyz
		mass_properties.mInertia(2, 1) = -(float)product_of_inertia.x;  // Iyz

		mass_properties.mInertia(0, 2) = -(float)product_of_inertia.y;  // Ixz
		mass_properties.mInertia(2, 0) = -(float)product_of_inertia.y;  // Ixz

		mass_properties.mInertia(0, 1) = -(float)product_of_inertia.z;  // Ixy
		mass_properties.mInertia(1, 0) = -(float)product_of_inertia.z;  // Ixy
	}
...

Similarly, for the Godot engine, the set_param method was modified to accept the product of inertia vector. However, this required a bit of additional logic. A new method _update_local_inertia was created to compute the principle moments and local axes of inertia. This function is also called (and replaces 2 lines of code) in the regular inertia case.

void GodotBody3D::_update_local_inertia() {
	// Set local inertia tensor to diagonal matrix
	inertia_tensor_local = Basis();
	inertia_tensor_local.scale(inertia);

	// Add off-diagonal entries using the "alternate" (but correct) convention
	// https://en.wikipedia.org/wiki/Moment_of_inertia#Inertia_tensor
	inertia_tensor_local[1][2] = -product_of_inertia.x;
	inertia_tensor_local[2][1] = -product_of_inertia.x;
	
	inertia_tensor_local[0][2] = -product_of_inertia.y;
	inertia_tensor_local[2][0] = -product_of_inertia.y;

	inertia_tensor_local[0][1] = -product_of_inertia.z;
	inertia_tensor_local[1][0] = -product_of_inertia.z;

	principal_inertia_axes_local = Basis();
	Vector3 principal_inertia = Vector3();

	// Compute the principal axes and moments of inertia.
	eigen_value_symmetric(inertia_tensor_local, principal_inertia_axes_local, principal_inertia);
	_inv_inertia = principal_inertia.inverse();
}

This relies on a new function eigen_value_symmetric which I've added to the core/math area. It computes the eigenvalues (principle moments of inertia) and eigenvectors (principle axes of inertia) of a symmetric matrix (the local inertia tensor). It's essentially copied from the Jolt physics library, but modified for Godot's Vector3 and Basis classes. I'm not going to reproduce it here. The Basis method diagonalize does essentially the same thing, but only returns the eigenvectors so I had to make a new function.

The _update_transform_dependent() function ended up not requiring any changes. This is good because it leaves the base implementation intact.

I'll be creating a video demonstrating the new feature and the code changes in the coming days.

[erikscott128]

Pull Request opened (currently in draft): godotengine/godot#112367