API Docs

Class: LocalCoordinates

PD. LocalCoordinates

Sets up a new local coordinate system (LCS) with its own origin and axis.

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

Creates a new local coordinate system (LCS).

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 Default Description
origin THREE.Vector3 | null <optional>
 null

The new origin of the local coordinate system, defaults to world origin.
xAxis THREE.Vector3 | null <optional>
 null

The new local X-axis within the local coordinate system, defaults to world X-axis.
yAxis THREE.Vector3 | null <optional>
 null

The new local Y-axis within the local coordinate system, defaults to world Y-axis.
zAxis THREE.Vector3 | null <optional>
 null

The new local Z-axis within the local coordinate system, defaults to world Z-axis.
Author:
  • drajmarsh

Members

:THREE.Box3

bbox

A bounding box aligned with the local axis.

Type
  • THREE.Box3
:THREE.Vector3

currentPos

A temporary position that can be moved around the coordinates.

This is especially useful when generating display geometry as meshes store positions in buffer arrays, so effectively snapshot the x, y and z components of any vectors that are added as vertices. Thus, you can use

Type
  • THREE.Vector3
Example
const coords = new PD.LocalCoordinates();

shell.addQuad(
    shell.addVertex(coords.getCurrentPos()),
    shell.addVertex(coords.moveBy(1000.0, 150.0, 0)),
    shell.addVertex(coords.moveBy(0.0, 0.0, 2400.0)),
    shell.addVertex(coords.moveBy(-1000.0, -150.0, 0)),
    false
);

