Beryllium.Math 0.2.1

BerylliumMath

A small, dependency-free set of math helpers for .NET 10: tolerance-aware comparisons, clamping, angle conversion, interpolation and remapping, frame-rate independent damping, and a guarded look-rotation builder on System.Numerics types.

Everything lives in one static class, Beryllium.Mathematics.MathUtils.

Install

dotnet add package BerylliumMath

Targets net10.0. No package dependencies.

Comparison

Single-precision helpers use an absolute tolerance of 1e-6, double-precision helpers 1e-10. Every comparison method has a float and a double overload.

NaN never compares equal to anything, itself included. Two same-signed infinities are equal.

Clamping

ClampToNonNegative(value) for int, float and double. NaN is propagated rather than clamped to zero.

Conversions

ToDegrees(radians) and ToRadians(degrees) for float and double. The single-precision radians-to-degrees factor is the correctly rounded float nearest 180/π; 180.0f / MathF.PI evaluates one ULP low.

Interpolation and remapping

These helpers are single-precision only.

The last two together give frame-rate independent smoothing:

// Reach 95% of the way to the target in 0.18 seconds, whatever the frame rate.
var damping = MathUtils.SecondsToDampingCoefficient(0.95f, 0.18f);

// Each frame:
var amount = MathUtils.InverseExpLerpAmount(damping, elapsedSeconds);
current = float.Lerp(current, target, amount);

convergenceFraction is clamped to [1e-4, 0.9999], since a fraction of exactly 1 would need an infinite coefficient, and durationSec to at least 1e-4, so a zero or negative duration behaves as a near-instant snap rather than producing an infinite or negative coefficient. NaN in either argument propagates.

Orientation

LookRotation(forward, up) builds the unit System.Numerics.Quaternion whose local -Z axis points along forward, with its local +Y axis along the part of up perpendicular to forward. That is the right-handed, "-Z is forward" convention shared by System.Numerics and MonoGame. Neither input needs to be unit length, and even components too large to square in single precision are handled. LookRotation(forward) uses world +Y as the up reference.

It never returns NaN, whatever the input:

• A forward shorter than 1e-6, or with a NaN or infinite component, returns Quaternion.Identity.
• An up that is zero, NaN or infinite, or within about 0.8° of the forward axis, cannot define a frame, so world +Y is substituted. When forward itself is (nearly) vertical, world +Z is used looking up and world -Z looking down instead, which gives the default view pitched straight up or down.

The fallback cannot follow yaw, so a camera driven by LookRotation(forward) snaps when pitched within about 0.8° of straight up or down, by the angle between its heading and world -Z; clamp the pitch short of that.

using System.Numerics;
using Beryllium.Mathematics;

var rotation = MathUtils.LookRotation(target - position, Vector3.UnitY);
var facing = Vector3.Transform(-Vector3.UnitZ, rotation); // ≈ Vector3.Normalize(target - position)

MonoGame users can pass the components through new System.Numerics.Vector3(v.X, v.Y, v.Z) and read the result back with new Quaternion(q.X, q.Y, q.Z, q.W); the component semantics are identical.

Building and testing

dotnet test BerylliumMath.sln

Changelog

• 0.2.1 LookRotation no longer returns NaN for an infinite forward or one too large to square in single precision (beyond about 1.8e19), and honours a very large up instead of replacing it with world +Y. Looking (nearly) straight up now gives the default view pitched up, as looking down already did, rather than that view rolled by 180°.
• 0.2.0 Added LookRotation.
• 0.1.0 Renamed the Mathematics class to MathUtils.

License

MIT