API Docs

Class: PlaneArray

PD. PlaneArray

new PlaneArray()

A helper class for performing vector math using [a,b,c,d] array-based plane equations.

The array entries represent components of the Ax + By + Cz + D = 0 plane equation. When stored this way, the first three entries in the plane array are also a vector array defining the normal direction, and can be used directly in many PD.VectorArray methods.

Any Float32Array with at least four items in the same [a,b,c,d] format can also be used entirely interchangeably as both output or input in all plane array methods.

Author:
  • drajmarsh

Methods

clone(out) <static>

Creates a copy of the given plane array.

This method simply returns out.slice() but is included for API compatibility.

Parameters:
Name Type Description
out Array.<number>

The [a,b,c,d] plane array to clone.
Returns:

Returns a new copied plane array.

Type
number

computeFromIndexedPath(out, indices, vertices) <static>

Computes the [a,b,c,d] plane array from the surface normal of given array of connected points.

This method calculates the surface normal from multiple points along a path using Newell's Method, which provides a very robust way of computing an 'average' normal from points which may vary quite considerably from being coplanar.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [a,b,c,d] plane array to set.
indices Array.<number>

An array of ordinal indexes to points within the vertices array.
vertices Array.<number>

A repository of [x,y,z] coordinate arrays that indices.
Returns:

Returns the given [a,b,c,d] plane array.

Type
Array.<number>

computeFromPath(out, path) <static>

Computes the [a,b,c,d] plane array from the surface normal of given array of connected points.

This method calculates the surface normal from multiple points along a path using Newell's Method, which provides a very robust way of computing an 'average' normal from points which may vary quite considerably from being coplanar.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [a,b,c,d] plane array to set.
path Array.<number>

An array of [x,y,z] coordinate arrays defining a polyline or polygon.
Returns:

Returns the given [a,b,c,d] plane array.

Type
Array.<number>

computeInclinedFromLine(out, rayPos, rayDir, angle) <static>

Calculates an [a,b,c,d] plane array that is inclined by the given angle from a line that is roughly horizontal.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [a,b,c,d] plane array to receive the result.
rayPos Array.<number>

The [x,y,z] vector array giving the first point on a line.
rayDir Array.<number>

The [x,y,z] vector array giving the second point on a line.
angle number

The tilt angle of the plane in radians (0:horizontal to PI/2:vertical).
Returns:

Returns the modified out [a,b,c,d] plane array.

Type
Array.<number>

coplanarPoint(out, plane1) <static>

Projects the origin onto the give plane.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

An [x,y,z] vector array to receive the planar point.
plane1 Array.<number>

The [a,b,c,d] plane array to project the point onto.
Returns:

Returns the out [x,y,z] vector array.

Type
Array.<number>

copy(out, pln) <static>

Copies the first four components of p to out.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [a,b,c,d] plane array to receive the result.
pln Array.<number>

The [a,b,c,d] plane array to copy from.
Returns:

Returns the modified out [a,b,c,d] plane array.

Type
Array.<number>

create( [a] [, b] [, c] [, d]) <static>

Creates a new [a,b,c,d] plane array with the given components.

The four (4) array entries represent components of the plane equation Ax + By + Cz + D = 0, where the first three (3) entries are also a [x,y,z] vector array representing the surface normal direction.

Parameters:
Name Type Argument Description
a number <optional>

The A (X-axis) component, or zero if not defined.
b number <optional>

The B (Y-axis) component, or zero if not defined.
c number <optional>

The C (Z-axis) component, or one if not defined.
d number <optional>

The D constant component, or zero if not defined.
Returns:

Returns a new [a,b,c,d] plane array.

Type
Array.<number>

distanceTo(plane, pt) <static>

Computes the signed distance from a 3D point to given plane.

Parameters:
Name Type Description
plane Array.<number>

The [a,b,c,d] plane array to test.
pt Array.<number>

The [x,y,z] vector array of the point.
Returns:

Returns the signed distance to the plane.

Type
number

inFront(plane, pt) <static>

Checks if a 3D points is on the same side of the given plane as its normal is pointing.

Parameters:
Name Type Description
plane Array.<number>

The [a,b,c,d] plane array to test.
pt Array.<number>

The [x,y,z] vector array of the point to check.
Returns:

Returns true if point is on same side of plane as its normal.

Type
boolean

intersectLine(out, p1, p2, plane [, min]) <static>

Calculates the intersection point of a line and plane.

This method calculates intersections beyond both ends of the line, not just inside it. If you want to only intersect in front of p1, set the min argument to 0. If you want to only intersect in front of p2, set the min argument to 1.

NOTE: If successful, this method changes values within the out parameter to the intersection point. Otherwise it sets it to the p1 position as this must lie directly on the plane.

Parameters:
Name Type Argument Description
out Array.<number>

The [x,y,z] vector array to receive the result.
p1 Array.<number>

The [x,y,z] vector array defining the line start position.
p2 Array.<number>

The [x,y,z] vector array defining the line end position.
plane Array.<number>

