vector_math

Introduction

A Vector math library for 2D and 3D applications.

Features

• 2D, 3D, and 4D vector and matrix types.
• Quaternion type for animating rotations.
• Collision detection: AABB, rays, spheres, ...
• Utilities like color and common rendering related operations
• Flexible getters and setters, for example, position.xwz = color.grb;.
• Fully documented.
• Well tested.
• Heavily optimized.

Libraries using vector_math

• Flutter
• Flame

Examples

1. Using the GLSL getter and setter syntax.

import 'package:vector_math/vector_math.dart';
                
                void main() {
                  Vector3 x = Vector3.zero(); // Zero vector
                  Vector4 y = Vector4.all(4.0); // Vector with 4.0 in all lanes
                  x.zyx = y.xzz; // Sets z,y,x the values in x,z,z
                }
                

2. Transforming a vector.

import 'dart:math';
                import 'package:vector_math/vector_math.dart';
                
                void main() {
                  // Rotation of PI/2 degrees around the Y axis followed by a
                  // translation of (5.0, 2.0, 3.0).
                  Matrix4 T = Matrix4.rotationY(PI * 0.5)..translate(5.0, 2.0, 3.0);
                  // A point.
                  Vector3 position = Vector3(1.0, 1.0, 1.0);
                  // Transform position by T.
                  T.transform3(position);
                }
                

3. Invert a matrix

import 'dart:math';
                import 'package:vector_math/vector_math.dart';
                
                void main() {
                  // Rotation of 90 degrees around the Y axis followed by a
                  // translation of (5.0, 2.0, 3.0).
                  Matrix4 T = Matrix4.rotationY(PI * 0.5)..translate(5.0, 2.0, 3.0);
                  // Invert T.
                  T.invert();
                  // Invert just the rotation in T.
                  T.invertRotation();
                }
                

4. Rotate a vector using a quaternion

import 'dart:math';
                import 'package:vector_math/vector_math.dart';
                
                void main() {
                  // The X axis.
                  Vector3 axis = Vector3(1.0, 0.0, 0.0);
                  // 90 degrees.
                  double angle = PI / 2.0;
                  // Quaternion encoding a 90 degree rotation along the X axis.
                  Quaternion q = Quaternion.axisAngle(axis, angle);
                  // A point.
                  Vector3 point = Vector3(1.0, 1.0, 1.0);
                  // Rotate point by q.
                  q.rotate(point);
                }
                

5. Check if two axis aligned bounding boxes intersect

import 'package:vector_math/vector_math.dart';
                
                void main() {
                  // Define the first box with a minimum and a maximum.
                  Aabb2 aabbOne = Aabb2.minMax(Vector2.zero(), Vector2(4.0, 4.0));
                  // Define the second box
                  Aabb2 aabbTwo = Aabb2.minMax(Vector2(5.0, 5.0), Vector2(6.0, 6.0));
                  // Extend the second box to contain a point
                  aabbTwo.hullPoint(Vector2(3.0, 3.0));
                  // Check if the two boxes intersect, returns true in this case.
                  bool intersect = aabbOne.intersectsWithAabb2(aabbTwo);
                }
                

6. Check where a ray and a sphere intersect

import 'package:vector_math/vector_math.dart';
                
                void main() {
                  // Define a ray starting at the origin and going into positive x-direction.
                  Ray ray = Ray.originDirection(Vector3.zero(), Vector3(1.0, 0.0, 0.0));
                  // Defines a sphere with the center (5.0 0.0 0.0) and a radius of 2.
                  Sphere sphere = Sphere.centerRadius(Vector3(5.0, 0.0, 0.0), 2.0);
                  // Checks if the ray intersect with the sphere and returns the distance of the
                  // intersection from the origin of the ray. Would return null if no intersection
                  // is found.
                  double distanceFromOrigin = ray.intersectsWithSphere(sphere);
                  // Evaluate the position of the intersection, in this case (3.0 0.0 0.0).
                  Vector3 position = ray.at(distanceFromOrigin);
                }
                

7. Work with colors

