API Docs Class: Utils

new Utils()

Provides a set of generally useful tools and utilities for working with the framework and its classes.

Author:

drajmarsh

Members

:number DEG2RAD <static, constant>

The conversion factor for degrees to radians, being Math.PI / 180.

Type

number

:number EPSILON <static, constant>

A relatively small number used to define the threshold below which two values would be effectively considered the same for our needs.

Type

number

:number HALF_PI <static, constant>

Stores a quick reference to the value of Math.PI / 2.0.

Type

number

:number MAX_CHUNK_SIZE <static>

An arbitrary maximum size for pre-allocated array chunks.

Type

number

:THREE.Vector3 Neg_Z_Axis <static, constant>

Defines a vector in the negative Z axis ({0,0,-1}).

Type

THREE.Vector3

:THREE.Vector3 Origin <static, constant>

Defines the position of the global world origin.

Type

THREE.Vector3

:number QTR_PI <static, constant>

Stores a quick reference to the value of Math.PI / 4.0.

Type

number

:number RAD2DEG <static, constant>

The conversion factor for radians to degrees, being 180 / Math.PI.

Type

number

:number TWO_PI <static, constant>

Stores a quick reference to the value of Math.PI * 2.0.

Type

number

:THREE.Vector3 X_Axis <static, constant>

Defines a vector in the positive X axis ({1,0,0}).

Type

THREE.Vector3

:THREE.Vector3 Y_Axis <static, constant>

Defines a vector in the positive Y axis ({0,1,0}).

Type

THREE.Vector3

:THREE.Vector3 Z_Axis <static, constant>

Defines a vector in the positive Z axis ({0,0,1}).

Type

THREE.Vector3

:function nullFunction <static, constant>

Defines an empty function that does nothing and returns nothing.

This is typically used to nullify callbacks on objects just before they are disposed or detached, just in case they are shared somewhere.

Type

function

:function simpleHash <static>

Generates a simple string hash value from the given input.

Type

function

Methods

Base64_to_UTF8(str) <static>

Converts a Base64 encoded string to UTF8.

Parameters:

Name	Type	Description
`str`	string	The Base64 string to encode.

Returns:

Returns the UTF8 string.

Type: string

UTF8_to_Base64(str) <static>

Converts a UTF8 encoded string to Base64.

Parameters:

Name	Type	Description
`str`	string	The UTF8 string to encode.

Returns:

Returns the Base64 string.

Type: string

addCornerFilletToShape(shape, x1, y1, x2, y2, radius) <static>

A utility for adding rounded corners in a 2D shape path.

