API Docs

Class: Curve

PD. Curve

An extension of the THREE.Curve base class to support path points.

The primary aim of this class is better integrate curves with PD.PathPoint and PD.Path objects. In this instance, a curve defines how a path travels from one path point to the next, so there is no need to redefine the start and end points as these can be taken directly from the parent path point.

Having separate classes for each curve type is sub-optimal when users are experimenting with and switching between different curve types to find the most appropriate. Rather, having a single class that can easily switch between different types whilst retaining control point positions and user-specific data is a more optimal solution for this particular use case.

Also, each curve can have any number of optional editable control nodes. Control nodes are points that belong to each curve and are used to generate arc, bezier or spline paths. To make dynamic editing easier, the positions of control nodes are stored relative to the path of the host junction. If you resize the path, the control nodes will similarly resize to ensure that the resulting curve remains viable.

Control Points

Control points are used to define the shape of some types of curve. They serve as standard point in 3D model space, but also include their positions relative to the host path point and a weighting fraction that governs how 'attractive' they are to the curve shape.

The absolute position of a control point is always dynamically updated using its position relative to a curve's host path point and its path direction. The relative position is always stored using fractional local coordinates, where the local +X axis corresponds to the path point's outVec4, the +Y axis to its outNormal and the Z to its upVector. The value in each axis is stored as a fraction of the junction segment length.

new Curve(pathPoint [, curveType] [, config])

Creates a new curve for a path segment.

Parameters:
Name Type Argument Description
pathPoint PD.PathPoint

The path point to add this curve to.
curveType PD.CURVE <optional>

The type of curve to add to the path point.
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
curveType PD.CURVE <optional>

The type of curve to add to the path point.
controlNodes Array <optional>

The control points that define this curve.
useUMapping boolean <optional>

Whether or not to base segment length on curvature.
segments number <optional>

The number of segments in the curve.
Author:
  • drajmarsh

Extends

  • THREE.Curve

Members

:Array.<PD.PathPoint>

contour

The faceted path of the curve.

Type
:Array.<PD.Point>

controlNodes

The control points that define this curve.

Type
:PD.CURVE

curveType

The type of curve to add to the path point.

Type
:object

endConnection

Stores a path point at the same position as the end junction, but incoming from the very last curve segment.

This is always set as the very last point in the curve contour. It shares the same position as the next junction, but its incoming vectors and normals are set using the second-last point in the curve contour rather than the previous junction in the host path.

Using this property is a quick and robust way for other classes to access the end of the curve segment without having to reference the last point in the contour array.

Type
  • object
:object

extents

Stores the 3D bounding box around the curve path.

Type
  • object
:boolean

hasChanged

Whether or not the curve has changed since last update.

NOTE: This property is different from the needsUpdate property which is used internally by THREE.Curve to maintain the segment length cache. This property manages the calculation and update of curve parameters when they change.

Type
  • boolean
:boolean

isValid

Whether or not the parameters generate a valid curve.

Some curves can be invalid, such as when consecutive points are coincident or when all three points on an arc are colinear. This value is therefore set automatically within the update() method, which should be called after any notable parameter changes.

Type
  • boolean
:PD.PathPoint

junction

The parent path point that this curve affects.

Type
:number

segments

The number of segments in the curve.

Type
  • number
:object

startConnection

Stores a path point at the same position as the start path point, but outgoing to the very first curve segment.

This is always set as the very first point in the curve contour. It shares the same position as the host junction, but its outgoing vectors and normals are set using the second point in the curve contour rather than the next junction in the host path.

Using this property is a quick and robust way for other classes to access the start of the curve segment without having to reference the first point in the contour array.

Type
  • object
:boolean

useUMapping

Whether or not to base segment length on curvature.

Type
  • boolean
:number

DEFAULT_SEGMENTS <static>

The default number of segments within a curve.

Type
  • number
:number

MAX_CURVE_SEGMENTS <static>

The maximum number of segments allowed within a curve.

