A 2D vector math library built as a modern module without dependencies.
Check out the documentation and the interactive examples.
The code is largely inspired from Victor.js adding TypeScript typing, updating documentation, fixing some long running issues and adding some features.
The published package on npm contains CommonJS, ECMAScript and UMD modules. So you should be able to use this package anywhere from nodeJS or deno backends to frontent applications using vanilla JavaScript or your favorite frontend framework like Svelte or React.
Install with
npm install --save simple-vector
Use:
// If in an ESM project
import { Vector } from 'simple-vector';
// Else if in a commonJS project
const { Vector } = require('simple-vector');
// Create a new vector
const v = new Vector(1, 0);
// Create a second vector from the first one and transform it
const w = v
.clone()
.multiplyScalar(10)
.rotateBy(Math.PI / 2);
// Compute their dot product
const dot = v.dot(w);
Using a CDN to include the package in a vanilla JS page
<html>
<head>
<title>SimpleVector Example</title>
</head>
<body>
<script src="https://unpkg.com/simple-vector/dist/simple-vector.umd.js"></script>
<script>
const { Vector } = SimpleVector;
const v1 = new Vector(0, 0);
const v2 = new Vector(5, 5);
const sum = v1.clone().add(v2);
const span = document.createElement('span');
span.innerText = `${v1.toString()} + ${v2.toString()} = ${sum.toString()}`;
document.body.appendChild(span);
</script>
</body>
</html>
If you are a user of Victor.js you should feel mostly at home with simple-vector. Be warned that some features have been reworked:
.rotateBy and .rotateByDeg which seemed to be broken or not useful (Related issue).rotate and .rotateDeg to .rotateBy and .rotateByDeg to make the name more explicit..length and .lengthSq to .mag and .magSq for personal preferences, because it's more consistent with method names like clampMag and the vocabulary used in several places in the doc..toFixed was renamed to .fixPrecision. Also it converted components to string so we fixed the method to keep them number (Related issue)Note that we also added a few features we felt were missing on Victor.js or were requested in the project's issues:
.angleWith, .angleWithDeg, .orientedAngleWith and .orientedAngleDegWith to compute angle between two vectors..mix now validates the percentage value and throws an error if the percentage is <0 or >1..resize (Related issue, Victor MR #39 but with a ~10x faster implementation than the proposed code).rotateTowards/.rotateTowardsDeg to steer a vector toward another one..fromArray and .fromObject to explicitly fail on invalid input..clampMag to clamp the magnitude, also .clampX, .clampY and .clampAxes to clamp the axes..fromPolar and .toPolar methods. (Related issue).limitX and .limitY to go with .limit.isParallelTo and .isPerpendicularTo. (Victor #42 but using already existing .dot and .cross methods).slope to get the slope of the line passing by the vector.reflect to reflect the vector against a surface's normal vector.randomUnitVector to create a random vector of magnitude 1.isEqualTo and .isCloseTo to compare vectors axes.manhattanDistance(other: Vector) and distanceChebyshev(vec: Vector) to compute different distances between vectors.We also ported the original tests and added new ones.
DEV.md has some notes about how to setup the repo for development.
I don't expect anyone to contribute to this repo anytime soon, if I'm wrong don't hesitate to create an issue on GitHub.