API Docs

Class: PathPoint

PD. PathPoint

A path point is similar to a normal PD.Point but also defines how it connects to the previous and next points in a path.

Path points are used to mark a change of direction or any other significant property that may occur along a continuous path. Paths are primarily used as the basis for constructing shapes and other geometry.

The critical thing to understand about paths and path points is that they do not necessarily mark the actual edge or outer boundary of a shape. Rather, they mark a reference line that the shape follows or is based on. The actual shape may be offset from the path, and may even have multiple offsets and curves.

Thus, the role of the path point is to store enough path-based trigonometric information to be able to calculate and generate those actual edges and boundaries of a shape, as well as the geometric detail of the path point itself and the path segment between it and the next path point. Moreover, it provides an extensible basis for more sophisticated path points capable of a range of intelligent behaviours and dynamic adaptions.

This path-based trigonometric information is stored as a series of vector and numeric properties, as detailed in the illustration below.

                          .next
                           _^   ^
         angle       .  '   |   |
                  .         |   | .outVec4
               A        . - |
            .   \_  . '     |---------- .outNormal
                 .\__  a    |__|
        .      .     \_     |
             .     a   \__  |           A = 2a
      .     .             \_|
  .prev >-------------------+_this
                   |_|        \__
   .inVec4 ----->  |             \_
                   |               \__
              .inNormal            .normal

new PathPoint( [x] [, y] [, z] [, config])

Creates a new path point.

Parameters:
Name Type Argument Default Description
x number | THREE.Vector3 <optional>
 0

The position in the X-axis, defaults to zero.
y number <optional>
 0

The position in the Y-axis, defaults to zero.
z number <optional>
 0

The position in the Z-axis, defaults to zero.
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
pos Array.<number> <optional>

An optional vector array to override the x, y and z values.
path PD.Path <optional>

An optional path that this path point belongs to, if any.
curve PD.Curve <optional>

An optional curve to follow when travelling to the next joint.
height number <optional>

An optional extrusion height of any shell facets generated by this path point.
projection number <optional>

An optional additional offset added to the outer edge of the element.
outerEdgeOffset number <optional>

An optional displacement distance of the outside face from the path, defaults to construction.
innerEdgeOffset number <optional>

An optional displacement distance of the inside face from the path, defaults to construction.
flags number <optional>

An optional set of bitwise flags describing boolean properties.
Author:
  • drajmarsh

Extends

Classes

Cache

Members

:number

angle

The angle between the incoming and outgoing lines, in degrees.

  .prev >-------------------+_ this
            '                  \_
             '                    \_
              '        angle         \_
                '                       \_
                   .                 .     \_
                      '  .  _  .  '         .next

This requires both prev and next connections, otherwise it will always be 180 (assuming it to be part of straight line). It stores the internal angle where zero means a U-turn, (+/-)90 is a right-angle joint and (+/-)180.0 means the path continues straight.

Type
  • number
:Map

attributes

A map to store additional properties for the point.

You are encouraged to use the getAttribute(), setAttribute() and deleteAttribute() methods when working with attributes as this will future-proof your code against any changes in how point attributes are stores.

In addition, this class provides a number of getter/setter accessors for frequently used attributes, which means that you can use them as you would normal properties. These point attributes include:

NAME TYPE DESCRIPTION
selected boolean Whether or not the point is selected by the user.
junction BIM.Junction The parent junction that generated this point.
curveId number An integer indicating that point is part of a curve.
normal THREE.Vector3 The surface normal direction.
tangent THREE.Vector3 The average between incoming and outgoing vectors.
binormal THREE.Vector3 The cross-product of the normal and tangent.
uv THREE.Vector2 The texture coordinate at the point.
color THREE.Color The vertex color at the point.
refPos THREE.Vector3 A copy of the point's position at some previous time.
Type
  • Map
Inherited From:
Overrides:
:THREE.Vector3|null

binormal

Stores a tangent direction at the given point.

Tangents on points are mainly used when generating and displaying curved polylines and surfaces.

As not all model points require a binormal direction, this is actually a getter/setter for a vector object that is dynamically created as an attribute when first set. To remove this attribute from the attribute list, set its value to null.

Type
  • THREE.Vector3 | null
Inherited From:
Overrides:
:THREE.Color|null

color

Stores a color value for the given point.

Color values on points are mainly used for rendering.

As not all points require a color value, this is actually a getter/setter for a color value that is dynamically created as an attribute when first set. To remove this attribute from the attribute list, set its value to null.

Type
  • THREE.Color | null
Inherited From:
Overrides:
:number

cornerInset

The calculated inset of the internal face along the path line.

This is computed from the angles between the previous and next path path points, as well as the innerEdgeOffset (or outerEdgeOffset if the path point is concave relative to the host path). It is used as a sideways position limit for windows and doors to ensure that they will actually fit within the depth of their host wall, and by columns, railing posts and stair landings to ensure that the geometry of railings and other types of infill will not overlap at very acute corner angles.

                                       __..--'\
     __..--''\                 __..--''\       \ == depth
    |    :    \ < depth       |    :    \       \
    |  - + - - +              |  - + - - + - - - + -
    |    :    / < depth       |    :    /       /
     ''--..__/                 ''--..__/       / == depth
                                   :   ''--.._/  :
                                   :             :
                                 - + - - - - - - + -
                                   : cornerInset :
Type
  • number
:PD.Curve|null

curve

The curve to follow when travelling to the next joint, if any.

If no curve is assigned, the path travels in a straight line to the next path point in the path. If a curve is assigned, the path follows the segments defined in the curve's own path.

Type
:number

curveId

Stores an integer identifier indicating that the given point is part of a sequence of points defining a curve.

