# 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.

## Getting Started #

1. Add the following to your project's pubspec.yaml and run `pub get`.

``````dependencies:
vector_math: any
``````

``````import 'package:vector_math/vector_math.dart';
``````

## Examples #

1. Using the GLSL getter and setter syntax.

``````import 'package:vector_math/vector_math.dart';

void main() {
Vector3 x = new Vector3.zero(); // Zero vector
Vector4 y = new 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 = new Matrix4.rotationY(PI * 0.5)..translate(5.0, 2.0, 3.0);
// A point.
Vector3 position = new 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 = new 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 = new 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 = new Quaternion.axisAngle(axis, angle);
// A point.
Vector3 point = new 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 = new Aabb2.minMax(new Vector2.zero(), new Vector2(4.0, 4.0));
// Define the second box
Aabb2 aabbTwo =
new Aabb2.minMax(new Vector2(5.0, 5.0), new Vector2(6.0, 6.0));
// Extend the second box to contain a point
aabbTwo.hullPoint(new 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 = new Ray.originDirection(new Vector3.zero(), new 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 = new Sphere.centerRadius(new 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 = new Vector4.zero();
// Convert the red color to a grayscaled color.
Colors.toGrayscale(red, gray);
// Parse a blue color from a hex string.
Vector4 blue = new 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);
}
``````

## Development #

To run test cases:

``````~/src/vector_math/> pub run test:test
``````

To automatically generate the latest version of `vector_math_64`:

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

# Changelog - vector_math #

## v 2.0.8 - July 2018 #

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

## v 2.0.7 - April 2018 #

• Fixed indexing bug in MeshGeometry.combine

## v 2.0.6 - March 2018 #

• Fixed angleTo for vectors that do not have unit length

## v 2.0.5 - July 2017 #

• Strong mode clean

## v 2.0.3 - May 2016 #

• Synchronize Float64 version

## v 2.0.1 - April 2016 #

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

## v 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

## v 1.4.7 - February 2016 #

• Fixed ArgumentError usage in Matrix4.inverted constructor

## v 1.4.4 - December 2014 #

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

## v 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

## v 1.4.1 - January 2014 #

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

## v 1.4.0 - November 2013 #

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

## v 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)

## v 1.1.0 - April 2013 #

• Large refactoring.

## v 0.9.7 - March 2013 #

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

## v 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.

## v 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.

## v 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

## v 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().

## v 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.

## v 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
• 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

## v 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 buildPlaneVectors which constructs the spanning vectors given a plane normal
• Fixed many bugs in quaternion class
• Fixed adjoint matrix code generation
• Added serialization support for Float32Array and Vectors/Matrices

## v 0.0.0 - March 20 2012 #

• Initial release

## Use this package as a library

### 1. Depend on it

``````
dependencies:
vector_math: ^2.0.8

``````

### 2. Install it

You can install packages from the command line:

with pub:

``````
\$ pub get

``````

with Flutter:

``````
\$ flutter pub get

``````

Alternatively, your editor might support `pub get` or `flutter pub get`. Check the docs for your editor to learn more.

### 3. Import it

Now in your Dart code, you can use:

``````
import 'package:vector_math/vector_math.dart';
``````
 Popularity: Describes how popular the package is relative to other packages. [more] 99 Health: Code health derived from static analysis. [more] 75 Maintenance: Reflects how tidy and up-to-date the package is. [more] 29 Overall: Weighted score of the above. [more] 78

We analyzed this package on Jan 24, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

• Dart: 2.7.0
• pana: 0.13.4

#### Health suggestions

Fix `lib/src/vector_math/colors.dart`. (-25 points)

Analysis of `lib/src/vector_math/colors.dart` reported 146 hints, including:

line 11 col 45: Unnecessary new keyword.

line 14 col 46: Unnecessary new keyword.

line 71 col 11: Unnecessary new keyword.

line 79 col 18: Use `=` to separate a named parameter from its default value.

line 79 col 37: Use `=` to separate a named parameter from its default value.

Fix `lib/src/vector_math/vector3.dart`. (-25 points)

Analysis of `lib/src/vector_math/vector3.dart` reported 129 hints, including:

line 42 col 7: Unnecessary new keyword.

line 46 col 7: Unnecessary new keyword.

line 49 col 33: Unnecessary new keyword.

line 52 col 40: Unnecessary new keyword.

line 55 col 42: Unnecessary new keyword.

Fix `lib/src/vector_math/vector4.dart`. (-25 points)

Analysis of `lib/src/vector_math/vector4.dart` reported 346 hints, including:

line 45 col 7: Unnecessary new keyword.

line 49 col 7: Unnecessary new keyword.

line 52 col 33: Unnecessary new keyword.

line 55 col 33: Unnecessary new keyword.

line 58 col 40: Unnecessary new keyword.

Fix additional 57 files with analysis or formatting issues. (-431.13 points)

Additional issues in the following files:

• `lib/src/vector_math_64/colors.dart` (146 hints)
• `lib/src/vector_math_64/vector3.dart` (129 hints)
• `lib/src/vector_math_64/vector4.dart` (346 hints)
• `lib/src/vector_math_geometry/generators/cube_generator.dart` (48 hints)
• `lib/src/vector_math/matrix4.dart` (39 hints)
• `lib/src/vector_math_64/matrix4.dart` (39 hints)
• `lib/src/vector_math/vector2.dart` (37 hints)
• `lib/src/vector_math_64/vector2.dart` (37 hints)
• `lib/src/vector_math/aabb3.dart` (36 hints)
• `lib/src/vector_math_64/aabb3.dart` (36 hints)
• `lib/src/vector_math/third_party/noise.dart` (28 hints)
• `lib/src/vector_math_64/third_party/noise.dart` (28 hints)
• `lib/src/vector_math/obb3.dart` (24 hints)
• `lib/src/vector_math_64/obb3.dart` (24 hints)
• `lib/src/vector_math_geometry/mesh_geometry.dart` (21 hints)
• `lib/src/vector_math/matrix3.dart` (20 hints)
• `lib/src/vector_math_64/matrix3.dart` (20 hints)
• `lib/src/vector_math/quaternion.dart` (19 hints)
• `lib/src/vector_math_64/quaternion.dart` (19 hints)
• `lib/src/vector_math_geometry/generators/attribute_generators.dart` (17 hints)
• `lib/src/vector_math/opengl.dart` (15 hints)
• `lib/src/vector_math_64/opengl.dart` (15 hints)
• `lib/src/vector_math/matrix2.dart` (14 hints)
• `lib/src/vector_math_64/matrix2.dart` (14 hints)
• `lib/src/vector_math/aabb2.dart` (13 hints)
• `lib/src/vector_math_64/aabb2.dart` (13 hints)
• `lib/src/vector_math/quad.dart` (12 hints)
• `lib/src/vector_math_64/quad.dart` (12 hints)
• `lib/src/vector_math/ray.dart` (11 hints)
• `lib/src/vector_math_64/ray.dart` (11 hints)
• `lib/src/vector_math_geometry/generators/geometry_generator.dart` (11 hints)
• `lib/src/vector_math/triangle.dart` (9 hints)
• `lib/src/vector_math_64/triangle.dart` (9 hints)
• `lib/src/vector_math_geometry/generators/cylinder_generator.dart` (9 hints)
• `lib/src/vector_math/frustum.dart` (8 hints)
• `lib/src/vector_math_64/frustum.dart` (8 hints)
• `lib/src/vector_math_geometry/filters/flat_shade_filter.dart` (8 hints)
• `lib/src/vector_math_lists/vector_list.dart` (8 hints)
• `lib/src/vector_math_geometry/filters/barycentric_filter.dart` (7 hints)
• `lib/src/vector_math_geometry/generators/ring_generator.dart` (7 hints)
• `bin/mesh_generator.dart` (6 hints)
• `lib/src/vector_math/plane.dart` (5 hints)
• `lib/src/vector_math_64/plane.dart` (5 hints)
• `lib/src/vector_math_geometry/generators/circle_generator.dart` (5 hints)
• `lib/src/vector_math_geometry/generators/sphere_generator.dart` (5 hints)
• `lib/src/vector_math_geometry/filters/color_filter.dart` (4 hints)
• `lib/src/vector_math/sphere.dart` (3 hints)
• `lib/src/vector_math_64/sphere.dart` (3 hints)
• `lib/src/vector_math_operations/matrix.dart` (3 hints)
• `lib/src/vector_math_lists/scalar_list_view.dart` (2 hints)
• `lib/src/vector_math/intersection_result.dart` (1 hint)
• `lib/src/vector_math_64/intersection_result.dart` (1 hint)
• `lib/src/vector_math_geometry/filters/geometry_filter.dart` (1 hint)
• `lib/src/vector_math_geometry/filters/transform_filter.dart` (1 hint)
• `lib/src/vector_math_lists/vector2_list.dart` (1 hint)
• `lib/src/vector_math_lists/vector3_list.dart` (1 hint)
• `lib/src/vector_math_lists/vector4_list.dart` (1 hint)

#### Maintenance suggestions

Package is getting outdated. (-50.41 points)

The package was last published 78 weeks ago.

The package description is too short. (-11 points)

Add more detail to the `description` field of `pubspec.yaml`. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Maintain an example. (-10 points)

Create a short demo in the `example/` directory to show how to use this package.

Common filename patterns include `main.dart`, `example.dart`, and `vector_math.dart`. Packages with multiple examples should provide `example/README.md`.