API Docs

Class: AxisArray

PD. AxisArray

A helper class for defining local coordinate systems (LCS) for creating and manipulating [x,y,z] vector arrays.

An LCS defines an origin position and the local X, Y and Z axis as [x,y,z] vector arrays within the global cartesian coordinate system. The magnitude of each axis is typically 1, resulting in a direct spatial rotation followed by a translation. Any magnitude other than one represents a scaling in the corresponding axis.

    Z
     +           Y
      \         +
       \       /
        \  /\ /
         \/__/___
          \ / \ /
           +------------------+ X
        origin

This effectively creates a 3x3 row-major transformation matrix with a translation component. This can also be thought of as a 4x4 row-major matrix with the bottom row being [0, 0, 0, 1].

Rather than simply replicate other matrix classes, the aim of this class is to assist with the manual creation of 3D shapes and forms though the overt use of an LCS. This means explicitly setting up the direction of each axis and then creating vertices and edges using a series of moveTo() and moveBy() method calls. To support this, the class also stores a currentPos as a [x,y,z] vector array and updates it with each move.

new AxisArray( [origin] [, xAxis] [, yAxis] [, zAxis])

Creates a new local coordinate system using vector arrays.

If no arguments are given, the coordinates default to standard cartesian coordinates. You can also use null or undefined for any particular argument to use its default.

Parameters:
Name Type Argument Description
origin Array.<number> <optional>

The new origin of the local coordinate system, defaults to global origin.
xAxis Array.<number> <optional>

The new local X-axis, defaults to the global Cartesian X-axis.
yAxis Array.<number> <optional>

The new local Y-axis, defaults to the global Cartesian Y-axis.
zAxis Array.<number> <optional>

The new local Z-axis, defaults to the global Cartesian Z-axis.
Author:
  • drajmarsh

Members

:Object

bbox

A bounding box aligned with the local axis.

This object has a min and max property, each being an [x,y,z] vector array, that define the minimum and maximum corners of the box in local coordinates.

Type
  • Object
:Array.<number>

currentPos

A temporary position that can be moved around the coordinate system as an [x,y,z] vector array, defaults to [0,0,0].

Type
  • Array.<number>
:boolean

isAxisArray <readonly>

A flag identifying this object as a local coordinate system.

Type
  • boolean
:Array.<number>

origin

The origin of the local coordinate system as an [x,y,z] vector array, defaults to [0,0,0].

This is the reference position about which all other coordinates are taken.

Type
  • Array.<number>
:Array.<number>

xAxis

The relative X-axis within the local coordinate system as a normalized [dx,dy,dz] vector array, defaults to [1,0,0].

Type
  • Array.<number>
:Array.<number>

yAxis

The relative Y-axis within the local coordinate system as a normalized [dx,dy,dz] vector array, defaults to [0,1,0].

Type
  • Array.<number>
:Array.<number>

zAxis

The relative Z-axis within the local coordinate system as a normalized [dx,dy,dz] vector array, defaults to [0,0,1].

Type
  • Array.<number>

Methods

cartesianToLocal(point [, target])

Converts a 3D cartesian point in space to local coordinates.

Local coordinates are the three dimensions relative to the local origin and each of the three axis.

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

The Cartesian point to convert to local coordinates.
target Array.<number> <optional>

The vector array to receive the converted coordinates, defaults to a new array.
Returns:

Returns the target point.

Type
Array.<number>

clone()

Creates new local coordinates as a direct copy of these local coordinates.

Returns:

Returns a new local coordinate system.

Type
PD.AxisArray

computeBoundingBox(points)

Calculates the extents of the points in the current local axis.

Parameters:
Name Type Description
points Array.<number>

An array of one or more 3D point objects.
Returns:

Returns the shared computed bounding box.

Type
Array.<Array.<number>>

copy(from)

Copy the given local coordinates to these local coordinates.

Parameters:
Name Type Description
from PD.AxisArray

Another local coordinate system to copy.
Returns:

Returns these coordinates to support method chaining.

Type
PD.AxisArray

getCurrentPos()

Retrieves the current position of the local origin of the coordinate system.

The current position is a point that starts at the origin and is updated by the moveTo() and moveBy() method.

Returns:

Returns the local origin position.

Type
Array.<number>

getOrigin()