Type
  • number
:number

MIN_CURVE_SEGMENTS <static>

The minimum number of segments allowed within a curve.

Type
  • number

Methods

_getTangentNurbs(t, target)

Computes the tangent to the NURBS curve given a fractional distance.

Parameters:
Name Type Description
t number

A fractional distance along the curve (0 to 1).
target THREE.Vector3

A 3D point or vector to receive the results.
Returns:

Returns the tangent if given, or a new vertex.

Type
THREE.Vector3

_updateArc( [forceUpdate])

Computes the centre, radius and angle of the 3D Arc.

Parameters:
Name Type Argument Description
forceUpdate boolean <optional>

Whether or not to update even if curve has not changed, defaults to false.
Returns:

Returns true if the arc is valid and able to be generated.

Type
boolean

addControlNode( [node])

Adds a new control node to the curve.

Parameters:
Name Type Argument Description
node PD.Point <optional>

The node to insert after.

addToClipPath(clipPath [, axis] [, startOffset] [, endOffset])

Adds 3D curve path points to the given 2D clip path.

A curve path includes the positions of both the start path point and the end path point. The curve uses these points to determine if their positions have and the curve needs to be updated.

However, sometimes you may not want to include the start and/or end points in the clip path as they may be added at some other point in the process. You can set the start and end offsets to handle this form you.

Parameters:
Name Type Argument Default Description
clipPath Array.<PD.ClipPt2D>

An existing clip path to add to.
axis PD.AXIS <optional>

The cartesian axis to convert curve points, defaults to the XY axis.
startOffset number <optional>
 0

The start index within the curve path, defaults to zero.
endOffset number <optional>
 0

The number of points from the end of the path to ignore, defaults to zero.

checkConstraints()

Check and updates any 'smooth' constraints on this curve's control nodes.

Returns:

Returns this curve instance to support method chaining.

Type
PD.Curve

computeEndConnection()

Calculates and stores ending curve path data.

This method is provided as it is sometimes necessary to update the last segment in a curve if the next path point in the path also has a curve and that curve is being interactively edited. Rather than recompute the entire previous curve, we only need to update the end connection properties to accommodate the changed first segment of the next curve.

copy(source)

Copies another curve object to this instance.

Parameters:
Name Type Description
source PD.Curve

The curve to copy from.
Returns:

Returns this instance to support method chaining.

Type
PD.Curve

dimensionControlNodes(mesh, size)

Displays dimensions for this curve's control nodes.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to render nodes to.
size number

The size to show highlight markers.
Returns:

Returns true if dimensions were added.

Type
boolean

fromJSON(data)

Safely copy properties from a source object.

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

Parameters:
Name Type Description
data object

The source object containing data to copy.
Returns:

Returns this instance to support method chaining.

Type
PD.Curve

generateContour(shell)

Generates a series of points along the curve.

Parameters:
Name Type Description
shell PD.Shell

The shell to add vertices to.
Returns:

Returns an array of points.

Type
Array.<PD.Point>

getBoundedSegmentCount()

Retrieves the number of segments constrained to min/max values.

See:
Returns:

Returns the number of segments constrained to min/max values.

Type
number

getCurveDataAt(u, pnt)

Computes a point on the curve at a given parameter and sets its tangent and normal.

This method is different from the getPoint() and getPointAt() methods in that it requires a PD.Point object (as opposed to a THREE.Vector3) so that it can also set the tangent and normal properties/attributes as well as the position.

Parameters:
Name Type Description
u number

The parameter along the curve (0 to 1).
pnt PD.Point

The 3D point object to update.
Returns:

Returns the updated point.

Type
PD.Point

getFirstControlNode()

Retrieve the first control node in the list if there is one.

Returns:

Returns the first control node.

Type
PD.Point | null

getFirstControlNodeIfSmooth()

Retrieve the first control node in the list if it is linked to the last curve.