The arc() and ellipse()methods in theTHREE.Path` class are not that easy to use when trying to generate rounded corners between lines, as you have to already know the center, radius and angles of the required arc.

This method computes that information given two points new points and using the current position. The first of the two points define the corner that is to be filleted whilst the second point is the end of the line that follows the fillet. This needs two points in order to make the fillet tangential to both the incoming and outgoing lines, as shown in the illustration below.

  (x2,y2)     a2
     + - - - - x.__     + (x1,y1)
               .   ''-.
               .       \
               .        :
               +  -  -  x a1
            center      |
                        |
                        + (currentPosition)

This method first computes the center of the arc filleting arc, then determines the start and end points of the arc based on the current, path, and the next two. Once computed, it will call the arc() method and then the lineTo() method to add the arc to the shape.

Parameters:

Name	Type	Description
`shape`	THREE.Path	The path instance to add the arc to.
`x1`	number	The X-axis position of the filleted corner point.
`y1`	number	The Y-axis position of the filleted corner point.
`x2`	number	The X-axis position of the end line point.
`y2`	number	The Y-axis position of the end line point.
`radius`	number	The fillet radius for the corner.

Returns:

Returns true if the fillet was computed successfully, false if the lines are colinear or too short.

Type: boolean

addRandomness(out, factor) <static>

Applies the given randomisation factor to the given vector in each axis.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The 3D vector to add randomness to.
`factor`	number	The randomisation amount to apply in model units.

Returns:

Returns the modified out vector.

Type: Array

addToArray(value, item) <static>

Adds item to the given array if it does not already exist.

NOTE: This function uses array.indexOf() to check if the item already exists in the array. If not, it is added using the array.push() method.

Parameters:

Name	Type	Description
`value`	Array	The array to add the item to.
`item`	any	The item to add if not already in the array.

Returns:

Returns true if the item was added to the array, otherwise false.

Type: boolean

addToVector3(out, x, y, z) <static>

Adds x, y and z components to the given 3D vector.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The 3D vector to add components to.
`x`	number	The X-axis component to add.
`y`	number	The Y-axis component to add.
`z`	number	The Z-axis component to add.

Returns:

Returns the out 3D vector.

Type: boolean

angleBetweenPoints(p1, p2, p3) <static>

Computes the 3D angle between two lines that share a common point, in radians.

The angle is calculated by first normalising the vectors (p1 -> p2) and (p2 -> p3), where p2 is the shared point about which the angle is determined, and then using PD.Utils.angleBetweenVectors and returning the result.

                        p3     p1             p2
                        +       +---o--------+
                       /            : angle /
               ..--''-o              '._   /
             -'      /                  '-o
           .' angle /                    /
      +----o-------+                    +
     p1             p2                 p3

Parameters:

Name	Type	Description
`p1`	THREE.Vector3	The start coordinate on the angle line.
`p2`	THREE.Vector3	The middle coordinate on the angle line.
`p3`	THREE.Vector3	The end coordinate on the angle line.

Returns:

Returns the angle in radians.

Type: number

angleBetweenPointsXY(p1, p2, p3) <static>

Computes the 2D horizontal angle between two lines that share a common point, in radians.

                        p3     p1             p2
                        +       +---o--------+
                       /            : angle /
               ..--''-o              '._   /
             -'      /                  '-o
           .' angle /                    /
      +----o-------+                    +
     p1             p2                 p3

Parameters:

Name	Type	Description
`p1`	THREE.Vector3	The start coordinate on the angle line.
`p2`	THREE.Vector3	The middle coordinate on the angle line.
`p3`	THREE.Vector3	The end coordinate on the angle line.

Returns:

Returns the angle in radians.

Type: number

angleBetweenVectors(v1, v2) <static>

Computes the lesser angle between two normalised vectors, in radians.

                                   v1
                        +    +---o--------+
                       /         : angle /
               ..--''-o           '._   /
             -'      / v2            '-o v2
           .' angle /                 /
      +----o-------+                 +
            v1

Parameters:

Name	Type	Description
`v1`	THREE.Vector3	The incoming normalised direction vector.
`v2`	THREE.Vector3	The outgoing normalised direction vector.

Returns:

Returns a 3D angle in the range 0 to PI, in radians.

Type: number

applyMatrixToCoordArray(matrix, coord [, result]) <static>

Transforms an [x,y,z] coordinate array by the given matrix.

This method treats the array as a 3D position rather than a vector direction.

Parameters:

Name	Type	Argument	Description
`matrix`	THREE.Matrix4		The matrix to apply to the coordinate array.
`coord`	Array		The [x,y,z] coordinate array to transform.
`result`	Array	<optional>	An optional [x,y,z] coordinate array to receive the results.

Returns:

Returns the result array, of a new array containing the results.

Type: Array

applyNormalMatrixToVectorArray(matrix, vector [, result]) <static>

Transforms an [x,y,z] vector array by the given normal matrix.

This method treats the array as a vector direction rather than a 3D position.

Parameters:

Name	Type	Argument	Description
`matrix`	THREE.Matrix3		The normal matrix to apply to the vector array.
`vector`	Array		The [x,y,z] vector array to transform.
`result`	Array	<optional>	An optional [x,y,z] vector array to receive the results.

Returns:

Returns the result array, of a new array containing the results.

Type: Array

areaOfTriangle(p1, p2, p3) <static>

Calculate the area of a triangle joining the three given points.

Parameters:

Name	Type	Description
`p1`	THREE.Vector3	The first corner the triangle.
`p2`	THREE.Vector3	The second corner of the triangle.
`p3`	THREE.Vector3	The third corner of the triangle.

Returns:

Returns the surface area in model units.

Type: number

areaOfTriangleByDotProduct(p1, p2, p3) <static>

Calculate the area of a triangle joining the three given points.

Parameters:

Name	Type	Description
`p1`	THREE.Vector3	The first corner the triangle.
`p2`	THREE.Vector3	The second corner of the triangle.
`p3`	THREE.Vector3	The third corner of the triangle.

Returns:

Returns the surface area in model units.

Type: number

bisectorBetweenPoints(out, p1, p2, p3) <static>

Computes the bisecting vector between two lines that share a common point.

                        p3     p1             p2
          out           +       +---o--------+
            \_         /            :   _.-'/
              \_.--''-o             _.-'   /
             -' \_   / v2       out'    '-o
           .'     \ /                    /
      <----o-------+                    +
     p1             p2                 p3

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The 3D vector to add randomness to.
`p1`	THREE.Vector3	The start coordinate on the angle line.
`p2`	THREE.Vector3	The middle coordinate on the angle line.
`p3`	THREE.Vector3	The end coordinate on the angle line.

Returns:

Returns the calculated 'out' vector.

Type: number

ceilOrFloor(value) <static>

A replacement for Math.ceil() than handles negative numbers better.

This method basically applies the Math.floor() method to negative numbers and the Math.ceil() method to positive and zero. This is useful when using increment values where you want parity between positive and negative values. For example, just as a positive increment of 2.15 should round up to 3, a negative increment of -2.15 should round down to -3.

Parameters:

Name	Type	Description
`value`	number	The value to determine the floor/ceiling of.

Returns:

Returns the signed floor/ceiling of value.

Type: number

clockwiseWinding(v1, v2, v3, normal) <static>

Returns true if the three given points traverse in a clockwise direction on a plane with the given normal direction.

This basically approximates the direction of the cross-product.

Parameters:

Name	Type	Description
`v1`	THREE.Vector3	The first triangle vertex.
`v2`	THREE.Vector3	The second triangle vertex.
`v3`	THREE.Vector3	The third triangle vertex.
`normal`	THREE.Vector3	The plane normal to use.

Returns:

Returns true if the triangle winding is clockwise.

Type: boolean

closeTo(value, reference [, tolerance]) <static>

Determine if two numeric values are within the specified tolerance of each other.

Parameters:

Name	Type	Argument	Description
`value`	number		The value to test.
`reference`	number		The reference value to test against.
`tolerance`	number	<optional>	The amount above or below that is still considered close.

Returns:

Returns true if the two values are within threshold, else false.

Type: boolean

closeToDegrees(angle1, angle2 [, tolerance]) <static>

Determine if two degree angles are within the specified tolerance of each other.

Angles needs some additional tests as -180 == +180 and -270 == +90, etc.

Parameters:

Name	Type	Argument	Description
`angle1`	number		The first angle, in degrees.
`angle2`	number		The second angle, in degrees.
`tolerance`	number	<optional>	The amount above or below that is still considered close, defaults to 0.01deg.

Returns:

Returns true if the two values are within threshold, else false.

Type: boolean

closeToZero(value [, tolerance]) <static>

Returns true if the given value is within PD.Utils.EPSILON of zero.

Parameters:

Name	Type	Argument	Description
`value`	number		The value to check.
`tolerance`	number	<optional>	The amount above or below that is still considered close.

Returns:

Returns true if the given value is close to zero.

Type: boolean

closestAxialPointOnPlane(plane, point [, result]) <static>

Calculates the nearest axially aligned point on the plane to the given point.

This simply determines the three nearest points on the X, Y and Z axis respectively, and then returns the closest one.

Parameters:

Name	Type	Argument	Description
`plane`	THREE.Plane		The plane to project on to.
`point`	THREE.Vector3		The position to find the closest axial point.
`result`	THREE.Vector3	<optional>	The point to receive the new position.

Returns:

Returns true if a point was found and copied to result, or false if no intersections were found.

Type: boolean

closestPointOnLine(out, point, p1, p2) <static>

Calculates the point on a line that is closest to the given point.

This method will return the closest point on an infinite line defined by p1->p2. If you want to constrain the closest point to being between the two end points, then use the PD.Utils.closestPointOnLineSegment() method instead.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`point`	THREE.Vector3	The point to calculate the distance from.
`p1`	THREE.Vector3	The first point at the start of the line segment.
`p2`	THREE.Vector3	The second point at the end of the line segment.

Returns:

Returns the distance in model units.

Type: number

closestPointOnLineParameter(pt, p1, p2) <static>

Calculates where the closest point on a line sits relative to the given points.

The pt argument represents the 3D point to test relative to the line segment defined by p1->p2. If the closest point on the line lies somewhere between p1 and p2, the returned parameter value will be between 0 and 1. If it lies outside the line segment the returned value will be either negative or greater than 1, as shown in the explanatory diagram below.

 pt                     pt                     pt
  +                      +                    __+
  |\                    /|                 __/  |
  | \                  / |              __/     |
  |  \  >90           /  | <90       __/        |
  +   +--------+     +---+----+     +--------+  +
  :   p1      p2     p1  :   p2     p1      p2 1.2
-0.3  0        1     0  0.4   1     0        1

The return value can be considered as the fractional distance along the line segment, relative to the linear distance between p1 and p2.

Parameters:

Name	Type	Description
`pt`	THREE.Vector3	The point to calculate the distance from.
`p1`	THREE.Vector3	The first point at the start of the line segment.
`p2`	THREE.Vector3	The second point at the end of the line segment.

Returns:

Returns a fraction position parameter.

Type: number

closestPointOnLineParameterXY(pt, p1, p2) <static>

Calculates where the closest point on a line sits relative to the given points.

The pt argument represents the 3D point to test relative to the line segment defined by p1->p2 in the XY plane. If the closest point on the line lies somewhere between p1 and p2, the returned parameter value will be between 0 and 1. If it lies outside the line segment the returned value will be either negative or greater than 1, as shown in the explanatory diagram below.

 pt                     pt                     pt
  +                      +                    __+
  |\                    /|                 __/  |
  | \                  / |              __/     |
  |  \  >90           /  | <90       __/        |
  +   +--------+     +---+----+     +--------+  +
  :   p1      p2     p1  :   p2     p1      p2 1.2
-0.3  0        1     0  0.4   1     0        1

The return value can be considered as the fractional distance along the line segment in the XY plane, relative to the linear XY distance between p1 and p2.

Parameters:

Name	Type	Description
`pt`	THREE.Vector3	The point to calculate the distance from.
`p1`	THREE.Vector3	The first point at the start of the line segment.
`p2`	THREE.Vector3	The second point at the end of the line segment.

Returns:

Returns a fraction position parameter.

Type: number

closestPointOnLineSegment(out, point, p1, p2) <static>

Calculates a point on a line segment that is closest to the given point.

If the given point is outside the line segment, the closest point will be one of the two end points (p1 or p2). If you don't want to constrain the closest point to being between the two end points, then use the PD.Utils.closestPointOnLine() method instead.

NOTE: This method changes values within the out parameter. It returns a fraction from 0 to 1 if the given point is somewhere within the line segment, -1 if closest to the start point (p1) and 1 if closest to the end point (p2).

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`point`	THREE.Vector3	The point to calculate the closest point to.
`p1`	THREE.Vector3	The first point at the start of the line segment.
`p2`	THREE.Vector3	The second point at the end of the line segment.

Returns:

Returns -1, 0 or 1 as described above.

Type: number

closestPointOnVector(out, point, origin, direction) <static>

Calculates a point along the given vector that is closest to the given point.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`point`	THREE.Vector3	The point to find the closest for.
`origin`	THREE.Vector3	The starting point of the vector ray.
`direction`	THREE.Vector3	The normalised direction vector (length = 1.0).

Returns:

Returns the resulting out vector.

Type: THREE.Vector3

colorScaleEcotect(fraction [, result]) <static>

Generates an Ecotect-themed color scale.

Parameters:

Name	Type	Argument	Description
`fraction`	number		A fractional scale value (0 to 1).
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

colorScaleRainbow(fraction [, result]) <static>

Generates a rainbow color scale.

Parameters:

Name	Type	Argument	Description
`fraction`	number		A fractional scale value (0 to 1).
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

colorScaleRainbowArray(fraction [, result]) <static>

Generates a rainbow color scale.

Parameters:

Name	Type	Argument	Description
`fraction`	number		A fractional scale value (0 to 1).
`result`	Array	<optional> <nullable>	An optional color array to store the result in.

Returns:

Returns the given color or a newly generated one.

Type: Array

colorScaleRedWhiteBlue(fraction [, result]) <static>

Generates a thermal color scale from blue(0) to white(0.5) to red(1).

Parameters:

Name	Type	Argument	Description
`fraction`	number		A fractional scale value (0 to 1).
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

colorScaleSepia(fraction [, result]) <static>

Generates a sepia color scale.

Parameters:

Name	Type	Argument	Description
`fraction`	number		A fractional scale value (0 to 1).
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

computeAverageBoxDimension(box) <static>

Computes the average size of each dimensions.

Parameters:

Name	Type	Description
`box`	THREE.Box3	The bounding box to get the size of.

Returns:

Returns the average dimension.

Type: number

computeBoxCorner(box, index [, result]) <static>

Sets the given vector to one of the 8 major corners of the given box.

You can also compute the center point of any edge by using and index between the range 8 and 19, as shown in the schematic below.

    +Z                max
     |   7-----18-----6
     |  /|   +Y      /|
     | 19|   /     17 |
     |/ 15  /      /  14
     4-----/16----5   |
     |   |/ -1+   |   |
     |   3-----10-|---2
    12  /         13 /
     | 11         | 9
     |/           |/
     0------8-----1-----+X
   min

Parameters:

Name	Type	Argument	Description
`box`	THREE.Box3		The bounding box to obtain corners from.
`index`	number		The numerical index of the corner (0 to 7), or -1 for the center.
`result`	THREE.Vector3	<optional>	An optional vector object to receive the corner.

Returns:

Returns either the given vector or a new one.

Type: THREE.Vector3

computeBoxPosition(box, align [, result]) <static>

Aligns a point within the given box.

Parameters:

Name	Type	Argument	Description
`box`	THREE.Box3		The bounding box to align the point within.
`align`	PD.ALIGN		The alignment of the point within the bounding box.
`result`	THREE.Vector3	<optional>	An optional vector object to receive the new position.

Returns:

Returns either the given vector or a new one.

Type: THREE.Vector3

computeCenterOfCircleFrom3Pts(out, p1, p2, p3 [, axis]) <static>

Computes the center of a circle passing through three points.

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

Parameters:

Name	Type	Argument	Description
`out`	THREE.Vector3		The vector to receive the center position.
`p1`	THREE.Vector3		The first point on the circle.
`p2`	THREE.Vector3		The second point on the circle.
`p3`	THREE.Vector3		The third point on the circle.
`axis`	THREE.Vector3	<optional>	An optional vector to receive the axis vector.

Returns:

Returns true if the out parameter was set, or false.

Type: boolean

computeIncrementValue(direction, key, step, minor, major, isLarge [, largeIncr]) <static>

Computes an increment value for the given parameter data.

This method is used internally by several numeric and color increment methods.

Parameters:

Name	Type	Argument	Description
`direction`	number		1 for increment, -1 for decrement.
`key`	PD.KEY \| WheelEvent		A scroll wheel event or current Control/Shift/Alt key status.
`step`	number		The smallest allowable increment value.
`minor`	number		The typical increment value.
`major`	number		The large increment value.
`isLarge`	number		Whether to use the large increment by default.
`largeIncr`	number	<optional>	If both Shift key and isLarge are set, multiply by this value, defaults to 5.

Returns:

Returns the increment/snap value.

Type: number

computeMajorAxis(normal) <static>

Determines the axis of maximum distance (±1:X, ±2:±Y, ±3:±Z).

Assumes that the given vector is a direction rather than a 3D coordinate.

Parameters:

Name	Type	Description
`normal`	THREE.Vector3	The direction vector to test.

Returns:

Returns the appropriate axis (±1:X, ±2:±Y, ±3:±Z).

Type: PD.AXIS

computeNormalFrom3Pts(out, p1, p2, p3) <static>

Computes the surface normal of a triangle from three points.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the normal.
`p1`	THREE.Vector3	The first point in the triangle.
`p2`	THREE.Vector3	The second point in the triangle.
`p3`	THREE.Vector3	The third point in the triangle.

Returns:

Returns the updated out parameter.

Type: THREE.Vector3

computeNormalFromContour(out, contour) <static>

Calculates the surface normal of the given series of connected points.

This method computes the average normal of all points in the list using Newell's Method.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the normal.
`contour`	Array.<THREE.Vector3>	An ordered series of contour vertices.

Returns:

Returns the updated out parameter.

Type: THREE.Vector3

computeNormalInXY(out, p1, p2) <static>

Computes the normal of a horizontal line between two points.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the normal.
`p1`	THREE.Vector3	The first point on the line.
`p2`	THREE.Vector3	The second point on the line.

Returns:

Returns the updated out parameter.

Type: THREE.Vector3

computePlaneBisectingCorner(v1, v2, v3) <static>

Calculates a plane equation that bisects the two line segments travelling from v1 through v2 to v3.

The surface normal of the resulting plane will be the tangent at the corner and runs parallel to the bisecting line.

                           v3
                           .^
                     .  '   |
                  .         |
               A        . - |           normal
            .   \_  . '     |         (tangent)
                 .\__  a    |        __/
        .      .     \_     |     __/
             .     a   \__  |  __/
      .     .             \_|_/
     v1 >-------------------+_v2
                              \__
                                 \_
                                   \__
                                    plane

Parameters:

Name	Type	Description
`v1`	THREE.Vector3	The first point on the line.
`v2`	THREE.Vector3	The second point on the line.
`v3`	THREE.Vector3	The third point on the line.

Returns:

Returns a shared plane instance.

Type: THREE.Plane

computePlaneFrom3Pts(p1, p2, p3) <static>

Calculates a plane equation given a triangle of three points.

Parameters:

Name	Type	Description
`p1`	THREE.Vector3	The first point in the triangle.
`p2`	THREE.Vector3	The second point in the triangle.
`p3`	THREE.Vector3	The third point in the triangle.

Returns:

Returns a shared plane instance.

Type: THREE.Plane

computePlaneFromAxisAndOffset( [axis] [, offset]) <static>

Calculates a plane equation given a cartesian axis and offset distance.

Parameters:

Name	Type	Argument	Description
`axis`	PD.AXIS	<optional>	The axis to use as the plane normal, defaults to XY plane.
`offset`	number	<optional>	The offset distance from origin in given axis, defaults to 0.

Returns:

Returns a shared plane instance.

Type: THREE.Plane

computePlaneFromNormalAndOffset(normal, offset) <static>

Calculates a plane equation given a normal and offset distance.

Parameters:

Name	Type	Description
`normal`	THREE.Vector3	The normal vector of the plane.
`offset`	number	The offset distance from origin to the plane.

Returns:

Returns a shared plane instance.

Type: THREE.Plane

computePlaneFromNormalAndPoint(normal [, pos] [, vertical]) <static>

Calculates a plane equation given a normal direction and 3D position.

Parameters:

Name	Type	Argument	Description
`normal`	THREE.Vector3		The plane normal vector direction.
`pos`	THREE.Vector3	<optional>	A point on the plane, defaults to the origin.
`vertical`	boolean	<optional>	Whether or not to keep the plane vertical (dz = 0).

Returns:

Returns a shared plane instance.

Type: THREE.Plane

computePlaneFromUV(u_vec, v_vec [, pos]) <static>

Calculates a plane equation given the relative X (U) and Y (V) axis and an optional 3D model position it passes through.

Parameters:

Name	Type	Argument	Description
`u_vec`	THREE.Vector3		The relative vector in the U axis.
`v_vec`	THREE.Vector3		The relative vector in the V axis.
`pos`	THREE.Vector3	<optional>	A point on the plane, defaults to the origin.

Returns:

Returns a shared plane instance.

Type: THREE.Plane

computePlaneNormalToLine(v1, v2 [, vertical]) <static>

Calculates a plane equation that passes through v2 with a normal in the direction of the line v1 to v2.

                      plane
                         \  |
      Z                   : |           normal (vertical == false)
      ^                    \|   _ . - '
      :                 _..-+v2 - - - > normal (vertical == true)
      :          _..--''    |\
      :   _..--''           | :
    v1+-''  - - - > X       |  \
                          plane
                        (vertical)

Parameters:

Name	Type	Argument	Description
`v1`	THREE.Vector3		The first point on the line.
`v2`	THREE.Vector3		The second point on the line.
`vertical`	boolean	<optional>	Whether or not to keep the plane vertical (dz = 0).

Returns:

Returns a shared plane instance.

Type: THREE.Plane

computePlaneParallelToLine(v1, v2 [, up]) <static>

Calculates a plane equation parallel to the line v1 to v2.

The surface normal of the plane is computed from the cross-product of the line and up vectors.

Parameters:

Name	Type	Argument	Description
`v1`	THREE.Vector3		The first point on the line.
`v2`	THREE.Vector3		The second point on the line.
`up`	boolean	<optional>	The direction vector of up, defaults to +Z axis.

Returns:

Returns a shared plane instance.

Type: THREE.Plane

computeQuadrant(ref_pt, test_pt) <static>

Calculates the quadrant of the test point relative to the reference point.

Parameters:

Name	Type	Description
`ref_pt`	THREE.Vector3	The reference point for the quadrant.
`test_pt`	THREE.Vector3	The point to determine which quadrant its it.

Returns:

Returns TOP_RIGHT, TOP_LEFT, BOT_RIGHT or BOT_LEFT.

Type: PD.ALIGN

computeShadowLengthFromVector(vector) <static>

Calculates an additional frustum or area extension due at low angle.

Parameters:

Name	Type	Description
`vector`	THREE.Vector	The shadow direction vector.

Returns:

Returns a shadow length modifier.

Type: number

computeTickIncrement(range, max_ticks) <static>

Calculates a reasonable tick increment for the given range.

In this context, a tick is effectively a smaller interval that can be used to divide the given range. This is typically used for charts and graphs to display a reasonable number of ticks or values along an axis.

Parameters:

Name	Type	Description
`range`	number	The overall range of values (max - min).
`max_ticks`	number	The maximum number of allowable ticks, defaults to 20.

Returns:

Returns a tick increment value.

Type: number

concaveHullXY(points, concavity, lengthThreshold) <static>

Calculates the concave hull of an array of points in the XY plane.

NOTE: This method uses vector objects in the form {x,y[,z]}, such as THREE.Vector3, THREE.Vector2 or PD.Point object. If you need to process an array of [x,y[,z]] vector arrays, use the PD.VectorArray.concaveHullXY method instead.

The concavity arguments is a relative measure of concavity, where a value of 1.0 results in a relatively detailed shape, and Infinity results in a convex hull. You can use values lower than 1, but they can produce pretty crazy shapes.

When a segment length is less than lengthThreshold, it stops being considered for further processing. Higher values result in a simpler shape.

The return value is an ordered array of points that define the line of the concave hull around the point cloud.

This uses concaveman (https://github.com/mapbox/concaveman), a fast algorithm for finding concave and convex hulls in 2D points.

Parameters:

Name	Type	Description
`points`	Array.<THREE.Vector3>	An array of vectors.
`concavity`	number	A relative measure of concavity, defaults to 1.0.
`lengthThreshold`	number	The minimum point radius to consider.

Returns:

Returns an array of vectors defining the concave hull.

Type: Array.<THREE.Vector3>

constrainTo(value, range1, range2) <static>

Clamps the given value to the given range.

NOTE: In this function, the minimum/maximum allowable values are automatically calculated from the two given range values. This means that range1 can be greater than, equal to or less than range2.

Parameters:

Name	Type	Description
`value`	number	The value to trim within the range.
`range1`	number	The first value in the allowable range.
`range2`	number	The second value in the allowable range.

Returns:

Returns a value between min and max, inclusive.

Type: number

convertMapToJSON(map [, ignore]) <static>

Converts a Map to a simple POJO for conversion to JSON.

NOTE: This method assumes that any key name that starts with a $ char is for internal use only and will not include them in the conversion.

Parameters:

Name	Type	Argument	Description
`map`	Map		A Javascript Map containing data.
`ignore`	Array	<optional>	An optional array of items to ignore.

Returns:

Returns a Plain Old Javascript Object (POJO).

Type: object

convertToString(thing) <static>

Converts the given argument to a string, even if it is an array.

Parameters:

Name	Type	Description
`thing`	string \| Array.<string>	A single or multi-line string to convert.

Returns:

Returns the argument as a joined string.

Type: string

copyBox3(from [, to]) <static>

Copies extents data from a source object to a THREE.Box3.

This method is required to handle different types of user input values, such as simple [min_x,min_y,min_z,max_x,max_y,max_z] arrays, [[min_x,min_y,min_z],[max_x,max_y,max_z]] arrays, {min:{x,y,z},max:{x,y,z}} objects or similar.

Parameters:

Name	Type	Argument	Description
`from`	THREE.Box3 \| Array.<number>		The array/object to copy from.
`to`	THREE.Box3	<optional>	An optional `THREE.Box3` to copy the data to.

Returns:

Returns the extents, or a newly created one.

Type: THREE.Box3

copyColor(from [, to]) <static>

Copies color data from an array/object to a THREE.Color.

This method extends THREE.Color.set() to handle more types of color input values, such as hex numbers (0x2b362), CSS strings ('#ffc49c'), simple arrays ([r,g,b]) and any type of {r,g,b} objects.

Parameters:

Name	Type	Argument	Description
`from`	number \| string \| Array.<number> \| THREE.Color		The color number/string/array/object to copy from.
`to`	THREE.Color	<optional>	An optional `THREE.Color` to copy the data to.

Returns:

Returns the to color, or a newly created one.

Type: THREE.Color

copyMap(data [, map]) <static>

Copies data from a source object/map to a Map, with string-based keys.

NOTE: This method assumes that any key name that startswith a $ char is for internal use only and will not copy them.

Parameters:

Name	Type	Argument	Description
`data`	Map \| object		The Javascript Map or object to copy from.
`map`	Map	<optional>	An optional Javascript Map to copy the data to.

Returns:

Returns the destination Map, or a newly created one.

Type: Map

copyMap(data [, map]) <static>

Copies data from a source object/map to a Map, with string-based keys.

NOTE: This method assumes that any key name that startswith a $ char is for internal use only and will not copy them.

Parameters:

Name	Type	Argument	Description
`data`	Map \| object		The Javascript Map or object to copy from.
`map`	Map	<optional>	An optional Javascript Map to copy the data to.

Returns:

Returns the destination Map, or a newly created one.

Type: Map

copyMatrix3(from [, to]) <static>

Copies data from an array/object to a THREE.Matrix3.

This method is required to handle different types of user input values, such as simple [0..8] arrays, { elements: [0-8] } objects or similar.

Parameters:

Name	Type	Argument	Description
`from`	THREE.Matrix3 \| Array.<number>		The array/object to copy from.
`to`	THREE.Matrix3	<optional>	An optional `THREE.Matrix3` to copy the data to.

Returns:

Returns the matrix, or a newly created one.

Type: THREE.Matrix3

copyMatrix4(from [, to]) <static>

Copies data from an array/object to a THREE.Matrix4.

This method is required to handle different types of user input values, such as simple [0..15] arrays, { elements: [0-15] } objects or similar.

Parameters:

Name	Type	Argument	Description
`from`	THREE.Matrix4 \| Array.<number>		The array/object to copy from.
`to`	THREE.Matrix4	<optional>	An optional `THREE.Matrix4` to copy the data to.

Returns:

Returns the matrix, or a newly created one.

Type: THREE.Matrix4

copyPlane(from [, to]) <static>

Copies plane data from a source object to a THREE.Plane.

This method is required to handle different types of user input values, such as simple [A,B,C,D] plane equation arrays, [[x,y,z],c] arrays, {min:{x,y,z},c:number} objects or similar.

Parameters:

Name	Type	Argument	Description
`from`	THREE.Plane \| Array.<number>		The array/object to copy from.
`to`	THREE.Plane	<optional>	An optional `THREE.Plane` to copy the data to.

Returns:

Returns the plane, or a newly created one.

Type: THREE.Plane

copyQuaternion(from [, to]) <static>

Copies data from an array/object to a THREE.Quaternion.

This method is required to handle different types of user input values, such as simple [x,y,z,w] arrays, {x,y,z,w} objects or similar.

Parameters:

Name	Type	Argument	Description
`from`	THREE.Quaternion \| Array.<number>		The array/object to copy from.
`to`	THREE.Quaternion	<optional>	An optional `THREE.Quaternion` to copy the data to.

Returns:

Returns the quaternion, or a newly created one.

Type: THREE.Quaternion

copyVector2(from [, to]) <static>

Copies data from an array/object to a THREE.Vector2.

This method is required to handle different types of user input values, such as simple [x,y] arrays, {x,y} objects or similar.

Parameters:

Name	Type	Argument	Description
`from`	THREE.Vector2 \| Array.<number>		The array/object to copy from.
`to`	THREE.Vector2	<optional>	An optional `THREE.Vector2` to copy the data to.

Returns:

Returns the vector, or a newly created one.

Type: THREE.Vector2

copyVector3(from [, to]) <static>

Copies data from an array/object to a THREE.Vector3.

This method is required to handle different types of user input values, such as simple [x,y,z] arrays, {x,y,z} objects or similar.

Parameters:

Name	Type	Argument	Description
`from`	THREE.Vector3 \| Array.<number>		The array/object to copy from.
`to`	THREE.Vector3	<optional>	An optional `THREE.Vector3` to copy the data to.

Returns:

Returns the vector, or a newly created one.

Type: THREE.Vector3

copyVector4(from [, to]) <static>

Copies data from an array/object to a THREE.Vector4.

This method is required to handle different types of user input values, such as simple [x,y,z,w] arrays, {x,y,z,w} objects or similar.

Parameters:

Name	Type	Argument	Description
`from`	THREE.Vector4 \| Array.<number>		The array/object to copy from.
`to`	THREE.Vector4	<optional>	An optional `THREE.Vector4` to copy the data to.

Returns:

Returns the vector, or a newly created one.

Type: THREE.Vector4

copyVectorXY(out, from) <static>

Copies the X and Y components of a 3D vector.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`from`	THREE.Vector3	The vector to copy from.

Returns:

Returns the resulting out vector.

Type: THREE.Vector3

cosDegrees(degrees) <static>

Determines Math.cos() based on an angle given in decimal degrees.

Parameters:

Name	Type	Description
`degrees`	number	The required angle in decimal degrees.

Returns:

Returns the trigonometric cosine of the given angle.

Type: number

degToRad() <static>

Returns the value converted from degrees to radians.

Returns:

Returns the converted value in radians.

Type: number

disposeObject(obj) <static>

Recursively releases the resources of a THREE object or mesh.

Parameters:

Name	Type	Description
`obj`	THREE.Object3D	The THREE object to dispose of.

distanceInVectorDirection(from, direction, to) <static>

Calculates the signed distance between two 3D points along a given vector.

This method is used when dragging something that is restricted to a given vector. It uses the dot product to determine the positive or negative distance of the closest point between the given 3D position and the ray.

Parameters:

Name	Type	Description
`from`	THREE.Vector3	The reference position to calculate the distance from.
`direction`	THREE.Vector3	The direction vector to measure against, which does not have to be normalized.
`to`	THREE.Vector3	The point to check the distance of.

Returns:

Returns the distance in the direction of the given vector.

Type: number

distanceInVectorDirectionXY(from, direction, to) <static>

Calculates the signed distance in the XY plane between two points on a given vector.

Parameters:

Name	Type	Description
`from`	THREE.Vector3	The reference position to calculate the distance from.
`direction`	THREE.Vector3	The direction vector to measure against, which does not have to be normalized.
`to`	THREE.Vector3	The point to check the distance of.

Returns:

Returns the distance in the direction of the given vector.

Type: number

distancePointToLine(pt, p1, p2 [, closest_pt]) <static>

Calculate the perpendicular distance from pt to the 3D line p1->p2.

This method differs from distancePointToLineSegment() in that it considers the line to be continuous, with p1 and p2 just points somewhere along the line rather than end points.

NOTE: This method will change values within the closest_pt parameter if it is given.

Parameters:

Name	Type	Argument	Description
`pt`	THREE.Vector3		The point to calculate the distance from.
`p1`	THREE.Vector3		The first point on the line.
`p2`	THREE.Vector3		The second point on the line.
`closest_pt`	THREE.Vector3	<optional>	An optional point to be set to the closest point to the line.

Returns:

Returns the distance in model units.

Type: number

distancePointToLineSegment(pt, p1, p2 [, closest_pt]) <static>

Calculate the perpendicular distance from pt to the 3D line segment p1->p2.

If the perpendicular to the given point is outside the line segment, the distance to the closest end point will be returned.

NOTE: This method will change values within the closest_pt parameter if it is given.

Parameters:

Name	Type	Argument	Description
`pt`	THREE.Vector3		The point to calculate the distance from.
`p1`	THREE.Vector3		The first point at the start of the line segment.
`p2`	THREE.Vector3		The second point at the end of the line segment.
`closest_pt`	THREE.Vector3	<optional>	An optional point to be set to the closest point to the line segment.

Returns:

Returns the distance in model units.

Type: number

distancePointToLineSegmentXY(pt, p1, p2 [, closest_pt]) <static>

Calculate the perpendicular distance in the XY plane from pt to the line segment p1->p2.

If the perpendicular to the given point is outside the line segment, the distance to the closest end point will be returned.

Parameters:

Name	Type	Argument	Description
`pt`	THREE.Vector3		The point to calculate the distance from.
`p1`	THREE.Vector3		The first point at the start of the line segment.
`p2`	THREE.Vector3		The second point at the end of the line segment.
`closest_pt`	THREE.Vector3	<optional>	An optional point to be set to the closest point to the line segment.

Returns:

Returns the XY distance in model units.

Type: number

distanceToXY(from, to) <static>

Calculates the distance between two 3D points only in the XY plane.

Parameters:

Name	Type	Description
`from`	THREE.Vector3	The point to calculate distance from.
`to`	THREE.Vector3	The point to check the distance to.

Returns:

Returns the distance in the XY plane.

Type: number

endsWith(haystack, needle) <static>

Determines if a string ends with the given string.

Parameters:

Name	Type	Description
`haystack`	string	The larger string to be checked.
`needle`	string	The smaller string to use for checking.

Returns:

Returns true if 'haystack' ends with the exact same characters as 'needle'.

Type: boolean

expandBoxByRadius(box, radius) <static>

Expands the given box by a radius from its center.

Parameters:

Name	Type	Description
`box`	THREE.Box3	The bounding box to expand.
`radius`	number	The radius from the box center.

Returns:

Returns given bounding box.

Type: THREE.Box3

expandBoxXY(box, xy [, z]) <static>

Expands the given box in the XY axis by a radius from its center.

Parameters:

Name	Type	Argument	Description
`box`	THREE.Box3		The bounding box to expand.
`xy`	number		The horizontal radius from the box center.
`z`	number	<optional>	The vertical radius from the box center.

Returns:

Returns given bounding box.

Type: THREE.Box3

extendContour(contour, distanceStart [, distanceEnd]) <static>

Extends the start and end segments of a contour by the given distance(s).

This method extrapolates the start and end points of an open contour by the given distance(s).

Parameters:

Name	Type	Argument	Description
`contour`	Array.<THREE.Vector3>		An ordered series of contour vertices.
`distanceStart`	number		The extension to add at the start of the contour.
`distanceEnd`	number	<optional>	The extension to add at the end of the contour, defaults to `distanceStart`.

Returns:

Returns the extended contour.

Type: Array.<THREE.Vector3>

formatFeetAndInches(mm) <static>

Generates an imperial string representation of the given dimension in millimetres.

Parameters:

Name	Type	Description
`mm`	number	The dimension in millimetres.

Returns:

Returns a feet and inches string.

Type: string

formatInBytes(bytes) <static>

Formats a number of bytes into a human-readable string.

This method uses the shortenBytes() function to convert the number of bytes into a more readable format, such as "157Bytes", "1.52KB", "2.31MB", etc.

Parameters:

Name	Type	Description
`bytes`	number	The number of bytes to format.

Returns:

Returns a string representation of the size in bytes.

Type: string

formatInFractionsOfAnInch(mm) <static>

Generates an imperial string representation of the given very small dimension in millimetres.

Parameters:

Name	Type	Description
`mm`	number	The dimension in millimetres.

Returns:

Returns a string in 1/16, 1/32 or 1.64 of an inch.

Type: string

formatNumberAsOrdinal(value) <static>

Formats a value as an ordinal string, such as 1st, 2nd, 3rd, etc.

Parameters:

Name	Type	Description
`value`	number	The value to get the ordinal of.

Returns:

Returns a string formatted with the given precision.

Type: string

fromXML(xmlDoc) <static>

Recursively converts an XML document into a simple JSON-based object.

Parameters:

Name	Type	Description
`xmlDoc`	XMLDocument	An XML document obtained from 'DOMParser().parseFromString()'.

Returns:

Returns a JSON-based object.

Type: object

generateSinCosLookUpTable(increments) <static>

Create a look-up table of [sin,cos] array values.

The number of entries in the table will equal increments+1 as the first entry in the table is repeated at the end to make it easier to close the circular loop.

Parameters:

Name	Type	Description
`increments`	number	The number of circular increments in table (3 to 360).

Returns:

Returns an array if [sin,cos] values for a unit circle.

Type: Array.<Array.<number>>

getBoxHeight(box) <static>

Calculates the height in the Z axis of the given box.

This is simply the difference between the maximum and minimum Z values, clamped to a minimum of 0.

Parameters:

Name	Type	Description
`box`	THREE.Box3	The bounding box to compute the height of.

Returns:

Returns the height of the box.

Type: number

getCosLookUpTable_15deg() <static>

Returns a look up table cosine values in 15 degree increments over 180 degrees.

The returned table has 13 values, inclusive of 180deg.

Returns:

Type: Array.<number>

getFileExtension(filename) <static>

Extracts the file extension from a given filename.

This method returns the file extension with the leading dot. For example, given the filename document.pdf, it will return .pdf. If the filename does not have an extension, it returns an empty string.

Parameters:

Name	Type	Description
`filename`	string	The name of the file to extract the file extension from.

Returns:

Returns the file extension or an empty string if none exists.

Type: string

getNestedProperty(host, path [, defaultValue]) <static>

Retrieve the value of a nested property on a host object using a string path.

A nested property is one where the path contains one or more period ('.') characters that separate it into a hierarchy of parent/child objects. If the path does not contain a period, then the whole string is treated as a field name on the host object.

As objects and arrays in JavaScript behave in some ways similar, you can use nested properties to access array entries by simply using a number as the field name to represent the ordinal index you want.

Parameters:

Name	Type	Argument	Description
`host`	object		The object containing the nested properties.
`path`	string		A string containing dot-separated properties.
`defaultValue`	any	<optional> <nullable>	The value to return if the property path does not exist, defaults to `undefined`.

Returns:

Returns the property value or undefined if the path does not resolve to a valid property.

Type: any

getSinLookUpTable_15deg() <static>

Returns a look up table sine values in 15 degree increments over 180 degrees.

The returned table has 13 values, inclusive of 180deg.

Returns:

Type: Array.<number>

getSphericalCoordinatesFromPoints(from, to) <static>

Calculates the distance, azimuth and altitude angle between the given two points and returns an [azi,alt,radius] array.

The azimuth angle is returned in radians CCW from the +X axis, and the altitude angle is in radians above the horizontal. The radius is set to the distance between the two points.

Parameters:

Name	Type	Description
`from`	THREE.Vector3	The reference point.
`to`	THREE.Vector3	The target point.

Returns:

Returns the spherical angles as a [azi,alt,radius] array, with angles in radians.

Type: Array

getUniqueId() <static>

Utility function to generate a consecutive but unique numeric id value.

Returns:

Returns a unique number incremented on each call.

Type: number

getUniqueIdAsString( [id]) <static>

Utility function to generate a formatted string from a numeric id value.

If this method is called without an argument (or the optional argument is zero, null or undefined), a new unique numeric id value will be generated. It uses the id value to generate a left padded string of at least four (4) characters.

Parameters:

Name	Type	Argument	Description
`id`	number	<optional>	The numeric id value to format, defaults to a new unique value if zero, null or undefined.

Returns:

Returns the numeric id formatted to string of at least four characters.

Type: string

getUniqueIdForDOM( [prefix]) <static>

Utility function to generate consecutive but unique DOM id values.

This method generates a string identifier that is unique to the current web page session and can be used for the id attribute of HTML tags. It generates a string value in the form pd-dom-id-XXXX, where XXXX is a four digit number (left padded with zeros) that is incremented on each call.

Parameters:

Name	Type	Argument	Description
`prefix`	string	<optional> <nullable>	An optional prefix to use, defaults to 'pd-dom-id'.

Returns:

Returns a unique DOM identifier string.

Type: string

imperialOrMetric(inches [, mm]) <static>

Returns either the imperial or metric value based on the current value of PD.DIMENSION.units.

This method allows you to initialise standard items such as bench heights, shelf depths, wall widths and grid sizes with values that are relevant to the current model units and will snap appropriately to reasonable dimensions - for example: inches in imperial and 25mm or 50mm in metric.

This method exists because the dimensions of many things are often still given in inches to be compatible with US measurements, but rounded to the nearest 50 or 100 in regions that use in metric units. Thus, rather that have all sorts of tests for imperial units dotted throughout your code, you can simply use this method and solve many of these issues.

If PD.DIMENSION.units are imperial, the first argument given in inches will be converted directly to millimetres and returned. If the current model units are metric, the second argument given in millimetres will be returned.

If there is no second argument, the given number of inches in the the first argument will be multiplied by 25 to give a reasonably rounded metric value (NOT 25.4).

The term 'reasonably' is based on the fact that, if light switches are installed 48" (1,219.2mm) above the floor in the US, this is almost invariably going to be 1200mm in countries that use metric units (as opposed to just rounding it to 1220mm). Similarly, a 600mm bench depth is almost invariably going to be 2' (609.6mm) in the US (as opposed to 2' 3/8").

This way, the dimensions of models created using imperial units will snap nicely to the nearest inch, and models created in metric units will snap nicely to the nearest 25, 50 and 100mm. Obviously if you create half the model using imperial units and the other half using metric units, you can't expect your model to land very gently on whatever planet you send it to https://www.simscale.com/blog/2017/12/nasa-mars-climate-orbiter-metric/.

Parameters:

Name	Type	Argument	Description
`inches`	number		The number of inches to use if imperial.
`mm`	number	<optional>	The number of millimetres to use if metric, defaults to `inches * 25`.

Returns:

Returns a moderated value in millimetres.

Type: number

Example

/// Instead of this...
const defaultSlabDepth = PD.DIMENSION.useImperial ? 203.2 : 200.0; // 8".

/// ...you can do this to do exactly the same thing.
const defaultSlabDepth = PD.Utils.imperialOrMetric(8, 200);

/// Or this to, again, do exactly the same thing.
const defaultSlabDepth = PD.Utils.imperialOrMetric(8);

incrementHex_Hue(hex, direction, key, step, minor, major, isLarge [, largeIncr]) <static>

Increments the hue of a hexadecimal color number given a range of parameters.

Parameters:

Name	Type	Argument	Description
`hex`	number		The hexadecimal color to increment.
`direction`	number		1 for increment, -1 for decrement.
`key`	PD.KEY		The current Control/Shift/Alt key status.
`step`	number		The smallest allowable increment value.
`minor`	number		The typical increment value.
`major`	number		The large increment value.
`isLarge`	number		Whether to use the large increment by default.
`largeIncr`	number	<optional>	If both Shift key and isLarge are set, multiply by this value, defaults to 5.

Returns:

Returns the incremented value.

Type: number

incrementHex_Lightness(hex, direction, key, step, minor, major, isLarge [, largeIncr]) <static>

Increments the lightness of a hexadecimal color given a range of parameters.

Parameters:

Name	Type	Argument	Description
`hex`	number		The hexadecimal color to increment.
`direction`	number		1 for increment, -1 for decrement.
`key`	PD.KEY		The current Control/Shift/Alt key status.
`step`	number		The smallest allowable increment value.
`minor`	number		The typical increment value.
`major`	number		The large increment value.
`isLarge`	number		Whether to use the large increment by default.
`largeIncr`	number	<optional>	If both Shift key and isLarge are set, multiply by this value, defaults to 5.

Returns:

Returns the incremented value.

Type: number

incrementHex_Saturation(hex, direction, key, step, minor, major, isLarge [, largeIncr]) <static>

Increments the saturation of a hexadecimal color given a range of parameters.

Parameters:

Name	Type	Argument	Description
`hex`	number		The hexadecimal color to increment.
`direction`	number		1 for increment, -1 for decrement.
`key`	PD.KEY		The current Control/Shift/Alt key status.
`step`	number		The smallest allowable increment value.
`minor`	number		The typical increment value.
`major`	number		The large increment value.
`isLarge`	number		Whether to use the large increment by default.
`largeIncr`	number	<optional>	If both Shift key and isLarge are set, multiply by this value, defaults to 5.

Returns:

Returns the incremented value.

Type: number

incrementNumber(value, direction, key, step, minor, major, isLarge [, largeIncr]) <static>

Increments a value given a range of parameters.

This method first determines a value to increment/decrement the value by, then snaps the result to the nearest multiple of that value.

Parameters:

Name	Type	Argument	Description
`value`	number		The value to increment.
`direction`	number		1 for increment, -1 for decrement.
`key`	PD.KEY \| WheelEvent		A scroll wheel event or current Control/Shift/Alt key status.
`step`	number		The smallest allowable increment value.
`minor`	number		The typical increment value.
`major`	number		The large increment value.
`isLarge`	number		Whether to use the large increment by default.
`largeIncr`	number	<optional>	If both Shift key and isLarge are set, multiply by this value, defaults to 5.

Returns:

Returns the incremented value.

Type: number

insertInArray(value, index, item) <static>

Inserts item at the given index, if not already in the array.

NOTE: This function uses array.indexOf() to check if the item already exists in the array. If not, it is inserted using the array.splice() method.

Parameters:

Name	Type	Description
`value`	Array	The array to add the item to.
`index`	number	The ordinal index in the array at which to insert.
`item`	any	The item to insert if not already in the array.

Returns:

Returns true if the item was added to the array, otherwise false.

Type: boolean

interpolate(start, stop, t) <static>

Interpolate between two scalar values, where t is a fractional value (0-1).

Parameters:

Name	Type	Description
`start`	number	The value when t == 0.0.
`stop`	number	The value when t == 1.0.
`t`	number	The fractional interpolator value (0-1).

Returns:

Returns the interpolated value.

Type: number

interpolateHexAsRGB(hex1, hex2, t) <static>

Interpolates between two hexadecimal color numbers using their RGB components.

Parameters:

Name	Type	Description
`hex1`	number	The hexadecimal color number when t == 0.0.
`hex2`	number	The hexadecimal color number when t == 1.0.
`t`	number	The fractional interpolation value in the range (0 to 1).

Returns:

Returns an interpolated hexadecimal number.

Type: number

interpolateHexViaHSL(hex1, hex2, t) <static>

Interpolates between two hexadecimal color numbers using their HSL components.

Parameters:

Name	Type	Description
`hex1`	number	The hexadecimal color number when t == 0.0.
`hex2`	number	The hexadecimal color number when t == 1.0.
`t`	number	The fractional interpolation value in the range (0 to 1).

Returns:

Returns an interpolated hexadecimal number.

Type: number

intersectBoxesInAxis(box1, box2, axis) <static>

Determines if the two boxes overlap in the XY axis (plan view).

Parameters:

Name	Type	Description
`box1`	THREE.Box3	The first bounding box to check.
`box2`	THREE.Box3	The second bounding box to check.
`axis`	PD.AXIS	The axis in which to test the boxes, defaults to +Z axis.

Returns:

Returns true if the two boxes overlap in plan view.

Type: boolean

intersectLineSegmentsXY(p1, p2, p3, p4 [, out]) <static>

Calculates if the line segment p1->p2 intersects the line segment p3->p4 in the XY plane.

Parameters:

Name	Type	Argument	Description
`p1`	THREE.Vector3		The first point on the first line segment.
`p2`	THREE.Vector3		The second point on the first line segment.
`p3`	THREE.Vector3		The first point on the second line segment.
`p4`	THREE.Vector3		The second point on the second line segment.
`out`	THREE.Vector3	<optional>	An optional point to receive the intersection.

Returns:

Returns true if segments intersect, and out modified.

Type: boolean

intersectLineWithAxialPlane(out, p1, p2, pos [, axis] [, min]) <static>

Calculates the position of the intersection point of line and plane.

This method is different from THREE.Ray.intersectPlane() in that it calculates intersections on both sides of the ray, not just in its direction of travel.

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

Parameters:

Name	Type	Argument	Description
`out`	THREE.Vector3		The vector to receive the result.
`p1`	THREE.Vector3		The position of the start point of the line.
`p2`	THREE.Vector3		The position of the end point of the line.
`pos`	THREE.Vector3		A position somewhere on the axial plane.
`axis`	PD.AXIS	<optional>	The axis to use as the plane normal, defaults to YZ plane.
`min`	number	<optional>	The minimum distance along the ray, defaults to `-Infinity`.

Returns:

Returns true if there was a valid intersection point and out was successfully set, otherwise false.

Type: boolean

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

Calculates the position of the intersection point of ray and plane.

This method is different from THREE.Ray.intersectPlane() in that it calculates intersections on both sides of the ray, not just in its direction of travel.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Argument	Description
`out`	THREE.Vector3		The vector to receive the result.
`p1`	THREE.Vector3		The position of the start point of the line.
`p2`	THREE.Vector3		The position of the end point of the line.
`plane`	THREE.Plane		The plane to intersect with the line.
`min`	number	<optional>	The minimum distance along the line.

Returns:

Returns true if there was a valid intersection point and out was successfully set, otherwise false.

Type: boolean

intersectRayWithAxialPlane(out, ray, pos [, axis] [, min]) <static>

Calculates the position of the intersection point of ray and plane.

This method is different from THREE.Ray.intersectPlane() in that it calculates intersections on both sides of the ray, not just in its direction of travel.

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

Parameters:

Name	Type	Argument	Description
`out`	THREE.Vector3		The vector to receive the result.
`ray`	THREE.Ray		The ray to intersect with the plane.
`pos`	THREE.Vector3		A position somewhere on the axial plane.
`axis`	PD.AXIS	<optional>	The axis to use as the plane normal, defaults to YZ plane.
`min`	number	<optional>	The minimum distance along the ray, defaults to `-Infinity`.

Returns:

Returns true if there was a valid intersection point and out was successfully set, otherwise false.

Type: boolean

intersectRayWithBox(out, ray, bbox, tolerance) <static>

Calculates the position of the intersection point of ray and bounding box.

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

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`ray`	THREE.Ray	The ray to intersect with the plane.
`bbox`	THREE.Box	The bounding box to intersect with the ray.
`tolerance`	number	An amount of tolerance around the box.

Returns:

Returns true if there was a valid intersection point and out was successfully set, otherwise false.

Type: boolean

intersectRayWithHemisphere(out, ray, sphere) <static>

Computes the closest intersection point of the ray and the +Z half of the given sphere.

This method is different from THREE.Ray.intersectSphere() in that it calculates intersections on just the half of the sphere that is at or above the Z axis of the center point, and returns a boolean instead of the target/null.

NOTE: This method may change values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`ray`	THREE.Ray	The ray to intersect with the sphere.
`sphere`	THREE.Sphere	The sphere to intersect with the ray.

Returns:

Returns true if there was a valid intersection point and out was successfully set, otherwise false.

Type: boolean

intersectRayWithPlane(out, ray, plane [, min]) <static>

Calculates the position of the intersection point of ray and plane.

This method is different from THREE.Ray.intersectPlane() in that it calculates intersections on both sides of the ray, not just in its direction of travel.

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

Parameters:

Name	Type	Argument	Description
`out`	THREE.Vector3		The vector to receive the result.
`ray`	THREE.Ray		The ray to intersect with the plane.
`plane`	THREE.Plane		The plane to intersect with the ray.
`min`	number	<optional>	The minimum distance along the ray, defaults to `-Infinity`.

Returns:

Returns true if there was a valid intersection point and out was successfully set, otherwise false.

Type: boolean

intersectRayWithPlaneByComponents(out, ray_pos, ray_dir, plane_pos, plane_normal [, min]) <static>

Calculates the position of the intersection point of ray and plane.

This method is different from THREE.Ray.intersectPlane() in that it calculates intersections on both sides of the ray, not just in its direction of travel.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Argument	Description
`out`	THREE.Vector3		The vector to receive the result.
`ray_pos`	THREE.Vector3		The position of the start point of the ray.
`ray_dir`	THREE.Vector3		The vector direction of the ray.
`plane_pos`	THREE.Vector3		A position on the intersection plane.
`plane_normal`	THREE.Vector3		The normal of the intersection plane.
`min`	number	<optional>	The minimum distance along the ray.

Returns:

Returns true if there was a valid intersection point and out was successfully set, otherwise false.

Type: boolean

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`	THREE.Vector3	A 3D vector to receive the intersection point.
`plane1`	THREE.Plane	The first plane to intersect.
`plane2`	THREE.Plane	The second plane to intersect.
`plane3`	THREE.Plane	The third plane 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

