vector_math 2.0.4

vector_math

Build Status Coverage Status

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

Getting Started

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

dependencies:
  vector_math: any

2. Add the correct import for your project.

import 'package:vector_math/vector_math.dart';

Documentation

Read the docs

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 distancFromOrigin = ray.intersectsWithSphere(sphere);
  // Evaluate the position of the intersection, in this case (3.0 0.0 0.0).
  Vector3 position = ray.at(distancFromOrigin);
}

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.4 - February 2017

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

v 2.0.3 - May 2016

  • Synchronize Float64 version

v 2.0.2 - May 2016

  • Add Matrix4.leftTranslate

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.6 - January 2016

  • Added MatrixX.fromList constructor

v 1.4.5 - January 2016

  • Added 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
  • 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

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

v 0.0.0 - March 20 2012

  • Initial release

1. Depend on it

Add this to your package's pubspec.yaml file:

dependencies:
  vector_math: "^2.0.4"

2. Install it

You can install packages from the command line:

$ pub get

Alternatively, your editor might support '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';

About

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

Author

Email john@johnmccutchan.com John McCutchan

Homepage

github.com/google/vector_math.dart

Documentation

www.dartdocs.org/documentation/vector_math/2.0.4/

Source code (hyperlinked)

www.crossdart.info/p/vector_math/2.0.4/

Uploader

john@johnmccutchan.com
kevmoo@google.com
johnmccutchan@google.com

Share