diff --git a/src/math/Matrices/Matrix.js b/src/math/Matrices/Matrix.js
index cf7c691268..b4d0b7d420 100644
--- a/src/math/Matrices/Matrix.js
+++ b/src/math/Matrices/Matrix.js
@@ -1,3 +1,7 @@
+/**
+ * @module Math
+ */
+
import { Vector } from "../p5.Vector";
import { MatrixInterface } from "./MatrixInterface";
@@ -15,61 +19,7 @@ if (typeof Float32Array !== "undefined") {
GLMAT_ARRAY_TYPE = Float32Array;
isMatrixArray = (x) => Array.isArray(x) || x instanceof Float32Array;
}
-/**
- * The `Matrix` class represents a mathematical matrix and provides various methods for matrix operations.
- *
- * This class extends the `MatrixInterface` and includes methods for creating, manipulating, and performing
- * operations on matrices. It supports both 3x3 and 4x4 matrices, as well as general NxN matrices.
- *
- * @class
- * @extends MatrixInterface
- *
- * @example
- * // Creating a 3x3 matrix from an array
- * const matrix = new Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
- *
- * // Creating a 4x4 identity matrix
- * const identityMatrix = new Matrix(4);
- *
- * // Adding two matrices
- * const matrix1 = new Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
- * const matrix2 = new Matrix([9, 8, 7, 6, 5, 4, 3, 2, 1]);
- * matrix1.add(matrix2); // matrix1 is now [10, 10, 10, 10, 10, 10, 10, 10, 10]
- *
- * // Setting an element in the matrix
- * matrix.setElement(0, 10); // matrix is now [10, 2, 3, 4, 5, 6, 7, 8, 9]
- *
- * // Resetting the matrix to an identity matrix
- * matrix.reset();
- *
- * // Getting the diagonal elements of the matrix
- * const diagonal = matrix.diagonal(); // [1, 1, 1]
- *
- * // Transposing the matrix
- * matrix.transpose();
- *
- * // Multiplying two matrices
- * matrix1.mult(matrix2);
- *
- * // Inverting the matrix
- * matrix.invert();
- *
- * // Scaling the matrix
- * matrix.scale(2, 2, 2);
- *
- * // Rotating the matrix around an axis
- * matrix.rotate4x4(Math.PI / 4, 1, 0, 0);
- *
- * // Applying a perspective transformation
- * matrix.perspective(Math.PI / 4, 1, 0.1, 100);
- *
- * // Applying an orthographic transformation
- * matrix.ortho(-1, 1, -1, 1, 0.1, 100);
- *
- * // Multiplying a vector by the matrix
- * const vector = new Vector(1, 2, 3);
- * const result = matrix.multiplyPoint(vector);
- */
+
export class Matrix extends MatrixInterface {
matrix;
#sqDimention;
@@ -90,7 +40,7 @@ export class Matrix extends MatrixInterface {
}
/**
- * Getter for a 3x3 matrix.
+ * Returns the 3x3 matrix if the dimensions are 3x3, otherwise returns `undefined`.
*
* This method returns the matrix if its dimensions are 3x3.
* If the matrix is not 3x3, it returns `undefined`.
@@ -106,7 +56,7 @@ export class Matrix extends MatrixInterface {
}
/**
- * Getter for a 4x4 matrix.
+ * Returns the 4x4 matrix if the dimensions are 4x4, otherwise returns `undefined`.
*
* This method returns the matrix if its dimensions are 4x4.
* If the matrix is not 4x4, it returns `undefined`.
@@ -122,16 +72,27 @@ export class Matrix extends MatrixInterface {
}
/**
- * Adds the corresponding elements of the given matrix to this matrix.
+ * Adds the corresponding elements of the given matrix to this matrix, if the dimentions are the same.
*
* @param {Matrix} matrix - The matrix to add to this matrix. It must have the same dimensions as this matrix.
* @returns {Matrix} The resulting matrix after addition.
* @throws {Error} If the matrices do not have the same dimensions.
*
* @example
- * const matrix1 = new Matrix([1, 2, 3]);
- * const matrix2 = new Matrix([4, 5, 6]);
+ * const matrix1 = new p5.Matrix([1, 2, 3]);
+ * const matrix2 = new p5.Matrix([4, 5, 6]);
* matrix1.add(matrix2); // matrix1 is now [5, 7, 9]
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix1 = new p5.Matrix([1, 2, 3, 4]);
+ * const matrix2 = new p5.Matrix([5, 6, 7, 8]);
+ * matrix1.add(matrix2);
+ * console.log(matrix1.matrix); // Output: [6, 8, 10, 12]
+ * }
+ *
*/
add(matrix) {
if (this.matrix.length !== matrix.matrix.length) {
@@ -144,17 +105,58 @@ export class Matrix extends MatrixInterface {
}
/**
- * Sets the value of a specific element in the matrix.
+ * Sets the value of a specific element in the matrix in column-major order.
+ *
+ * A matrix is stored in column-major order, meaning elements are arranged column by column.
+ * This function allows you to update or change the value of a specific element
+ * in the matrix by specifying its index in the column-major order and the new value.
+ *
+ * Parameters:
+ * - `index` (number): The position in the matrix where the value should be set.
+ * Indices start from 0 and follow column-major order.
+ * - `value` (any): The new value you want to assign to the specified element.
+ *
+ * Example:
+ * If you have the following 3x3 matrix stored in column-major order:
+ * ```
+ * [
+ * 1, 4, 7, // Column 1
+ * 2, 5, 8, // Column 2
+ * 3, 6, 9 // Column 3
+ * ]
+ * ```
+ * Calling `setElement(4, 10)` will update the element at index 4
+ * (which corresponds to row 2, column 2 in row-major order) to `10`.
+ * The updated matrix will look like this:
+ * ```
+ * [
+ * 1, 4, 7,
+ * 2, 10, 8,
+ * 3, 6, 9
+ * ]
+ * ```
+ *
+ * This function is useful for modifying specific parts of the matrix without
+ * having to recreate the entire structure.
*
* @param {Number} index - The position in the matrix where the value should be set.
* Must be a non-negative integer less than the length of the matrix.
- * @param {*} value - The new value to be assigned to the specified position in the matrix.
+ * @param {Number} value - The new value to be assigned to the specified position in the matrix.
* @returns {Matrix} The current instance of the Matrix, allowing for method chaining.
*
* @example
- * // Assuming matrix is an instance of Matrix with initial values [1, 2, 3]
- * matrix.setElement(1, 10);
- * // Now the matrix values are [1, 10, 3]
+ * // Assuming matrix is an instance of Matrix with initial values [1, 2, 3, 4] matrix.setElement(2, 99);
+ * // Now the matrix values are [1, 2, 99, 4]
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix([1, 2, 3, 4]);
+ * matrix.setElement(2, 99);
+ * console.log(matrix.matrix); // Output: [1, 2, 99, 4]
+ * }
+ *
*/
setElement(index, value) {
if (index >= 0 && index < this.matrix.length) {
@@ -168,8 +170,29 @@ export class Matrix extends MatrixInterface {
*
* This method replaces the current matrix with an identity matrix of the same dimensions.
* An identity matrix is a square matrix with ones on the main diagonal and zeros elsewhere.
+ * This is useful for resetting transformations or starting fresh with a clean matrix.
*
* @returns {Matrix} The current instance of the Matrix class, allowing for method chaining.
+ *
+ * @example
+ * // Resetting a 4x4 matrix to an identity matrix
+ * const matrix = new p5.Matrix(4);
+ * matrix.scale(2, 2, 2); // Apply some transformations
+ * console.log(matrix.matrix); // Output: Transformed matrix
+ * matrix.reset(); // Reset to identity matrix
+ * console.log(matrix.matrix); // Output: Identity matrix
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4);
+ * matrix.scale(2, 2, 2); // Apply scaling transformation
+ * console.log("Before reset:", matrix.matrix);
+ * matrix.reset(); // Reset to identity matrix
+ * console.log("After reset:", matrix.matrix);
+ * }
+ *
*/
reset() {
this.matrix = this.#createIdentityMatrix(this.#sqDimention);
@@ -178,18 +201,49 @@ export class Matrix extends MatrixInterface {
/**
* Replace the entire contents of a NxN matrix.
- * If providing an array or a p5.Matrix, the values will be copied without
- * referencing the source object.
- * Can also provide NxN numbers as individual arguments.
*
- * @param {p5.Matrix|Float32Array|Number[]} [inMatrix] the input p5.Matrix or
- * an Array of length 16
- * @chainable
- */
- /**
- * @param {Number[]} elements 16 numbers passed by value to avoid
- * array copying.
- * @chainable
+ * This method allows you to replace the values of the current matrix with
+ * those from another matrix, an array, or individual arguments. The input
+ * can be a `Matrix` instance, an array of numbers, or individual numbers
+ * that match the dimensions of the current matrix. The values are copied
+ * without referencing the source object, ensuring that the original input
+ * remains unchanged.
+ *
+ * If the input dimensions do not match the current matrix, an error will
+ * be thrown to ensure consistency.
+ *
+ * @param {Matrix|Float32Array|Number[]} [inMatrix] - The input matrix, array,
+ * or individual numbers to replace the current matrix values.
+ * @returns {Matrix} The current instance of the Matrix class, allowing for
+ * method chaining.
+ *
+ * @example
+ * // Replacing the contents of a matrix with another matrix
+ * const matrix1 = new p5.Matrix([1, 2, 3, 4]);
+ * const matrix2 = new p5.Matrix([5, 6, 7, 8]);
+ * matrix1.set(matrix2);
+ * console.log(matrix1.matrix); // Output: [5, 6, 7, 8]
+ *
+ * // Replacing the contents of a matrix with an array
+ * const matrix = new p5.Matrix([1, 2, 3, 4]);
+ * matrix.set([9, 10, 11, 12]);
+ * console.log(matrix.matrix); // Output: [9, 10, 11, 12]
+ *
+ * // Replacing the contents of a matrix with individual numbers
+ * const matrix = new p5.Matrix(4); // Creates a 4x4 identity matrix
+ * matrix.set(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16);
+ * console.log(matrix.matrix); // Output: [1, 2, 3, ..., 16]
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix([1, 2, 3, 4]);
+ * console.log("Before set:", matrix.matrix);
+ * matrix.set([5, 6, 7, 8]);
+ * console.log("After set:", matrix.matrix); // Output: [5, 6, 7, 8]
+ * }
+ *
*/
set(inMatrix) {
let refArray = GLMAT_ARRAY_TYPE.from([...arguments]);
@@ -200,7 +254,7 @@ export class Matrix extends MatrixInterface {
}
if (refArray.length !== this.matrix.length) {
p5._friendlyError(
- `Expected same dimentions values but received different ${refArray.length}.`,
+ `Expected same dimensions values but received different ${refArray.length}.`,
"p5.Matrix.set"
);
return this;
@@ -210,20 +264,66 @@ export class Matrix extends MatrixInterface {
}
/**
- * Gets a copy of the vector, returns a p5.Matrix object.
+ * Gets a copy of the matrix, returns a p5.Matrix object.
+ *
+ * This method creates a new instance of the `Matrix` class and copies the
+ * current matrix values into it. The returned matrix is independent of the
+ * original, meaning changes to the copy will not affect the original matrix.
+ *
+ * This is useful when you need to preserve the current state of a matrix
+ * while performing operations on a duplicate.
+ *
+ * @return {p5.Matrix} A new instance of the `Matrix` class containing the
+ * same values as the original matrix.
+ *
+ * @example
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const originalMatrix = new p5.Matrix([1, 2, 3, 4]);
+ * const copiedMatrix = originalMatrix.get();
+ * console.log("Original Matrix:", originalMatrix.matrix); // Output: [1, 2, 3, 4]
+ * console.log("Copied Matrix:", copiedMatrix.matrix); // Output: [1, 2, 3, 4]
*
- * @return {p5.Matrix} the copy of the p5.Matrix object
+ * // Modify the copied matrix
+ * copiedMatrix.setElement(2, 99);
+ * console.log("Modified Copied Matrix:", copiedMatrix.matrix); // Output: [1, 2, 99, 4]
+ * console.log("Original Matrix remains unchanged:", originalMatrix.matrix); // Output: [1, 2, 3, 4]
+ * }
+ *
*/
get() {
return new Matrix(this.matrix); // TODO: Pass p5
}
/**
- * return a copy of this matrix.
+ * Return a copy of this matrix.
* If this matrix is 4x4, a 4x4 matrix with exactly the same entries will be
- * generated. The same is true if this matrix is 3x3.
+ * generated. The same is true if this matrix is 3x3 or any NxN matrix.
*
- * @return {p5.Matrix} the result matrix
+ * This method is useful when you need to preserve the current state of a matrix
+ * while performing operations on a duplicate. The returned matrix is independent
+ * of the original, meaning changes to the copy will not affect the original matrix.
+ *
+ * @return {p5.Matrix} The result matrix.
+ *
+ * @example
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const originalMatrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const copiedMatrix = originalMatrix.copy();
+ * console.log("Original Matrix:", originalMatrix.matrix);
+ * console.log("Copied Matrix:", copiedMatrix.matrix);
+ *
+ * // Modify the copied matrix
+ * copiedMatrix.setElement(4, 99);
+ * console.log("Modified Copied Matrix:", copiedMatrix.matrix);
+ * console.log("Original Matrix remains unchanged:", originalMatrix.matrix);
+ * }
+ *
*/
copy() {
return new Matrix(this.matrix);
@@ -235,16 +335,64 @@ export class Matrix extends MatrixInterface {
* without modifying the original one.
*
* @returns {Matrix} A new matrix instance that is a copy of the current matrix.
+ *
+ * @example
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const originalMatrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const clonedMatrix = originalMatrix.clone();
+ * console.log("Original Matrix:", originalMatrix.matrix);
+ * console.log("Cloned Matrix:", clonedMatrix.matrix);
+ *
+ * // Modify the cloned matrix
+ * clonedMatrix.setElement(4, 99);
+ * console.log("Modified Cloned Matrix:", clonedMatrix.matrix);
+ * console.log("Original Matrix remains unchanged:", originalMatrix.matrix);
+ * }
+ *
*/
clone() {
return this.copy();
}
+
/**
* Returns the diagonal elements of the matrix in the form of an array.
* A NxN matrix will return an array of length N.
*
+ * This method extracts the diagonal elements of the matrix, which are the
+ * elements where the row index equals the column index. For example, in a
+ * 3x3 matrix:
+ * ```
+ * [
+ * 1, 2, 3,
+ * 4, 5, 6,
+ * 7, 8, 9
+ * ]
+ * ```
+ * The diagonal elements are [1, 5, 9].
+ *
+ * This is useful for operations that require the main diagonal of a matrix,
+ * such as calculating the trace of a matrix or verifying if a matrix is diagonal.
+ *
* @return {Number[]} An array obtained by arranging the diagonal elements
- * of the matrix in ascending order of index
+ * of the matrix in ascending order of index.
+ *
+ * @example
+ * // Extracting the diagonal elements of a matrix
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const diagonal = matrix.diagonal(); // [1, 5, 9]
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const diagonal = matrix.diagonal();
+ * console.log("Diagonal elements:", diagonal); // Output: [1, 5, 9]
+ * }
+ *
*/
diagonal() {
const diagonal = [];
@@ -255,11 +403,31 @@ export class Matrix extends MatrixInterface {
}
/**
- * This function is only for 3x3 matrices.
- * A function that returns a row vector of a NxN matrix.
+ * This function is only for 3x3 matrices A function that returns a row vector of a NxN matrix.
+ *
+ * This method extracts a specific row from the matrix and returns it as a `p5.Vector`.
+ * The row is determined by the `columnIndex` parameter, which specifies the column
+ * index of the matrix. This is useful for operations that require working with
+ * individual rows of a matrix, such as row transformations or dot products.
+ *
+ * @param {Number} columnIndex - The index of the column to extract as a row vector.
+ * Must be a non-negative integer less than the matrix dimension.
+ * @return {p5.Vector} A `p5.Vector` representing the extracted row of the matrix.
+ *
+ * @example
+ * // Extracting a row vector from a 3x3 matrix
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const rowVector = matrix.row(1); // Returns a vector [2, 5, 8]
+ *
+ * // p5.js script example
+ *
+ * function setup() {
*
- * @param {Number} columnIndex matrix column number
- * @return {p5.Vector}
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const rowVector = matrix.row(1); // Extract the second row (index 1)
+ * console.log("Row Vector:", rowVector.toString()); // Output: Row Vector: [2, 5, 8]
+ * }
+ *
*/
row(columnIndex) {
const columnVector = [];
@@ -272,8 +440,29 @@ export class Matrix extends MatrixInterface {
/**
* A function that returns a column vector of a NxN matrix.
*
- * @param {Number} rowIndex matrix row number
- * @return {p5.Vector}
+ * This method extracts a specific column from the matrix and returns it as a `p5.Vector`.
+ * The column is determined by the `rowIndex` parameter, which specifies the row index
+ * of the matrix. This is useful for operations that require working with individual
+ * columns of a matrix, such as column transformations or dot products.
+ *
+ * @param {Number} rowIndex - The index of the row to extract as a column vector.
+ * Must be a non-negative integer less than the matrix dimension.
+ * @return {p5.Vector} A `p5.Vector` representing the extracted column of the matrix.
+ *
+ * @example
+ * // Extracting a column vector from a 3x3 matrix
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const columnVector = matrix.column(1); // Returns a vector [4, 5, 6]
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const columnVector = matrix.column(1); // Extract the second column (index 1)
+ * console.log("Column Vector:", columnVector.toString()); // Output: Column Vector: [4, 5, 6]
+ * }
+ *
*/
column(rowIndex) {
const rowVector = [];
@@ -283,9 +472,6 @@ export class Matrix extends MatrixInterface {
return new Vector(...rowVector);
}
-
-
-
/**
* Transposes the given matrix `a` based on the square dimension of the matrix.
*
@@ -293,14 +479,36 @@ export class Matrix extends MatrixInterface {
* and the columns become rows. It handles matrices of different dimensions (4x4, 3x3, NxN)
* by delegating to specific transpose methods for each case.
*
- * @param {Array} a - The matrix to be transposed. It should be a 2D array where each sub-array represents a row.
- * @returns {Array} - The transposed matrix.
+ * If no argument is provided, the method transposes the current matrix instance.
+ * If an argument is provided, it transposes the given matrix `a` and updates the current matrix.
+ *
+ * @param {Array} [a] - The matrix to be transposed. It should be a 2D array where each sub-array represents a row.
+ * If omitted, the current matrix instance is transposed.
+ * @returns {Matrix} - The current instance of the Matrix class, allowing for method chaining.
+ *
+ * @example
+ * // Transposing a 3x3 matrix
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * matrix.transpose();
+ * console.log(matrix.matrix); // Output: [1, 4, 7, 2, 5, 8, 3, 6, 9]
+ *
+ * // Transposing a 4x4 matrix
+ * const matrix4x4 = new p5.Matrix(4);
+ * matrix4x4.transpose();
+ * console.log(matrix4x4.matrix); // Output: Transposed 4x4 identity matrix
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * console.log("Before transpose:", matrix.matrix);
+ * matrix.transpose();
+ * console.log("After transpose:", matrix.matrix); // Output: [1, 4, 7, 2, 5, 8, 3, 6, 9]
+ * }
+ *
*/
transpose(a) {
- // TODO: Cristian: What does passing an argument to a transpose mean?
- // In the codebase this is never done in any reference
- // Actually transposse of a 4x4 is never done dierectly,
- // I'm thinking it is incorrect, transpose3x3 is only used for inverseTranspose4x4
if (this.#sqDimention === 4) {
return this.#transpose4x4(a);
} else if (this.#sqDimention === 3) {
@@ -310,7 +518,6 @@ export class Matrix extends MatrixInterface {
}
}
-
/**
* Multiplies the current matrix with another matrix or matrix-like array.
*
@@ -321,9 +528,37 @@ export class Matrix extends MatrixInterface {
*
* If the input is the same as the current matrix, a copy is made to avoid modifying the original matrix.
*
+ * The method determines the appropriate multiplication strategy based on the dimensions of the current matrix
+ * and the input matrix. It supports 3x3, 4x4, and NxN matrices.
+ *
* @param {Matrix|Array|...number} multMatrix - The matrix or matrix-like array to multiply with.
* @returns {Matrix|undefined} The resulting matrix after multiplication, or undefined if the input is invalid.
* @chainable
+ *
+ * @example
+ * // Multiplying two 3x3 matrices
+ * const matrix1 = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const matrix2 = new p5.Matrix([9, 8, 7, 6, 5, 4, 3, 2, 1]);
+ * matrix1.mult(matrix2);
+ * console.log(matrix1.matrix); // Output: [30, 24, 18, 84, 69, 54, 138, 114, 90]
+ *
+ * // Multiplying a 4x4 matrix with another 4x4 matrix
+ * const matrix4x4_1 = new p5.Matrix(4); // Identity matrix
+ * const matrix4x4_2 = new p5.Matrix([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 2, 3, 1]);
+ * matrix4x4_1.mult(matrix4x4_2);
+ * console.log(matrix4x4_1.matrix); // Output: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 2, 3, 1]
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix1 = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const matrix2 = new p5.Matrix([9, 8, 7, 6, 5, 4, 3, 2, 1]);
+ * console.log("Before multiplication:", matrix1.matrix);
+ * matrix1.mult(matrix2);
+ * console.log("After multiplication:", matrix1.matrix); // Output: [30, 24, 18, 84, 69, 54, 138, 114, 90]
+ * }
+ *
*/
mult(multMatrix) {
let _src;
@@ -348,13 +583,35 @@ export class Matrix extends MatrixInterface {
}
/**
- * This function is only for 3x3 matrices.
- * Takes a vector and returns the vector resulting from multiplying to
- * that vector by this matrix from left.
+ * Takes a vector and returns the vector resulting from multiplying to that vector by this matrix from left. This function is only for 3x3 matrices.
+ *
+ * This method applies the current 3x3 matrix to a given vector, effectively
+ * transforming the vector using the matrix. The resulting vector is returned
+ * as a new vector or stored in the provided target vector.
+ *
+ * @param {p5.Vector} multVector - The vector to which this matrix applies.
+ * @param {p5.Vector} [target] - The vector to receive the result. If not provided,
+ * a copy of the input vector will be created and returned.
+ * @return {p5.Vector} - The transformed vector after applying the matrix.
*
- * @param {p5.Vector} multVector the vector to which this matrix applies
- * @param {p5.Vector} [target] The vector to receive the result
- * @return {p5.Vector}
+ * @example
+ * // Multiplying a 3x3 matrix with a vector
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const vector = new p5.Vector(1, 2, 3);
+ * const result = matrix.multiplyVec(vector);
+ * console.log(result.toString()); // Output: Transformed vector
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const vector = new p5.Vector(1, 2, 3);
+ * const result = matrix.multiplyVec(vector);
+ * console.log("Original Vector:", vector.toString()); // Output : Original Vector: [1, 2, 3]
+ * console.log("Transformed Vector:", result.toString()); // Output : Transformed Vector: [30, 36, 42]
+ * }
+ *
*/
multiplyVec(multVector, target) {
if (target === undefined) {
@@ -372,9 +629,41 @@ export class Matrix extends MatrixInterface {
* This method inverts a matrix based on its dimensions. Currently, it supports
* 3x3 and 4x4 matrices. If the matrix dimension is greater than 4, an error is thrown.
*
+ * For 4x4 matrices, it uses a specialized algorithm to compute the inverse.
+ * For 3x3 matrices, it uses a different algorithm optimized for smaller matrices.
+ *
+ * If the matrix is singular (non-invertible), the method will return `null`.
+ *
* @param {Array} a - The matrix to be inverted. It should be a 2D array representing the matrix.
- * @returns {Array} - The inverted matrix.
+ * @returns {Array|null} - The inverted matrix, or `null` if the matrix is singular.
* @throws {Error} - Throws an error if the matrix dimension is greater than 4.
+ *
+ * @example
+ * // Inverting a 3x3 matrix
+ * const matrix = new p5.Matrix([1, 2, 3, 0, 1, 4, 5, 6, 0]);
+ * const invertedMatrix = matrix.invert();
+ * console.log(invertedMatrix.matrix); // Output: Inverted 3x3 matrix
+ *
+ * // Inverting a 4x4 matrix
+ * const matrix4x4 = new p5.Matrix(4); // Identity matrix
+ * matrix4x4.scale(2, 2, 2);
+ * const invertedMatrix4x4 = matrix4x4.invert();
+ * console.log(invertedMatrix4x4.matrix); // Output: Inverted 4x4 matrix
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix([1, 2, 3, 0, 1, 4, 5, 6, 0]);
+ * console.log("Original Matrix:", matrix.matrix);
+ * const invertedMatrix = matrix.invert();
+ * if (invertedMatrix) {
+ * console.log("Inverted Matrix:", invertedMatrix.matrix);
+ * } else {
+ * console.log("Matrix is singular and cannot be inverted.");
+ * }
+ * }
+ *
*/
invert(a) {
if (this.#sqDimention === 4) {
@@ -389,10 +678,39 @@ export class Matrix extends MatrixInterface {
}
/**
- * This function is only for 4x4 matrices.
- * Creates a 3x3 matrix whose entries are the top left 3x3 part and returns it.
+ * Creates a 3x3 matrix whose entries are the top left 3x3 part and returns it. This function is only for 4x4 matrices.
+ *
+ * This method extracts the top-left 3x3 portion of a 4x4 matrix and creates a new
+ * 3x3 matrix from it. This is particularly useful in 3D graphics for operations
+ * that require only the rotational or scaling components of a transformation matrix.
+ *
+ * If the current matrix is not 4x4, an error is thrown to ensure the method is used
+ * correctly. The resulting 3x3 matrix is independent of the original matrix, meaning
+ * changes to the new matrix will not affect the original.
+ *
+ * @return {p5.Matrix} A new 3x3 matrix containing the top-left portion of the original 4x4 matrix.
+ * @throws {Error} If the current matrix is not 4x4.
+ *
+ * @example
+ * // Extracting a 3x3 submatrix from a 4x4 matrix
+ * const matrix4x4 = new p5.Matrix(4); // Creates a 4x4 identity matrix
+ * matrix4x4.scale(2, 2, 2); // Apply scaling transformation
+ * const subMatrix3x3 = matrix4x4.createSubMatrix3x3();
+ * console.log("Original 4x4 Matrix:", matrix4x4.matrix);
+ * console.log("Extracted 3x3 Submatrix:", subMatrix3x3.matrix);
+ *
+ * // p5.js script example
+ *
+ * function setup() {
*
- * @return {p5.Matrix}
+ * const matrix4x4 = new p5.Matrix(4); // Creates a 4x4 identity matrix
+ * matrix4x4.scale(2, 2, 2); // Apply scaling transformation
+ * console.log("Original 4x4 Matrix:", matrix4x4.matrix);
+ *
+ * const subMatrix3x3 = matrix4x4.createSubMatrix3x3();
+ * console.log("Extracted 3x3 Submatrix:", subMatrix3x3.matrix);
+ * }
+ *
*/
createSubMatrix3x3() {
if (this.#sqDimention === 4) {
@@ -413,17 +731,45 @@ export class Matrix extends MatrixInterface {
}
/**
- * Converts a 4×4 matrix to its 3×3 inverse transform
- * commonly used in MVMatrix to NMatrix conversions.
- * @param {p5.Matrix} mat4 the matrix to be based on to invert
- * @chainable
- * @todo finish implementation
+ * Converts a 4×4 matrix to its 3×3 inverse transpose transform.
+ * This is commonly used in MVMatrix to NMatrix conversions, particularly
+ * in 3D graphics for transforming normal vectors.
+ *
+ * This method extracts the top-left 3×3 portion of a 4×4 matrix, inverts it,
+ * and then transposes the result. If the matrix is singular (non-invertible),
+ * the resulting matrix will be zeroed out.
+ *
+ * @param {p5.Matrix} mat4 - The 4×4 matrix to be converted.
+ * @returns {Matrix} The current instance of the Matrix class, allowing for method chaining.
+ * @throws {Error} If the current matrix is not 3×3.
+ *
+ * @example
+ * // Converting a 4×4 matrix to its 3×3 inverse transpose
+ * const mat4 = new p5.Matrix(4); // Create a 4×4 identity matrix
+ * mat4.scale(2, 2, 2); // Apply scaling transformation
+ * const mat3 = new p5.Matrix(3); // Create a 3×3 matrix
+ * mat3.inverseTranspose4x4(mat4);
+ * console.log("Converted 3×3 Matrix:", mat3.matrix);
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const mat4 = new p5.Matrix(4); // Create a 4×4 identity matrix
+ * mat4.scale(2, 2, 2); // Apply scaling transformation
+ * console.log("Original 4×4 Matrix:", mat4.matrix);
+ *
+ * const mat3 = new p5.Matrix(3); // Create a 3×3 matrix
+ * mat3.inverseTranspose4x4(mat4);
+ * console.log("Converted 3×3 Matrix:", mat3.matrix);
+ * }
+ *
*/
inverseTranspose4x4({ mat4 }) {
if (this.#sqDimention !== 3) {
- p5._friendlyError("sorry, this function only works with mat3");
+ throw new Error("This function only works with 3×3 matrices.");
} else {
- //convert mat4 -> mat3
+ // Convert mat4 -> mat3 by extracting the top-left 3×3 portion
this.matrix[0] = mat4[0];
this.matrix[1] = mat4[1];
this.matrix[2] = mat4[2];
@@ -436,11 +782,11 @@ export class Matrix extends MatrixInterface {
}
const inverse = this.invert();
- // check inverse succeeded
+ // Check if inversion succeeded
if (inverse) {
inverse.transpose(this.matrix);
} else {
- // in case of singularity, just zero the matrix
+ // In case of singularity, zero out the matrix
for (let i = 0; i < 9; i++) {
this.matrix[i] = 0;
}
@@ -455,6 +801,10 @@ export class Matrix extends MatrixInterface {
* in several forms: another Matrix instance, an array representing a matrix, or as
* individual arguments representing the elements of a 4x4 matrix.
*
+ * This operation is useful for combining transformations such as translation, rotation,
+ * scaling, and perspective projection into a single matrix. By applying a transformation
+ * matrix, you can modify the current matrix to represent a new transformation.
+ *
* @param {Matrix|Array|number} multMatrix - The matrix to multiply with. This can be:
* - An instance of the Matrix class.
* - An array of 16 numbers representing a 4x4 matrix.
@@ -462,18 +812,39 @@ export class Matrix extends MatrixInterface {
* @returns {Matrix} The current matrix after applying the transformation.
*
* @example
+ *
+ * function setup() {
+ *
* // Assuming `matrix` is an instance of Matrix
- * const anotherMatrix = new Matrix();
+ * const anotherMatrix = new p5.Matrix(4);
+ * const anotherMatrix = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
* matrix.apply(anotherMatrix);
*
- * @example
* // Applying a transformation using an array
* const matrixArray = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
* matrix.apply(matrixArray);
*
- * @example
* // Applying a transformation using individual arguments
* matrix.apply(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1);
+ *
+ *
+ * // Create a 4x4 identity matrix
+ * const matrix = new p5.Matrix(4);
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Create a scaling transformation matrix
+ * const scalingMatrix = new p5.Matrix([2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 1]);
+ *
+ * // Apply the scaling transformation
+ * matrix.apply(scalingMatrix);
+ * console.log("After Scaling Transformation:", matrix.matrix);
+ *
+ * // Apply a translation transformation using an array
+ * const translationMatrix = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 5, 5, 1];
+ * matrix.apply(translationMatrix);
+ * console.log("After Translation Transformation:", matrix.matrix);
+ * }
+ *
*/
apply(multMatrix) {
let _src;
@@ -533,9 +904,58 @@ export class Matrix extends MatrixInterface {
}
/**
- * scales a p5.Matrix by scalars or a vector
- * @param {p5.Vector|Float32Array|Number[]} s vector to scale by
- * @chainable
+ * Scales a p5.Matrix by scalars or a vector.
+ *
+ * This method applies a scaling transformation to the current matrix.
+ * Scaling is a transformation that enlarges or shrinks objects by a scale factor
+ * along the x, y, and z axes. The scale factors can be provided as individual
+ * numbers, an array, or a `p5.Vector`.
+ *
+ * If a `p5.Vector` or an array is provided, the x, y, and z components are extracted
+ * from it. If the z component is not provided, it defaults to 1 (no scaling along the z-axis).
+ *
+ * @param {p5.Vector|Float32Array|Number[]} s - The vector or scalars to scale by.
+ * Can be a `p5.Vector`, an array, or individual numbers.
+ * @returns {Matrix} The current instance of the Matrix class, allowing for method chaining.
+ *
+ * @example
+ * // Scaling a matrix by individual scalars
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * matrix.scale(2, 3, 4); // Scale by 2 along x, 3 along y, and 4 along z
+ * console.log(matrix.matrix);
+ *
+ * // Scaling a matrix by a p5.Vector
+ * const scaleVector = new p5.Vector(2, 3, 4);
+ * matrix.scale(scaleVector);
+ * console.log(matrix.matrix);
+ *
+ * // Scaling a matrix by an array
+ * const scaleArray = [2, 3, 4];
+ * matrix.scale(scaleArray);
+ * console.log(matrix.matrix);
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Scale the matrix by individual scalars
+ * matrix.scale(2, 3, 4);
+ * console.log("Scaled Matrix (2, 3, 4):", matrix.matrix);
+ *
+ * // Scale the matrix by a p5.Vector
+ * const scaleVector = new p5.Vector(1.5, 2.5, 3.5);
+ * matrix.scale(scaleVector);
+ * console.log("Scaled Matrix (Vector):", matrix.matrix);
+ *
+ * // Scale the matrix by an array
+ * const scaleArray = [0.5, 0.5, 0.5];
+ * matrix.scale(scaleArray);
+ * console.log("Scaled Matrix (Array):", matrix.matrix);
+ * }
+ *
*/
scale(x, y, z) {
if (x instanceof Vector) {
@@ -567,11 +987,44 @@ export class Matrix extends MatrixInterface {
}
/**
- * rotate our Matrix around an axis by the given angle.
- * @param {Number} a The angle of rotation in radians
- * @param {p5.Vector|Number[]} axis the axis(es) to rotate around
+ * Rotate the Matrix around a specified axis by a given angle.
+ *
+ * This method applies a rotation transformation to the matrix, modifying its orientation
+ * in 3D space. The rotation is performed around the provided axis, which can be defined
+ * as a `p5.Vector` or an array of numbers representing the x, y, and z components of the axis.
+ * Rotate our Matrix around an axis by the given angle.
+ * @param {Number} a The angle of rotation in radians.
+ * Angles in radians are a measure of rotation, where 2π radians
+ * represent a full circle (360 degrees). For example:
+ * - π/2 radians = 90 degrees (quarter turn)
+ * - π radians = 180 degrees (half turn)
+ * - 2π radians = 360 degrees (full turn)
+ * Use `Math.PI` for π or `p5`'s `PI` constant if using p5.js.
+ * @param {p5.Vector|Number[]} axis The axis or axes to rotate around.
+ * This defines the direction of the rotation.
+ * - If using a `p5.Vector`, it should represent
+ * the x, y, and z components of the axis.
+ * - If using an array, it should be in the form
+ * [x, y, z], where x, y, and z are numbers.
+ * For example:
+ * - [1, 0, 0] rotates around the x-axis.
+ * - [0, 1, 0] rotates around the y-axis.
+ * - [0, 0, 1] rotates around the z-axis. *
* @chainable
* inspired by Toji's gl-matrix lib, mat4 rotation
+ *
+ * @example
+ * // p5.js script example
+ *
+ * function setup() {
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix.slice().toString()); // [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]
+ *
+ * // Translate the matrix by a 3D vector
+ * matrix.rotate4x4(Math.PI, [1,0,0]);
+ * console.log("After rotation of PI degrees on vector [1,0,0]:", matrix.matrix.slice().toString()); // [1,0,0,0,0,-1,1.2246468525851679e-16,0,0,-1.2246468525851679e-16,-1,0,0,0,0,1]
+ * }
+ *
*/
rotate4x4(a, x, y, z) {
if (x instanceof Vector) {
@@ -637,10 +1090,42 @@ export class Matrix extends MatrixInterface {
}
/**
- * @todo finish implementing this method!
- * translates
- * @param {Number[]} v vector to translate by
- * @chainable
+ * Translates the current matrix by a given vector.
+ *
+ * This method applies a translation transformation to the current matrix.
+ * Translation moves the matrix by a specified amount along the x, y, and z axes.
+ * The input vector can be a 2D or 3D vector. If the z-component is not provided,
+ * it defaults to 0, meaning no translation along the z-axis.
+ *
+ * @param {Number[]} v - A vector representing the translation. It should be an array
+ * with two or three elements: [x, y, z]. The z-component is optional.
+ * @returns {Matrix} The current instance of the Matrix class, allowing for method chaining.
+ *
+ * @example
+ * // Translating a matrix by a 3D vector
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * matrix.translate([10, 20, 30]); // Translate by 10 units along x, 20 along y, and 30 along z
+ * console.log(matrix.matrix);
+ *
+ * // Translating a matrix by a 2D vector
+ * matrix.translate([5, 15]); // Translate by 5 units along x and 15 along y
+ * console.log(matrix.matrix);
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix.slice().toString()); // [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]
+ *
+ * // Translate the matrix by a 3D vector
+ * matrix.translate([10, 20, 30]);
+ * console.log("After 3D Translation (10, 20, 30):", matrix.matrix.slice().toString()); // [1,0,0,0,0,1,0,0,0,0,1,0,10,20,30,1]
+ *
+ * // Translate the matrix by a 2D vector
+ * matrix.translate([5, 15]);
+ * console.log("After 2D Translation (5, 15):", matrix.matrix.slice().toString()); // [1,0,0,0,0,1,0,0,0,0,1,0,15,35,30,1]
+ * }
+ *
*/
translate(v) {
const x = v[0],
@@ -654,6 +1139,7 @@ export class Matrix extends MatrixInterface {
this.matrix[2] * x + this.matrix[6] * y + this.matrix[10] * z;
this.matrix[15] +=
this.matrix[3] * x + this.matrix[7] * y + this.matrix[11] * z;
+ return this;
}
/**
@@ -662,7 +1148,30 @@ export class Matrix extends MatrixInterface {
* This method modifies the current matrix to apply a rotation transformation
* around the X-axis. The rotation angle is specified in radians.
*
+ * Rotating around the X-axis means that the Y and Z coordinates of the matrix
+ * are transformed while the X coordinates remain unchanged. This is commonly
+ * used in 3D graphics to create animations or transformations along the X-axis.
+ *
* @param {Number} a - The angle in radians to rotate the matrix by.
+ *
+ * @example
+ * // Rotating a matrix around the X-axis
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * matrix.rotateX(Math.PI / 4); // Rotate 45 degrees around the X-axis
+ * console.log(matrix.matrix);
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Rotate the matrix 45 degrees (PI/4 radians) around the X-axis
+ * matrix.rotateX(Math.PI / 4);
+ * console.log("After Rotation (X-axis, 45 degrees):", matrix.matrix);
+ * }
+ *
*/
rotateX(a) {
this.rotate4x4(a, 1, 0, 0);
@@ -673,11 +1182,33 @@ export class Matrix extends MatrixInterface {
*
* This method modifies the current matrix to apply a rotation transformation
* around the Y-axis. The rotation is performed in 3D space, and the angle
- * is specified in radians.
+ * is specified in radians. Rotating around the Y-axis means that the X and Z
+ * coordinates of the matrix are transformed while the Y coordinates remain
+ * unchanged. This is commonly used in 3D graphics to create animations or
+ * transformations along the Y-axis.
*
* @param {Number} a - The angle in radians to rotate the matrix by. Positive
* values rotate the matrix counterclockwise, and negative values rotate it
* clockwise.
+ *
+ * @example
+ * // Rotating a matrix around the Y-axis
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * matrix.rotateY(Math.PI / 4); // Rotate 45 degrees around the Y-axis
+ * console.log(matrix.matrix);
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Rotate the matrix 45 degrees (PI/4 radians) around the Y-axis
+ * matrix.rotateY(Math.PI / 4);
+ * console.log("After Rotation (Y-axis, 45 degrees):", matrix.matrix);
+ * }
+ *
*/
rotateY(a) {
this.rotate4x4(a, 0, 1, 0);
@@ -686,29 +1217,79 @@ export class Matrix extends MatrixInterface {
/**
* Rotates the matrix around the Z-axis by a given angle.
*
- * @param {Number} a - The angle in radians to rotate the matrix by.
- *
* This method modifies the current matrix to apply a rotation transformation
* around the Z-axis. The rotation is performed in a 4x4 matrix context, which
- * is commonly used in 3D graphics to handle transformations.
+ * is commonly used in 3D graphics to handle transformations. Rotating around
+ * the Z-axis means that the X and Y coordinates of the matrix are transformed
+ * while the Z coordinates remain unchanged.
*
- * Example usage:
- * ```
- * const matrix = new Matrix();
- * matrix.rotateZ(Math.PI / 4); // Rotates the matrix 45 degrees around the Z-axis
- * ```
+ * @param {Number} a - The angle in radians to rotate the matrix by. Positive
+ * values rotate the matrix counterclockwise, and negative values rotate it
+ * clockwise.
+ *
+ * @returns {Matrix} The current instance of the Matrix class, allowing for
+ * method chaining.
+ *
+ * @example
+ * // Rotating a matrix around the Z-axis
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * matrix.rotateZ(Math.PI / 4); // Rotate 45 degrees around the Z-axis
+ * console.log(matrix.matrix);
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Rotate the matrix 45 degrees (PI/4 radians) around the Z-axis
+ * matrix.rotateZ(Math.PI / 4);
+ * console.log("After Rotation (Z-axis, 45 degrees):", matrix.matrix);
+ * }
+ *
*/
rotateZ(a) {
this.rotate4x4(a, 0, 0, 1);
}
/**
- * sets the perspective matrix
- * @param {Number} fovy [description]
- * @param {Number} aspect [description]
- * @param {Number} near near clipping plane
- * @param {Number} far far clipping plane
- * @chainable
+ * Sets the perspective projection matrix.
+ *
+ * This method modifies the current matrix to represent a perspective projection.
+ * Perspective projection is commonly used in 3D graphics to simulate the effect
+ * of objects appearing smaller as they move further away from the camera.
+ *
+ * The perspective matrix is defined by the field of view (fovy), aspect ratio,
+ * and the near and far clipping planes. The near and far clipping planes define
+ * the range of depth that will be rendered, with anything outside this range
+ * being clipped.
+ *
+ * @param {Number} fovy - The field of view in the y direction, in radians.
+ * @param {Number} aspect - The aspect ratio of the viewport (width / height).
+ * @param {Number} near - The distance to the near clipping plane. Must be greater than 0.
+ * @param {Number} far - The distance to the far clipping plane. Must be greater than the near value.
+ * @returns {Matrix} The current instance of the Matrix class, allowing for method chaining.
+ *
+ * @example
+ * // Setting a perspective projection matrix
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * matrix.perspective(Math.PI / 4, 1.5, 0.1, 100); // Set perspective projection
+ * console.log(matrix.matrix);
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Set a perspective projection with a 45-degree field of view,
+ * // an aspect ratio of 1.5, and near/far clipping planes at 0.1 and 100.
+ * matrix.perspective(Math.PI / 4, 1.5, 0.1, 100);
+ * console.log("Perspective Matrix:", matrix.matrix);
+ * }
+ *
*/
perspective(fovy, aspect, near, far) {
const f = 1.0 / Math.tan(fovy / 2),
@@ -735,14 +1316,40 @@ export class Matrix extends MatrixInterface {
}
/**
- * sets the ortho matrix
- * @param {Number} left [description]
- * @param {Number} right [description]
- * @param {Number} bottom [description]
- * @param {Number} top [description]
- * @param {Number} near near clipping plane
- * @param {Number} far far clipping plane
+ * Sets this matrix to an orthographic projection matrix.
+ *
+ * An orthographic projection matrix is used to create a 2D rendering
+ * of a 3D scene by projecting points onto a plane without perspective
+ * distortion. This method modifies the current matrix to represent
+ * the orthographic projection defined by the given parameters.
+ *
+ * @param {number} left - The coordinate for the left vertical clipping plane.
+ * @param {number} right - The coordinate for the right vertical clipping plane.
+ * @param {number} bottom - The coordinate for the bottom horizontal clipping plane.
+ * @param {number} top - The coordinate for the top horizontal clipping plane.
+ * @param {number} near - The distance to the near depth clipping plane. Must be positive.
+ * @param {number} far - The distance to the far depth clipping plane. Must be positive.
* @chainable
+ * @returns {Matrix} The current matrix instance, updated with the orthographic projection.
+ *
+ * @example
+ *
+ * // Example using p5.js to demonstrate orthographic projection
+ * function setup() {
+ * let orthoMatrix = new p5.Matrix(4);
+ * console.log(orthoMatrix.matrix.toString()) // Output: 1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1
+ * orthoMatrix.ortho(-200, 200, -200, 200, 0.1, 1000);
+ * console.log(orthoMatrix.matrix.toString()) // Output: [24 0.004999999888241291,0,0,0,0,0.004999999888241291,0,0,0,0,-0.0020002000965178013,0,0,0,-1.0002000331878662,1]
+ * applyMatrix(
+ * orthoMatrix.mat4[0], orthoMatrix.mat4[1], orthoMatrix.mat4[2], orthoMatrix.mat4[3],
+ * orthoMatrix.mat4[4], orthoMatrix.mat4[5], orthoMatrix.mat4[6], orthoMatrix.mat4[7],
+ * orthoMatrix.mat4[8], orthoMatrix.mat4[9], orthoMatrix.mat4[10], orthoMatrix.mat4[11],
+ * orthoMatrix.mat4[12], orthoMatrix.mat4[13], orthoMatrix.mat4[14], orthoMatrix.mat4[15]
+ * );
+ * console.log(orthoMatrix.matrix.toString()) // Output: [31 0.004999999888241291,0,0,0,0,0.004999999888241291,0,0,0,0,-0.0020002000965178013,0,0,0,-1.0002000331878662,1]
+ * }
+ *
+ *
*/
ortho(left, right, bottom, top, near, far) {
const lr = 1 / (left - right),
@@ -769,10 +1376,45 @@ export class Matrix extends MatrixInterface {
}
/**
- * apply a matrix to a vector with x,y,z,w components
- * get the results in the form of an array
- * @param {Number}
- * @return {Number[]}
+ * Applies a matrix to a vector with x, y, z, w components and returns the result as an array.
+ *
+ * This method multiplies the current matrix by a 4D vector (x, y, z, w) and computes the resulting vector.
+ * It is commonly used in 3D graphics for transformations such as translation, rotation, scaling, and perspective projection.
+ *
+ * The resulting vector is returned as an array of four numbers, representing the transformed x, y, z, and w components.
+ *
+ * @param {Number} x - The x component of the vector.
+ * @param {Number} y - The y component of the vector.
+ * @param {Number} z - The z component of the vector.
+ * @param {Number} w - The w component of the vector.
+ * @returns {Number[]} An array containing the transformed [x, y, z, w] components.
+ *
+ * @example
+ * // Applying a matrix to a 4D vector
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * const result = matrix.multiplyVec4(1, 2, 3, 1); // Transform the vector [1, 2, 3, 1]
+ * console.log(result); // Output: [1, 2, 3, 1] (unchanged for identity matrix)
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Apply the matrix to a 4D vector
+ * const result = matrix.multiplyVec4(1, 2, 3, 1);
+ * console.log("Transformed Vector:", result); // Output: [1, 2, 3, 1]
+ *
+ * // Modify the matrix (e.g., apply a translation)
+ * matrix.translate([5, 5, 5]);
+ * console.log("Modified Matrix:", matrix.matrix);
+ *
+ * // Apply the modified matrix to the same vector
+ * const transformedResult = matrix.multiplyVec4(1, 2, 3, 1);
+ * console.log("Transformed Vector after Translation:", transformedResult); // Output: [6, 7, 8, 1]
+ * }
+ *
*/
multiplyVec4(x, y, z, w) {
const result = new Array(4);
@@ -787,13 +1429,52 @@ export class Matrix extends MatrixInterface {
}
/**
- * Applies a matrix to a vector.
- * The fourth component is set to 1.
+ * Applies a matrix to a vector. The fourth component is set to 1.
* Returns a vector consisting of the first
* through third components of the result.
*
- * @param {p5.Vector}
- * @return {p5.Vector}
+ * This method multiplies the current matrix by a 4D vector (x, y, z, 1),
+ * effectively transforming the vector using the matrix. The resulting
+ * vector is returned as a new `p5.Vector` instance.
+ *
+ * This is useful for applying transformations such as translation,
+ * rotation, scaling, or perspective projection to a point in 3D space.
+ *
+ * @param {p5.Vector} vector - The input vector to transform. It should
+ * have x, y, and z components.
+ * @return {p5.Vector} A new `p5.Vector` instance representing the transformed point.
+ *
+ * @example
+ * // Applying a matrix to a 3D point
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * const point = new p5.Vector(1, 2, 3); // Define a 3D point
+ * const transformedPoint = matrix.multiplyPoint(point);
+ * console.log(transformedPoint.toString()); // Output: [1, 2, 3] (unchanged for identity matrix)
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Define a 3D point
+ * const point = new p5.Vector(1, 2, 3);
+ * console.log("Original Point:", point.toString());
+ *
+ * // Apply the matrix to the point
+ * const transformedPoint = matrix.multiplyPoint(point);
+ * console.log("Transformed Point:", transformedPoint.toString());
+ *
+ * // Modify the matrix (e.g., apply a translation)
+ * matrix.translate([5, 5, 5]);
+ * console.log("Modified Matrix:", matrix.matrix);
+ *
+ * // Apply the modified matrix to the same point
+ * const translatedPoint = matrix.multiplyPoint(point);
+ * console.log("Translated Point:", translatedPoint.toString()); // Output: [6, 7, 8]
+ * }
+ *
*/
multiplyPoint({ x, y, z }) {
const array = this.multiplyVec4(x, y, z, 1);
@@ -806,8 +1487,47 @@ export class Matrix extends MatrixInterface {
* Returns the result of dividing the 1st to 3rd components
* of the result by the 4th component as a vector.
*
- * @param {p5.Vector}
- * @return {p5.Vector}
+ * This method multiplies the current matrix by a 4D vector (x, y, z, 1),
+ * effectively transforming the vector using the matrix. The resulting
+ * vector is normalized by dividing its x, y, and z components by the w component.
+ * This is useful for applying transformations such as perspective projection
+ * to a point in 3D space.
+ *
+ * @param {p5.Vector} vector - The input vector to transform. It should
+ * have x, y, and z components.
+ * @return {p5.Vector} A new `p5.Vector` instance representing the transformed and normalized point.
+ *
+ * @example
+ * // Applying a matrix to a 3D point and normalizing it
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * const point = new p5.Vector(1, 2, 3); // Define a 3D point
+ * const transformedPoint = matrix.multiplyAndNormalizePoint(point);
+ * console.log(transformedPoint.toString()); // Output: [1, 2, 3] (unchanged for identity matrix)
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Define a 3D point
+ * const point = new p5.Vector(1, 2, 3);
+ * console.log("Original Point:", point.toString());
+ *
+ * // Apply the matrix to the point and normalize it
+ * const transformedPoint = matrix.multiplyAndNormalizePoint(point);
+ * console.log("Transformed and Normalized Point:", transformedPoint.toString());
+ *
+ * // Modify the matrix (e.g., apply a perspective transformation)
+ * matrix.perspective(Math.PI / 4, 1.5, 0.1, 100);
+ * console.log("Modified Matrix (Perspective):", matrix.matrix);
+ *
+ * // Apply the modified matrix to the same point
+ * const perspectivePoint = matrix.multiplyAndNormalizePoint(point);
+ * console.log("Point after Perspective Transformation:", perspectivePoint.toString());
+ * }
+ *
*/
multiplyAndNormalizePoint({ x, y, z }) {
const array = this.multiplyVec4(x, y, z, 1);
@@ -823,8 +1543,46 @@ export class Matrix extends MatrixInterface {
* Returns a vector consisting of the first
* through third components of the result.
*
- * @param {p5.Vector}
- * @return {p5.Vector}
+ * This method multiplies the current matrix by a 4D vector (x, y, z, 0),
+ * effectively transforming the direction vector using the matrix. The resulting
+ * vector is returned as a new `p5.Vector` instance. This is particularly useful
+ * for transforming direction vectors (e.g., normals) without applying translation.
+ *
+ * @param {p5.Vector} vector - The input vector to transform. It should
+ * have x, y, and z components.
+ * @return {p5.Vector} A new `p5.Vector` instance representing the transformed direction.
+ *
+ * @example
+ * // Applying a matrix to a direction vector
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * const direction = new p5.Vector(1, 0, 0); // Define a direction vector
+ * const transformedDirection = matrix.multiplyDirection(direction);
+ * console.log(transformedDirection.toString()); // Output: [1, 0, 0] (unchanged for identity matrix)
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * const matrix = new p5.Matrix(4); // Create a 4x4 identity matrix
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Define a direction vector
+ * const direction = new p5.Vector(1, 0, 0);
+ * console.log("Original Direction:", direction.toString());
+ *
+ * // Apply the matrix to the direction vector
+ * const transformedDirection = matrix.multiplyDirection(direction);
+ * console.log("Transformed Direction:", transformedDirection.toString());
+ *
+ * // Modify the matrix (e.g., apply a rotation)
+ * matrix.rotateY(Math.PI / 4); // Rotate 45 degrees around the Y-axis
+ * console.log("Modified Matrix (Rotation):", matrix.matrix);
+ *
+ * // Apply the modified matrix to the same direction vector
+ * const rotatedDirection = matrix.multiplyDirection(direction);
+ * console.log("Rotated Direction:", rotatedDirection.toString()); // Output: Rotated vector
+ * }
+ *
*/
multiplyDirection({ x, y, z }) {
const array = this.multiplyVec4(x, y, z, 0);
@@ -832,22 +1590,53 @@ export class Matrix extends MatrixInterface {
}
/**
- * This function is only for 3x3 matrices.
- * Takes a vector and returns the vector resulting from multiplying to
- * that vector by this matrix from left.
+ * Takes a vector and returns the vector resulting from multiplying. This function is only for 3x3 matrices.
+ * that vector by this matrix from the left.
*
- * @param {p5.Vector} multVector the vector to which this matrix applies
- * @param {p5.Vector} [target] The vector to receive the result
- * @return {p5.Vector}
- */
- /**
- * This function is only for 3x3 matrices.
- * Takes a vector and returns the vector resulting from multiplying to
- * that vector by this matrix from left.
+ * This method applies the current 3x3 matrix to a given vector, effectively
+ * transforming the vector using the matrix. The resulting vector is returned
+ * as a new vector or stored in the provided target vector.
+ *
+ * This is useful for operations such as transforming points or directions
+ * in 2D or 3D space using a 3x3 transformation matrix.
+ *
+ * @param {p5.Vector} multVector - The vector to which this matrix applies.
+ * @param {p5.Vector} [target] - The vector to receive the result. If not provided,
+ * a copy of the input vector will be created and returned.
+ * @return {p5.Vector} - The transformed vector after applying the matrix.
+ *
+ * @example
+ * // Multiplying a 3x3 matrix with a vector
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const vector = new p5.Vector(1, 2, 3);
+ * const result = matrix.multiplyVec3(vector);
+ * console.log(result.toString()); // Output: Transformed vector
+ *
+ * // p5.js script example
+ *
+ * function setup() {
*
- * @param {p5.Vector} multVector the vector to which this matrix applies
- * @param {p5.Vector} [target] The vector to receive the result
- * @return {p5.Vector}
+ * // Create a 3x3 matrix
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * console.log("Original Matrix:", matrix.matrix);
+ *
+ * // Define a vector
+ * const vector = new p5.Vector(1, 2, 3);
+ * console.log("Original Vector:", vector.toString()); // Output: [1, 2, 3]
+ *
+ * // Apply the matrix to the vector
+ * const transformedVector = matrix.multiplyVec3(vector);
+ * console.log("Transformed Vector:", transformedVector.toString()); // Output: [30, 36, 42]
+ *
+ * // Modify the matrix (e.g., apply a scaling transformation)
+ * matrix.scale(2, 2, 2);
+ * console.log("Modified Matrix (Scaling):", matrix.matrix); // Output: [2, 4, 6, 8, 10, 12, 14, 16, 18]
+ *
+ * // Apply the modified matrix to the same vector
+ * const scaledVector = matrix.multiplyVec3(vector);
+ * console.log("Scaled Vector:", scaledVector.toString()); // Output: [60, 72, 84]
+ * }
+ *
*/
multiplyVec3(multVector, target) {
if (target === undefined) {
@@ -861,6 +1650,12 @@ export class Matrix extends MatrixInterface {
// ====================
// PRIVATE
+ /**
+ * Creates identity matrix
+ * This method updates the current matrix with the result of the multiplication.
+ *
+ * @private
+ */
#createIdentityMatrix(dimension) {
// This it to prevent loops in the most common 3x3 and 4x4 cases
// TODO: check performance if it actually helps
@@ -950,6 +1745,7 @@ export class Matrix extends MatrixInterface {
/**
* @param {p5.Matrix|Float32Array|Number[]} multMatrix The matrix
* we want to multiply by
+ * @private
* @chainable
*/
#multNxN(multMatrix) {
@@ -979,6 +1775,7 @@ export class Matrix extends MatrixInterface {
*
* @param {p5.Matrix|Float32Array|Number[]} multMatrix The matrix
* we want to multiply by
+ * @private
* @chainable
*/
#mult3x3(_src) {
@@ -1028,6 +1825,7 @@ export class Matrix extends MatrixInterface {
* transpose according to a given matrix
* @param {p5.Matrix|Float32Array|Number[]} a the matrix to be
* based on to transpose
+ * @private
* @chainable
*/
#transpose4x4(a) {
@@ -1093,6 +1891,7 @@ export class Matrix extends MatrixInterface {
* If no arguments, it transposes itself and returns it.
*
* @param {Number[]} mat3 1-dimensional array
+ * @private
* @chainable
*/
#transpose3x3(mat3) {
@@ -1120,6 +1919,7 @@ export class Matrix extends MatrixInterface {
* invert matrix according to a give matrix
* @param {p5.Matrix|Float32Array|Number[]} a the matrix to be
* based on to invert
+ * @private
* @chainable
*/
#invert4x4(a) {
@@ -1205,6 +2005,7 @@ export class Matrix extends MatrixInterface {
/**
* Inverts a 3×3 matrix
* @chainable
+ * @private
*/
#invert3x3() {
const a00 = this.mat3[0];
@@ -1241,6 +2042,7 @@ export class Matrix extends MatrixInterface {
/**
* inspired by Toji's mat4 determinant
* @return {Number} Determinant of our 4×4 matrix
+ * @private
*/
#determinant4x4() {
if (this.#sqDimention !== 4) {
diff --git a/src/math/math.js b/src/math/math.js
index c3e9103da4..e88957e50d 100644
--- a/src/math/math.js
+++ b/src/math/math.js
@@ -1,11 +1,10 @@
/**
* @module Math
- * @submodule Vector
* @for p5
* @requires core
*/
-function math(p5, fn){
+function math(p5, fn) {
/**
* Creates a new p5.Vector object.
*
@@ -19,6 +18,11 @@ function math(p5, fn){
* y-component of 4. From the origin, this vector's tip is 3 units to the
* right and 4 units down.
*
+ * You can also pass N dimensions to the `createVector` function. For example,
+ * calling `createVector(1, 2, 3, 4)` creates a vector with four components.
+ * This allows for flexibility in representing vectors in higher-dimensional
+ * spaces.
+ *
* p5.Vector objects are often used to program
* motion because they simplify the math. For example, a moving ball has a
* position and a velocity. Position describes where the ball is in space. The
@@ -30,9 +34,7 @@ function math(p5, fn){
* p5.Vector class.
*
* @method createVector
- * @param {Number} [x] x component of the vector.
- * @param {Number} [y] y component of the vector.
- * @param {Number} [z] z component of the vector.
+ * @param {...Number} components Components of the vector.
* @return {p5.Vector} new p5.Vector object.
*
* @example
@@ -110,19 +112,19 @@ function math(p5, fn){
*
* A matrix is a mathematical concept that is useful in many fields, including
* computer graphics. In p5.js, matrices are used to perform transformations
- * on shapes and images.
+ * on shapes and images. The `createMatrix` method can take a column-major
+ * array representation of a square matrix as an argument. In the current implementation we only use squared matrices.
*
* @method createMatrix
+ * @param {Array} components Column-major array representation of the square matrix.
+ *
* @return {p5.Matrix} new p5.Matrix object.
*
* @example
- *
+ *
*
* function setup() {
- * createCanvas(100, 100);
- * let matrix = createMatrix();
- * console.log(matrix);
- * describe('Logs a new p5.Matrix object to the console.');
+ * let matrix = createMatrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
* }
*
*
@@ -134,6 +136,6 @@ function math(p5, fn){
export default math;
-if(typeof p5 !== 'undefined'){
+if (typeof p5 !== "undefined") {
math(p5, p5.prototype);
}
diff --git a/src/math/p5.Matrix.js b/src/math/p5.Matrix.js
index 704544dc86..0b0ab66e9d 100644
--- a/src/math/p5.Matrix.js
+++ b/src/math/p5.Matrix.js
@@ -1,4 +1,5 @@
/**
+ * @module Math
* @requires constants
* @todo see methods below needing further implementation.
* future consideration: implement SIMD optimizations
@@ -6,25 +7,109 @@
* https://developer.mozilla.org/en-US/docs/Web/JavaScript/
* Reference/Global_Objects/SIMD
*/
-import { Matrix } from './Matrices/Matrix'
+import { Matrix } from "./Matrices/Matrix";
// import { MatrixNumjs as Matrix } from './Matrices/MatrixNumjs'
-
-
-function matrix(p5, fn){
+function matrix(p5, fn) {
/**
- * A class to describe a 4×4 matrix
+ * A class to describe a matrix
* for model and view matrix manipulation in the p5js webgl renderer.
+ * The `Matrix` class represents a mathematical matrix and provides various methods for matrix operations.
+ *
+ * The `Matrix` class represents a mathematical matrix and provides various methods for matrix operations.
+ * This class extends the `MatrixInterface` and includes methods for creating, manipulating, and performing
+ * operations on matrices. It supports both 3x3 and 4x4 matrices, as well as general NxN matrices.
* @class p5.Matrix
- * @private
* @param {Array} [mat4] column-major array literal of our 4×4 matrix
+ * @example
+ * // Creating a 3x3 matrix from an array using column major arrangement
+ * const matrix = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ *
+ * // Creating a 4x4 identity matrix
+ * const identityMatrix = new p5.Matrix(4);
+ *
+ * // Adding two matrices
+ * const matrix1 = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const matrix2 = new p5.Matrix([9, 8, 7, 6, 5, 4, 3, 2, 1]);
+ * matrix1.add(matrix2); // matrix1 is now [10, 10, 10, 10, 10, 10, 10, 10, 10]
+ *
+ * // Setting an element in the matrix
+ * matrix.setElement(0, 10); // matrix is now [10, 2, 3, 4, 5, 6, 7, 8, 9]
+ *
+ * // Resetting the matrix to an identity matrix
+ * matrix.reset();
+ *
+ * // Getting the diagonal elements of the matrix
+ * const diagonal = matrix.diagonal(); // [1, 1, 1]
+ *
+ * // Transposing the matrix
+ * matrix.transpose();
+ *
+ * // Multiplying two matrices
+ * matrix1.mult(matrix2);
+ *
+ * // Inverting the matrix
+ * matrix.invert();
+ *
+ * // Scaling the matrix
+ * matrix.scale(2, 2, 2);
+ *
+ * // Rotating the matrix around an axis
+ * matrix.rotate4x4(Math.PI / 4, 1, 0, 0);
+ *
+ * // Applying a perspective transformation
+ * matrix.perspective(Math.PI / 4, 1, 0.1, 100);
+ *
+ * // Applying an orthographic transformation
+ * matrix.ortho(-1, 1, -1, 1, 0.1, 100);
+ *
+ * // Multiplying a vector by the matrix
+ * const vector = new Vector(1, 2, 3);
+ * const result = matrix.multiplyPoint(vector);
+ *
+ * // p5.js script example
+ *
+ * function setup() {
+ *
+ * // Create a 4x4 identity matrix
+ * const matrix = new p5.Matrix(4);
+ * console.log("Original p5.Matrix:", matrix.matrix.toString()); // Output: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+ *
+ * // Add two matrices
+ * const matrix1 = new p5.Matrix([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ * const matrix2 = new p5.Matrix([9, 8, 7, 6, 5, 4, 3, 2, 1]);
+ * matrix1.add(matrix2);
+ * console.log("After Addition:", matrix1.matrix.toString()); // Output: [10, 10, 10, 10, 10, 10, 10, 10, 10]
+ *
+ * // Reset the matrix to an identity matrix
+ * matrix.reset();
+ * console.log("Reset p5.Matrix:", matrix.matrix.toString()); // [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+ *
+ * // Apply a scaling transformation
+ * matrix.scale(2, 2, 2);
+ * console.log("Scaled p5.Matrix:", matrix.matrix.toString()); // [2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 1]
+ *
+ * // Apply a rotation around the X-axis
+ * matrix.rotate4x4(Math.PI / 4, 1, 0, 0);
+ * console.log("Rotated p5.Matrix (X-axis):", matrix.matrix.toString()); // [2, 0, 0, 0, 0, 1.4142135381698608, 1.4142135381698608, 0, 0, -1.4142135381698608, 1.4142135381698608, 0, 0, 0, 0, 1]
+ *
+ * // Apply a perspective transformation
+ * matrix.perspective(Math.PI / 4, 1, 0.1, 100);
+ * console.log("Perspective p5.Matrix:", matrix.matrix.toString());// [2.4142136573791504, 0, 0, 0, 0, 2.4142136573791504, 0, 0, 0, 0, -1.0020020008087158, -1, 0, 0, -0.20020020008087158, 0]
+ *
+ * // Multiply a vector by the matrix
+ * const vector = new p5.Vector(1, 2, 3);
+ * const transformedVector = matrix.multiplyPoint(vector);
+ * console.log("Transformed Vector:", transformedVector.toString());
+ * }
+ *
*/
- p5.Matrix = Matrix
+ p5.Matrix = Matrix;
}
export default matrix;
export { Matrix };
-if(typeof p5 !== 'undefined'){
+if (typeof p5 !== "undefined") {
matrix(p5, p5.prototype);
}
diff --git a/src/math/p5.Vector.js b/src/math/p5.Vector.js
index fa3386e023..97b72ab61b 100644
--- a/src/math/p5.Vector.js
+++ b/src/math/p5.Vector.js
@@ -1,10 +1,9 @@
/**
* @module Math
- * @submodule Vector
* @requires constants
*/
-import * as constants from '../core/constants';
+import * as constants from "../core/constants";
/// HELPERS FOR REMAINDER METHOD
const calculateRemainder2D = function (xComponent, yComponent) {
@@ -52,7 +51,7 @@ class Vector {
}
/**
- * Gets the values of the vector.
+ * Gets the values of the N-dimensional vector.
*
* This method returns an array of numbers that represent the vector.
* Each number in the array corresponds to a different component of the vector,
@@ -382,7 +381,7 @@ class Vector {
}
/**
- * Adds to a vector's `x`, `y`, and `z` components.
+ * Adds to a vector's components.
*
* `add()` can use separate numbers, as in `v.add(1, 2, 3)`,
* another
p5.Vector object, as in `v.add(v2)`, or
@@ -392,11 +391,13 @@ class Vector {
* example, `v.add(4, 5)` adds 4 to `v.x`, 5 to `v.y`, and 0 to `v.z`.
* Calling `add()` with no arguments, as in `v.add()`, has no effect.
*
+ * This method supports N-dimensional vectors.
+ *
* The static version of `add()`, as in `p5.Vector.add(v2, v1)`, returns a new
*
p5.Vector object and doesn't change the
* originals.
*
- * @param {Number} x x component of the vector to be added.
+ * @param {Number|Array} x x component of the vector to be added or an array of components.
* @param {Number} [y] y component of the vector to be added.
* @param {Number} [z] z component of the vector to be added.
* @chainable
@@ -715,7 +716,6 @@ class Vector {
*
p5.Vector object and doesn't change the
* originals.
*
- * @method sub
* @param {Number} x x component of the vector to subtract.
* @param {Number} [y] y component of the vector to subtract.
* @param {Number} [z] z component of the vector to subtract.
@@ -1592,6 +1592,7 @@ class Vector {
* using coordinates as in `dist(x1, y1, x2, y2)`.
*
* @method dist
+ * @submodule p5.Vector
* @param {p5.Vector} v x, y, and z coordinates of a
p5.Vector.
* @return {Number} distance.
*
@@ -3814,7 +3815,7 @@ class Vector {
}
return v.equals(v2);
}
-};
+}
function vector(p5, fn) {
/**
@@ -3930,6 +3931,6 @@ function vector(p5, fn) {
export default vector;
export { Vector };
-if (typeof p5 !== 'undefined') {
+if (typeof p5 !== "undefined") {
vector(p5, p5.prototype);
}