import 'package:vector_math/vector_math.dart';
                
                void main() {
                  // Access a build-in color, colors are stored in 4-dimensional vectors.
                  Vector4 red = Colors.red;
                  Vector4 gray = Vector4.zero();
                  // Convert the red color to a grayscaled color.
                  Colors.toGrayscale(red, gray);
                  // Parse a blue color from a hex string.
                  Vector4 blue = Vector4.zero();
                  Colors.fromHexString('#0000FF', blue);
                  // Convert the blue color from RGB to HSL.
                  Colors.rgbToHsl(blue, blue);
                  // Reduce the lightness of the color by 50%.
                  blue.z *= 0.5;
                  // Convert the HSL color back to RGB.
                  Colors.hslToRgb(blue, blue);
                }
                

8. Use 64bit float precision (instead of 32bit)

// Use different import statement.
                // Which is a drop-in replacement for 'package:vector_math/vector_math.dart'
                import 'package:vector_math/vector_math_64.dart';
                void main() {
                  // Types work the same, but using 64 bit storage.
                  Vector3 x = Vector3.zero(); 
                  Matrix4 m = Matrix4.identity();
                }
                

Development

To run the unit tests:

~/src/vector_math/> dart test
                

To automatically generate the latest version of vector_math_64:

~/src/vector_math/> dart tool/generate_vector_math_64.dart
                

2.2.0

• Performance of functions that take dynamic arguments improved.

• Most of the members that take dynamic arguments are deprecated. New members with non-dynamic arguments added.

  Deprecated members:

  • Matrix4.translate

    Instead use: Matrix4.translateByDouble, Matrix4.translateByVector3, Matrix4.translateByVector4.

  • Matrix4.leftTranslate

    Instead use: Matrix4.leftTranslateByDouble, Matrix4.leftTranslateByVector3, Matrix4.leftTranslateByVector4.

  • Matrix4.scale

    Instead use: Matrix4.scaleByDouble, Matrix4.scaleByVector3, Matrix4.scaleByVector4.

  • Matrix4.scaled

    Instead use: Matrix4.scaledByDouble, Matrix4.scaledByVector3, Matrix4.scaledByVector4.

2.1.5

• Fixed operator -() of Quaternion (Contributed by tlserver)
• Fixed Matrix3.rotationY direction (Contributed by tlserver, moritzblume)
• Added an operator== to Quaternion so that two instances of quaternions can be evaluated for equality.
• Require Dart 3.1

2.1.4

• Refactor the locations of the SimplexNoise related part files.

2.1.3

• operator == overrides no longer take nullable arguments. This is only visible for classes that implement the interfaces defined in this package which no longer need to also widen the argument type.
• Deprecate SimplexNoise (see https:github.com/google/vector_math.dart/issues/270 for more information).

2.1.2