If two sequential points in a path are curved, and the shared path point is set to a smooth transition, then the position of the first control node of the next path point curve will be affected by the position of the last node in the previous. This method is used to retrieve the first control node of the next path point curve, but only if it has at least one control nodes.

Returns:

Returns the first linked control node.

Type
PD.Point | null

getLastControlNode()

Retrieve the last control node in the list if there is more than one.

Returns:

Returns the last control node.

Type
PD.Point | null

getLastControlNodeIfLinked()

Retrieve the last control node in the list if it is linked to the next curve.

If two sequential points in a path are curved, and the shared path point is set to a smooth transition, then the position of the last control node of the previous path point curve will be affected by the position of the first node in the next. This method is used to retrieve the last control node of the previous path point curve, but only if there are more than one control nodes.

Returns:

Returns the last linked control node.

Type
PD.Point | null

getNodeRelativePos(node)

Retrieves the relative position of a control node.

Parameters:
Name Type Description
node PD.Point

The control node to get the relative position of.
Returns:

Returns the reference point.

Type
THREE.Vector3

getNodeSmoothLockedJunction(node [, index])

Retrieves the path point the node is smooth-locked to.

Parameters:
Name Type Argument Description
node PD.Point

The control node to check for smoothing.
index number <optional>

The index of the node in the control nodes list, will be determined if not given.
Returns:

Returns the path point the given node is locked to.

Type
BIM.Junction

getNodeSmoothLockedVector(node [, index])

Retrieves the vector if the node is smooth-locked to a path point without a curve.

Parameters:
Name Type Argument Description
node PD.Point

The control node to get the vector for.
index number <optional>

The index of the node in the control nodes list, will be determined if not given.
Returns:

Returns the smooth-locked vector, or null if not locked.

Type
PD.ScaledVector

getNodeSmoothingDistance(node)

Retrieves the smooth distance of a control node.

Parameters:
Name Type Description
node PD.Point

The control node to get the smooth distance of.
Returns:

Returns the distance, defaulting to 0.4.

Type
number

getNodeWeighing(node)

Retrieves the weighting of a control node.

Parameters:
Name Type Description
node PD.Point

The control node to get the weight of.
Returns:

Returns the weighting, defaulting to 1.0.

Type
number

getPoint(t [, target])

Computes an absolute position on the curve given a fractional distance.

Parameters:
Name Type Argument Description
t number

A fractional distance along the curve (0 to 1).
target PD.Point <optional>

An optional point to receive the results.
Returns:

Returns the target if given, or a new point.

Type
THREE.Vector3

getTangent(t, target)

Computes the tangent to the the curve given a fractional distance.

Parameters:
Name Type Description
t number

A fractional distance along the curve (0 to 1).
target THREE.Vector3

An optional vector to receive the results.
Returns:

Returns the tangent if given, or a new vector.

Type
THREE.Vector3

handleMove()

Updates the curve when a path point is moved.

This method updates the positions of each control node as well as the previous and next linked curve control nodes.

isNodeSmoothLocked(node [, index])

Determines if the given control node's position is locked due to smoothing.

Parameters:
Name Type Argument Description
node PD.Point

The control node to check for smoothing.
index number <optional>

The index of the node in the control nodes list, will be determined if not given.
Returns:

Returns the whether or not the node is smooth locked.

Type
boolean

orientLocalCoordinates(t, coords)

Sets the given local coordinates to orient with a curve point.

Parameters:
Name Type Description
t number

A fractional distance along the curve (0 to 1).
coords PD.LocalCoordinates

The local coordinates to orient.
Returns:

Returns the given local coordinates.

Type
PD.LocalCoordinates

renderControlNodes(mesh, size)

Displays control nodes for this curve.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to render nodes to.
size number

The size to show highlight markers.
Returns:

Returns true if nodes were added.

Type
boolean

renderPath(mesh)

Renders an outline of the curve path.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to render the path to.
Returns:

Returns true if lines were added.

Type
boolean

setCurveType(type)

