Home

Awesome

BurstMathUtils

Editor tests openupm

Burst compatible miscellaneous math related utility functions.

Currently, the package focuses on 2d related utilities, but functions for 3d math will be added as well.

Table od Contents

Getting started

Install the package using one of the following methods

<details open> <summary> Using scoped registry <b>(recommended)</b> </summary> Use OpenUPM CLI or add corresponding entries to the project's <code>manifest.json</code> manually. Add or modify scoped registries in the manifest <pre> "scopedRegistries": [ { "name": "OpenUPM", "url": "https://package.openupm.com/", "scopes": [ "com.andywiecko" ] } ] </pre> and in the dependencies provide selected version of the package <pre> "dependencies": { "com.andywiecko.burst.mathutils": "1.3.1", ... </pre> See Unity docs for more details https://docs.unity3d.com/2021.1/Documentation/Manual/upm-scoped.html </details> <details> <summary> <code>git</code> install </summary> Use package manager via git install: https://github.com/andywiecko/BurstMathUtils.git#v1.3.1 </details> <details> <summary> Manual instalation </summary> Clone or download this repository and then select <code>package.json</code> using Package Manager (<code>Window/Package Manager</code>). </details>

Features

Package contains a static class with utilities (and extensions), i.e. MathUtils which includes many useful functions related to the following categories Algebra, Primitives, Geometry, and Misc.

Additionally, the package introduces struct Complex struct, a burst-friendly complex number representation.

Algebra

float Angle(float2 a, float2 b)

Angle (in radias) between vectors a and b.

float Cross(float2 a, float2 b)

Two-dimensional cross product between vectors a and b.

void EigenDecomposition(float2x2 matrix, out float2 eigval, out float2x2 eigvec)

Procedure solves eigen problem for symmetric matrix.

float2 Max(float2 a, float2 b, float2 c)

Componentwise maximum of three vectors.

float2 Min(float2 a, float2 b, float2 c)

Componentwise minimum of three vectors.

float2x2 OuterProduct(float2 a, float2 b)

Outer product of two vectors, i.e. a · bᵀ.

void PolarDecomposition(float2x2 A, out float2x2 U)

Procedure solves polar decomposition problem for matrix A, formulated as A = U · P, where U a is unitary matrix and P is a positive semi-definite Hermitian matrix.

void PolarDecomposition(float2x2 A, out float2x2 U, out float2x2 P)

Procedure solves polar decomposition problem for matrix A, formulated as A = U · P, where U a is unitary matrix and P is a positive semi-definite Hermitian matrix.

float2 Right()

Right axis (1, 0).

float2 Rotate90CCW(this float2 a)

Rotated vector a by 90° (counter-clockwise).

float2 Rotate90CW(this float2 a)

Rotated vector a by 90° (clockwise).

float2x2 ToDiag(this float2 a)

Diagonal matrix with values a placed in the diagonal.

float2x2 Transform(this float2x2 M, float2x2 A)

Transformed matrix M, with given transformation A, i.e. A · M · Aᵀ.

float2 Up()

Up axis (0, 1).

Primitives

(float2 p, float r) TriangleBoundingCircle(float2 a, float2 b, float2 c)

Bounding circle at point p and radius r of the triangle (a, b, c)

(float2 p, float r) TriangleCircumcenter(float2 a, float2 b, float2 c)

Circumcenter at point p and radius r of the triangle (a, b, c)

float TriangleSignedArea(float2 a, float2 b, float2 c)

Signed area of triangle (a, b, c).

float TriangleSignedArea2(float2 a, float2 b, float2 c)

Doubled signed area of triangle (a, b, c).

Geometry

float2 Barycentric(float2 a, float2 b, float2 p)

Position p expressed in barycentric coordinate system defined within line segment (a, b).

float3 Barycentric(float2 a, float2 b, float2 c, float2 p)

Position p expressed in barycentric coordinate system defined within triangle (a, b, c).

float2 BarycentricSafe(float2 a, float2 b, float2 p, float2 @default = default)