This value is typically set when a path containing a curve is offset to generate a new path. Each point on the same curve is assigned the same positive integer curve ID, which can then be used to determine the starting and ending points of each curve. When this value is set, the associated PD.Curve instance can be found using the point.junction?.curve property.

If the value of this property is 0 or negative, then the point is not part of a curve.

Type
  • number
Inherited From:
Overrides:
:boolean

hasChanged

Whether or not the path point's properties have changed since last update.

Type
  • boolean
:boolean

hasCurve <readonly>

Whether or not the path segment is curved.

Type
  • boolean
:boolean

hasEndPlane

Whether or not the path point has a different end plane.

Type
  • boolean
:number

height

The height at this path point.

Not all path points use height, so this is a getter/setter for an attribute of the same name. This is typically only used when extruding geometry.

Type
  • number
:THREE.Vector3

inNormal

A vector giving the normal direction of the previous line.

NOTE: This is based solely on the incoming path line that joins the reference positions of this and the previous path point, and therefore may not be the same as the actual face normal. However it is very useful for internal processing and displaying highlight lines.

PLAN VIEW               this.next
                            ^
                            |
                            |
 this.prev >----------------+
                   |_|     this
                   |
                   |
               inNormal
Type
  • THREE.Vector3
:PD.ScaledVector

inVec4

A scaled vector from the previous point.

This is calculated as the vector from the previous joint to this one. The x, y and z components are a normalised direction vector, with scale being the absolute distance from the last joint.

    this.prev          this
        +------->-------+
        - - - - - - - - > inVec4
      (from)           (to)
Type
:number

innerEdgeOffset

Stores the displacement distance of the inside face from the path.

This value is used by elements such as walls, slabs, columns, railings and stairs, all of them elements that follow a PD.Path but whose surfaces are slightly offset from the path. It defines the distance that any inner surfaces will be positioned away from the path in the OPPOSITE DIRECTION of the outgoing segment normal (outNormal). As a result, this value is typically positive if the path is somewhere between the inner and outer edges, as shown below.

            outNormal
                ^
                :
  - - - - - - - - - - - - - - -  outerEdgeOffset
                :
  +--- PATH -------------------> outVec4

  - - - - - - - - - - - - - - -  innerEdgeOffset

In the specific cases of walls and columns, this value is automatically set to the inner offset of the BIM.Construction assigned to them and cannot be overridden without changing the construction.

Type
  • number
:boolean

isColinear

Whether or not the path point is colinear with its previous and next path points.

Type
  • boolean
:boolean

isConcave

Whether or not the cross-product is inverted compared to others in the path.

Type
  • boolean
:boolean

isPathPoint <readonly>

A flag identifying this object as a path point.

Type
  • boolean
:boolean

isPoint <readonly>

A flag identifying this object as a 3D point.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isSmooth

Whether or not the path point's curve should maintain a smooth change in direction.

When set to true, any Bezier or NURBS curve at the path point will smoothly transition the path direction using control points that can only move along the tangent between incoming and outgoing vectors. When false, control points can move independently.

Type
  • boolean
:boolean

isSymmetric

Whether or not the magnitude of smooth control points are reflected equally.

Type
  • boolean
:boolean

isVariableWidth

Whether material changes are gradual instead of sudden or stepped.

Type
  • boolean
:boolean

isVirtual

Whether the path point was added to its path dynamically rather than manually by the user.

Type
  • boolean
:BIM.Junction|null

junction

Stores the parent junction that generated this point.

This is typically set when shell geometry is generated directly from an element path. It is used when post-processing the geometry to allocate selectable facets to junctions.

As not all model points have a parent junction, this is actually a getter/setter for an attribute value. To remove this attribute from the attribute map, set its value to null.

Type
Inherited From:
Overrides:
:PD.PathPoint|null

next

A reference to the next path point in the path that this is connected to.

This value is set and managed by the parent path.

Type
:THREE.Vector3

normal

A normalised vector as the average between incoming and outgoing normals.

This vector defines the direction of offset projection at the path point, and considers both the inNormal and outNormal vectors as well as differences in offset distance in each direction due to changes in material thickness.

NOTE: This property overrides the getter/setter in the PD.Point class.

                        this.next
                           _^
         A = 2a      .  '   |
                  .         |
               A        . - |
            .   \_  . '     |
                 .\__  a    |
        .      .     \_     |
             .     a   \__  |
      .     .             \_|
 this.prev >----------------+_this
                              \__
                                 \_
                                 normal
Type
  • THREE.Vector3
Inherited From:
Overrides:
:number

orientation

Stores an orientation angle around the local Z axis.

As not all path points use orientation, this is a getter/setter for an attribute of the same name. This is typically only used on elements whose BIM.Element#usesJunctionOrientation method returns true.

Type
  • number
:THREE.Vector3

outNormal

A vector giving the normal direction of the next line.

NOTE: This is based solely on the outgoing path line that joins the reference positions of this and the next path point, and therefore may not be the same as the actual face normal. However it is very useful for internal processing and displaying highlight lines.

PLAN VIEW       this.next
                    +
                    |
                    ^
                    |---------- outNormal
                    |__|
                    |
                    |
 this.prev >--------+
                   this
Type
  • THREE.Vector3
:PD.ScaledVector

outVec4

A scaled vector to the next point.

This is calculated as the vector from this joint to the next one. The x, y and z components are a normalised direction vector, with scale being the absolute distance to the next joint.

PLAN VIEW           (to)
                 this.next
                      +    ^
                      |    :
                      |    :
                      ^    : outVec4
                      |    :
                      |    :
    >-----------------+
                     this
                    (from)
Type
:number

outerEdgeOffset

Stores the displacement distance of the outside face from the path.