Sets the type of curve to use.

Parameters:
Name Type Description
type PD.CURVE

The new curve type to set.
Returns:

Returns true if curve type was set and curve updated.

Type
boolean

setNodePosition(node [, position])

Set a new position for the given control node.

If no new position is given, the node's relative position is updated based on its current position.

Parameters:
Name Type Argument Description
node PD.Point

The control node to set the position of.
position THREE.Vector3 <optional>

An optional new position for the given control node.
Returns:

Returns this instance to support method chaining.

Type
PD.Curve

setNodeRelativePos(node, pos)

Sets the relative position of a control node.

Parameters:
Name Type Description
node PD.Point

The control node to et the relative position of.
pos THREE.Vector

The new relative position of the node.
Returns:

Returns the reference point.

Type
THREE.Vector3

setNodeRelativePosAsFractions(node, x, y, z)

Sets the relative position of a control node as fractions of length.

Parameters:
Name Type Description
node PD.Point

The control node to et the relative position of.
x number

The new relative X position as a fraction of segment length (0 to 1).
y number

The new relative Y position as a fraction of segment length (0 to 1).
z number

The new relative Z position as a fraction of segment length (0 to 1).
Returns:

Returns the reference point.

Type
THREE.Vector3

setNodeWeighting(node, weighting)

Sets the weighting of a control node.

Parameters:
Name Type Description
node PD.Point

The control node to set the weighting of.
weighting number

The new weighting value to set, defaults to 1.
Returns:

Returns the new weighting.

Type
number

toJSON( [data])

Converts the object instance to a simple POJO for JSON storage.

This method is used to copy, store and save the data for ths object, 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.

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

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Returns:

Returns a Plain Old Javascript Object (POJO).

Type
object

update( [forceUpdate])

Computes any parameters required for the generation of the path.

Parameters:
Name Type Argument Description
forceUpdate boolean <optional>

Whether or not to update even if curve has not changed, defaults to false.
Returns:

Returns true if the curve is valid and able to be generated.

Type
boolean

Checks and updates node positions if the isSmooth state of a path point is set.

The isSmooth property of a path point indicates that any transition between two curves at its location must be as close to smooth as possible. This means that both the incoming and outgoing control nodes at that path point must be effectively parallel.

This method ensures that the last control node in the previous curve (if defined) is kept parallel with the first control node of this curve. If the first control node of this curve has been moved by the user, the last control node in the previous curve will be moved to match.

If there is no previous curve, the first control node in this curve will be moved to ensure that it is parallel to the incoming vector at the path point.

Parameters:
Name Type Argument Description
set_node_dist boolean <optional>

When true, stores the smoothing distance of the first node.
Returns:

Returns this instance to support method chaining.

Type
PD.Curve

Checks and updates node positions if the isSmooth state of a path point has changed.

The isSmooth property of a path point indicates that any transition between two curves at its location must be as close to smooth as possible. This means that both the incoming and outgoing control nodes at that path point must be effectively parallel.

This method ensures that the first control node in the next curve (if defined) is kept parallel with the last control node of this curve. If the last control node of this curve has been moved by the user, the first control node in the previous curve will be moved to match.

If there is no next curve, and the junction.next.isSmooth value is true, the last control node in this curve will be moved to ensure that it is parallel to the outgoing vector at the next path point.

Parameters:
Name Type Argument Description
set_node_dist boolean <optional>

When true, stores the smoothing distance of the last node.
Returns:

Returns this instance to support method chaining.

Type
PD.Curve

createOffsetCurve(curve [, offsetXY] [, offsetZ]) <static>

Sets the offset curve and offset value.

Parameters:
Name Type Argument Description
curve PD.Curve

The curve to use as the basis for the offset.
offsetXY number <optional>

An offset normal to the path lines, defaults to zero.
offsetZ number <optional>

An offset in the local Z-axis, defaults to zero.
Returns:

Returns a new offset curve.

Type
PD.Curve