• Fix to Quad.copy (#221)

2.1.1

• Deprecate hash.dart.
• Require Dart v2.14 or greater.

2.1.0

• Stable release for null safety.
• Improve performance of Matrix4.decompose by reusing objects.

2.0.8 - July 2018

• Internal fix to use Dart 2 core library constant names.

2.0.7 - April 2018

• Fixed indexing bug in MeshGeometry.combine

2.0.6 - March 2018

• Fixed angleTo for vectors that do not have unit length
• Added Matrix4.tryInvert.

2.0.5 - July 2017

• Strong mode clean

2.0.4 - February 2017

• Added Matrix4.isIdentity()
• Added Matrix4.isZero()
• Added Matrix3.isIdentity()
• Added Matrix3.isZero()
• Added Vector2.angleTo and Vector2.angleToSigned

2.0.3 - May 2016

• Synchronize Float64 version

2.0.2 - May 2016

• Add Matrix4.leftTranslate

2.0.1 - April 2016

• Add Matrix4.SkewX, Matrix4.SkewY, and Matrix4.Skew constructors

2.0.0 - March 2016

• Remove call chaining, methods don't return this anymore. You can use the method cascade operator instead.
• Remove dependency on quiver package

1.4.7 - February 2016

• Fixed ArgumentError usage in Matrix4.inverted constructor

1.4.6 - January 2016

• Added MatrixX.fromList constructor

1.4.5 - January 2016

• Added Matrix4.inverted constructor

1.4.4 - December 2014

• Updated dependencies.
• Moved benchmark code into benchmark/
• Updated vector_math_64.

1.4.3 - February 2014

• Add color conversion routines (Contributed by Oliver Sand)
• More collision and geometry routines (Contributed by Oliver Sand)
• More tests (Contributed by Oliver Sand)
• v 1.4.3 pub release

1.4.1 - January 2014

• Better mesh generators (contributed by Brandon Jones)
• Fix bug in ray v. triangle intersection test (contributed by @AMagill)

1.4.0 - November 2013

• Add basic mesh generators (contributed by Brandon Jones)
• Add more collision detection objects (contributed by Oliver Sand)

1.3.5 - July 2013

• Class names now start with upper case, following Dart style guide.
• Performance audit.
• New vector_math_operations library.
• New vector_math_lists library.
• Added Aabb2 and fleshed out Aabb3 (thanks to Laszlo Korte)
• Added Matrix solve methods (thanks to Laszlo Korte)
• Added Methods needed for Three.dart (thanks to Anders Forsell)

1.1.0 - April 2013

• Large refactoring.

0.9.7 - March 2013

• Refactor generated constructor code into small functions.
• Refactor generated operator* code into small functions.
• Fix typo in quaternion code.

0.9.6 - March 2013

• Update to latest String library.
• Fix holding references in matrix constructor.
• Replace double type with num in rotationY, and rotationZ.

0.9.5 - February 2013

• Remove remaining double type tests and replace them with num.
• Don't throw in the default matrix and vector constructors.

0.9.4 - February 2013

• Remove unnecessary dart:scalarlist import.
• Now that dart2js is fixed, rename negate_ back to negate.
• Fix library imports in test suites.
• Flexible constructor fix added to the generator.
• Tested library under dart2js

0.9.3 - February 2013

• Revert to using a single library!
• Public API reverted to taking nums instead of doubles.
• Fixed all warnings/errors introduced by M3.
• drone.io integrated tests.
• Fixed bug in rotation construction.
• Fixed bug in orthographic matrix construction.
• External contribution by fkleon fixing flexible constructors.
• External contribution by donny-dont adding a missing cast .toDouble().

0.9.0 - October 2012

• Pub: Dart Vector Math now fully supports the pub package management system!
• API++: Minor changes to the API everywhere. The changes improve the aesthetics and performance of the library.
• Faster: Lots of performance tweaks resulting in the library getting faster and generating less garbage.
• 2D Cross Product: The Box2D Dart port requires a 2D cross product.
• Library Split: Two libraries, one for browser applications and console applications.

0.8.5 - July 29 2012

• 33% faster matrix matrix multiply
• Fix generated operator[]=
• Fix OpenGL lookat and perspective matrix constructors
• Fix mat4x4 rotation constructors
• Fix mat4x4 multiplied with vector3 not applying translation
• Add utility methods for moving between Dart Vector Math types and Float32Array/Float32List types
• Add mat4x4 translation constructor
• Fixed buildPlaneVectors method
• Fix mat4x4 transformDirect3 not applying translation
• Add a new variant of mix() that takes the parameter t as a num or a vector
• Large code reorganization to make it fit the 'dartblanklib' template

0.8.0 - June 10 2012

• Inverse of 2x2,3x3,4x4 matrices
• Inverse of upper 3x3 of a 4x4 matrix
• Added zero, copy and raw specialized (and branchless) vector constructors
• Added specialized copy matrix constructor
• Added specialized rotation matrix constructors for mat2x2, mat3x3, and mat4x4
• Added setRotation(num radians) to mat2x2
• Added setRotationAround[x,y,z](num radians) to mat3x3 and mat4x4
• Added buildPlaneVectors which constructs the spanning vectors given a plane normal
• Added Adjoint of 2x2,3x3, and 4x4 matrices
• Fixed many bugs in quaternion class
• Fixed adjoint matrix code generation
• Added selfAdd, selfSub, selfScale and selfNegate to matrix classes
• Added serialization support for Float32Array and Vectors/Matrices

0.0.0 - March 20 2012

• Initial release