This value is used by elements such as walls, slabs, columns, railings and stairs, all of them elements that follow a PD.Path but whose surfaces are slightly offset from the path. It defines the distance that outer surfaces will be positioned away from the path in the DIRECTION of the outgoing path segment normal (outNormal). As a result, this value is typically positive if the path is somewhere between the inner and outer edges, as shown below.

            outNormal
                ^
                :
  - - - - - - - - - - - - - - -  outerEdgeOffset
                :
  +--- PATH -------------------> outVec4

  - - - - - - - - - - - - - - -  innerEdgeOffset

In the specific cases of walls and columns, this value is automatically set to the outer offset of the BIM.Construction assigned to them and cannot be overridden without changing the construction.

Type
  • number
:PD.Path|null

path

The path that this path point belongs to, if any.

Type
:PD.PathPoint|null

prev

A reference to the previous path point in the path that this is connected to.

This value is set and managed by the parent path.

Type
:number

projection

An additional offset added to the edge of an offset profile.

Projections are used to make small adjustments to the profiles of area elements such as slabs, ceilings and roof shapes, as well as to the positions of elements that follow an open path such as fixtures, furniture and appliances. Wall and space elements do not use a path point's projection.

Type
  • number
:THREE.Vector3|null

refPos

Retrieves the point's reference position, if stored.

Reference positions store the original position of a point just prior to an interactive user manipulation, so that transformations can be given as absolute/cumulative values rather than relative to the previous frame.

As not all model points require a reference points, this is actually a getter/setter for a vector object that is dynamically created as an attribute when first set. To remove this attribute from the attribute list, set its value to null.

This same attribute value is used by the PD.Point#getRefPoint and PD.Point#storeRefPoint methods, so it will very likely keep being recreated if you manually remove it.

Type
  • THREE.Vector3 | null
Inherited From:
Overrides:
:boolean

selected

Whether or not the point is in the current selection set.

As not all model points require a selection indicator, this is actually a getter/setter for a boolean value that is dynamically created as an attribute when first set. To remove this attribute from the attribute map, set its value to null.

Type
  • boolean
Inherited From:
Overrides:
:number

signedAngleInRadians

The signed angle between the incoming and outgoing path, in radians.

                         . - ' - .
                    . '             '  .
                 .                        .
               .                             .
              .     signedAngleInRadians      .
             .                                 .
  .prev >-------------------+_this             .
                               \_              .
                                  \_          .
                                     \_     .
                                        \_.
                                           \_
                                           .next

This requires both prev and next connections, otherwise it will always be PI (assuming it to be part of straight line). It stores the signed angle where zero means a U-turn, (+/-)PI/2 is a right-angle joint and (+/-)PI means the path continues straight.

Type
  • number
:THREE.Vector3|null

tangent

Stores a tangent direction at the given point.

Tangents on points are mainly used when generating and displaying curved polylines and surfaces.

As not all model points require a tangent direction, this is actually a getter/setter for a vector object that is dynamically created as an attribute when first set. To remove this attribute from the attribute list, set its value to null.

Type
  • THREE.Vector3 | null
Inherited From:
Overrides:
:THREE.Vector3

upVector

A vector calculated as the cross-product of prev to this to next.

3D VIEW             Z
                    ^
                    :         Y
                    :        /
                upVector    /
                    ^
                    | this.next
                    |    +
                    |   /
                    |  /
                    | /
                    |/
 this.prev >--------+  - - - > Y
                   this
Type
  • THREE.Vector3
:boolean

useFillet

Whether or not to truncate acute angles using a fillet instead of a mitre.

Type
  • boolean
:THREE.Vector3|null

uv

Stores a UV texture coordinate at the given point.

UV coordinates are 2D vectors that are typically used to store texture mapping information for each vertex of a surface.

As not all model points require a UV coordinates direction, this is actually a getter/setter for a 2D vector object that is dynamically created as an attribute when first set. To remove this attribute from the attribute map, set its value to null.

Type
  • THREE.Vector3 | null
Inherited From:
Overrides:

Methods

arePathAndPlaneAlignedInZ()

Retrieves whether or not the path point's path plane normal and the path normal both point upwards or both point downwards in the Z-axis. If the path point does not yet belong to a path, it returns true.

Returns:

Returns true if both normals face up or down in z-axis.

Type
boolean

computeOffsetProfilePoints(shell, contour, prevOffset, nextOffset [, offsetUp])

Generates a profile around the path point with the given offsets, creating new vertices in the given shell and adding them the contour array.

This method generates a ray that runs parallel to the incoming vector (inVec4) but displaced by the given prevOffset value in the incoming normal direction (inNormal).

It then creates a plane whose surface normal is the same as the outgoing normal (outNormal) and displaced in that direction by the given nextOffset value.

The resulting intersection point is the projected position, as shown in the following illustration. If the angle at the path point is less than the current mitre angle, then a chamfered profile will be generated containing two points. Otherwise the profile will contain a single point.

                            up
                             ^            Ray
                            _|  _/        /
             <- plane ->   | |_/        -    :
   - - - - - - - - - - - - - - - - - -(x)- - + - -
 next                  this          /       : nextOffset
   +---------------------+     - - - - - - - + - -
                       _/        /           :
            angle    _/        -
                   _/        /
                 _/        -
           prev +        /
               :        :
             - +- - - - + -
               :        :
               prevOffset

NOTE: This method is designed to be as fast as possible as it is used a lot by walls and spaces in the model. As a result, it is highly optimised for the most common use cases where the path point itself sits between the inside and outside profiles. As this method only knows about one side at a time (it is called twice with different offsets to get both sides), it cannot easily predict the best position for a mitering plane when the angle is less that the current mitre angle, so uses the path point itself as the reference point. This works fine when the path point is within both profiles or just outside them, but not when large offsets put it well outside them.