Retrieves the position of the local origin of the coordinate system.

The origin is the reference position about which all other coordinates are taken.

Returns:

Returns the local origin as an [x,y,z] vector array.

Type
Array.<number>

moveBy(dx [, dy] [, dz])

Moves the current position by a relative amount in each axis.

Parameters:
Name Type Argument Default Description
dx number 0

The distance along the local X-axis.
dy number <optional>
 0

The distance along the local Y-axis, defaults to zero.
dz number <optional>
 0

The distance along the local Z-axis, defaults to zero.
Returns:

Returns the current position.

Type
Array.<number>

moveOrigin(dx [, dy] [, dz])

Repositions the origin by a distance in each axis relative to itself.

This method allows you to move the origin within the local coordinate system. To avoid confusion, the current position is also moved to that it maintains its position relative to the origin. If you need to set the origin to a position in absolute global Cartesian coordinates, use the setOrigin() method instead.

Parameters:
Name Type Argument Default Description
dx number 0

The distance to move in the local X-axis.
dy number <optional>
 0

The distance to move in the local Y-axis, defaults to zero.
dz number <optional>
 0

The distance to move in the local Z-axis, defaults to zero.
Returns:

Returns the new origin as an [x,y,z] vector array.

Type
Array.<number>

movePointBy(pos [, dx] [, dy] [, dz])

Moves the given position in each axis relative to itself.

Parameters:
Name Type Argument Default Description
pos Array.<number>

The {x,y,z} point to set the position of.
dx number <optional>
 0

The distance along the local X-axis, defaults to zero.
dy number <optional>
 0

The distance along the local Y-axis, defaults to zero.
dz number <optional>
 0

The distance along the local Z-axis, defaults to zero.
Returns:

Returns the pos argument.

Type
Array.<number>

movePointByX(pos, dx)

Moves the given position in the U-Axis relative to itself.

Parameters:
Name Type Description
pos Array.<number>

The point to receive the new position.
dx number

The distance along the local X-axis.
Returns:

Returns the pos argument.

Type
Array.<number>

movePointByY(pos, dy)

Moves the given position in the V-Axis relative to itself.

Parameters:
Name Type Description
pos Array.<number>

The point to set the position of.
dy number

The distance along the local Y-axis.
Returns:

Returns the pos argument.

Type
Array.<number>

movePointByZ(pos, dz)

Moves the given position in the W-Axis relative to itself.

Parameters:
Name Type Description
pos Array.<number>

The point to set the position of.
dz number

The distance in the Z-axis.
Returns:

Returns the pos argument.

Type
Array.<number>

movePointTo(pos, x [, y] [, z])

Calculates an absolute position in the W-Axis relative to the origin.

Parameters:
Name Type Argument Default Description
pos Array.<number>

The point to receive the new position.
x number 0

The distance from the origin in the local X-axis.
y number <optional>
 0

The distance from the origin in the local Y-axis, defaults to zero.
z number <optional>
 0

The distance from the origin in the local Z-axis, defaults to zero.
Returns:

Returns the pos argument.

Type
Array.<number>

movePointToX(pos, x)

Calculates an absolute position in the U-Axis relative to the origin.

Parameters:
Name Type Description
pos Array.<number>

The point to receive the new position.
x number

The distance from the origin in the local X-axis.
Returns:

Returns the pos argument.

Type
Array.<number>

movePointToY(pos, y)

Calculates an absolute position in the V-Axis relative to the origin.

Parameters:
Name Type Description
pos Array.<number>

The point to receive the new position.
y number

The distance from the origin in the local Y-axis.
Returns:

Returns the pos argument.

Type
Array.<number>

movePointToZ(pos, z)

Calculates an absolute position in the W-Axis relative to the origin.

Parameters:
Name Type Description
pos Array.<number>

The point to receive the new position.
z number

The distance from the origin in the local Z-axis.
Returns:

Returns the pos argument.

Type
Array.<number>

moveTo(x [, y] [, z])

Sets the current position relative to the origin.

Parameters:
Name Type Argument Default Description
x number 0

The distance from the origin in the local X-axis.
y number <optional>
 0

The distance from the origin in the local Y-axis, defaults to zero.
z number <optional>
 0

The distance from the origin in the local Z-axis, defaults to zero.
Returns:

Returns the current position.

Type
Array.<number>

peekState()

Sets the current coordinate system state to the last state pushed onto the stack.

NOTE: This method can only be called when bookended between calls to pushState() and popState(). It does not affect the stack in any way, so may be called any number of times to reset the current position and origin to the state they were when the last pushState() call was made.

Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

popState()

Restores the last LCS state pushed onto the stack.

NOTE: It is important that every call to popState() have a corresponding preceding call to pushState() to ensure the stack is not empty.

Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

pushState()

Stores the current LCS state on the stack.

NOTE: It is important that every call to pushState() has a corresponding subsequent call to popState() to ensure the stack does not grow too large and overflow.

Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

reset()

Resets the local coordinate system to the global origin ([0,0,0]) and each axis to the corresponding global Cartesian axis.

Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

restoreOrigin()

Repositions the origin back to its original position.

The original origin position is the one set using the last call to the reset() method.

Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

restoreSnapshot()

Restores the last snapshot copy of the current coordinate system.

The snapshot system does not use a stack and is only one level deep, which means that you can call the restoreSnapshot() method multiple times to return to the last snap-shotted copy.

To create a stored snapshot of the current coordinate system, simply call the storeSnapshot() method.

Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

rotateByCartesianAxis(radians [, axis])

Rotates the axis of the local coordinate system by an angle around a major cartesian axis.

This method just affects the direction of each axis, not the current position or origin.

Parameters:
Name Type Argument Default Description
radians number

The angle of rotation, in radians.
axis PD.AXIS <optional>
 0

The axis to rotate about (1:X, 2:Y, 3|0:Z), defaults to the positive Z-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

rotateByLocalAxis(radians [, axis])

Rotates the axis of the local coordinate system by an angle.

This method just affects the direction of each axis, not the current position or origin.

NOTE Rotations are cumulative. If you call the same rotation method twice with the same values, it will rotate by twice the given angle.

Parameters:
Name Type Argument Default Description
radians number

The angle of rotation, in radians.
axis PD.AXIS <optional>
 0

The axis to rotate about (1:X, 2:Y, 3|0:Z), defaults to the local Z-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

rotateLocalX(radians)

Rotates all axis by the given angle around the current local X axis.

This method just affects the direction of each axis, not the current position or origin.

Parameters:
Name Type Description
radians number

The angle of rotation, in radians.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

rotateLocalY(radians)

Rotates the axis by the given angle around the current local Y axis.

This method just affects the direction of each axis, not the current position or origin.

Parameters:
Name Type Description
radians number

The angle of rotation, in radians.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

rotateLocalZ(radians)

Rotates the axis by the given angle around the current local Z-axis.

This method just affects the direction of each axis, not the current position or origin.

Parameters:
Name Type Description
radians number

The angle of rotation, in radians.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

rotateX(radians)

Rotates the axis by the given angle around the global Cartesian X-axis.

This method just affects the direction of each axis, not the current position or origin.

Parameters:
Name Type Description
radians number

The angle of rotation, in radians.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

rotateY(radians)

Rotates the axis by the given angle around the global Cartesian Y-axis.

This method just affects the direction of each axis, not the current position or origin.

Parameters:
Name Type Description
radians number

The angle of rotation, in radians.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

rotateZ(radians)

Rotates the axis by the given angle around the global Cartesian Z-axis.

This method just affects the direction of each axis, not the current position or origin.

Parameters:
Name Type Description
radians number

The angle of rotation, in radians.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

scaleBy( [scale])

Applies a scaling factor to each local axis.

Parameters:
Name Type Argument Description
scale number | Array.<number> <optional>

A scale factor or [sx,sy,sz] vector array to scale local axis by, defaults to 1.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

scaleIndexedPoints(indices, vertices, scale [, negAxisScale])

Scales a set of indexed points about a local origin and X, Y and Z axis.

Rather than the points consisting of an array of coordinates, indexed points consist of an array of indexes into a separate array of vertices.

You can use the PD.AxisArray to set up a local origin point and re-orient the local X, Y and Z to whatever direction you want. The scale factors you provide are then applied in the direction of these local axis and about the local origin.

