[Merged by Bors] - Add Beziers to bevy_math

[aevyrie]

Objective

• Adds foundational math for Bezier curves, useful for UI/2D/3D animation and smooth paths.

2023-02-14.12-07-33.mp4

Solution

• Adds the generic Bezier type, and a Point trait. The Point trait allows us to use control points of any dimension, as long as they support vector math. I've implemented it for f32(1D), Vec2(2D), and Vec3/Vec3A(3D).
• Adds CubicBezierEasing on top of Bezier with the addition of an implementation of cubic Bezier easing, which is a foundational tool for UI animation.
  • This involves solving for $t$ in the parametric Bezier function $B(t)$ using the Newton-Raphson method to find a value with error $\leq$ 1e-7, capped at 8 iterations.
• Added type aliases for common Bezier curves: CubicBezier2d, CubicBezier3d, QuadraticBezier2d, and QuadraticBezier3d. These types use Vec3A to represent control points, as this was found to have an 80-90% speedup over using Vec3.
• Benchmarking shows quadratic/cubic Bezier evaluations $B(t)$ take ~1.8/2.4ns respectively. Easing, which requires an iterative solve takes ~50ns for cubic Beziers.

---

Changelog

• Added CubicBezier2d, CubicBezier3d, QuadraticBezier2d, and QuadraticBezier3d types with methods for sampling position, velocity, and acceleration. The generic Bezier type is also available, and generic over any degree of Bezier curve.
• Added CubicBezierEasing, with additional methods to allow for smooth easing animations.

[alice-i-cecile]

Very useful as a primitive. I'm not sure how I feel about a trait specifically for cubic beziers; a const generic for the number of control points feels more correct.

That's 110% fine to punt to later work though.

[aevyrie]

Very useful as a primitive. I'm not sure how I feel about a trait specifically for cubic beziers; a const generic for the number of control points feels more correct.

That's 110% fine to punt to later work though.

Cubic Beziers always have 4 control points. An algorithm for higher-order Bezier curves is not included here, and could become a performance footgun. If users need more control points per spline, they should (probably) either chain cubic Beziers, or use a different type of spline.

I created a trait because the math is the same for cubic Beziers of any dimension. I originally had a generic function, but wanted to be able to use self, so I made a trait. That had the downside of requiring the trait to be imported, so I "re-exported" the trait method by adding delegates to the concrete types. Because of this, I could go back to using a generic function while still being able to use self via the delegate.

[alice-i-cecile]

That's a good explanation: I'm happy with this approach.

[aevyrie]

We need some tests to verify this is working as expected. Any suggestions?

1. Draw an animation curve that exactly represents a diagonal line, and compare samples to an explicit function:
   $y = 0.5 * x$ = Bezier.evaluate_y_at(t)
2. Use another program to compute the values, and hardcode those as correct answers in the test

[alice-i-cecile]

I like both of these. I would also suggest testing the derivative at various points using a simple finite differences sanity check, and verifying that tweaking coefficients results in directionally correct changes.

Bugs here are almost certain to be of either a "catastrophic" or "swapped sign" form.

[aevyrie]

Huh, looks like there is a duplicate dep, though I haven't touched the lockfile.

Alice nerd sniped me, I made Beziers const generic over any degree, as well as for 1D/2D/3D. The API is pretty nice, no generics needed as all information is provided during instantiation; e.g. this is a degree 4, 3D (Vec3) Bezier:

let bezier = Bezier::new([
    vec3(0.0, 0.0, 0.0),
    vec3(0.0, 1.0, 0.0),
    vec3(1.0, 0.0, 0.0),
    vec3(1.0, 1.0, 1.0),
    vec3(0.0, 0.0, 0.0),
]);

I've added type aliases for common Beziers:

pub type CubicBezier2d = Bezier<Vec2, 4>;
pub type CubicBezier3d = Bezier<Vec3A, 4>;
pub type QuadraticBezier2d = Bezier<Vec2, 3>;
pub type QuadraticBezier3d = Bezier<Vec3A, 3>;

I did some benchmarking, and saw a massive speedup after switching the cubic and quadratic types to use Vec3A. Bezier evaluations $B(t)$ take ~1.8 - 2.4ns. For easing, which requires an iterative solve, I have this down to ~54ns for cubics.

[bors]

try

Build failed:

• check-doc

[bors]

try

Build failed:

• check-doc

[bors]

try

Build succeeded:

• run-examples-on-wasm
• ci
• build (ubuntu-latest)
• build-without-default-features (bevy_reflect)
• build (windows-latest)
• build (macos-latest)
• build-wasm
• build-android
• markdownlint
• run-examples
• check-doc
• check-missing-examples-in-docs
• check-compiles
• build-and-install-on-iOS
• run-examples-on-windows-dx12
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• msrv

[JoJoJet]

Seems like it will be very useful to have this standardized. I've needed bezier curves in my own projects before, it will be nice to have a foundation in bevy itself.

[JoJoJet]

Nice documentation, it's extensive enough where necessary. The code all looks correct, but I'm quite concerned about the lack of tests. Earlier in the thread you gave two suggestions for ways of testing this. I think both of them would be good.

[aevyrie]

Added tests and did some further cleanup.

[alice-i-cecile]

@aevyrie once you fix CI I'll merge this :)

[alice-i-cecile]

bors r+

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-and-install-on-iOS
• build-android
• build (macos-latest)
• build (ubuntu-latest)
• build-wasm
• build (windows-latest)
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• build-without-default-features (bevy_reflect)
• check-compiles
• check-doc
• check-missing-examples-in-docs
• ci
• markdownlint
• msrv
• run-examples
• run-examples-on-wasm
• run-examples-on-windows-dx12