If you must use large offsets, consider generating an offset path first using the PD.Path#generateOffsetPath method and then generating geometry from that path instead. There is also a BIM.ATTRIB.OFFSET_PATH attribute you can use to store such paths in your element.

Parameters:
Name Type Argument Default Description
shell PD.Shell

The shell to reuse points from.
contour Array

The array to add offset points to.
prevOffset number

The offset distance normal to the incoming line segment.
nextOffset number

The offset distance normal to the outgoing line segment.
offsetUp number <optional>
 0

The offset distance in the direction of the path point UP vector in mm, defaults to 0.
Returns:

Returns an array of one or more projected positions.

Type
Array

computeOffsetProfilePointsByCallback(prevOffset, nextOffset, offsetUp, callback [, ignoreCurve])

Computes points on a line offset from this path point.

This method generates a ray that runs parallel to the incoming vector (inVec4) but displaced by the given prevOffset value in the incoming normal direction (inNormal).

It then creates a plane whose surface normal is the same as the outgoing normal (outNormal) and displaced in that direction by the given nextOffset value.

The resulting intersection point is the projected position, as shown in the following illustration. If the angle at the path point is less than the current mitre angle, then a chamfered profile will be generated containing two points. Otherwise the profile will contain a single point.

                            up
                             ^            Ray
                            _|  _/        /
             <- plane ->   | |_/        -    :
   - - - - - - - - - - - - - - - - - -(x)- - + - -
 next                  this          /       : nextOffset
   +---------------------+     - - - - - - - + - -
                       _/        /           :
            angle    _/        -
                   _/        /
                 _/        -
           prev +        /
               :        :
             - +- - - - + -
               :        :
               prevOffset

NOTE 1: This method is designed to be as fast as possible as it is used a lot by walls and spaces in the model. As a result, it is highly optimised for the most common use cases where the path point itself sits between the inside and outside profiles. As this method only knows about one side at a time (it is called twice with different offsets to get both sides), it cannot easily predict the best position for a mitering plane when the angle is less that the current mitre angle, so uses the path point itself as the reference point. This works fine when the path point is within both profiles or just outside, but not when large offsets put it well outside them.

If you must use large offsets, consider generating an offset path first using the PD.Path#generateOffsetPath method and then generating geometry from that path instead. There is also a BIM.ATTRIB.OFFSET_PATH attribute you can use to store such paths in your element.

NOTE 2: The callback function is invoked for each point in the offset profile with a THREE.Vector3 position as the first argument and a numeric curve identifier as the second. The position argument object is a static shared object with its x, y and z position updated prior to each call. Thus, if you want to persist each position in the callback, you will need to create a new point or vertex object and copy the x, y, and z values tp it, as shown in the example below.

Parameters:
Name Type Argument Default Description
prevOffset number

The offset distance normal to the incoming line segment in mm.
nextOffset number

The offset distance normal to the outgoing line segment in mm.
offsetUp number

The offset distance in the direction of the path point UP vector in mm.
callback function

A callback invoked each time an offset point is added.
ignoreCurve boolean <optional>
 false

A flag to not include curve points when creating columns, posts or platforms, defaults to false.
Example
const contour = [];
     const shell = new PD.Shell();
     const path = getPathToCreateOuterEdgeProfileFor();

     for (const point of path.getContour(0)) {
         point.computeOffsetProfilePointsByCallback(
             (point.prev) ? point.prev.outerEdgeOffset : point.outerEdgeOffset,
             point.outerEdgeOffset,
             0.0,
             (pt) => {
                 const vtx = shell.addVertex(pt); // Copy position to shell.
                 vtx.junction = point; // Store point that created it.
                 contour.push(vtx);
             }
         }
     );

computeProjectedPosition(result [, offset])

Computes the bounded path point position after projection and offset.

This method generates a ray that runs parallel to the incoming vector (inVec4) but displaced by the given offset and the previous path point's projection value in the incoming normal direction (inNormal).

It then creates a plane whose surface normal is the same as the outgoing normal (outNormal) and displaced in that direction by the given offset and the current path point's projection value.

The resulting intersection point is the projected position, as shown in the following illustration. However, This method places a limit on the distance of the intersection point to prevent it from extending beyond the sizes of the incoming and outgoing vectors at very acute angles.

                            up
                             ^            Ray
                            _|  _/        /
             <- plane ->   | |_/        -    :
   - - - - - - - - - - - - - - - - - -(x)- - + - -
 next                   this         /       : this.projection + offset
   +---------------------+     - - - - - - - + - -
                       _/        /           :
            angle    _/        -
                   _/        /
                 _/        -
           prev +        /
               :        :
             - +- - - - + -
               :        :
        prev.projection + offset
Parameters:
Name Type Argument Description
result THREE.Vector3

A point vector to receive the projected position.
offset number <optional>

An optional additional path offset value, defaults to zero.
Returns:

Returns the result argument with the new position.

Type
THREE.Vector3

computeProjectedPositionUnBounded(result, prevOffset, nextOffset)

Computes the unbounded position relative to the path point with the given previous and next offset values.

Unbounded means that the distance of the computed position is not limited by the current mitre angle, so at acute angles and/or relatively large offsets, it can extend well beyond the path point. Thus, only use this method instead of the computeProjectedPosition() method when you need the position accurately computed, but have some other means of limiting geometry based on that position.

This method generates a ray that runs parallel to the incoming vector (inVec4) but displaced by the given prevOffset in the incoming normal direction (inNormal). It then creates a plane whose surface normal is the same as the outgoing normal (outNormal) and displaced in that direction by the nextOffset.

