# Objective

Fixes #474.

The angular locked axes are applied to the inertia instead of the inverse inertia in gyroscopic torque computations introduced in #420, causing incorrect behavior.

## Solution

Apply the locked axes correctly.

# Objective

#420 changed Avian to use implicit Euler integration for solving gyroscopic torque. This was done for stability, as the semi-implicit version was prone to blowing up, because it extrapolated angular velocity and brought energy into the system.

However, that implementation of gyroscopic torque is fairly expensive, often being more than half of the total cost of velocity integration. It is also computed even for shapes with isotropic inertia tensors (e.g. spheres and regular solids) that don't experience gyroscopic torque. It would be nice to make this have less overhead.

Additionally, #735 broke gyroscopic motion, which needs to be fixed.

## Solution

1. Switch gyroscopic torque back to an approach that is closer to semi-implicit Euler integration, but clamp the magnitude of the angular momentum to remain the same. This prevents energy from being introduced to the system and seems to be sufficiently accurate for game physics. This idea was inspired by Jolt's [`ApplyGyroscopicForceInternal`](https://github.com/jrouwe/JoltPhysics/blob/d497df2b9b0fa9aaf41295e1406079c23148232d/Jolt/Physics/Body/MotionProperties.inl#L102).
2. Skip computation of gyroscopic torque for shapes with isotropic inertia tensors. This makes e.g. spheres, cubes, and other regular solids faster.

> [!NOTE]
> Do regular solids really have isotropic inertia tensors? Yes!
> See [Moments of inertia of Archimedean solids](https://web.archive.org/web/20211003110410/https://www.ipgp.fr/sites/default/files/archimedeani_200115.pdf) by Frédéric Perrier: "The condition of two axes of threefold or higher rotational symmetry crossing at the center of gravity is sufficient to produce an isotropic tensor of inertia. The MI around any axis passing by the center of gravity are then identical."

## Results

This is a 3D test scene with a bunch of cube stacks. The cubes have isotropic inertia tensors.

- **Left**: Before any optimizations.
- **Middle**: With the faster gyroscopic torque solver.
- **Right**: With the faster gyroscopic torque solver, but ignoring computation for isotropic tensors (all dynamic bodies in this scene).

![Performance comparison](https://github.com/user-attachments/assets/a5887f4d-298d-4522-b4b4-777ff816a9c0)

Velocity integration went down from 0.24 ms to 0.18 ms with the new solver, and still down to 0.13 ms ignoring unnecessary gyroscopic computations. Nice!

In the future, we could also consider making gyroscopic motion opt-in with a `GyroscopicMotion` component if we wanted to optimize this further for non-isotropic cases.

## Bonus: `gyroscopic_motion` Example

I added a new `gyroscopic_motion` example to demonstrate the Dzhanibekov effect and test the conservation of angular momentum.

https://github.com/user-attachments/assets/9ef9e335-feb9-4685-8f12-2f34ba442937