intersectTwoRays(out, ray1, ray2 [, up]) <static>

Calculates the position of the intersection point of ray and plane.

This method is different from THREE.Ray.intersectPlane() in that it calculates intersections on both sides of the ray, not just in its direction of travel.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Argument	Description
`out`	THREE.Vector3		The vector to receive the result.
`ray1`	THREE.Ray		The ray to intersect with the plane.
`ray2`	THREE.Ray		The ray to intersect with the plane.
`up`	THREE.Vector3	<optional>	The relative up direction for the two rays, defaults to cross product.

Returns:

Returns true if there was a valid intersection point and out was successfully set, otherwise false.

Type: boolean

intersectVectorWithPlane(out, ray_pos, ray_dir, plane [, min]) <static>

Calculates the position of the intersection point of ray and plane.

This method is different from THREE.Ray.intersectPlane() in that it calculates intersections on both sides of the ray, not just in its direction of travel.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Argument	Description
`out`	THREE.Vector3		The vector to receive the result.
`ray_pos`	THREE.Vector3		The position of the start point of the ray.
`ray_dir`	THREE.Vector3		The vector direction of the ray.
`plane`	THREE.Plane		A position on the intersection plane.
`min`	number	<optional>	The minimum distance along the ray.

Returns:

Returns true if there was a valid intersection point and out was successfully set, otherwise false.