The resulting intersection point is the projected position, as shown in the following illustration.

                            up
                             ^            Ray
                            _|  _/        /
             <- plane ->   | |_/        -    :
   - - - - - - - - - - - - - - - - - -(x)- - + - -
 next                  this          /       : nextOffset
   +---------------------+     - - - - - - - + - -
                       _/        /           :
                     _/        -
                   _/        /
                 _/        -
           prev +        /
               :        :
             - +- - - - + -
               :        :
               prevOffset
Parameters:
Name Type Description
result THREE.Vector3

A point vector to receive the projected position.
prevOffset number

The offset distance normal to the incoming line segment in mm.
nextOffset number

The offset distance normal to the outgoing line segment in mm.
Returns:

Returns the result argument with the new position.

Type
THREE.Vector3

computeProjectionOffset()

Checks for adjacent relationships and adds the appropriate offset.

Simple paths don't store relationships, so this method always returns the path point's projection property. When overridden by a BIM.Junction, this method is used by furniture and fixtures that are adjacent to walls or other surfaces in a space, and need to be offset by their inner/outer construction thickness.

See the BIM.Junction#computeProjectionOffset method for more details.

Returns:

Returns the computed projection.

Type
number

computeProperties(path)

Computes core properties required for this path point when it sits in a path.

This method essentially calculates and updates all the path properties stored by the path point.

Parameters:
Name Type Description
path PD.Path

The path that this path point is part of.
Returns:

Returns this path point to support method chaining.

Type
PD.PathPoint

computeWallSurfaceOffset()

Checks for adjacent relationships and offset the appropriate end.

Simple paths don't store relationships, so this method always returns 0.0. When overridden by a BIM.Junction, this method is used by furniture and fixtures that are adjacent to walls or other surfaces in a space, and need to be offset by their inner/outer construction thickness.

See the BIM.Junction#computeWallSurfaceOffset method for more details.

Returns:

Returns the computed offset, always zero.

Type
number

constrainPointToSegmentPlane(point [, target])

Constrains the point to lie between this path point and the next.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to constrain inside the path point.
target THREE.Vector3 <optional>

An optional point to receive the new position, defaults to point.
Returns:

Returns true if the point was constrained.

Type
boolean

copyAttribs(pos [, normal] [, flip])

Copies the position and normal direction from the given point/vertex.

NOTE: If the pos argument is a PD.Point, its normal will also be automatically copied if it has one. You can provide the normal argument as well if you wish to override the normal direction.

Parameters:
Name Type Argument Default Description
pos THREE.Vector3

The 3D position to set this point to.
normal THREE.Vector3 <optional>

The unit normal at the point position.
flip boolean <optional>
 false

Whether or not to store a negated normal, defaults to false.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

copyPathProperties(pathPoint)

Copies path properties from the given path point to this one.

This includes vectors, normals, angles, flags and some attributes. This is useful when you want to duplicate a path point's properties without creating a new instance, for example when updating a path point with new values from another path point.

Parameters:
Name Type Description
pathPoint PD.PathPoint

The path point to copy properties from.
Returns:

Returns this path point to support method chaining.

Type
PD.PathPoint

copyPoint(data)

Copies point data from an array, vector or another point.

Parameters:
Name Type Description
data Array | object

The array/object to copy from.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

deleteAttribute(name)

Removes an arbitrary attribute from this point, if it exists.

Parameters:
Name Type Description
name string

The name of the attribute to remove.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

distancePointToSegment(point [, target])

Computes the distance from a point to the line segment between this and its next path point.

As this is typically used for snapping, it will only return a valid value if the closest point on the line segment is between this and the next path point. Otherwise it will return Infinity, even if there is just a single path point in the path as it has no corresponding segment.

If a target vector is given, this will be set to the closest point on the path segment if the return value is less than Infinity.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to test for distance.
target THREE.Vector3 <optional>

An optional point to receive the closest point on the segment.
Returns:

Returns the distance to the line segment.

Type
number

distancePointToSegmentPlane(point)

Computes the distance between the given point and the path point face.

This uses the plane equation of the segment between this path point and its next to compute the distance of the point away.

Parameters:
Name Type Description
point THREE.Vector3

The point to
Returns:

Returns the distance to the given plane

Type
number

extendToPlane(plane [, target] [, reverse] [, min])

Projects the path point's outgoing direction vector to intersect the given plane.

If the reverse argument is set to true or PD.REVERSE, the point will be extended in the direction of its incoming vector. If false or PD.FORWARD, (the default value) the outgoing vector (PD.REVERSE) will be used.

If the plane is behind the point, parallel to the direction vector, or no intersection was found, the target will not be modified and the method will return false.

Parameters:
Name Type Argument Default Description
plane THREE.Plane

The plane to intersect with.
target THREE.Vector3 <optional>

An optional vector to receive the intersection point, defaults to this point.
reverse boolean <optional>
 false

Whether or not to reverse the direction to extend, either PD.FORWARD or PD.REVERSE, defaults to false.
min number <optional>

An optional minimum distance in the given direction from the path point to consider a valid intersection, defaults to -Infinity.
Returns:

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

Type
boolean

findPathContourAndIndex()

Determines which contour the path point belongs to and its ordinal index within that contour.

This method iterates through the contours of the path, and checks if they contain the path point. If found, it returns an array with the contour as the first item and the index of the path point within that contour as the second item.

Returns:

Returns a [contour,index] array.

Type
Array

fromJSON(data)

Safely copy properties from a source object.

See the PD.Base#fromJSON method for more details.

Override this method in derived classes to read additional properties, but call data = super.toJSON(data); at the top of the method.

Parameters:
Name Type Description
data object

The source object containing data to copy.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point
Example
// Overriding this method.