This method also allows you to use two separate sets of scaling factors. If you only provide one set, it will be used as the default. However, providing a second set allows you to apply a different scale when a point is on the negative side of the origin compared to the positive side.

           +Z
             +          +Y
              \         +
               \       /
                \  /\ /     [scale]
                 \/__/___
                  \ / \ /
   -X  -  -  -  -  +----------------+ +X
                origin
                 .   '
   [scaleNeg]   .     '
               .       '
              .         '
             .           -Z
           -Y
Parameters:
Name Type Argument Description
indices Array.<number>

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

An array of [x,y,z] coordinate arrays.
scale number | Array.<number>

The scale factor or an [sx,sy,sz] vector array to scale in local axis, defaults to 1.
negAxisScale number | Array.<number> <optional>

A optional scale factor or [sx,sy,sz] vector array to apply when points are in the negative local axis, defaults to scalePos.

scalePoints(points, scale [, negAxisScale])

Scales a set of points about a local origin and X, Y and Z axis.

You can use the PD.AxisArray to set up a local origin point and re-orient the local X, Y and Z to whatever direction you want. The scale factors you provide are then applied in the direction of these local axis and about the local origin.

This method also allows you to use two separate sets of scaling factors. If you only provide one set, it will be used as the default. However, providing a second set allows you to apply a different scale when a point is on the negative side of the origin compared to the positive side.

           +Z
             +          +Y
              \         +
               \       /
                \  /\ /     [scale]
                 \/__/___
                  \ / \ /
   -X  -  -  -  -  +----------------+ +X
                origin
                 .   '
   [scaleNeg]   .     '
               .       '
              .         '
             .           -Z
           -Y
Parameters:
Name Type Argument Description
points Array.<Array.<number>>

An array of [x,y,z] coordinate arrays to scale in place.
scale number | Array.<number>

The scale factor or an [sx,sy,sz] vector array to scale in local axis, defaults to 1.
negAxisScale number | Array.<number> <optional>

A optional scale factor or [sx,sy,sz] vector array to apply when points are in the negative local axis, defaults to scalePos.
Returns:

Returns the points array with modified coordinates.

Type
number

scalePointsXY(points, fromZ, toZ, scaleXY [, easing])

Scales the shape in the local X and Y axis by an amount that varies over a range within the local Z axis.

If the from and to values are both in the range 0 to 1, then they are considered to be fractions of the size of the shape in the local Z axis. If either value is outside the range 0 to 1, then they are both considered to be in absolute model units along the axis.

If the scale is given as a single number, it represents the maximum scale at the to point on the axis, varying from 1 at the from point. If given as a [fromScale, toScale] array, you can specify the scales to use at both the from and to points. You can specify an easing function if you wish to make it a non-linear variation.

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

An array of [x,y,z] coordinate arrays to scale in place.
fromZ number

A value on the local Z axis to start scaling from, in model units.
toZ number

A value on the local Z axis to finish scaling at, in model units.
scaleXY number | Array.<number>

The scale at or above the to value, or a [fromScale,toScale] array, defaults to 1 (no scale).
easing function <optional>

An easing function to use, defaults to PD.Easing.linear.
Returns:

Returns the modified points.

Type
Array.<Array.<number>>

scaleTo( [scale])

Sets the scaling factor for each local axis.

Parameters:
Name Type Argument Description
scale number | Array.<number> <optional>

A scale factor or [sx,sy,sz] vector array to scale local axis to, defaults to 1.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

set( [origin] [, xAxis] [, yAxis] [, zAxis])

Sets or resets the components of the local coordinate system.

This method sets both the actual and stored origin, and resets the current position to the new origin. If no arguments are given, the coordinates will defaults to normal cartesian coordinates. You can also use null for any particular argument to use its default.

Parameters:
Name Type Argument Description
origin Array.<number> | undefined <optional>

The new origin of the local coordinate system, defaults to global origin.
xAxis Array.<number> | undefined <optional>

The new local X-axis, defaults to global Cartesian X-axis.
yAxis Array.<number> | undefined <optional>

The new local Y-axis, defaults to global Cartesian Y-axis.
zAxis Array.<number> | undefined <optional>

The new local Z-axis, defaults to global Cartesian Z-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

setByAxis( [origin] [, axis])

Aligns the local coordinate system with the given global Cartesian axis.

This method sets both the actual and stored origin, and resets the current position to the new origin. If no arguments are given, the coordinates will defaults to normal global Cartesian coordinates. You can also use null for any particular argument to use its default.