Type: boolean

intersectsBoxXY(box1, box2) <static>

Determines whether or not box1 intersects box2 in the XY plane.

Parameters:

Name	Type	Description
`box1`	THREE.Box3	The first bounding box to check.
`box2`	THREE.Box3	The second bounding box to check.

Returns:

Returns true if they intersect in XY.

Type: boolean

isAlpha(chr) <static>

Testing if a single character is alphabetical (A-Z|a-z).

Parameters:

Name	Type	Description
`chr`	string	The variable to check.

Returns:

Returns true if 'chr' is alphabetical.

Type: boolean

isBetween(value, range1, range2 [, tolerance]) <static>

Determine if value is within the given range and tolerance.

This method is exclusive of the range boundaries, but will still work fine if range1 is greater-than or less-than range2. If you want to include the range bounds, simply use a small negative tolerance.

Parameters:

Name	Type	Argument	Description
`value`	number		The value to test if within the range.
`range1`	number		The first value defining the allowable range.
`range2`	number		The second value defining the allowable range.
`tolerance`	number	<optional>	The tolerance value at each end of the range, defaults to zero.

Returns:

Returns true if value is between the value range, otherwise false.

Type: boolean

isBoolean(value) <static>

Determine if given value is a boolean.

NOTE: This method applies only to boolean values, not Boolean objects which are very different things.

