# math2d

Two dimensional vector math library for JavaScript. Built for performance in computation-heavy real-time engines without sacrificing usability. Supports tree shaking and dead code removal to avoid bloating client-side bundles.

## Getting Started

`$ yarn add math2d`

`; ;;console.logvecTransformBythreeFour, rotation; // or, re-use existing memory to avoid potentially expensive heap allocations.;vecTransformBytmp, rotation, tmp;`

## API

Documentation for Math2d's API is available at https://crazytoucan.github.io/math2d/api/.

### Box Functions

- boxAlloc: Creates a new Box object in memory, with all values initialized to
`NaN`

. - boxClone: Copies values from an existing IBox into a new box.
- boxComputeIntersection: Computes the area intersection of the two box regions.
- boxComputeUnion: Compute the smallest bounding box that contains both given boxes.
- boxContainsBox: Determines whether the second box is completely enclosed in the first.
- boxContainsPoint: Determines whether the box contains a given point.
- boxEncapsulate: Grows the box to include a given point.
- boxGetOutCode: Determines where the specified point lies in relation to the given box.
- boxGrow: Expands a box by a given amount in all directions.
- boxIntersectsBox: Determines whether two boxes overlap.
- boxIsEmpty: Determines whether this box represents an empty area.
- boxReset: Construct a new box given
`minX`

,`minY`

,`maxX`

, and`maxY`

bounding values. - boxScale: Scales a box by a fixed scalar in both directions.
- boxTransformBy: Compute the bounds of the image of this box after applying a 2D affine transformation.
- boxTranslate: Translate a box by an offset in the x- and y- directions.

### Line Functions

- lineAlloc: Creates a new Line object in memory, with all values initialized to
`NaN`

. - lineClone: Copies the values from the given line into a new line.
- lineContainsPoint: Determines if the point is on the line
- lineGetPointAt: Gets a point along the line, parameterized according to distance along its direction vector.
- lineIntersectLine: Computes the intersection point between the two given lines, if it exists.
- lineIntersectPolylineIterator: Computes all locations at which a line crosses a given polyline.
- lineIntersectRay: Computes the intersection point between the given line and ray, if it exists.
- lineIntersectSegment: Computes the intersection point between the given line and segment, if it exists.
- lineNearestDistanceToPoint: Determines the closest the line comes to a given point
- lineNearestSignedDistanceToPoint: Determines the closest
*signed*distance the line comes to a given point - lineProjectPoint: Projects a point onto the given line, returning the distance
*t*along the line where it falls. - lineReset: Construct a new line given an (x0, y0) initial point and (dirX, dirY) direction vector.
- lineThroughPoints: Construct a line that passes through two given points.
- lineTransformBy: Transforms a line by an affine matrix.
- lineWhichSide: Computes on which side of the line a given point lies.

### Mat2d Functions

- mat2dAlloc: Creates a new mat2d object in memory, with all values initialized to
`NaN`

. - mat2dClone: Copies the values from the given matrix into a new matrix.
- mat2dDeterminant: Computes the determinant of the affine matrix
- mat2dFromRotation: Computes the affine transform corresponding to a given rotation, in radians
- mat2dFromTranslation: Computes the affine transform corresponding to a given (tx, ty) translation
- mat2dIdentity: Returns the identity affine matrix,
`[1 0 0 1 0 0]`

- mat2dInvert: Computes the inverse of the given 2d affine matrix
- mat2dIsOrthogonal: Returns whether the matrix is an orthogonal matrix.
- mat2dIsTranslationOnly: Returns whether the matrix corresponds to only a translation.
- mat2dMulMat2d: Computes the result of affine matrix multiplication
*m1*×*m2*. - mat2dReset: Construct a new matrix given component values.
- mat2dRotate: Applies a rotation in radians to the given matrix, returning the result.
- mat2dScale: Applies a scaling transform on top of the given affine matrix, returning the result.
- mat2dTranslate: Applies a translation on top of the given matrix, returning the result.

### Polygon Functions

- polygonAlloc: Creates a new Array object in memory to hold Polygon data. Its initial length is 0.
- polygonContainsPointInside: Determines whether the point is inside the given polygon, using the even-odd fill rule.
- polygonGetBounds: Calculate the smallest bounding box that contains this polygon's geometry
- polygonGetNumSides: Return the number of sides of this polygon, which is
`poly.length / 2`

. - polygonGetPerimeterLength: Computes the total perimeter length of this polygon.
- polygonGetPerimeterPointAt: Computes a point along the polygon's perimeter, parameterized according to linear interpolation between adjacent vertices, cycling back to the start after its last vertex.
- polygonGetSideLength: Returns the length of a polygon's side by index, starting at 0.
- polygonGetSideSegment: Returns a polygon's side by given index as a segment, starting at 0.
- polygonIntersectLineIterator: Computes all locations at which a polygon crosses a given line.
- polygonIntersectRayIterator: Computes all locations at which a polygon crosses a given ray.
- polygonIntersectSegmentIterator: Computes all locations at which a polygon crosses a given line segment.
- polygonNearestDistanceSqToPoint: Computes the closest the polygon's perimeter comes to a given reference point.
- polygonTransformBy: Transforms a polygon by an affine matrix.

### Polyline Functions

