API Docs Class: Point

new Point(x, y, z)

Creates a new 3D selectable and manipulable point.

Parameters:

Name	Type	Description
`x`	number	The position in the X-axis.
`y`	number	The position in the Y-axis.
`z`	number	The position in the Z-axis.

Author:

drajmarsh

Extends

THREE.Vector3

Members

: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

: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

: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

: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

:boolean isPoint <readonly>

A flag identifying this object as a 3D point.

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

BIM.Junction | null

:THREE.Vector3|null normal

Stores a normal direction at the given point.

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

As not all model points require a normal 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

: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

: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

: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

: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

Methods

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.

Returns:

Returns this point to support method chaining.

Type: PD.Point

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.

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.

Returns:

Returns this point to support method chaining.

Type: PD.Point

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.

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;

     };
     /// ...
 };

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.

Returns:

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

Type: any | undefined

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.

Returns:

Returns the reference point.

Type: THREE.Vector3

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.

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.

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.

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.

Returns:

Returns this point to support method chaining.

Type: PD.Point

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.

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.

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.

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.

Returns:

Returns this point to support method chaining.

Type: PD.Point

setNormal(normal)

Sets the direction of the normal at this point.

This value is stored as an attribute of the point and is accessible via the normal getter/setter. As not all points require a normal direction, this method dynamically creates 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
`normal`	THREE.Vector3 \| Array.<number>	The vector array/object to copy.

Returns:

Returns this point to support method chaining.

Type: PD.Point

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.

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.

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.

Returns:

Returns this point to support method chaining.

Type: PD.Point

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.

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.

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;

     };
     /// ...
 };

fromVector3(vec) <static>

Create a new point from a given vector.

Parameters:

Name	Type	Description
`vec`	THREE.Vector3	A generic vector object.

Returns:

Returns a new point based on the given vector.

Type: PD.Point