class MyPoint extends PD.Point {
     /// ...
     fromJSON(data) {

         super.fromJSON(data);

         if ('extraData' in data) {
             this.extraData = PD.Utils.toIntegerInRange(data.extraData, this.extraData, 0, 16);
         }

         if ('evenMoreData' in data) {
             this.evenMoreData = PD.Utils.toNumber(data.evenMoreData, this.evenMoreData);
         }

         return this;

     };
     /// ...
 };

generateCornerProfileByCallback(coords, width, offset, callback [, options])

Generates a corner profile used for columns, railing posts and stair landings.

This method requires that the innerEdgeOffset and outerEdgeOffset properties of the path point have already been set appropriately for the profile. This requirement allows elements and/or components greater control over the relative alignment of the profile and the ability to offer more detailed options than could be provided internally through a simple alignment argument.

The overall depth of the profile will be equal to outerEdgeOffset + innerEdgeOffset. If these properties have not been set, or the resulting profile depth is zero, a default depth of 900mm (3') will be used.

When the options.maintainDepth argument is greater than 1, the method will make all reasonable attempts to ensure that the two edges that point towards the previous and next path points are equal to the depth of the profile, even when the angle at the path point is quite acute. It does this by either displacing the sides or extending out the profile width to to maintain the depth, as shown in the illustration below.

   maintainDepth:                      maintainDepth:
         0                                   2                   prev
                         prev                __..--'\    __..--''
     __..--''\   __..--''            __..--''      __\--'
    |    : __.\'' < depth           |    : __..--''   \  == depth
    |  - +'- - +                    |  - +'- - > > > > +
    |    :'--./__ < depth           |    :'--..__     /  == depth
     ''--..__/   ''--..__            ''--..__    ''--/.__
                         next                ''--.._/    ''--..__
                                                                 next

When generating the profile, this method also computes connection data for the incoming and outgoing edges of the profile, creating or updating a PD.ConnectionData object as an attribute of the path point with the PD.ATTRIB.CONNECT_DATA key. This basically stores the four points that define the incoming and outgoing edges of the profile, being the corner points marked as 0 and 1 in the illustration below. The first point (0) in each edge is on the inner side based on the direction of travel along the path, and the second point (1) is on the outer side.

    ^ Y
    :
    :   Outer                      Outer
    1----------1  -  -  >  -  -  1-------+._ - - - - -> X
    |          |                 |          ''-.1 _
incoming    outgoing -  >  -  incoming         /    ' - _
    |   from   |                 |     to  outgoing       ' - _
    0----------0  -  -  >  -  -  0-----+._   /    ' - _
        Inner                      Inner  ''0 _         '
                                               ' - _
Parameters:
Name Type Argument Description
coords PD.LocalCoordinates

The local coordinate system to use.
width number

The size of the corner profile in the path direction.
offset number

The offset of the corner profile normal to the path.
callback function

A callback invoked each time a profile point is added.
options object <optional>

An optional configuration object containing flags to control corner generation.
Properties of options:
Name Type Argument Description
maintainDepth number <optional>

How to maintain edge depth of acutely angled profiles (0 to 2), defaults to 0.
noCurveOffset boolean <optional>

Whether to not add a half the width at the start of a curved path, defaults to false.
noStartOffset boolean <optional>

Whether to not add a half the width at the start of an open path, defaults to false.
noEndOffset boolean <optional>

Whether to not add a half the width at the end of an open path, defaults to false.
Returns:

Returns edge connection data for the profile.

Type
PD.ConnectionData

generateInnerEdge(shell [, swapSides] [, addProjection] [, ignoreCurve])

Generates the inside edge of the path point.

This method computes the inner edge points for this path point. It reuses vertices from the given shell so that facets can be extruded that reference the same points.

The inner edge is usually offset by the innerEdgeOffset property of the path point. However, if the swap argument is set to true, then the outerEdgeOffset property will be used to swap the inner/outer aspect of the wall element.

Parameters:
Name Type Argument Default Description
shell PD.Shell

The shell to reuse vertices from.
swapSides boolean <optional>
 false

A flag to use the outer offset rather than inner, defaults to false.
addProjection boolean <optional>
 false

A flag to include the path point's projection offset as well, defaults to false.
ignoreCurve boolean <optional>
 false

A flag to not include curve points when creating columns, posts or platforms, defaults to false.
Returns:

Returns an array of one or more projected positions.

Type
Array

generateOuterEdge(shell [, swapSides] [, addProjection] [, ignoreCurve])

Generates the outside edge of the path point.

This method computes the outer edge points for this path point. It reuses vertices from the given shell so that facets can be extruded that reference the same points.

The outer edge is usually offset by the outerEdgeOffset property of the path point. However, if the swap argument is set to true, then the innerEdgeOffset property will be used to swap the inner/outer aspect of the wall element.

Parameters:
Name Type Argument Default Description
shell PD.Shell

The shell to reuse vertices from.
swapSides boolean <optional>
 false

A flag to use the inner offset rather than outer, defaults to false.
addProjection boolean <optional>
 false

A flag to include the projection offset as well, defaults to false.
ignoreCurve boolean <optional>
 false

A flag to not include curve points when creating columns, posts or platforms, defaults to false.
Returns:

Returns true if one or more vertices were added to the outer edge array.

Type
boolean

getAngle()

Checks if the path point is curved and returns either the angle of the first curve segment or, if not curved, the standard path point angle.

Returns:

Returns either the curved or linear angle in degrees.

Type
number

getAttribute(name)

Retrieve an arbitrary attribute stored on this point, if it exists.

Parameters:
Name Type Description
name string

The name of the attribute to retrieve.
Inherited From:
Overrides:
Returns:

Returns the attribute value, or undefined if it does not exist.

Type
any | undefined

getIncomingNormal()

Checks if the previous path point is curved and returns either the incoming normal of the last curve segment or, if not curved, the standard path point incoming normal.

Returns:

Returns either the curved or linear ingoing normal.

Type
THREE.Vector3

getIncomingVector()

Checks if the previous path point is curved and returns either the incoming vector of the last curve segment or, if not curved, the standard path point incoming vector.

Returns:

Returns either the curved or linear incoming vector.

Type
PD.ScaledVector

getInnerEdge( [create])

An array for inner boundary points calculated relative to the path.

For polygonal spaces and closed loop wall elements, there are definite interior and exterior sides. This array stores the inside.

Edges are stored as an array of PD.Point objects marking the path of travel. They are stored internally as attributes as only space and wall junctions need to cache this information.

Parameters:
Name Type Argument Default Description
create boolean <optional>
 false

When true, creates an array if not yet created, defaults to false.
Returns:

Returns an array of inner edge points, if any.

Type
Array | null

getInnerFacets( [create])

An array of internal facets generated when this path point is part of a space.

This is set when the generateInnerFacets() method is called by the parent space. The facets in this array are links to facets within the parent spaces innerShell.

Parameters:
Name Type Argument Default Description
create boolean <optional>
 false

When true, creates an array if not yet created, defaults to false.
Returns:

Returns an array of inner edge points, if any.

Type
Array | null

getNormal()

Checks if the path point is curved and returns either the normal of the first curve segment or, if not curved, the standard path point normal.

Returns:

Returns either the curved or linear normal.

Type
THREE.Vector3

getOuterEdge( [create])

An array for outer boundary points calculated relative to the path.

For simple slab elements, the boundary is assumed to be the external edge that runs along the right-hand side of the polygon/polyline path, based on the right-hand rule and the +Z axis. It is determined by the current position and projection values, as well aa shared element properties.

Edges are stored as an array of PD.Point objects marking the path of travel. They are stored internally as attributes as only space and wall junctions need to cache this information.

Parameters:
Name Type Argument Default Description
create boolean <optional>
 false

When true, creates an array if not yet created, defaults to false.
Returns:

Returns an array of outer edge points, if any.

Type
Array | null

getOutgoingNormal()

Checks if the path point is curved and returns either the outgoing normal of the first curve segment or, if not curved, the standard path point outgoing normal.

Returns:

Returns either the curved or linear outgoing normal.

Type
THREE.Vector3

getOutgoingVector()

Checks if the path point is curved and returns either the outgoing vector of the first curve segment or, if not curved, the standard path point outgoing vector.

Returns:

Returns either the curved or linear outgoing vector.

Type
PD.ScaledVector

getPathUpVector()

Retrieves the path point's path normal if it belongs to a path, otherwise its own upVector property.

Returns:

Returns the 'up' vector for this path point.

Type
THREE.Vector3

getRefPoint()

Retrieves the point's reference position.

Reference positions allow a point to be interactively manipulated even if it is referenced multiple times within the same selection set. This is done by always moving or transforming point relative to its original reference position.

As not all model points require a reference position, this is actually a getter for a vector object that is dynamically created as an attribute when first accessed.

Inherited From:
Overrides:
Returns:

Returns the reference point.

Type
THREE.Vector3

getSignedAngleInRadians()

Checks if the path point is curved and returns either the signed angle of the first curve segment or, if not curved, the standard signed path point angle in radians.

Returns:

Returns either the curved or linear angle in radians.

Type
number

isPointInsideSegmentPlane(point)

Check if the point lies between this path point and the next.

Parameters:
Name Type Description
point THREE.Vector3

The point to constrain inside the path point.
Returns:

Returns true if the point was constrained.

Type
boolean

moveByCoordinates(dx, dy, dz)

Moves this point relative to its reference position.

This method is typically called by the host application after storing the reference position. The given movement in each axis is the translation value relative to the stored reference position. This allows points to be accurately dragged interactively even if some frames are skipped due to slow updates or the point is referenced multiple times within the selection set that is being manipulated.

Parameters:
Name Type Description
dx number

The relative movement distance in the X-axis.
dy number

The relative movement distance in the Y-axis.
dz number

The relative movement distance in the Z-axis.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

moveByMatrix4(matrix [, about])

Applies the given matrix to the point's reference position.

This method is typically called by the host application after storing the reference position. The given transformation matrix is applied to the stored reference position. This allows points to be accurately scaled and rotated interactively even if some frames are skipped due to slow updates or the point is referenced multiple times within the selection set that is being manipulated.

Parameters:
Name Type Argument Description
matrix THREE.Matrix4

The relative transform matrix.
about THREE.Vector3 <optional>

An optional point about which to apply the transform.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

moveByQuaternion(quat [, about])

Applies the given quaternion to the point's reference position.

This method is typically called by the host application after storing the reference position. The given quaternion is applied relative to the stored reference position. This allows points to be accurately rotated interactively even if some frames are skipped due to slow updates or the point is referenced multiple times within the selection set that is being manipulated.

Parameters:
Name Type Argument Description
quat THREE.Quaternion

The quaternion to apply.
about THREE.Vector3 <optional>

An optional point about which to apply the transform.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

moveByVector3(vector)

Moves this point relative to its reference position.

This method is typically called by the host application after storing the reference position. The given movement vector is the translation value relative to the stored reference position. This allows points to be accurately dragged interactively even if some frames are skipped due to slow updates or the point is referenced multiple times within the selection set that is being manipulated.

Parameters:
Name Type Description
vector THREE.Vector3

The relative movement vector.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

orientLocalCoordinates(coords)

Sets the given local coordinates to orient with the path segment of this path point.

Parameters:
Name Type Description
coords PD.LocalCoordinates

The local coordinates to orient.
Returns:

Returns the given local coordinates.

Type
PD.LocalCoordinates

revertToRefPoint()

Resets the point to its reference position.

This method is typically called by the host application after storing the reference position. This allows an interactive drag or transformation to be aborted part-way through whilst accurately returning the point to its original position.

Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

setAttribute(name, value)

Stores an arbitrary attribute on this point, or replaces its value.

Parameters:
Name Type Description
name string

The name of the attribute to store.
value string

The attribute value to store.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

setBinormal(binormal)

Sets the binormal direction at this point.

This value is accessible via the binormal getter/setter. As not all model points require a binormal direction, this method will dynamically create a new attribute as and when required. To remove this attribute from the attribute map, set its value to null.

This method is can accept any {x,y,z} object or similar, as well as simple [x,y,z] vector arrays.

Parameters:
Name Type Description
binormal THREE.Vector3 | Array.<number>

The vector array/object to copy.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

setColor(color)

Sets the color value at this point.

This value is accessible via the color getter/setter. As not all model points require a color value, this method will dynamically create a new attribute as and when required. To remove this attribute from the attribute map, set its value to null.

In addition to THREE.Color objects, this method can handle different types of color input value such as hex numbers (0x2b362), CSS strings ('#ffc49c'), simple arrays ([r,g,b]) and any type of {r,g,b} object.

Parameters:
Name Type Description
color THREE.Color | Array.<number>

The number/string/array/object defining a color.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

setCurveType(type)

Sets the curve type for this path point.

Parameters:
Name Type Description
type PD.CURVE

The new curve type.
Returns:

Returns true if the type was changed, otherwise false.

Type
boolean

setNormal(normal)

Sets the direction of the path normal at this point.

Parameters:
Name Type Description
normal THREE.Vector3

The normal vector to copy.
Inherited From:
Overrides:
Returns:

Returns this path point to support method chaining.

Type
PD.PathPoint

setPathEndPlane(azi, alt [, extend])

Sets the start plane angles for the first path point in a path.

This method is used by classes that extrude shapes along the path and allow the user to set a starting azimuth and altitude angle.

Parameters:
Name Type Argument Description
azi number

The azimuth angle relative to the outgoing vector, in radians.
alt number

The altitude angle relative to the outgoing vector, in radians.
extend number <optional>

An optional end extension in mm, defaults to 0.
Returns:

Returns this path point to support method chaining.

Type
PD.PathPoint

setPathStartPlane(azi, alt [, extend])

Sets the start plane angles for the first path point in a path.

This method is used by classes that extrude shapes along the path and allow the user to set a starting azimuth and altitude angle.

Parameters:
Name Type Argument Description
azi number

The azimuth angle relative to the outgoing vector, in radians.
alt number

The altitude angle relative to the outgoing vector, in radians.
extend number <optional>

An optional start extension in mm, defaults to 0.
Returns:

Returns this path point to support method chaining.

Type
PD.PathPoint

setPos(pos)

Sets the position of this point in model space.

This method is can accept any {x,y,z} object or similar, as well as simple [x,y,z] vector arrays.

Parameters:
Name Type Description
pos THREE.Vector3 | Array.<number>

The vector array/object to copy.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

setTangent(tangent)

Sets the tangent direction at this point.

This value is accessible via the tangent getter/setter. As not all model points require a tangent direction, this method will dynamically create a new attribute as and when required. To remove this attribute from the attribute map, set its value to null.

This method is can accept any {x,y,z} object or similar, as well as simple [x,y,z] vector arrays.

Parameters:
Name Type Description
tangent THREE.Vector3 | Array.<number>

The vector array/object to copy.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

setUV(uv)

Sets the UV texture coordinate at this point.

This value is accessible via the uv getter/setter. As not all model points require a binormal direction, this method will dynamically create a new attribute as and when required. To remove this attribute from the attribute map, set its value to null.

This method is can accept any {x,y} object or similar, as well as simple [x,y] vector arrays.

Parameters:
Name Type Description
uv THREE.Vector2 | Array.<number>

The vector array/object to copy.
Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

squaredDistanceSegmentToRay(selection)

Computes the squared distance between the selection ray and the path segment between this and its next path point.

This method does not actually affect the section set, it just computes the distance using the selection ray. It also uses the selection radius when the path point has a curve to compute the distance to the curve path.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Returns:

Returns the distance to the line segment or curve path.

Type
number

storeRefPoint()

Updates the reference position to the current point position.

This method is typically called automatically by the host application immediately prior to an interactive move or transform event in order to snapshot the current position. This allows the same point object to be accurately moved even if it is referenced multiple times within the selection set that is being manipulated.

Inherited From:
Overrides:
Returns:

Returns this point to support method chaining.

Type
PD.Point

toJSON( [data])

Converts the point to a simple POJO for conversion to JSON.

This method is used to copy, store and save the data for a point, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

Override this method in derived classes to add additional properties, but call data = super.toJSON(data); at the top of the method, as shown in the example below.

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Inherited From:
Overrides:
Returns:

Returns a Plain Old Javascript Object (POJO).

Type
object
Example
// Overriding this method.

class MyPoint extends PD.Point {
     /// ...
     toJSON(data) {

         data = super.toJSON(data);

         data.extraData = this.extraData;
         data.evenMoreData = this.evenMoreData;
         return data;

     };
     /// ...
 };

trimContourToInsideFace(contour)

Trims an array of connected points to the inside of the inner plane.

Parameters:
Name Type Description
contour Array

An array of connected points.
Returns:

Returns the trimmed points array.

Type
Array

fromVector3(vec) <static>

Create a new path point from a given vector.

Parameters:
Name Type Description
vec THREE.Vector3

A generic vector object.
Returns:

Returns a new path point based on the given vector.

Type
PD.PathPoint