API Docs

Class: GridCell

PD. GridCell

A subclass of PD.Point that defines the position, boundary and value of a grid cell.

new GridCell( [value] [, x] [, y] [, z])

Creates a data object for storing a position, boundary and value for a grid cell.

Parameters:
Name Type Argument Default Description
value number <optional>
 0

The value stored by the cell at its given position.
x Array | number <optional>
 0

An optional X-axis position of the start of the cell, in chart or model coordinates.
y number <optional>
 0

An optional Y-axis position of the start of the cell, in chart or model coordinates.
z number <optional>
 0

An optional Z-axis position of the start of the cell, in chart or model coordinates.
Author:
  • drajmarsh

Extends

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
  • 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:
:Array|null

boundary

The cell boundary consisting of shared points.

Cell boundaries are mainly used when displaying the grid in block-color with displacement. Caching boundary information makes it much faster to determine value/height differences and generate the side walls of each block.

Cell boundaries consist of points ordered in a anti-clockwise direction around the cell center point.

Type
  • Array | 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
Inherited From:
Overrides:
: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

isGridCell <readonly>

A flag identifying this object as a grid cell.

Type
  • boolean
:boolean

isPoint <readonly>

A flag identifying this object as a 3D point.

Type
  • boolean
Inherited From:
Overrides:
: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:
: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
Inherited From:
Overrides:
: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:
: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|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:
:number

value

The value stored by the cell.

Type
  • number
:boolean

visible

Whether or not the cell is visible.

Type
  • boolean

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.
Inherited From:
Overrides:
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.
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

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;

     };
     /// ...
 };

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

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

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

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

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.
Inherited From:
Overrides:
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.
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

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;

     };
     /// ...
 };