Parameters:

Name	Type	Description
`value`	boolean	The value to test.

Returns:

Returns true if its an actual boolean.

Type: boolean

isFunction(fn) <static>

Testing if a variable is a function.

Parameters:

Name	Type	Description
`fn`	function	The variable to check.

Returns:

Returns true if 'str' is a string.

Type: boolean

isInsideBox(box, point [, tolerance]) <static>

Determines whether or not the point is on or in the given box.

This method differs from THREE.Box3.containsPoint() in that it applies a small 0.5mm tolerance to allow for planes and polygons that are flat in any of the cartesian axis.

Parameters:

Name	Type	Argument	Description
`box`	THREE.Box3		The bounding box to check.
`point`	THREE.Vector3		The point to check if inside of.
`tolerance`	number	<optional>	An optional additional area around the box, defaults to 0.5mm.

Returns:

Returns whether or not the point is on or inside the box.

Type: boolean

isInsideBoxXY(box, point) <static>

Determines whether or not the point is on or in the given box in the XY plane.

This method differs from THREE.Box3.containsPoint() in that it applies a small 0.5mm tolerance to allow for planes and polygons that are flat in any of the cartesian axis and only considers the X and Y components.

Parameters:

Name	Type	Description
`box`	THREE.Box3	The bounding box to check.
`point`	THREE.Vector3	The point to check if inside of.

Returns:

Returns whether or not the point is on or inside the box in the XY plane.

Type: boolean

isInsideContour(point, contour, normal) <static>

Determine whether or not a point is inside the given contour boundary.

This method sums the signed angle between the given point and each line segment of the given contour boundary. If the total angle is near zero, then the point must be outside. If near 360, it must be inside.

Parameters:

Name	Type	Description
`point`	THREE.Vector3	The point to check if inside.
`contour`	Array	A array of `THREE.Vector3` forming a closed loop.
`normal`	THREE.Vector3	The normal to the contour.

Returns:

Returns true if inside, otherwise false.

Type: boolean

isInsideContourXY(point, contour) <static>

Determine whether or not a point is inside the given contour in plan view.

This method only considers the airspace above the contour, so only checks the X and Y components of each point. Thus, the test point can be well above or below the contour in the Z axis but still considered inside. To check if a point is both on and in a contour, use the isInsideContour() method instead.

Parameters:

Name	Type	Description
`point`	THREE.Vector3	The point to check if inside.
`contour`	Array	A array of `THREE.Vector3` forming a closed loop.

Returns:

Returns true if inside, otherwise false.

Type: boolean

isInsideTriangleXY(pt, v1, v2, v3) <static>

Returns true if the given XY point lies within the specified triangle.

This method only considers the airspace above the triangle, so only checks the X and Y components of each point. Thus, the test point can be well above or below the triangle in the Z axis but still considered inside. To check if a point is both on and in a triangle, use the isInsideTriangle() method instead.

Parameters:

Name	Type	Description
`pt`	THREE.Vector3	The intersection point to test.
`v1`	THREE.Vector3	The first triangle vertex.
`v2`	THREE.Vector3	The second triangle vertex.
`v3`	THREE.Vector3	The third triangle vertex.

Returns:

Returns true if the pt is inside the triangle.

Type: boolean

isInsideTriangles(hit_pt, triangles, normal) <static>

Returns true if the given 3D point lies within any of the given triangles.

This calculation assumes that the hit point and all triangle vertices lie on the same plane, so it is relatively fast as the normal is already given.

Parameters:

Name	Type	Description
`hit_pt`	THREE.Vector3	The intersection point to test.
`triangles`	Array	A triangle array generated by the tessellator.
`normal`	THREE.Vector3	The plane normal to use.

Returns:

Returns true if the hit_pt is inside the triangle.

Type: boolean

isInsideTrianglesXY(pt, triangles) <static>

Returns true if the given point lies within any of the given triangles in plan view.

This method only considers the airspace above the triangles, so only checks the X and Y components of each point. Thus, the test point can be well above or below the triangle in the Z axis but still considered inside. To check if a point is both on and in triangles, use the isInsideTriangles() method instead.

Parameters:

Name	Type	Description
`pt`	THREE.Vector3	The intersection point to test.
`triangles`	Array	A triangle array generated by the tessellator.

Returns:

Returns true if the hit_pt is inside the triangle.

Type: boolean

isNumeric(value) <static>

Determine if given value is or can be easily converted to a valid number less than infinity.

This is needed as the standard function isNaN(null) returns false (technically null != NaN), and isFinite(null) returns true. Thus we need to test for both null and infinity.

Parameters:

Name	Type	Description
`value`	number	The value to test.

Returns:

Returns true if numeric.

Type: boolean

isObject(obj) <static>

Testing if a variable represents a javascript object.

NOTE: This method returns true for built-in pseudo-objects such as Array(), Number() and String() objects. If you want to exclude these, use isPlainObject() instead.

Parameters:

Name	Type	Description
`obj`	object	The variable to check.

Returns:

Returns true if 'obj' is a real javascript object.

Type: boolean

isOnSameSideOfPlane(plane, p1, p2) <static>

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

Parameters:

Name	Type	Description
`plane`	THREE.Plane	The plane equation to check for.
`p1`	THREE.Vector3	The first point to check.
`p2`	THREE.Vector3	The second point to check.

Returns:

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

Type: boolean

isParallelVector(v1, v2 [, tolerance]) <static>

Determines if two 3D vectors are parallel to each other.

This simply checks if the two vectors point in either the same or opposite directions, within the given tolerance in each axis of PD.Utils.EPSILON if not given. The two vectors are assumed to have already been normalised so that their axial magnitudes can match, however you can use non-normalised vectors if you are sure that they have the same magnitude and that it is greater than the given tolerance.

NOTE: Any two vectors who's magnitudes are less than or equal to the given tolerance value will pass this test regardless. To account for such cases, you should normalise each vector before calling this method.

Parameters:

Name	Type	Argument	Description
`v1`	THREE.Vector3		The first vector/coordinate.
`v2`	THREE.Vector3		The second vector/coordinate.
`tolerance`	number	<optional>	An optional amount by which results can vary from zero and still be considered close, defaults to `PD.Utils.EPSILON`.

Returns:

Returns 1 if the vectors are in the same direction, -1 if they are in opposite directions or 0 if the vectors are not within the given tolerance of parallel.

Type: number

isPlainObject(obj) <static>

Testing if a variable represents just a plain old object.

NOTE: This method returns false for built-in pseudo-objects such as Array(), Number() and String() objects. If you want to include these, use isObject() instead.

Parameters:

Name	Type	Description
`obj`	object	The variable to check.

Returns:

Returns true if 'obj' is a plain old object.

Type: boolean

isPointInFrontOfPlane(plane, pt) <static>

Checks if a 3D point is on or in front of the given plane.

Parameters:

Name	Type	Description
`plane`	THREE.Plane	The plane equation to check for.
`pt`	THREE.Vector3	The point to check.

Returns:

Returns true if the point is on or in front of the plane.

Type: boolean

isPointOnLineSegment(pt, p1, p2, tolerance) <static>

Calculates whether pt is within the given tolerance of the 3D line segment p1->p2.

Parameters:

