@rawify/vector2
Version:
The RAW JavaScript 2D Vector library
336 lines (213 loc) • 7.92 kB
Markdown
# Vector2.js
[](https://www.npmjs.com/package/@rawify/vector2 "View this project on npm")
[](http://opensource.org/licenses/MIT)
Vector2.js is a lightweight 2D vector library for JavaScript that provides a set of vector operations commonly used in graphics, physics simulations, and other geometric applications.
## Features
- Basic vector operations: addition, subtraction, scaling, negation
- Geometric functions: dot product, cross product, orthogonal projection, reflection
- Utility functions: normalization, angle, distance, rotation, linear interpolation (lerp)
- Support for creating vectors from arrays or objects
- Ability to work with Hadamard products, rejection from vectors, and more
## Installation
You can install `Vector2.js` via npm:
```bash
npm install @rawify/vector2
```
Or with yarn:
```bash
yarn add @rawify/vector2
```
Alternatively, download or clone the repository:
```bash
git clone https://github.com/rawify/Vector2.js
```
## Usage
Include the `vector2.min.js` file in your project:
```html
<script src="path/to/vector2.min.js"></script>
```
Or in a Node.js project:
```javascript
const Vector2 = require('@rawify/vector2');
```
or
```javascript
import Vector2 from '@rawify/vector2';
```
### Creating a Vector
Vectors can be created using `new Vector2` or the `Vector2` function:
```javascript
let v1 = Vector2(1, 2);
let v2 = new Vector2(3, 4);
```
You can also initialize vectors from arrays or objects:
```javascript
let v3 = new Vector2([1, 2]);
let v4 = new Vector2({ x: 3, y: 4 });
```
## Methods
### `add(v)`
Adds the vector `v` to the current vector.
```javascript
let v1 = new Vector2(1, 2);
let v2 = new Vector2(3, 4);
let result = v1.add(v2); // {x: 4, y: 6}
```
### `sub(v)`
Subtracts the vector `v` from the current vector.
```javascript
let result = v1.sub(v2); // {x: -2, y: -2}
```
### `neg()`
Negates the current vector (flips the direction).
```javascript
let result = v1.neg(); // {x: -1, y: -2}
```
### `scale(s)`
Scales the current vector by a scalar `s`.
```javascript
let result = v1.scale(2); // {x: 2, y: 4}
```
### `prod(v)`
Calculates the Hadamard (element-wise) product of the current vector and `v`.
```javascript
let result = v1.prod(v2); // {x: 3, y: 8}
```
### `dot(v)`
Computes the [dot product](https://raw.org/book/linear-algebra/dot-product/) between of the current vector and `v`.
```javascript
let result = v1.dot(v2); // 11
```
### `cross(v)`
Calculates the [2D cross product](https://raw.org/book/linear-algebra/2d-perp-product/) (perpendicular dot product) between the current vector and `v`.
```javascript
let result = v1.cross(v2); // -2
```
### `perp()`
Finds a [perpendicular vector](https://raw.org/book/linear-algebra/2d-perp-operator/) to the current vector.
```javascript
let result = v1.perp(); // {x: -2, y: 1}
```
### `projectTo(v)`
Projects the current vector onto the vector `v` using [vector projection](https://raw.org/book/linear-algebra/dot-product/).
```javascript
let result = v1.projectTo(v2); // Projection of v1 onto v2
```
### `rejectFrom(v)`
Finds the orthogonal [vector rejection](https://raw.org/book/linear-algebra/dot-product/) of the current vector from the vector `v`.
```javascript
let result = v1.rejectFrom(v2); // Rejection of v1 from v2
```
### `reflect(n)`
Determines the [vector reflection](https://raw.org/book/linear-algebra/dot-product/) of the current vector across the vector `n`.
```javascript
let n = new Vector2(0, 1);
let result = v1.reflect(n); // Reflection of v1 across n
```
### `refract(n, eta)`
Determines the [vector refraction](https://raw.org/book/linear-algebra/dot-product/) of the current **unit vector** across a surface with **unit normal** `n`, using the index ratio `eta = η_in / η_out` (like from air η_in=1.0 to water η_out=1.33).
```javascript
let n = new Vector2(0, 1); // Surface normal pointing up
let eta = 1.0 / 1.33; // Air to glass
let result = v1.refract(n, eta); // Refraction of v1 across n
```
Returns a new unit vector representing the **refracted direction**, or `null` if **total internal reflection** occurs.
### `angle()`
Returns the angle of the current vector in radians relative to the x-axis.
```javascript
let result = v1.angle(); // 1.107 radians
```
### `norm()`
Returns the magnitude or length (Euclidean norm) of the current vector.
```javascript
let result = v1.norm(); // 2.236
```
### `norm2()`
Returns the squared magnitude or length (norm squared) of the current vector.
```javascript
let result = v1.norm2(); // 5
```
### `normalize()`
Returns a normalized vector (unit vector) of the current vector.
```javascript
let result = v1.normalize(); // {x: 0.447, y: 0.894}
```
### `distance(v)`
Calculates the Euclidean distance between the current vector and `v`.
```javascript
let result = v1.distance(v2); // 2.828
```
### `set(v)`
Sets the values of the current vector to match the vector `v`.
```javascript
v1.set(v2); // v1 is now {x: 3, y: 4}
```
### `rotate(angle)`
Rotates the current vector by the given `angle` (in radians).
```javascript
let result = v1.rotate(Math.PI / 4); // Rotates v1 by 45 degrees
```
### `apply(fn, v)`
Applies a function `fn` (such as `Math.abs`, `Math.min`, `Math.max`) to the components of the current vector and an optional vector `v`.
```javascript
let result1 = v1.apply(Math.min, v2); // Determines the minimum of v1 and v2 on each component
let result2 = v1.apply(Math.max, v2); // Determines the maximum of v1 and v2 on each component
let result3 = v1.apply(Math.round); // Rounds the components of the vector
let result4 = v1.apply(Math.floor); // Floors the components of the vector
let result4 = v1.apply(x => Math.min(upper, Math.max(lower, x))); // Clamps the component to the interval [lower, upper]
```
### `toArray()`
Returns the current vector as an array `[x, y]`.
```javascript
let result = v1.toArray(); // [1, 2]
```
### `clone()`
Returns a clone of the current vector.
```javascript
let result = v1.clone(); // A new vector with the same x and y values as v1
```
### `equals(v)`
Checks if the current vector is equal to the vector `v`.
```javascript
let result = v1.equals(v2); // false
```
### `isParallel(v)`
Checks if the current vector is parallel zu vector `v`.
### `isUnit()`
Checks if the current vector is a normalized unit vector.
### `lerp(v, t)`
Performs a linear interpolation between the current vector and `v` by the factor `t`.
```javascript
let result = v1.lerp(v2, 0.5); // {x: 2, y: 3}
```
### `toString()`
String representation of the current vector
## Static Methods
### `Vector2.random()`
Generates a vector with random x and y values between 0 and 1.
```javascript
let randomVector = Vector2.random(); // {x: 0.67, y: 0.45}
```
### `Vector2.fromPoints(a, b)`
Creates a vector from two points `a` and `b`.
```javascript
let result = Vector2.fromPoints({x: 1, y: 1}, {x: 4, y: 5}); // {x: 3, y: 4}
```
### `Vector2.fromBarycentric(A, B, C, u, v)`
Given a triangle (A, B, C) and a barycentric coordinate (u, v[, w = 1 - u - v]) calculate the cartesian coordinate in R^2.
## Coding Style
As every library I publish, Vector2.js is also built to be as small as possible after compressing it with Google Closure Compiler in advanced mode. Thus the coding style orientates a little on maxing-out the compression rate. Please make sure you keep this style if you plan to extend the library.
## Building the library
After cloning the Git repository run:
```
npm install
npm run build
```
## Run a test
Testing the source against the shipped test suite is as easy as
```
npm run test
```
## Copyright and Licensing
Copyright (c) 2025, [Robert Eisele](https://raw.org/)
Licensed under the MIT license.