Position p expressed in barycentric coordinate system defined within line segment (a, b). If the result is not finite, then returns default.

float3 BarycentricSafe(float2 a, float2 b, float2 c, float2 p, float3 @default = default)

Position p expressed in barycentric coordinate system defined within triangle (a, b, c). If the result is not finite, then returns default.

float CCW(float2 a, float2 b, float2 c)

Triangle (a, b, c) counterclockwise check.

Returns:

bool IsConvexQuadrilateral(float2 a, float2 b, float2 c, float2 d)

true if quadrilateral (a, b, c, d) is convex, false otherwise.

void PointClosestPointOnLineSegment(float2 a, float2 b0, float2 b1, out float2 p)

Procedure finds the closest point p on the line segment (b0, b1) to point a.

bool PointInsideTriangle(float2 p, float2 a, float2 b, float2 c)

true if p is inside triangle (a, b, c), false otherwise.

bool PointInsideTriangle(float2 p, float2 a, float2 b, float2 c, out float3 bar)

true if p is inside triangle (a, b, c), false otherwise. bar corresponds to barycentric coordinates of p in triangle (a, b, c).

float PointLineSignedDistance(float2 p, float2 n, float2 a)

Point–line signed distance.

void ShortestLineSegmentBetweenLineSegments(float2 a0, float2 a1, float2 b0, float2 b1, out float2 pA, out float2 pB)

Procedure finds the shortest line segment (pA, pB), between line segments (a0, a1) and (b0, b1)

Misc

int BilateralInterleavingId(int id, int count)

Utility function for id enumeration in bilateral interleaving order, e.g. sequence of id = 0, 1, 2, 3, 4, 5 (count = 6), will be enumerated in the following way: 0, 5, 1, 4, 2, 3.

int2 ConvertFromTriMatId(int index)

Utility function for converting linear index into 2-d index for lower triangular matrix, stored in a row-wise fashion.

Based on the paper1.

int ConvertToTriMatId(int i, int j)

Utility function for converting 2-d index into linear index for lower triangular matrix, stored in a row-wise fashion.

float Round(float value, int digits)

Rounds value with respect to given digits.

float2 Round(float value, int digits)

Rounds value with respect to given digits.

float3 Round(float value, int digits)

Rounds value with respect to given digits.

Complex

Struct complex is a burst-friendly complex number representation. It supports basic arthimetic operators +, -, *, /. Complex struct implementation is based on Unity.Collections.float2 so all functions/operations should be optimized using Burst SIMD intrinsics.

Small demo how Complex can be used is presented below

Complex z = (1.2f, 5.7f);
z += 1f; // Expected: z = (2.2f, 5.7f)

z = (0, 1);
z *= z; // Expected: z = (-1, 0)

z = Complex.Polar(r: 2, phi: math.PI); // Returns 2 * exp(i * PI)

Additional utility functions for complex numbers can be found below.

Complex Conjugate(Complex z)

Conjugated number z, i.e. z*.

Complex LookRotation(float2 direction)

Complex number which represent view in the given direction.

Complex LookRotationSafe(float2 direction, float2 @default = default)

Complex number which represent view in the given direction. If rotation cannot be represented by the finite number, then returns default.

Complex Normalize(Complex z)

Normalized complex number z.

Complex NormalizeSafe(Complex z, Complex @default = default)

Normalized complex number z. If normalized number cannot be represented by the finite number, then returns default.

Complex Polar(float r, float phi)

Complex number via polar construction: r · eⁱᵠ.

Complex PolarUnit(float phi)

Complex number via (unit length) polar construction: r · eⁱᵠ.

Complex Pow(Complex z, float x)

z raised to the power x, i.e. zˣ.

Complex Reciprocal(Complex z)

Repciprocal of z, i.e. z⁻¹.

Dependencies

Footnotes

  1. M. Angeletti, J-M. Bonny, and J. Koko. "Parallel Euclidean distance matrix computation on big datasets." (2019). ↩