Parameters:
Name Type Argument Default Description
origin Array.<number> | null <optional>
 null

The new origin of the local coordinate system, defaults to global origin.
axis PD.AXIS <optional>
 0

The new local Z axis (1:X, 2:Y, 3|0:Z), default to the global Cartesian Z-axis (0).
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

setByThreePoints(p1, p2, p3)

Aligns the the local coordinate system. with the given three points.

This method sets the origin to p2, the X axis to (p2 -> p3), the Y axis to (p2 -> p1), and the Z axis axis to the cross product the X and Y axis.

    Z           Y
     +         + p1
      \       /
       \  /\ /
        \/  /___
         \ /   /
          +------------------+ X
         p2                  p3
Parameters:
Name Type Description
p1 Array.<number>

A point on the +Y-axis.
p2 Array.<number>

The new origin point.
p3 Array.<number>

A point on the +X-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

setByTwoPointsAndNormal(p1, p2 [, normal])

Aligns the local coordinate system with a vector between two points and an opposing normal.

 normal         Y
     +         :
      \       :
       \  /\ :
        \/  :___
         \ :   /
          +------------------+ X
         p1                  p2

This method sets the origin to p1, the X axis to (p1 -> p2), the Z axis axis to the given normal, and the Y axis to the cross product thew X and Z axis.

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

The origin of the new axis.
p2 Array.<number>

A point somewhere on the new +X-axis.
normal Array.<number> <optional>

The new local +Z-axis, defaults to global Cartesian Z-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

setOrigin(x, y, z)

Repositions the origin to an absolute position in global model space.

To avoid confusion, the current position is also moved to that it maintains its position relative to the origin. If you need to set the origin to a position relative to itself, use the moveOrigin() method instead.

Parameters:
Name Type Default Description
x number 0

The position of the origin in the global Cartesian X-axis.
y number 0

The position of the origin in the global Cartesian Y-axis.
z number 0

The position of the origin in the global Cartesian Z-axis.
Returns:

Returns the new origin as an [x,y,z] vector array.

Type
Array.<number>

setOriginAndReset( [origin])

Sets the origin of the local coordinate system.

This method sets both the actual and stored origin, and resets the current position to the new origin. If no argument is given, the origin will be set to the current position.

Parameters:
Name Type Argument Description
origin Array.<number> | null <optional>

The new origin of the local coordinate system, defaults to global origin.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

storeOrigin()

Stores the current origin so it can be restored at some later time.

The stored origin position is automatically stored whenever you use and od the setXXX, so the restoreOrigin() method will return the origin to that position without having to call this method. Thus, you only need to use this method if you wish to store any changes that you have made to the origin using the moveOrigin() or moveOriginTo() methods.

Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

storeSnapshot()

Stores a copy of the current coordinate system.

The snapshot system does not use a stack and is only one level deep, so the stored snapshot will be overwritten each time the storeSnapshot() method is called. This can be useful in situations where you want to store the current state, and then restore it multiple times after a series of operations.

To restore the current coordinate system to the stored snapshot, call the restoreSnapshot() method.

Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

swapAxis(axis)

Swaps the two axis of the local coordinate system in the plane of the given axis.

This method just affects the direction of each axis, not the current position or origin.

To swap the X and Y axis, use 3:PD.AXIS.Z_POS or -3:PD.AXIS.Z_NEG as the argument. To swap the Y and Z axis, use 1:PD.AXIS.X_POS or -1:PD.AXIS.X_NEG as the argument. To swap the X and Z axis, use 2:PD.AXIS.Y_POS or -2:PD.AXIS.Y_NEG as the argument. To swap the axis back, simply use the same call with the same argument.

Parameters:
Name Type Description
axis PD.AXIS

The axis to of the plane to swap in.
Returns:

Returns this LCS to support method chaining.

Type
PD.AxisArray

translatePoints(points, offset)

Applies a local [dx,dy,dz] translation to the given points.

Parameters:
Name Type Description
points Array.<Array.<number>>

An array of [x,y,z] coordinate arrays to scale in place.
offset Array.<number>

A [x,y,z] vector array to move the points by, in the local axis.
Returns:

Returns the points array with modified coordinates.

Type
number