Name	Type	Description
`pt`	THREE.Vector3	The point to test.
`p1`	THREE.Vector3	The first point at the start of the line segment.
`p2`	THREE.Vector3	The second point at the end of the line segment.
`tolerance`	number	The allowable distance to be considered 'on'.

Returns:

Returns true if point is within tolerance.

Type: boolean

isPointOnLineSegmentXY(pt, p1, p2, tolerance) <static>

Calculates if pt is within the given tolerance of the line segment p1->p2 in the XY plane.

Parameters:

Name	Type	Description
`pt`	THREE.Vector3	The point to test.
`p1`	THREE.Vector3	The first point at the start of the line segment.
`p2`	THREE.Vector3	The second point at the end of the line segment.
`tolerance`	number	The allowable distance to be considered 'on'.

Returns:

Returns true if point is within tolerance in the XY plane.

Type: boolean

isPointOnPlane(plane, p1 [, tolerance]) <static>

Checks if a 3D point is on or in front of the given plane.

Parameters:

Name	Type	Argument	Description
`plane`	THREE.Plane		The plane equation to check for.
`p1`	THREE.Vector3		The point to check.
`tolerance`	number	<optional>	An amount of tolerance in model units, defaults to 0.001.

Returns:

Returns true if the point is on within the given tolerance of the plane.

Type: boolean

isReverseVector(v1, v2 [, tolerance]) <static>

Returns true if two 3D vectors are very close to opposite each other.

This simply checks if the difference between each component of the two vectors is within the given tolerance, which defaults to the current value of PD.Utils.EPSILON if not given. The two vectors are assumed to have already been normalised so that their axial magnitudes can match, however you can use non-normalised vectors if you are sure that they have the same magnitude and that it is greater than the given tolerance.

Parameters:

Name	Type	Argument	Description
`v1`	THREE.Vector3		The first normalised vector/coordinate.
`v2`	THREE.Vector3		The second normalised vector/coordinate.
`tolerance`	number	<optional>	An optional amount by which results can vary from zero and still be considered close, defaults to `PD.Utils.EPSILON`.

Returns:

Returns true if each component difference is within the specified tolerance of zero.

Type: boolean

isSameVector(v1, v2 [, tolerance]) <static>

Returns true if two 3D vectors are very close to each other.

Parameters:

Name	Type	Argument	Description
`v1`	THREE.Vector3		The first normalised vector/coordinate.
`v2`	THREE.Vector3		The second normalised vector/coordinate.
`tolerance`	number	<optional>	An optional amount by which results can vary from zero and still be considered close, defaults to `PD.Utils.EPSILON`.

Returns:

Returns true if each component difference is within the specified tolerance of zero.

Type: boolean

isString(str) <static>

Testing if a variable is a string value.

Parameters:

Name	Type	Description
`str`	object	The variable to check.

Returns:

Returns true if 'str' is a string.

Type: boolean

isVector3(obj) <static>

Testing if a object is a valid THREE.Vector3.

Parameters:

Name	Type	Description
`obj`	object	The object to check.

Returns:

Returns true if it is a valid THREE.Vector3.

Type: boolean

isWithinLineSegmentXY(pt, p1, p2) <static>

Checks if pt lies within the 3D line segment p1->p2 in plan view.

Parameters:

Name	Type	Description
`pt`	THREE.Vector3	The point to calculate the distance from.
`p1`	THREE.Vector3	The first point at the start of the line segment.
`p2`	THREE.Vector3	The second point at the end of the line segment.

Returns:

Returns true if the point is within the other two points, otherwise returns false.

Type: boolean

joinArrayWithLineBreaks(array) <static>

Converts an array of strings to multi-line string.

Parameters:

Name	Type	Description
`array`	Array.<string>	The multi-line string as an array.

Returns:

Returns the joined string.

Type: string

jsonStringify(obj) <static>

Returns a JSON string with arrays formatted be on the same line.

Parameters:

Name	Type	Description
`obj`	object	An object to convert to formatted JSON.

Returns:

Returns A formatted JSON string.

Type: string

lerpVectorsXY(out, from, to, t) <static>

Calculates the distance between two 3D points only in the XY plane.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`from`	THREE.Vector3	The start point.
`to`	THREE.Vector3	The ending point.
`t`	number	The fractional interpolation value (0-1).

Returns:

Returns the resulting out vector.

Type: THREE.Vector3

lineIntersectsFrustum(frustum, p1, p2) <static>

Determines if the given line intersects the frustum.

Parameters:

Name	Type	Description
`frustum`	THREE.Frustum	The frustum to check for intersection.
`p1`	THREE.Vector3	The position of the start point of the line.
`p2`	THREE.Vector3	The position of the end point of the line.

Returns:

Returns true if the line intersected the frustum.

Type: boolean

makePlanarByAxis(contour, plane [, axis] [, tolerance]) <static>

Projects any non-planar points back onto a plane in the given axis.

Parameters:

Name	Type	Argument	Description
`contour`	Array.<THREE.Vector3>		An array of 3D vector objects.
`plane`	THREE.Plane		The plane to project the points back onto.
`axis`	PD.AXIS	<optional>	The axis to use as the plane normal, will be computed if not given.
`tolerance`	number	<optional>	An optional threshold value within which a point is considered coplanar.

Returns:

Returns true if any points were outside the tolerance and moved, otherwise false.

Type: boolean

makePlanar_Normal(contour, plane [, tolerance]) <static>

Projects any non-planar points back onto plane using its normal.

Parameters:

Name	Type	Argument	Description
`contour`	Array.<THREE.Vector3>		An array of 3D vector objects.
`plane`	THREE.Plane		The plane to project the points back onto.
`tolerance`	number	<optional>	An optional threshold value within which a point is considered coplanar.

Returns:

Returns true if any points were outside the tolerance and moved, otherwise false.

Type: boolean

makePlanar_X_Axis(contour, plane [, tolerance]) <static>

Projects any non-planar points back onto a plane in the X axis.

Parameters:

Name	Type	Argument	Description
`contour`	Array.<THREE.Vector3>		An array of 3D vector objects.
`plane`	THREE.Plane		The plane to project the points back onto.
`tolerance`	number	<optional>	An optional threshold value within which a point is considered coplanar.

Returns:

Returns true if any points were outside the tolerance and moved, otherwise false.

Type: boolean

makePlanar_Y_Axis(contour, plane [, tolerance]) <static>

Projects any non-planar points back onto the line's plane via the Y axis.

Parameters:

Name	Type	Argument	Description
`contour`	Array.<THREE.Vector3>		An array of 3D vector objects.
`plane`	THREE.Plane		The plane to project the points back onto.
`tolerance`	number	<optional>	An optional threshold value within which a point is considered coplanar.

Returns:

Returns true if any points were outside the tolerance and moved, otherwise false.

Type: boolean

makePlanar_Z_Axis(contour, plane [, tolerance]) <static>

Projects any non-planar points back onto the line's plane via the Z axis.

Parameters:

Name	Type	Argument	Description
`contour`	Array.<THREE.Vector3>		An array of 3D vector objects.
`plane`	THREE.Plane		The plane to project the points back onto.
`tolerance`	number	<optional>	An optional threshold value within which a point is considered coplanar.

Returns:

Returns true if any points were outside the tolerance and moved, otherwise false.

Type: boolean

manhattanDistanceInXY(from, to) <static>

Calculates the manhattan distance between two 3D points only in the XY plane.

The manhattan distance is simply the sum of the absolute difference between the X and Y coordinate positions of two points. It is quicker to calculate that the actual distance as it does not require any multiplications or a square root, and can be useful for determining the proximity of points.

Parameters:

Name	Type	Description
`from`	THREE.Vector3	The point to calculate distance from.
`to`	THREE.Vector3	The point to check the distance to.

Returns:

Returns the manhattan distance in the XY plane.

Type: number

mapAndConstrainTo(value, v_min, v_max, o_min, o_max) <static>

Map a value from one scalar range to another, but clamped to that range.

Parameters:

Name	Type	Description
`value`	number	The value to map and constrain.
`v_min`	number	The start of the input range.
`v_max`	number	The end of the input range.
`o_min`	number	The start of the output range.
`o_max`	number	The end of the the output range.

Returns:

Returns the mapped value.

Type: number

mapTo(value, v_min, v_max, o_min, o_max) <static>

Map a value from one scalar range to another.

Parameters:

Name	Type	Description
`value`	number	The value to map.
`v_min`	number	The start of the input range.
`v_max`	number	The end of the input range.
`o_min`	number	The start of the output range.
`o_max`	number	The end of the the output range.

Returns:

Returns the mapped value.

Type: number

normalizeColor(color) <static>

Scales the color values to within the range 0 to 1.

Parameters:

Name	Type	Description
`color`	PD.Utils.ColorObject	The color object to normalise.

Returns:

Returns the given color object.

Type: PD.Utils.ColorObject

offsetPlaneByDistance(plane, offset) <static>

Calculates a plane equation that is offset from the given plane in the direction of its surface normal.

Parameters:

Name	Type	Description
`plane`	THREE.Plane	The plane to offset.
`offset`	number	The distance to offset in normal direction.

Returns:

Returns a shared plane instance.

Type: THREE.Plane

parseCSV(csv [, separator]) <static>

Parses a line of comma-separated values into an array.

Parameters:

Name	Type	Argument	Description
`csv`	string		A single-line string containing comma-separated values.
`separator`	string	<optional>	The delimiter to separate values with, defaults to a comma.

Returns:

Returns an array of values.

Type: Array

parseValidJSON(text) <static>

Tries to convert the string to a valid JSON object or array.

If the string is not a valid JSON object or array, the method returns nul1.

Parameters:

Name	Type	Description
`text`	String	The JSON text to parse.

Returns:

Returns the converted JSON, or null if invalid.

Type: Object | Array | null

radToDeg(value) <static>

Returns the value converted from radians to degrees.

Parameters:

Name	Type	Description
`value`	number	The radians value to convert to decimal degrees.

Returns:

Returns the converted value in decimal degrees.

Type: number

randomColorAsArray( [modifier] [, result]) <static>

Returns a random color as an [r,g,b] array.

Parameters:

Name	Type	Argument	Description
`modifier`	number	<optional>	A dark/light modifier value (-0.9 to 0.9), defaults to zero.
`result`	Array.<number>	<optional>	An optional [r,g,b] color array to store the result in.

Returns:

Returns the given [r,g,b] color array or a newly generated one.

Type: ColorType

randomColorAsHex( [modifier]) <static>

Returns a random hexadecimal color value.

Parameters:

Name	Type	Argument	Description
`modifier`	number	<optional>	A dark/light modifier value in the range (-0.9 to 0.9).

Returns:

Returns a random hexadecimal color value.

Type: number

randomColorAsObject( [modifier] [, result]) <static>

Returns a random color as an {r,g,b} object.

Parameters:

Name	Type	Argument	Description
`modifier`	number	<optional>	A dark/light modifier value (-0.9 to 0.9), defaults to zero.
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

randomNumber( [seed]) <static>

Returns a seeded random number in the range 0 to 1.

Parameters:

Name	Type	Argument	Description
`seed`	number	<optional>	An optional number to use as the generator seed.

Returns:

Returns a seeded random number in the range (0-1).

Type: number

randomRange(min, max) <static>

Generates a random number within the given range.

Parameters:

Name	Type	Description
`min`	number	The minimum value of the required range.
`max`	number	The maximum value of the required range.

Returns:

Returns the random value.

Type: number

removeFromArray(value, item) <static>

Removes the item from the given array if it exists.

NOTE: This function uses array.indexOf() to check if the item exists and obtain its index, then array.splice() to remove it.

Parameters:

Name	Type	Description
`value`	Array	The array to remove the item from.
`item`	any	The item to remove if it exists in the array.

Returns:

Returns true if the item was found in the array and removed, otherwise false.

Type: boolean

resizeTypedArray(array, new_length) <static>

Creates a new typed array with the new size and a copy of the original data.

Parameters:

Name	Type	Description
`array`	TypedArray	The typed array to resize.
`new_length`	number	The new size of the array.

Returns:

Returns a new array with the original data and a new size.

Type: TypedArray

restrictToLineSegmentXY(pt, p1, p2) <static>

Ensures pt lies within the 3D line segment p1->p2 in plan view.

NOTE: This method changes values within the pt parameter.

Parameters:

Name	Type	Description
`pt`	THREE.Vector3	The point to calculate the distance from.
`p1`	THREE.Vector3	The first point at the start of the line segment.
`p2`	THREE.Vector3	The second point at the end of the line segment.

Returns:

Returns pt with any required modifications.

Type: THREE.Vector3

rotateBySphericalCoordinates(out, about, azi, alt) <static>

Rotates the out point around about by the given angles.

NOTE: This method changes values within the out parameter.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The point to rotate.
`about`	THREE.Vector3	The point about which to rotate.
`azi`	number	The horizontal azimuth angle, in radians anti-clockwise from +X axis.
`alt`	number	The vertical angle, in radians above the horizontal plane.

Returns:

Returns the out vector, or a new vector if null.

Type: THREE.Vector3

rotatePointAroundAxis(point, origin, axis, angle) <static>

Rotates the position vector around the given axis by the given angle.

Parameters:

Name	Type	Description
`point`	THREE.Vector3	The point to rotate.
`origin`	THREE.Vector3	The local origin to rotate about.
`axis`	THREE.Vector3	The axis vector to rotate around.
`angle`	number	The angle of rotation, in radians.

Returns:

Returns point at the rotated position.

Type: THREE.Vector3

rotateVectorAroundZ(vec, angle) <static>

