Sylvester version: 0.1.0 onwards
- -Class methods:
-create,
-X,
-Y,
-Z
-
Instance methods:
-contains,
-distanceFrom,
-dup,
-eql,
-intersectionWith,
-intersects,
-isParallelTo,
-liesIn,
-pointClosestTo,
-reflectionIn,
-rotate,
-setVectors,
-translate
-
Instance variables:
- -anchor – a 3D Vector corresponding to a point on the linedirection – a normalized 3D Vector representing the line’s directionThe Line class is designed to model infinite straight lines in 3 dimensions. It is possible to specify lines using 2D Vectors, but they will be stored in the Line instance as 3D vectors whose third element is zero. Lines created in this way are thus 3D lines confined to the x-y plane. You can also specify 2D vectors as arguments for many of Line’s instance methods – again, these will be interpreted as 3D vectors with a zero third component.
Creates a Line instance with the specified properties. anchor and direction can each be either 2- or 3-dimensional arrays or Vectors, and they will be stored in the Line’s properties as 3D vectors. (The thrid element will be zero if a 2D vector was supplied.) direction will be normalized before being saved. The following are all fine:
var A = Line.create([4,8], [1,5]);
-var B = Line.create($V([4,8]), $V([1,5]));
-var C = Line.create([9,2,5], $V([8,2,0]));For situations where x, y and z are used to refer to co-ordinates, x corresponds to the first element of a vector, y the second and z the third.
- -This method is aliased as $L.
Predefined Line instances representing the x, y and z axes respectively.
Returns true iff the vector point is a point that lies on the receiver.
Returns the shortest distance between the receiver and obj, which can be a Line, a Plane or a Vector. If a Plane, this method will only return a non-zero value if the receiver is parallel to obj.
Returns a copy of the receiver.
- - -Returns true iff line is equal to the receiver, that is, if they both represent the same region of space. Their anchor and direction properties do not have to be identical for this to be the case. As long as line.anchor is a point on the receiver, and line.direction is (anti)parallel to the receiver’s direction, then this method returns true.
Returns a Vector representing the unique point of intersection of the receiver with obj, which can be either a Line or a Plane. If no such point exists, returns null.
Returns true iff the receiver has a unique point of intersection with obj, which can be either a Line or a Plane.
Returns true iff the receiver and line are parallel lines. Their direction vectors can point in opposite directions – two lines with opposing directions represent the same set of points.
Returns true iff the receiver lies in the given plane.
Returns a Vector representing the point on the receiver that is closest to obj, which can be either a Vector or a Line. If a Line, returns null if the lines are parallel – there is no unique closest point.
Returns a Line representing the result of reflecting (inverting) the receiver in obj, which can be a Line, a Plane or a Vector.
Returns the result of rotating the receiver by angle radians about axis, which can be a Line, or a Vector. If a Vector, the receiver is rotated about a line whose anchor is axis and whose direction is [0, 0, 1]. This is useful for working in 2D:
var L = Line.X.rotate(Math.PI/2, $V([5,0]));
-
-var test = L.eql(Line.create([5,0], [0,1]));
-// Returns true - the 90-degree rotation leaves Line.X parallel to the y axisBe careful when working with axis as a Line – rotations are performed in a right-handed fashion about the line’s direction.
Sets the receiver’s properties accordingly. See create.
- - -Returns the result of translating the receiver by adding vector to its anchor property. vector can be a 2- or 3- dimensional array or Vector. If 2-dimensional, a zero third component will be added.
Sylvester version: 0.1.0 onwards
- -Class methods:
-create,
-Diagonal,
-I,
-Random,
-Rotation,
-RotationX,
-RotationY,
-RotationZ,
-Zero
-
Instance methods:
-add,
-augment,
-canMultiplyFromLeft,
-col,
-cols,
-det,
-determinant,
-diagonal,
-dimensions,
-dup,
-e,
-eql,
-indexOf,
-inspect,
-inv,
-inverse,
-isSameSizeAs,
-isSingular,
-isSquare,
-map,
-max,
-minor,
-multiply,
-rank,
-rk,
-round,
-row,
-rows,
-setElements,
-snapTo,
-subtract,
-toRightTriangular,
-toUpperTriangular,
-tr,
-trace,
-transpose,
-x
-
Instance variables:
- -elements – a nested array containing the matrix’s elementsThe Matrix class is designed to model real matrices in any number of dimensions. All the elements in a matrix must be real numbers.
Creates and returns a new Matrix instance from the array elements. elements should be a nested array: the top level array is the rows, and each row is an array of elements. This means you write out a matrix in code in the same orientation you would on paper.
var M = $M([
- [8,3,9],
- [2,0,7],
- [1,9,3]
-]);Every row must have the same number of elements, otherwise the method will return null.
This method is aliased as $M.
Returns a square matrix whose leading-diagonal elements are the values in the array elements, and whose off-diagonal elements are zero.
var D = Matrix.Diagonal([4,3,7,1]);
-
-// D is the matrix
-// 4 0 0 0
-// 0 3 0 0
-// 0 0 7 0
-// 0 0 0 1Returns the n×n identity matrix.
Returns a matrix with n rows and m columns, all the elements of which are random numbers between 0 and 1.
If called with only one argument, returns the 2×2 matrix for an anticlockwise rotation of angle radians about the origin. That is, vectors are rotated anticlockwise with respect to the coordinate system, not the other way round.
If called with two arguments, returns the 3×3 matrix for a right-handed rotation of angle radians about the axis given by the 3-vector axis, keeping the origin fixed.
Each of these return the 3×3 matrix representing a right-handed rotation of points in 3-dimensional space relative to the coordinate system through an angle of angle radians about the x, y and z axes respectively. They are used as a foundation for the more general Matrix.Rotation.
Returns a matrix with n rows and m columns, all the elements of which are zero.
Returns the matrix sum of the receiver and matrix. Thus, A.add(B) is equivalent to A + B. Returns null if the matrices are different sizes.
Returns the result of augmenting the receiver with matrix, that is, appending matrix to the right hand side of the receiver. Both matrices must have the same number of rows for this to work.
var M = $M([
- [8,3,0],
- [4,4,2],
- [9,1,5]
-]).augment(Matrix.I(3));
-
-// M is the matrix
-// 8 3 0 1 0 0
-// 4 4 2 0 1 0
-// 9 1 5 0 0 1matrix can also be a Vector, as long as it has the same number of elements as the receiver has rows. It will be appended to the receiver as an extra column on the right hand side.
A.canMultiplyFromLeft(B) returns true iff AB is a mathematically valid expression. This is the case iff A has the same number of columns as B has rows. matrix can also be a Vector, as long as it has the same number of elements as the receiver has rows.
Returns the jth column of the receiver as a Vector.
Returns the number of columns the receiver has.
- - -Alias for determinant.
- - -If the receiver is square, returns its determinant, otherwise returns null. Note that if the receiver is singular, this method will return exactly zero, with no rounding errors.
If the receiver is square, returns its leading-diagonal elements as a Vector. Otherwise, returns null.
Returns an object containing the receiver’s dimensions.
- -var dims = Matrix.Zero(4,3).dimensions();
-// dims is {rows: 4, cols: 3}Returns a copy of the receiver.
- - -A.e(i,j) returns the element Aij of matrix A, that is the element in the ith row and jth column. Indexes begin at 1, in agreement with mathematical notation.
Returns true iff matrix has all its elements equal to those of the receiver.
Reads the receiver’s elements row by row from left to right and returns an object containing the indeces of the first exact match. Returns null if no match is found.
var foo = $M([
- [0,9,4],
- [9,5,8],
- [1,5,3]
-]).indexOf(9);
-
-// foo is {row: 1, col: 2}Returns a string representation of the receiver, useful for debugging.
- -alert(Matrix.I(4).inspect());
-
-// alerts:
-// [1, 0, 0, 0]
-// [0, 1, 0, 0]
-// [0, 0, 1, 0]
-// [0, 0, 0, 1]Alias for inverse.
- - -Returns the matrix inverse of the receiver, if one exists. If the matrix is singular or not square, then null is returned. The inverse is computed using Gauss-Jordan elimination.
Returns true iff matrix has the same number of rows and columns as the receiver. matrix can also be a Vector, as long as it has the same number of elements as the receiver has rows.
Returns true iff the receiver is square and has zero determinant.
Returns true iff the receiver is square.
Maps the receiver to another matrix by calling iterator on each element of the receiver in turn. iterator receives the row and column index of each element as second and third arguments. Some examples:
// Square all the elements of a matrix:
-
-var A_sq = A.map(function(x) { return x * x; });
-
-// Determine whether a matrix is symmetric:
-
-var is_sym = (A.map(
- function(x, i, j) { return (A.e(i,j) == A.e(j,i)) ? 1 : 0; }
-).indexOf(0) === null);Returns the value of the element of the receiver with the largest absolute value.
- - -This method returns a matrix formed from a subset of the receiver’s elements. It selects elements beginning at row i and column j of the receiver, and returns a matrix with n rows and m columns. The selection wraps to the other side of the receiver if n or m is large enough. This is best illustrated by example:
var M = $M([
- [9,2,6,5],
- [0,1,7,4],
- [4,2,6,7],
- [1,8,5,3]
-]);
-
-var A = M.minor(2,1,2,3);
-// 0 1 7
-// 4 2 6
-
-var B = M.minor(1,4,3,3);
-// 5 9 2
-// 4 0 1
-// 7 4 2
-
-// Augment M with itself
-var C = M.minor(1,1,4,8);
-// 9 2 6 5 9 2 6 5
-// 0 1 7 4 0 1 7 4
-// 4 2 6 7 4 2 6 7
-// 1 8 5 3 1 8 5 3If object is a matrix, then this method returns the result of multiplying the receiver by object in that order: A.multiply(B) means AB. If object is a Vector, then it is converted to a column matrix, multiplied by the receiver, and the result is returned as a Vector (this saves you having to call col(1) on the result). If object is a scalar, then the method returns a copy of the receiver with all its elements multiplied by object.
This method is aliased as x.
Returns the receiver’s rank, which is the number of linearly independent rows/columns it contains.
- - -Alias for rank.
Returns a copy of the receiver with all its elements rounded to the nearest integer.
- - -Returns the ith row of the receiver as a Vector.
Returns the number of rows the receiver has.
- - -Sets the receiver’s elements from the array elements. The element array’ top-level elements should be the rows, and each row is an array of values reading from left to right across the columns. See Matrix.create.
Returns a copy of the receiver in which any elements that differ from x by less than the value of Sylvester.precision are set exactly equal to x.
Returns the result of subtracting matrix from the receiver. Thus, A.subtract(B) is equivalent to A − B. Returns null if the matrices are different sizes.
Returns a copy of the receiver converted to right triangular form. The conversion is done only by adding multiples of rows to other rows, so the determinant (if the matrix is square) is unchanged. This method can be used on non-square matrices, which lets you use it to solve sets of simultaneous equations. For example: solving the system of linear equations
- -would be written as:
- -var equations = $M([
- [ 3, 2, -1, 1],
- [ 2, -2, 4, -2],
- [-1, 0.5, -1, 0]
-]);
-
-var eqns = equations.toRightTriangular();
-
-var sol_z = eqns.e(3,4) / eqns.e(3,3);
-var sol_y = (eqns.e(2,4) - eqns.e(2,3)*sol_z) / eqns.e(2,2);
-var sol_x = (eqns.e(1,4) - eqns.e(1,3)*sol_z - eqns.e(1,2)*sol_y) / eqns.e(1,1);Alias for toRightTriangular.
Alias for trace.
Returns the trace for square matrices, which is the sum of their leading-diagonal elements.
- - -Returns the matrix transpose of the receiver.
- - -Alias for multiply(k).
Sylvester version: 0.1.0 onwards
- -Class methods:
-create,
-XY,
-XZ,
-YX,
-YZ,
-ZX,
-ZY
-
Instance methods:
-contains,
-distanceFrom,
-dup,
-eql,
-intersectionWith,
-intersects,
-isParallelTo,
-isPerpendicularTo,
-pointClosestTo,
-reflectionIn,
-rotate,
-setVectors,
-translate
-
Instance variables:
- -anchor – a 3D Vector corresponding to a point in the planenormal – a normalized 3D Vector perpendicular to the planeThe Plane class is designed to model infinite flat planes in 3 dimensions.
Creates a new Plane instance with the given properties. If two arguments are supplied, v1 should be the normal to the plane. If three arguments, v1 and v2 should be directions of vectors in the plane, such that the normal is v1 × v2. The instance will not store these directions, only the calculated normal. anchor is any point in the plane, and the normal vector is normalized before being saved.
Predefined Plane instances representing the x-y, y-z and z-x planes.
Returns true iff obj is a Line or a Vector that lies in the receiver.
Returns the shortest distance between the receiver and obj, which can be a Line, a Plane or a Vector.
Returns a copy of the receiver.
- - -Returns true iff plane and the receiver represent the same region of space. Their anchor and normal properties need not be identical for this to be the case. As long as plane.anchor is a point in the receiver, and plane.normal is (anti)parallel to the receiver’s normal, then this method returns true.
Returns the unique intersection of the receiver with obj, which can be either a Line or a Plane. If obj is a Line, a Vector is returned. If obj is a Plane, a Line is returned. If no intersection exists, returns null.
Returns true iff the receiver has a unique intersection with obj, which can be either a Line or a Plane.
Returns true iff the receiver and obj are parallel. If obj is a plane, their normal vectors can point in opposite directions – two planes with opposing normals represent the same set of points. If obj is a Line then its direction must be perpendicular to the receiver’s normal.
Returns true iff plane is perpendicular to the receiver.
Returns a Vector representing the point on the receiver that is closest to the vector point.
Returns a Plane representing the result of reflecting (inverting) the receiver in obj, which can be a Line, a Plane or a Vector.
Returns the result of rotating the receiver by angle radians about the Line axis. The rotation is performed in a right-handed fashion about axis.direction.
Sets the receiver’s properties accordingly. See create.
- - -Returns the result of translating the receiver by adding vector to its anchor property. vector can be a 2- or 3- dimensional array or Vector. If 2-dimensional, a zero third component will be added.
Sylvester version: 0.1.0 onwards
- -Class methods:
-create,
-i,
-j,
-k,
-Random,
-Zero
-
Instance methods:
-add,
-angleFrom,
-cross,
-dimensions,
-distanceFrom,
-dot,
-dup,
-e,
-each,
-eql,
-indexOf,
-inspect,
-isAntiparallelTo,
-isParallelTo,
-isPerpendicularTo,
-liesIn,
-liesOn,
-map,
-max,
-modulus,
-multiply,
-reflectionIn,
-rotate,
-round,
-setElements,
-snapTo,
-subtract,
-to3D,
-toDiagonalMatrix,
-toUnitVector,
-x
-
Instance variables:
- -elements – an array containing the vector’s elementsThe Vector class is designed to model vectors in any number of dimensions. All the elements of a vector must be real numbers. Depending on what you’re using them for, it can be helpful to think of a vector either as a point in n-dimensional space, or as a line connecting the origin to that same point.
Creates and returns new Vector instance from the array elements. Example usage:
var v = Vector.create([6,2,9]);This method is aliased as $V.
Predefined Vector instances representing the 3-dimensional i, j and k vectors respectively.
Returns a vector with n elements, each of which is a random number between 0 and 1.
Returns a vector with n elements, all of which are zero.
If the receiver and vector have the same number of elements, returns a Vector formed by adding them together. Otherwise, returns null.
Returns the angle in radians between vector and the receiver. The return value will always be between 0 and +π inclusive. If the vectors have unequal numbers of elements, null is returned.
Returns the cross product (aka the vector product) of the receiver with vector, in the order in which they are written. For example, a.cross(b) is the same as the mathematical statement a × b. Both vectors must have three elements, otherwise this method returns null.
Returns the number of elements the receiver has – that is, the dimensionality of the vector space it inhabits.
- - -Returns the (always positive) distance of the receiver from vector. That is, a.distanceFrom(b) is equivalent to |a − b|.
Returns the value of the dot product (aka the scalar product) of the receiver with vector. That is, a.dot(b) is the same as a • b. Returns null if the vectors have unequal dimensions.
Returns a copy of the receiver.
- - -Returns the ith element of the receiver. Element indexes begin at 1, not 0 like array indexes. This is consistent with mathematical notation.
Calls iterator for each element of the receiver. iterator is passed the index (numbered from 1) of each element as the second argument. For example, the following alerts the index and value of each of the vector’s elements:
$V([4,9,3,6]).each(function(x, i) {
- alert(i + ': ' + x);
-});
-
-// Alerts: '1: 4', '2: 9', '3: 3', '4: 6'Returns true iff the receiver is equal to vector, that is, if all their elements are equal. See note on accuracy.
Returns the index position (numbered from 1, just as for e()) of the first element exactly equal to x. If no match is found, returns null.
Returns a string representation of the receiver, useful for debugging purposes. Example:
-alert($V([7,-2,5]).inspect())
-// alerts "[7, -2, 5]"Returns true iff vector’s direction is exactly opposed to that of the receiver, that is, if the angle between them is π. See note on accuracy.
Returns true iff vector’s direction is exactly aligned with that of the receiver, that is, if the angle between them is zero. See note on accuracy.
Returns true iff vector’s direction is perpendicular to that of the receiver, that is, if the angle between them is π/2. See note on accuracy.
Returns true iff the receiver is a point in the given Plane. Only works on 3-dimensional vectors.
Returns true iff the receiver is a point on the given Line. Only works on 3-dimensional vectors.
Maps the receiver to another vector by calling iterator with each element in turn. iterator is also passed the index (numbered from 1) of each element as the second argument. Some examples:
var a = $V([3,4,5]);
-
-// To square the elements of a
-var b = a.map(function(x) { return x * x; });
-
-// To add each element's index to its value
-var c = a.map(function(x, i) { return x + i; });Returns the element of the receiver with the largest absolute value. For example, $V([0,-6,5]).max() returns -6.
Returns the modulus of the receiver, given by |v| = √( Σ vi² ).
- - -Returns the vector obtained by multiplying all the elements of the receiver by the scalar quantity k. Aliased as x(k).
Returns the vector that results from reflecting the receiver in object, which can be a Vector, a Line or a Plane. If object is a Vector, then a.reflectionIn(b) returns b + (b − a). Otherwise, the same formula applies but b is the closest point on the line or plane to a.
Returns a copy of the receiver rotated by angle radians about axis. If the receiver is a 2-vector then axis should also be a 2-vector, and the method returns the result of rotating the receiver about the point given by axis. The rotation is performed anticlockwise from the point of view of someone looking down on the x-y plane, so for example:
var a = $V([10,5]);
-var b = $V([5,5]);
-
-var c = a.rotate(Math.PI/2, b);
-// c is the point (5,10)If the receiver is a 3-vector, then axis should be a Line, and the rotation is performed in a right-handed fashion around the line’s direction. Be careful that the line points in the right direction when using this method!
Returns a copy of the receiver with all its elements rounded to the nearest integer.
- - -Sets the receiver’s elements property equal to the array els. Since version 0.1.1, the numericality of els’s elements is not checked for performance reasons. It is assumed you’ll be using this with numbers, and if you throw anything else in then most method calls won’t work.
Returns a copy of the receiver with any elements that differ from x by less than the value of Sylvester.precision set exactly equal to x. This can be useful for working around rounding errors.
If the receiver and vector have the same number of elements, returns a Vector formed by subtracting the latter from the former. Otherwise, returns null.
If the receiver is 3-dimensional, it returns a copy of the receiver. If it is 2-dimensional, it returns a copy of the receiver with an additional third element, which is set to zero. For all other sizes, it returns null. Something is similar is done in many of the methods of the Line and Plane classes, although for performance reasons they don’t use this method.
Returns an n×n square Matrix, where n is the number of elements in the receiver, whose leading-diagonal elements are the elements of the receiver. All the off-diagonal elements are zero.
Returns a copy of the receiver, whose elements have been scaled such that the modulus of the new vector is equal to 1. If the receiver has zero modulus then a copy of it is returned unchanged.
Alias for multiply(k).
There a couple of things that don’t really fit in to any of the class references listed above. The first one is that there exist a series of shorthand functions for creating objects in Sylvester. They are:
- -$V – short for Vector.create$M – short for Matrix.create$L – short for Line.create$P – short for Plane.createThe second is that a lot of functionality in Sylvester relies on computing various quantities and comparing them to zero. Rounding errors on floating point numbers mean that quantities that should be zero can actually be a bit off. Therefore, quantities are compared to the value of Sylvester.precision – if the absolute value of x is less than this number, x is considered to be equal to zero. By default, Sylvester.precision is set to 1e-6, but you can just set the value yourself if you want to be more strict – it should ideally be several orders of magnitude smaller than the vector/matrix elements you’re working with.
Finally, as a general rule, trying to compute something that is not mathematically meaningful (like multiplying matrices with incompatible sizes) will produce a result of null. Similarly, trying to compute something that does not exist, such as the intersection of two parallel lines, will return null.