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-vectorUse:
// 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:
- Removed
.rotateByand.rotateByDegwhich seemed to be broken or not useful (Related issue) - Renamed
.rotateand.rotateDegto.rotateByand.rotateByDegto make the name more explicit. - Renamed
.lengthand.lengthSqto.magand.magSqfor personal preferences, because it's more consistent with method names likeclampMagand the vocabulary used in several places in the doc. - Added explicit errors when trying to divide by zero (Related issue)
- Added explicit errors when required parameters are missing or have invalid values.
.toFixedwas 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:
- Completed documentation (In particular for the remaining rotation functions)
- Added methods
.angleWith,.angleWithDeg,.orientedAngleWithand.orientedAngleDegWithto compute angle between two vectors. .mixnow validates the percentage value and throws an error if the percentage is<0or>1.- Added
.resize(Related issue, Victor MR #39 but with a ~10x faster implementation than the proposed code) - Added
.rotateTowards/.rotateTowardsDegto steer a vector toward another one. - Updated
.fromArrayand.fromObjectto explicitly fail on invalid input. - Added
.clampMagto clamp the magnitude, also.clampX,.clampYand.clampAxesto clamp the axes. - Added
.fromPolarand.toPolarmethods. (Related issue) - Added
.limitXand.limitYto go with.limit - Added
.isParallelToand.isPerpendicularTo. (Victor #42 but using already existing.dotand.crossmethods) - Added
.slopeto get the slope of the line passing by the vector - Added
.reflectto reflect the vector against a surface's normal vector - Added
.randomUnitVectorto create a random vector of magnitude1 - Added
.isEqualToand.isCloseToto compare vectors axes - Added
.manhattanDistance(other: Vector)anddistanceChebyshev(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.