The [a,b,c,d] plane array to intersect the ray with.
min number <optional>

The minimum distance along the line, defaults to -Infinity.
Returns:

Returns the modified out [x,y,z] vector array.

Type
Array.<number>

intersectRay(out, rayPos, rayDir, plane [, min]) <static>

Calculates the intersection point of a ray and plane.

This method calculates intersections on both sides of the ray, not just in its direction of travel. If you want to only intersect in its direction of travel, set the min argument to 0.

NOTE: If successful, this method changes values within the out parameter to the intersection point. Otherwise it sets it to the ray origin position as that must lie directly on the plane.

Parameters:
Name Type Argument Description
out Array.<number>

The [x,y,z] vector array to receive the result.
rayPos Array.<number>

The [x,y,z] vector array giving the origin point of the ray.
rayDir Array.<number>

The [x,y,z] vector array giving the travel direction of the ray.
plane Array.<number>

The [a,b,c,d] plane array to intersect the ray with.
min number <optional>

The minimum distance along the ray, defaults to -Infinity.
Returns:

Returns the modified out [x,y,z] vector array.

Type
Array.<number>

intersectThreePlanes(out, plane1, plane2, plane3) <static>

Computes the point of intersection between three planes.

NOTE: If successful, this method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

An [x,y,z] vector array to receive the intersection point.
plane1 Array.<number>

The first [a,b,c,d] plane array to intersect.
plane2 Array.<number>

The second [a,b,c,d] plane array to intersect.
plane3 Array.<number>

The third [a,b,c,d] plane array to intersect.
Returns:

Returns true if a valid intersection point was found and copied to the out argument, otherwise false and out is not set.

Type
boolean

isOnSameSide(plane, p1, p2) <static>

Checks if two 3D points are on the same side of the given plane.

Parameters:
Name Type Description
plane Array.<number>

The [a,b,c,d] plane array to test.
p1 Array.<number>

The [x,y,z] vector array of the first point.
p2 Array.<number>

The [x,y,z] vector array of the second point.
Returns:

Returns true if both points are on same side of the plane.

Type
boolean

negate(out [, pln]) <static>

Reverses the sign of each component of a plane array.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as p or simply give one argument to change it in-place.

Parameters:
Name Type Argument Description
out Array.<number>

The [a,b,c,d] plane array to receive the result.
pln Array.<number> <optional>

The [a,b,c,d] plane array to negate, set to out if not supplied.
Returns:

Returns the modified out plane array.

Type
Array.<number>

projectPoint(out, plane, pt) <static>

Projects a point onto the given plane using its normal.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z] coordinate array to receive the result.
plane Array.<number>

The [a,b,c,d] plane array to project onto.
pt Array.<number>

The [x,y,z] coordinate array of the point to project.
Returns:

Returns the modified out [x,y,z] coordinate array.

Type
Array.<number>

set(out, a, b, c, d) <static>

Sets the [a,b,c,d] plane array to the given components.

This method offers some flexibility in terms of the arguments it accepts. You can provide 4 separate numeric values or just a single [a,b,c,d] plane array, a 4D point-like {x,y,z,w} object, or even no arguments at all to create a unit plane.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [a,b,c,d] plane array to receive the result.
a number

The A (X-axis) component, or zero if not defined.
b number

The B (Y-axis) component, or zero if not defined.
c number

The C (Z-axis) component, or one if not defined.
d number

The D constant component, or zero if not defined.
Returns:

Returns the resulting out [a,b,c,d] plane array.

Type
Array.<number>

setComponents(out, a, b, c, d) <static>

Sets the [a,b,c,d] plane array by its individual components.

This method differs from the set() method in that you must provide all 4 components as separate numeric values. It does not perform any type checking, which makes it a bit faster in situations where you can reliably provide the separate component values.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [a,b,c,d] plane array to receive the result.
a number

The A (X-axis) component, or zero if not defined.
b number

The B (Y-axis) component, or zero if not defined.
c number

The C (Z-axis) component, or one if not defined.
d number

The D constant component, or zero if not defined.
Returns:

Returns the resulting out [a,b,c,d] plane array.

Type
Array.<number>

setFromCoplanarPoints(out, v1, v2, v3) <static>

Computes the [a,b,c,d] plane array from three points that lie on the plane.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [a,b,c,d] plane array to set.
v1 Array.<number>

An [x,y,z] vector array defining the first point on the plane.
v2 Array.<number>

An [x,y,z] vector array defining the second point on the plane.
v3 Array.<number>

An [x,y,z] vector array defining the third point on the plane.
Returns:

Returns the given [a,b,c,d] plane array.

Type
Array.<number>

setFromNormalAndCoplanarPoint(out, normal, point) <static>

Computes the [a,b,c,d] plane array from with the given normal and passing through the given point.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [a,b,c,d] plane array to set.
normal Array.<number>

An [x,y,z] vector array defining the normal, which must be normalized.
point Array.<number>

An [x,y,z] vector array oa point that sits on the plane.
Returns:

Returns the given [a,b,c,d] plane array.

Type
Array.<number>