Rotates the given direction vector around the Z axis by the given angle.

Parameters:

Name	Type	Description
`vec`	THREE.Vector3	The direction vector.
`angle`	number	The angle of rotation, in radians.

Returns:

Returns the given vector.

Type: THREE.Vector3

roundTo(value, increment) <static>

Rounds a number to the given number of decimal places.

This method is not totally accurate as rounding floating point numbers on a CPU/FPU is not trivial (see: https://stackoverflow.com/a/38676273). However, if you know the limitations, then there are always use-cases where something like this is useful.

Parameters:

Name	Type	Description
`value`	number	The value to round.
`increment`	number	The integer number of decimal places, defaults to 3.

Returns:

Returns the rounded value.

Type: number

safeDivide(top, bot) <static>

Performs division with divide-by-zero protection.

NOTE: If the denominator bot is within 1e-9 of zero, this function returns zero instead of Infinity. In most geometric applications, a denominator value close to zero is an indicator that two points share the same position. Returning Infinity would result in spurious vectors and invalid projections, which would require additional bounds checking and basically defeat the very purpose of using this function. In comparison, returning zero has very few side effects.

Parameters:

Name	Type	Description
`top`	number	The value to divide.
`bot`	number	The value to divide by.

Returns:

Returns the divided result or zero.

Type: number

setNestedProperty(host, path, value [, mustExist]) <static>

Set the value of a nested property on a host object using a string path.

If the optional mustExist flag is set to true, the property value will only be set if all intermediate objects and the property already exist on the object. If the property or any intermediate objects do not exist, the method will return false and not set anything. If the mustExist flag is false (default), any intermediate objects that do not exist will be created as needed along the path to the final property, which will then be created and set to the given value.

Parameters:

Name	Type	Argument	Description
`host`	object		The object containing the nested properties.
`path`	string		A string containing dot-separated properties.
`value`	any		The value to set the nested property to.
`mustExist`	boolean	<optional>	If false (default), creates new properties and intermediate objects as needed, otherwise only sets the property value if the full path already exists.

Returns:

Returns true if the property value was set, false otherwise.

Type: boolean

setQuaternionFromPlane(quaternion, plane) <static>

Compute the quaternion required to rotate from the XY plane to given plane.

Parameters:

Name	Type	Description
`quaternion`	THREE.Quaternion	The quaternion compute.
`plane`	THREE.Plane	The plane to get the normal from.

Returns:

Returns the quaternion argument with computed values.

Type: THREE.Quaternion

setQuaternionFromThreeAxis(quaternion, x_axis, y_axis, z_axis) <static>

Sets a quaternion based on its three axis.

Parameters:

Name	Type	Description
`quaternion`	THREE.Quaternion	The quaternion to set.
`x_axis`	THREE.Vector3	The new relative X-axis.
`y_axis`	THREE.Vector3	The new relative Y-axis.
`z_axis`	THREE.Vector3	The new relative Z-axis.

Returns:

Returns the updated quaternion.

Type: THREE.Quaternion

sign(value) <static>

Returns -1 or 1 based on whether the value is negative or zero/positive.

Parameters:

Name	Type	Description
`value`	number	The value to determine the sign of.

Returns:

Returns -1 or 1 based on the sign of the given value.

Type: number

signedAngleBetweenPoints(p1, p2, p3 [, up]) <static>

Computes the signed 3D angle between two lines that share a common point, in radians.

The angle is calculated by first normalising the vectors (p1 -> p2) and (p2 -> p3), where p2 is the shared point about which the angle is determined, and then calling PD.Utils.signedAngleBetweenVectors and returning the result.

                        + p3
                       /
               ..--''-o
             -'      /
           .' angle /
      +----o-------+
     p1             p2

Parameters:

Name	Type	Argument	Description
`p1`	THREE.Vector3		The start coordinate on the angle line.
`p2`	THREE.Vector3		The middle coordinate on the angle line.
`p3`	THREE.Vector3		The end coordinate on the angle line.
`up`	THREE.Vector3	<optional>	The cross-product of (v2->v1) and (v2->v2), if known.

Returns:

Returns the 3D angle in the range 0 to 2PI, in radians.

Type: number

signedAngleBetweenVectors(v1, v2 [, up]) <static>

Computes the signed 3D angle between two normalised vectors, in radians.

                                   v1
                        +    +---o--------+
                       /         : angle /
               ..--''-o           '._   /
             -'      / v2            '-o v2
           .' angle /                 /
      +----o-------+                 +
            v1

Parameters:

Name	Type	Argument	Description
`v1`	THREE.Vector3		The incoming normalised direction vector.
`v2`	THREE.Vector3		The outgoing normalised direction vector.
`up`	THREE.Vector3	<optional>	The cross-product of the two vectors, if known.

Returns:

Returns the 3D angle in the range -PI to PI, in radians.

Type: number

sinDegrees(degrees) <static>

Determines Math.sin() based on an angle given in decimal degrees.

Parameters:

Name	Type	Description
`degrees`	number	The required angle in decimal degrees.

Returns:

Returns the trigonometric sine of the given angle.

Type: number

sleepFor(ms) <static>

Pauses the application execution for the given duration.

Parameters:

Name	Type	Description
`ms`	number	The number of milliseconds to wait.

Returns:

Returns a promise.

Type: Promise

snapTo(value, increment) <static>

Utility function to snap to a given value increment.

Parameters:

Name	Type	Description
`value`	number	The value to snap.
`increment`	number	The increment value to snap to.

Returns:

Returns an integer multiple of increment.

Type: number

splitStringByLineBreaks(str) <static>

Converts a multi-line string to a JSON compatible string array.

Parameters:

Name	Type	Description
`str`	string	The multi-line string to convert.

Returns:

Returns the string array.

Type: Array.<string>

startsWith(haystack, needle) <static>

Determines if a string starts with the given string.

Parameters:

Name	Type	Description
`haystack`	string	The larger string to be checked.
`needle`	string	The smaller string to use for checking.

Returns:

Returns true if 'haystack' starts with the exact same characters as 'needle'.

Type: boolean

tanDegrees(degrees) <static>

Determines Math.tan() based on an angle given in decimal degrees.

Parameters:

Name	Type	Description
`degrees`	number	The required angle in decimal degrees.

Returns:

Returns the trigonometric tangent of the given angle.

Type: number

toBoolean(value, default_value) <static>

Tries to convert the defined value to a valid boolean.

If the value is defined and the conversion is valid, the converted value is returned. Otherwise the default value is returned.

Parameters:

Name	Type	Description
`value`	boolean	The value to convert.
`default_value`	boolean	Returned if value is null, undefined or the conversion fails.

Returns:

Returns either the converted value or the default.

Type: boolean

toCSSFromAnyColor(color [, defaultValue]) <static>

Converts a color number, string, {r,g,b} object or [r,g,b] array to a CSS color value in '#RRGGBB' format.

This method can handle different types of input color values, such as 0x2b362 and '#ffc49c' as well as simple [r,g,b] arrays or {r,g,b} objects whose elements or components are in the range (0 to 1).

As a result, this method must check the type of the argument before converting its value, which adds some overhead to the conversion when compared to using the PD.Utils.toCSSFromRGB, PD.Utils.toCSSFromHex, PD.Utils.toCSSFromColorObject or PD.Utils.toCSSFromColorArray methods directly, assuming that you know its type beforehand.

If the given argument does not define a valid color, this method will return 'none' or the default value.

NOTE: The components or values of any given {r,g,b} color object or [r,g,b] color array must be in the range (0 to 1).

Parameters:

Name	Type	Argument	Description
`color`	any		A number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
`defaultValue`	number	<optional> <nullable>	An optional default hexadecimal color value to use if the given color is invalid, defaults to zero.

Returns:

Returns a hexadecimal color string of the form '#RRGGBB'.

Type: string

toCSSFromColorArray(arr) <static>

Converts an [r,g,b] color array to a CSS color in '#RRGGBB' format.

If the given argument does not define a valid color, this method will return 'none'.

Parameters:

Name	Type	Description
`arr`	Array.<number>	An [r,g,b] color array with values in the range (0 to 1).

Returns:

Returns a hexadecimal color string of the form '#RRGGBB'.

Type: string

toCSSFromColorObject(obj) <static>

Converts an {r,g,b} color object to a CSS color in '#RRGGBB' format.

If the given argument does not define a valid color, this method will return 'none'.

Parameters:

Name	Type	Description
`obj`	ColorType	An {r,g,b} color object with components in the range (0 to 1).

Returns:

Returns a hexadecimal color string of the form '#RRGGBB'.

Type: string

toCSSFromHex(hex) <static>

Converts a hexadecimal number to a CSS color in '#RRGGBB' format.

Parameters:

Name	Type	Description
`hex`	number	The color as a hexadecimal number.

Returns:

Returns a CSS color string of the form '#RRGGBB'.

Type: string

toCSSFromRGB(r, g, b) <static>

Converts color components to a CSS color in '#RRGGBB' format.

Parameters:

Name	Type	Description
`r`	number	The red colour component in the range (0 to 1).
`g`	number	The green colour component in the range (0 to 1).
`b`	number	The blue colour component in the range (0 to 1).

Returns:

Returns a CSS color string of the form '#RRGGBB'.

Type: string

toCamelCase(name) <static>

Converts a kebab-case, snake_case or space separated string to camelCase.

This method converts hyphen, underscore and space separated strings to camelCase, or any combination of hyphens, underscores or spaces. It also trims any whitespace from the start and end of the string.

Kebab-case is a way of joining together multiple words where spaces are replaced with hyphens (-) and all the words are typically lower case. The name comes from the similarity of the words to meat on a kebab skewer.

Snake_case is the same a kebab-case but uses underscores (_) instead of hyphens (-). Space separated is just the normal way of writing.

Camel case is a way of joining together multiple words without using spaces or any other separators, and where the first letter of each after the first word is capitalized. The name comes from the similarity of the capital letters to the humps of a camel's back.

Parameters:

Name	Type	Description
`name`	string	The separated string to convert.

Returns:

Returns a copy of the string in camelCase.

Type: string

toColorArrayFromAnyColor(color [, result]) <static>

Converts a color number, string, {r,g,b} object or [r,g,b] array to an [r,g,b] color array.

This method must check the type of the argument before converting its value, which adds some overhead to the conversion.

If the given argument does not define a valid color, this method will set all array elements to zero (black).

NOTE: The components or values of any given {r,g,b} color object or [r,g,b] color array must be in the range (0 to 1).

Parameters:

Name	Type	Argument	Description
`color`	any		A number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
`result`	Array.<number>	<optional> <nullable>	An optional [r,g,b] color array to store the result in.

Returns:

Returns the given [r,g,b] color array or a newly generated one.

Type: Array.<number>

toColorArrayFromCSS(css [, result]) <static>

Converts a '#RRGGBB' format string to an [r,g,b] color array.

NOTE: The elements of the color array will be in the range (0 to 1).

Parameters:

Name	Type	Argument	Description
`css`	string		A Hexadecimal color string of the form '#RRGGBB'.
`result`	Array.<number>	<optional> <nullable>	An optional [r,g,b] color array to store the result in.

Returns:

Returns the given [r,g,b] color array or a newly generated one.

Type: Array.<number>

toColorArrayFromHex(hex [, result]) <static>

Converts a hexadecimal number to an [r,g,b] color array.

Parameters:

Name	Type	Argument	Description
`hex`	number		The color as a hexadecimal number.
`result`	Array.<number>	<optional> <nullable>	An optional [r,g,b] color array to store the result in.

Returns:

Returns the given [r,g,b] color array or a newly generated one.

Type: Array.<number>

toColorFromAnyColor(color [, result]) <static>

Converts a color number, string, {r,g,b} object or [r,g,b] array to an {r,g,b} color object.

This method can handle different types of input color values, such as 0x2b362 and '#ffc49c' as well as simple [r,g,b] arrays or {r,g,b} objects whose elements or components are in the range (0 to 1).

As a result, this method must check the type of the argument before converting its value, which adds some overhead to the conversion.

If the given argument does not define a valid color, this method will set all color components to zero (black).

Parameters:

Name	Type	Argument	Description
`color`	any		A number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

toColorFromCSS(css [, result]) <static>

Converts a CSS '#RRGGBB' format string to an {r,g,b} color object.

If the given argument does not define a valid color, this method will set the value all to zero (black).

NOTE: The components of the color object will be in the range (0 to 1).

Parameters:

Name	Type	Argument	Description
`css`	string		A hexadecimal CSS color string of the form '#RRGGBB'.
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

toColorFromColorArray(arr [, result]) <static>

Converts an [r,g,b] color array to an {r,g,b} color object.

If the given argument does not define a valid color, this method will set the value all to zero (black).

Parameters:

Name	Type	Argument	Description
`arr`	Array.<number>		An [r,g,b] color array with values in the range (0 to 1).
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

toColorFromHex(hex [, result]) <static>

Converts a hexadecimal number to an {r,g,b} color object.

Parameters:

Name	Type	Argument	Description
`hex`	number		The color as a hexadecimal number.
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

toColorFromRGB(r, g, b [, result]) <static>

Converts a CSS '#RRGGBB' format string to an {r,g,b} color object.

NOTE: The components of the color object will be in the range (0 to 1).

Parameters:

Name	Type	Argument	Description
`r`	number		The red colour component in the range (0 to 1).
`g`	number		The green colour component in the range (0 to 1).
`b`	number		The blue colour component in the range (0 to 1).
`result`	ColorType	<optional> <nullable>	An optional {r,g,b} color object to store the result in.

Returns:

Returns the given {r,g,b} color object or a newly generated one.

Type: ColorType

toDimension(value, default_inches [, default_mm]) <static>

Tries to convert the defined value to a valid dimension in mm based on the current value of PD.DIMENSION.units.

If the value is defined and the conversion is valid, the converted value is returned. Otherwise either the imperial or metric default value is used, based on the current value of PD.DIMENSION.units.

This method exists because the dimensions of many things are often still given in inches to be compatible with US measurements, but rounded to the nearest 50 or 100mm in regions that use in metric units. Thus, rather that have all sorts of tests for imperial units dotted throughout your code, you can simply use this method and solve many of these issues.

If PD.DIMENSION.units are imperial, the first default argument given in inches will be converted directly to millimetres and returned. If the current model units are metric, the second default argument given in millimetres will be returned.

If there is no second default argument, the given number of inches in the the first default argument will be multiplied by 25.0 to give a reasonably rounded metric value.

The term 'reasonable' is based on the fact that. if light switches are installed 48" (1,219.2mm) above the floor in the US, this is almost invariably going to be 1200mm in countries that use metric units. Similarly, a 600mm bench depth is almost invariably going to be 2' (24" or 609.6mm) in the US.