mesh.addQuad(
    mesh.addVertex(coords.moveTo(0.0, 0.0, 0.0),
    mesh.addVertex(coords.moveBy(1000.0, 150.0, 0)),
    mesh.addVertex(coords.moveBy(0.0, 0.0, 2400.0)),
    mesh.addVertex(coords.moveBy(-1000.0, -150.0, 0))
);
:boolean

isLocalCoordinates <readonly>

A flag identifying this object as a local coordinate system.

Type
  • boolean
:THREE.Vector3

origin

The origin of the local coordinate system.

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

Type
  • THREE.Vector3
:THREE.Vector3

xAxis

The relative X-axis within the local coordinate system.

Type
  • THREE.Vector3
:THREE.Vector3

yAxis

The relative Y-axis within the local coordinate system.

Type
  • THREE.Vector3
:THREE.Vector3

zAxis

The relative Z-axis within the local coordinate system.

Type
  • THREE.Vector3

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 Description
point THREE.Vector3

The Cartesian point to convert to local coordinates.
target THREE.Vector3

The vector object to receive the converted coordinates.
Returns:

Returns the target point.

Type
THREE.Vector3

clone()

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

Returns:

Returns a new local coordinate system.

Type
PD.LocalCoordinates

computeBoundingBox(points)

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

Parameters:
Name Type Description
points Array

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

Returns the shared computed bounding box.

Type
THREE.Box3

copy(from)

Copy the given local coordinates to these local coordinates.

Parameters:
Name Type Description
from PD.LocalCoordinates

Another local coordinate system to copy.
Returns:

Returns these coordinates to support method chaining.

Type
PD.LocalCoordinates

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
THREE.Vector3

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 position.

Type
THREE.Vector3

moveArrayBy(array, dx [, dy] [, dz])

Moves the given vector array in each axis relative to itself.

Parameters:
Name Type Argument Default Description
array Array

The [x,y,z] point to set the position of.
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 coord argument.

Type
Array

moveArrayTo(array, x [, y] [, z])

Calculates an absolute position for the array relative to the origin.

Parameters:
Name Type Argument Default Description
array Array

The [x,y,z] point to set the position of.
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 array argument.

Type
Array

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
THREE.Vector3

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. If you need to set the origin to a position in absolute world 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.

Type
THREE.Vector3

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

Moves the given position in each axis relative to itself.

Parameters:
Name Type Argument Default Description
pos THREE.Vector3

The {x,y,z} point to set the position of.
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 pos argument.

Type
THREE.Vector3

movePointByX(pos, dx)

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

Parameters:
Name Type Description
pos THREE.Vector3

The point to receive the new position.
dx number

The distance along the local X-axis.
Returns:

Returns the pos argument.

Type
THREE.Vector3

movePointByY(pos, dy)

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

Parameters:
Name Type Description
pos THREE.Vector3

The point to set the position of.
dy number

The distance along the local Y-axis.
Returns:

Returns the pos argument.

Type
THREE.Vector3

movePointByZ(pos, dz)

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

Parameters:
Name Type Description
pos THREE.Vector3

The point to set the position of.
dz number

The distance in the Z-axis.
Returns:

Returns the pos argument.

Type
THREE.Vector3

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

Calculates an absolute position relative to the origin.

Parameters:
Name Type Argument Default Description
pos THREE.Vector3

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
THREE.Vector3

movePointToX(pos, x)

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

Parameters:
Name Type Description
pos THREE.Vector3

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
THREE.Vector3

movePointToY(pos, y)

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

Parameters:
Name Type Description
pos THREE.Vector3

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
THREE.Vector3

movePointToZ(pos, z)

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

Parameters:
Name Type Description
pos THREE.Vector3

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
THREE.Vector3

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
THREE.Vector3

negate()

Reverses the direction of each axis in the local coordinate system.

Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

peekPositions()

Sets the current position and origin to the last position and origin pushed onto the stack.

NOTE: This method can only be called when bookended between calls to pushPositions() and popPositions(). 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 pushPositions() call was made.

Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

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.LocalCoordinates

popPositions()

Restores the last position and origin pushed onto the stack.

NOTE: This method pops an entry off an internal stack, so it is very important that every call to popPositions() have a corresponding preceding call to pushPositions() to ensure the stack is not empty.

Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

popState()

Restores the last coordinate 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.LocalCoordinates

pushPositions()

Stores the current position and origin on the stack.

NOTE: This method pushes an entry onto an internal stack, so it is very important that every call to pushPositions() have a corresponding subsequent call to popPositions() to ensure the stack does not grow too large.

Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

pushState()

Stores the current coordinate system 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.

Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

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.LocalCoordinates

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.LocalCoordinates

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.LocalCoordinates

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, defaults to the positive Z-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

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.

Parameters:
Name Type Argument Default Description
radians number

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

The axis to rotate about, defaults to the local Z-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

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.LocalCoordinates

rotateLocalY(radians)

Rotates all 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.LocalCoordinates

rotateLocalZ(radians)

Rotates all 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.LocalCoordinates

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.LocalCoordinates

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.LocalCoordinates

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.LocalCoordinates

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 Default Description
origin THREE.Vector3 | null <optional>
 null

The new origin of the local coordinate system, defaults to world origin.
xAxis THREE.Vector3 | null <optional>
 null

The new local X-axis within the local coordinate system, defaults to world X-axis.
yAxis THREE.Vector3 | null <optional>
 null

The new local Y-axis within the local coordinate system, defaults to world Y-axis.
zAxis THREE.Vector3 | null <optional>
 null

The new local Z-axis within the local coordinate system, defaults to world Z-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

setByAxis( [origin] [, axis])

Aligns the local coordinate system with the given 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 Cartesian coordinates. You can also use null for any particular argument to use its default.

Parameters:
Name Type Argument Default Description
origin THREE.Vector3 | null <optional>
 null

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

The new W axis, default to Z-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

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.

    Y
  p1 +
      \       Z
       \     /
        \   /__
         \ /  /
          +--+---------------+ X
         p2                  p3
Parameters:
Name Type Description
p1 THREE.Vector3

A point on the Y axis.
p2 THREE.Vector3

The origin point.
p3 THREE.Vector3

A point on the Z axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

setByTwoPointsAndNormal(p1, p2 [, normal])

Aligns the local coordinate system with a vector and normal.

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 THREE.Vector3

The start point on the line.
p2 THREE.Vector3

The second point on the line.
normal THREE.Vector3 <optional>

The new local Z-axis within the local coordinate system, defaults to world Z-axis.
Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

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 Argument Default Description
x number | THREE.Vector3 0

The position of the origin in the global Cartesian X-axis, or a point object.
y number <optional>
 0

The position of the origin in the global Cartesian Y-axis.
z number <optional>
 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 THREE.Vector3 | null <optional>

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

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

storeOrigin()

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

The origin position set during the last call to the reset() method is automatically stored and 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() method.

Returns:

Returns this LCS to support method chaining.

Type
PD.LocalCoordinates

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.LocalCoordinates

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 PD.AXIS.Z_POS or PD.AXIS.Z_NEG as the argument. To swap the Y and Z axis, use PD.AXIS.X_POS or PD.AXIS.X_NEG as the argument. To swap the X and Z axis, use PD.AXIS.Y_POS or 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.LocalCoordinates