- polylineAlloc: Creates a new Array object in memory to hold Polyline data. Its initial length is 0.
- polylineClose: Repeats the polyline's first vertex to form a closed path.
- polylineGetBounds: Computes bounding box of polyline's geometry
- polylineGetLength: Computes total length of polyline
- polylineGetNumSegments: Returns the number of individual line segments in this polyline
- polylineGetPointAt: Computes a point along the polyline, parameterized according to linear interpolation between adjacent vertices.
- polylineGetSegment: Returns a polyline's segment by given index, starting at 0.
- polylineGetSegmentLength: Computes the length of one of a polyline's segments by index, starting at 0.
- polylineGetVertex: Retrieves a vertex from this polyline's geometry, starting at index 0
- polylineIntersectLineIterator: Computes all locations at which a polyline crosses a given line.
- polylineIntersectRayIterator: Computes all locations at which a polyline crosses a given ray.
- polylineIntersectSegmentIterator: Computes all locations at which a polyline crosses a given line segment.
- polylineIsClosed: Returns whether the polyline's last vertex equals its first
- polylineNearestDistanceSqToPoint: Finds the closest the polyline comes to a given reference point.
- polylineTransformBy: Transforms a polyline by an affine matrix.
- polylineTrim: Trims a polyline to a range of its
*t*parameter.

### Ray Functions

- rayAlloc: Creates a new Ray object in memory, with all values initialized to
`NaN`

. - rayClone: Copies the values from the given ray into a new ray.
- rayContainsPoint: Determines if the point is on the ray
- rayGetPointAt: Gets a point along the ray, parameterized according to distance along its direction vector.
- rayIntersectLine: Computes the intersection point between the given ray and line, if it exists.
- rayIntersectPolylineIterator: Computes all locations at which a ray crosses a given polyline.
- rayIntersectRay: Computes the intersection point between the two rays, if it exists.
- rayIntersectSegment: Computes the intersection point between the ray and the segment, if it exists.
- rayLookAt: Constructs a ray from an initial point, pointing in the direction of a target point.
- rayNearestDistanceSqToPoint: Determines the closest the ray comes to a given reference point
- rayReset: Construct a new ray given an (x0, y0) initial point and (dirX, dirY) direction vector.
- rayTransformBy: Transforms a ray by an affine matrix.

### Segment Functions

- segmentAlloc: Creates a new Segment object in memory, with all values initialized to
`NaN`

. - segmentGetEndpoint0: Retrieves the starting endpoint (
*t*= 0) of the segment, as a vector. - segmentGetEndpoint1: Retrives the ending endpoint (
*t*= 1) of the segment, as a vector. - segmentGetLength: Computes the length of the line segment
- segmentGetLengthSq: Computes the squared length of the line segment
- segmentGetPointAt: Gets a point along the line segment, parameterized according to linear interpolation between its endpoints.
- segmentIntersectLine: Computes the intersection point between the given segment and line, if it exists.
- segmentIntersectPolylineIterator: Computes all locations at which a line segment meets a given polyline.
- segmentIntersectRay: Computes the intersection point between the ray and the segment, if it exists.
- segmentIntersectSegment: Computes the intersection point between the two line segments, if it exists.
- segmentNearestDistanceSqToPoint: Finds the closest the segment comes to a given reference point.
- segmentReset: Construct a new line segment given an (x0, y0) starting vertex and (x1, y1) ending vertex. The two points are allowed to be the same.
- segmentReverse: Computes the reverse of the segment, i.e. swapping its starting vertex and ending vertex.

### Vec Functions

- vecAdd: Computes the result of adding the two given vectors.
- vecAlloc: Creates a new Vec object in memory, with all values initialized to
`NaN`

. - vecClone: Copies the values from the given vector into a new vector.
- vecCross: Computes the two-dimensional cross product of the two vectors.
- vecDistance: Computes the straight-line (Euclidean) distance between the two points
- vecDistanceSq: Computes the squared straight-line (i.e. Euclidean) distance between the two points
- vecDot: Computes the dot product of the two vectors, i.e.
`u.x * v.x + u.y * v.y`

. - vecGetLength: Computes the straight-line length (i.e. Euclidean norm) of the given vector.
- vecGetLengthSq: Computes the squared straight-line length (i.e. square of the Euclidean norm) of the given vector.
- vecGetManhattanLength: Computes the Manhattan length of the given vector, i.e.
`|v.x| + |v.y|`

. - vecLerp: Performs a linear interpolation between the two vectors. The
`r`

parameter is allowed to be outside`[0, 1]`

. - vecManhattanDistance: Computes the Manhattan distance between the two points.
- vecNormalize: Normalizes the vector to be length 1. If the given vector is the zero-vector, this method
returns
`(NaN, NaN)`

. - vecOrigin: Returns the 2d origin vector,
`(0, 0)`

. - vecPerp: Computes the perp of the given vector, as defined by
`vecPerp(a, b) = (-b, a)`

. This is equivalent to a counter-clockwise rotation in the standard plane. - vecReset: Construct a new vector given an
`x`

and`y`

value. - vecScale: Scales both coordinates of this vector by a given scalar.
- vecSubtract: Computes
`u - v`

, i.e. subtracting the second vector from the first. - vecTransformBy: Multiplies the vector by an affine matrix.