This way, the dimensions of models created using imperial units will snap nicely to the nearest inch, and models created in metric units will snap nicely to the nearest 25, 50 and 100mm. Obviously if you create half the model using imperial units and the other half using metric units, you can't expect it to land very gently on whatever planet you send it to https://www.simscale.com/blog/2017/12/nasa-mars-climate-orbiter-metric/.

Parameters:

Name	Type	Argument	Description
`value`	number		The value to convert.
`default_inches`	number		The default number of inches to use if imperial.
`default_mm`	number	<optional>	The default number of millimetres if metric, defaults to `inches * 25`.

Returns:

Returns either the converted value or the appropriate default.

Type: boolean

Example

/// Instead of this:
const slab_depth = PD.Utils.toNumber(config.slabDepth, PD.DIMENSION.useImperial ? 203.2 : 200.0); // 8".

/// You can do this to avoid two function calls, specifying both the inches and millimeters.
const slab_depth = PD.Utils.toDimension(config.slabDepth, 8, 200);

/// Or this to, again, do exactly the same thing as the 8" value will converted to an appropriate metric value.
const slab_depth = PD.Utils.toDimension(config.slabDepth, 8);

toHexFromAnyColor(color [, defaultValue]) <static>

Converts a color number, string, {r,g,b} object or [r,g,b] array to a hexadecimal color number.

This method can handle different types of input color values, such as 0x2b362 and '#ffc49c' as well as simple [r,g,b] arrays or {r,g,b} objects whose elements or components are in the range (0 to 1).

As a result, this method must check the type of the argument before converting its value, which adds some overhead to the conversion when compared to using thePD.Utils.toHexFromRGB, PD.Utils.toHexFromCSS, PD.Utils.toHexFromColorObject or PD.Utils.toHexFromColorArray methods directly, assuming that you know its type beforehand.

If the given argument does not define a valid color, this method will return zero (black).

Parameters:

Name	Type	Argument	Description
`color`	any		A number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
`defaultValue`	number	<optional> <nullable>	An optional default hexadecimal color value to use if the given color is invalid, defaults to zero.

Returns:

Returns the color as a hexadecimal number.

Type: number

toHexFromCSS(css) <static>

Converts a '#RRGGBB' CSS color string to a hexadecimal color number.

If the string is not a valid CSS '#RRGGBB' value or a JSON array in the form '[r,g,b]', this method will return zero (black).

Parameters:

Name	Type	Description
`css`	string	A CSS color string of the form '#RRGGBB' or '[r,g,b]'.

Returns:

Returns the color as a hexadecimal number.

Type: number

toHexFromColorArray(arr) <static>

Converts an [r,g,b] color array to a hexadecimal color number.

If the given array does not define a valid [r,g,b] color, this method will return zero (black).

Parameters:

Name	Type	Description
`arr`	Array.<number>	An [r,g,b] color array with values in the range (0 to 1).

Returns:

Returns the color as a hexadecimal number.

Type: number

toHexFromColorObject(obj) <static>

Converts an {r,g,b} color object to a hexadecimal color number.

If the given object does not define a valid {r,g,b} color, this method will return zero (black).

Parameters:

Name	Type	Description
`obj`	ColorType	An {r,g,b} color object with components in the range (0 to 1).

Returns:

Returns the color as a hexadecimal number.

Type: number

toHexFromRGB(r, g, b) <static>

Converts color components to a hexadecimal color number.

Parameters:

Name	Type	Description
`r`	number	The red colour component in the range (0 to 1).
`g`	number	The green colour component in the range (0 to 1).
`b`	number	The blue colour component in the range (0 to 1).

Returns:

Returns the color as a hexadecimal number.

Type: number

toInteger(value, default_value) <static>

Tries to convert the defined value to a valid integer.

If the value is defined and conversion is valid, the converted value is returned. Otherwise the given default value is returned.

Parameters:

Name	Type	Description
`value`	number	The value to convert.
`default_value`	number	Returned if value is null, undefined or the conversion fails.

Returns:

Returns either the converted value or the default.

Type: number

toIntegerInRange(value, default_value, min, max) <static>

Tries to convert the defined value to a valid integer within the given range.

If the value is defined and conversion is valid, the clamped converted value is returned. Otherwise the clamped default value is returned.

Parameters:

Name	Type	Description
`value`	number	The value to convert.
`default_value`	number	Returned if value is null, undefined or the conversion fails.
`min`	number	The minimum allowed value.
`max`	number	The maximum allowed value.

Returns:

Returns either the converted value or the default.

Type: number

toKebabCase(name) <static>

Converts a camelCase or PascalCase string to kebab-case.

This method expects either a camelCase

can also convert underscore and space separated strings to camelCase, or any combination of hyphens, underscores or spaces. It also trims any whitespace from the start and end of the string.

PascalCase is the same as camelCase but with the first letter capitalised as well.

Kebab case is a way of joining together multiple words where spaces are replaced with hyphens (-) and all the words are typically lower case. The name comes from the similarity of the words to meat on a kebab skewer.

Parameters:

Name	Type	Description
`name`	string	The separated string to convert.

Returns:

Returns a copy of the string in camelCase.

Type: string

toNumber(value, default_value) <static>

Tries to convert the defined value to a valid number.

If the value is defined and conversion is valid, the converted value is returned. Otherwise the given default value is returned.

Parameters:

Name	Type	Description
`value`	number	The value to convert.
`default_value`	number	Returned if value is null, undefined or the conversion fails.

Returns:

Returns either the converted value or the given default.

Type: number

toNumberInRange(value, default_value) <static>

Tries to convert the defined value to a valid number within the given range.

If the value is defined and conversion is valid, the clamped converted value is returned. Otherwise the clamped default value is returned.

Parameters:

Name	Type	Description
`value`	number	The value to convert.
`default_value`	number	Returned if value is null, undefined or the conversion fails.

Returns:

Returns either the converted value or the given default.

Type: number

toSphericalCoordinates(vec) <static>

Calculates the distance, azimuth and altitude angle of the given direction vector and returns an [azi,alt,radius] array.

The azimuth angle is returned in radians CCW from the +X axis, and the altitude angle is in radians above the horizontal. The radius is set to the length of the vector.

Parameters:

Name	Type	Description
`vec`	THREE.Vector3	The direction vector.

Returns:

Returns the spherical angles as a [azi,alt,radius] array, with angles in radians.

Type: Array

toStringWithLeadingZeros(value [, size]) <static>

Formats a value with the given number of leading zeros.

This method limits the number of leading zeros to a maximum of 1024 in order to bullet-proof it against rogue input. If you need more than this number of leading zeros, use String.padStart() directly.

Parameters:

Name	Type	Argument	Default	Description
`value`	number			The value to convert to a string.
`size`	number	<optional>	2	The total number of characters required before the decimal place.

Returns:

Returns a string with zeros padding out to the required size.

Type: string

toStringWithPrecision(value, decimals) <static>

Formats a value with the given number of decimal places.

Parameters:

Name	Type	Description
`value`	number	The value to set the precision of.
`decimals`	number	The number of decimal places of precision.

Returns:

Returns a string formatted with the given precision.

Type: string

toStringWithPrecisionRange(value, min_decimals, max_decimals) <static>

Uses a minimum fixed minimum precision but allows greater accuracy up to a given maximum.

Parameters:

Name	Type	Description
`value`	number	The value to convert to a string.
`min_decimals`	number	The minimum number of decimal places of precision.
`max_decimals`	number	The maximum allowed number of decimal places of precision.

Throws:

Occurs if min_decimals or min_decimals are invalid or negative.
Type Error

Returns:

Returns a string formatted within the precision range.

Type: string

toVector3(obj, default_x, default_y, default_z) <static>

Tries to convert an object to a valid THREE.Vector3.

If the object is not a valid a valid THREE.Vector3 a new instance will be created with the default values.

Parameters:

Name	Type	Description
`obj`	object	The value to convert.
`default_x`	number	The default X axis component of a new vector if not valid.
`default_y`	number	The default Y axis component of a new vector if not valid.
`default_z`	number	The default Z axis component of a new vector if not valid.

Returns:

Returns either the valid vector or a new one with default values.

Type: object

toXML(jsonObj, rootTag) <static>

Converts a simple JSON-based object to an XML document.

Parameters:

Name	Type	Description
`jsonObj`	object	A simple JSON-based object.
`rootTag`	string	The name of the top-level XML tag.

Returns:

Returns an XML DOM object.

Type: object

translateBySphericalCoordinates(out, start, radius, azi, alt) <static>

Moves the out point a distance of radius from start at the given angles.

NOTE: This method changes values within the out parameter, however it is safe to use the same instance as start to change it in-place.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`start`	THREE.Vector3	The model position to begin from.
`radius`	number	The distance from the given start point.
`azi`	number	The horizontal azimuth angle, in radians anti-clockwise from +X axis.
`alt`	number	The vertical angle, in radians above the horizontal plane.

Returns:

Returns the out vector, or a new vector if null.

Type: THREE.Vector3

translateInVectorDirection(out, start, direction, distance) <static>

Calculates the position distance from start in the given vector direction.

NOTE: This method changes values within the out parameter, however it is safe to use the same instance as start to change it in-place.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`start`	THREE.Vector3	The model position to begin from.
`direction`	THREE.Vector3	The normalized vector giving the direction of movement.
`distance`	number	The scalar distance to move in the vector direction.

Returns:

Returns the out vector, or a new vector if null.

Type: THREE.Vector3

translateInVectorDirectionXY(out, start, direction, distance) <static>

Calculates a position distance from start in the given direction in the XY axis.

NOTE: This method changes values within the out parameter, however it is safe to use the same instance as start to change it in-place.

Parameters:

Name	Type	Description
`out`	THREE.Vector3	The vector to receive the result.
`start`	THREE.Vector3	The model position to begin from.
`direction`	THREE.Vector3	The normalized vector giving the direction of movement.
`distance`	number	The scalar distance to move in the vector direction.

Returns:

Returns the resulting out vector.

Type: THREE.Vector3

virtualBoundingClientRect( [x] [, y] [, w] [, h]) <static>

Creates a 'fake' dynamic bounding rectangle for use with Bootstrap popovers and tooltips that track virtual elements using Popper.js.

Parameters:

Name	Type	Argument	Description
`x`	number	<optional> <nullable>	The initial position of the rectangle in the page's X-axis, defaults to zero.
`y`	number	<optional> <nullable>	The initial position of the rectangle in the page's Y-axis, defaults to zero.
`w`	number	<optional> <nullable>	The initial width of the rectangle in the page's X-axis, defaults to zero.
`h`	number	<optional> <nullable>	The initial height of the rectangle in the page's Y-axis, defaults to zero.

Example

const virtual_rect = new PD.Utils.virtualBoundingClientRect();
 const virtual_element = {
     getBoundingClientRect: virtual_rect.getBoundingClientRectFn(),
 };

 const my_popover = new bootstrap.Popover(virtual_element, {
     content: 'Some Content',
     title: 'Title'
 });

 document.addEventListener('mousemove', (event) => {
     virtual_rect.setPos(event.clientX, event.clientY);
     my_popover.update();
 });

visibleTextColorAsCSS(color [, disabled]) <static>

Returns either black, gray or white as an '#RRGGBB' CSS color string, depending on the relative brightness of the given color.

This method is typically used to ensure that the text of a UI element with varying background color is always visible. It can handle different types of input color values, such as 0x2b362 and '#ffc49c' as well as simple [r,g,b] arrays or {r,g,b} objects whose elements or components are in the range (0 to 1).

As a result, this method must check the type of the argument before converting its value, which adds some overhead to the conversion.

If the given argument does not define a valid color, this method will return either white or gray if the disabled flag is true.

NOTE: The components or values of any given {r,g,b} color object or [r,g,b] color array must be in the range (0 to 1).

Parameters:

Name	Type	Argument	Description
`color`	any		A number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
`disabled`	boolean	<optional>	An optional flag indicating that the UI element is disabled.

Returns:

Returns a hexadecimal color string of the form '#RRGGBB'.

Type: string

wrapAt(value, min, max [, exclusive]) <static>

Utility function to wrap a value around specific bounds.

Parameters:

Name	Type	Argument	Description
`value`	number		The value to wrap if outside bounds.
`min`	number		The lowest allowable value in the range.
`max`	number		The highest allowable value in the range.
`exclusive`	number	<optional>	If true, the max value is not inclusive.

Returns:

Returns a value wrapped around to always be within the given bounds.

Type: number