API Docs

Class: Entity

BIM. Entity

The base class for all physical BIM entities.

This class provides BIM entities with an attribute map, volumetric extents and some basic flags. It is the core of each item in the project hierarchy, such as structures, levels, spaces, elements and components. The distinction between BIM.Entity and BIM.Element is important.

In the building design and construction industries, the term 'element' has a very specific meaning - referring to those parts of a building that contribute to its physical form and the load bearing capacity of its structure. This includes floors, walls, roofs, foundations, footings, beams, columns and others.

However, a building consists of so much more than just physical elements. For example, floors and walls typically belong to one or more building storeys or levels, levels typically belong to a structure and structures typically belong to a site or project. Levels and structures have no physical geometry of their own as this is generated solely from the building elements they contain. Also, elements such as walls can contain windows and doors that have a physical form, but cannot be elements in and of themselves as their form only makes sense when they are part of another element.

Thus, at their core, most things are a BIM.Entity, some entities are BIM.Element objects and elements can reference different BIM.Component objects to give them different characteristics and representations.

new Entity( [config] [, typeName])

Creates a new basic BIM entity.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
name string <optional>

An optional human-readable name for this item, defaults to class type.
uuid string <optional>

An optional universally unique identifier of this item, defaults to a new UUID.
visible boolean <optional>

Whether or not the entity is initially visible within the model, defaults to true.
attributes object | Map <optional>

An optional object or map with any arbitrary attributes to associate with this entity.
extents THREE.Box3 <optional>

An optional bounding box with the initial extents of the entity in model space.
typeName string <optional>

This additional parameter is typically used by subclasses to pass in a default name without altering the config object.
Author:
  • drajmarsh

Extends

Members

:Map

attributes

Stores any arbitrary attributes associated with this entity.

This is a simple key/value map that can be used to store any additional information about the entity that may be required by the application such as reference ids, material types, fire ratings, costings, etc.

Type
  • Map
:string

className <readonly>

The name of the subclass for this object instance.

This name must match the name of this class within the PD.Registry. Thus, the base implementation simply references this.constructor.getClassName() to ensure that this is always the case even for subclasses. As a result, there is rarely any need to override this method.

This property is used when copying, storing and exporting data for subclass instances to ensure that they are recreated as instances of the right class.

Type
  • string
Inherited From:
Overrides:
:string

displayName <readonly>

The name to display for this class within the user interface.

Type
  • string
Inherited From:
Overrides:
:BIM.ENTITY

entityType <readonly>

Defines the type of BIM entity this class represents.

This value is used by the PD.Registry for grouping elements and matching components. The base implementation simply references this.constructor.getEntityType() so that only a static method needs to be added to subclasses.

Type
:THREE.Box3

extents

The 3D extents of the element as a bounding box.

Type
  • THREE.Box3
:boolean

hasChanged

Whether or not the entity has recently changed and needs to update.

This property is typically set by the user interface or other parts of the framework when the entity's properties have changed and any visual representations need to be updated.

Type
  • boolean
:string

iconName <readonly>

The name of the SVG icon to associate with this object instance.

This name should match the name of the icon associated with this class within the PD.Registry. Thus, the default implementation simply references this.constructor.getClassName() to ensure that this is always the case, even for subclasses. However, you can override this property if you want a different icon dependant on other properties of the class instance, as shown in the example below.

Type
  • string
Inherited From:
Overrides:
Example
// Overriding the icon name.

MyElements.Table = class extends PD.Base {
    /// ...
    get iconName() {
        if (this.hasRoundTop) return 'MyElements.Table.Round';
        return this.constructor.getClassName();
    };
    /// ...
 };
:boolean

isEntity <readonly>

A flag identifying this object as an entity.

Type
  • boolean
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:boolean

selected

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

This property is typically set by the user interface when the user selects or deselects entities within the model view. The PD.SelectionManager uses this property to keep track of which entities are currently selected.

Type
  • boolean
:string

uuid

A universally unique identifier for the item instance.

Type
  • string
Inherited From:
Overrides:
:boolean

visible

Whether or not the entity is visible within the model.

The framework tries its best to avoid rendering invisible entities, but depending on the type of entity and how it is represented, this may not always be possible. For example, not rendering a chair is

Type
  • boolean

Methods

checkDynamicParameter(param, group [, host])

Provides an opportunity to dynamically limit the value and/or range of each parameter.

This method is called whenever a dynamic parameter is interactively changed. The param argument gives access to the parameter being changed whilst the group argument gives access to other parameters within the same parameter group.

NOTE: Range validation in this method is not absolutely required, but doing so can prevent unnecessary model rebuilds due to out-of-range parameters being different from their previous values, even though the object's geometry will not actually change due to range constraints within the subclasses rebuild() method. Thus, it is usually best to do them here so that someone's future airport model is not entirely rebuilt each time they try to set a too-large length in your custom door handle component.

Parameters:
Name Type Argument Description
param PD.Parameter

The parameter that is being interactively changed.
group PD.ParamGroup

The group that the dynamic parameter belongs to.
host object <optional>

For components only, the parent or host object that called this method.
Inherited From:
Overrides:
Example
checkDynamicParameter(param, group, host) {

     switch (param.name) {

         case 'height':
             if (param.value < 1.0) param.value = 1.0;
             break;

         case 'width':
         case 'length':
             if (param.value < 100.0) param.value = 100.0;
             if (this.standardBedSize > 0) { // If not custom.
                 group.setParameterValue('standardBedSize', 0);
                 this.standardBedSize = 0; // Make it custom.
             }
             break;

         case 'standardBedSize': {
                 const std_bed = this.getStandardBedSize(Math.round(param.value));
                 if (std_bed != null) {
                     const [ width, length ] = (PD.DIMENSION.useImperial) ? std_bed.sizeImperial : std_bed.sizeMetric;
                     this.width = PD.Utils.toNumber(width, this.width);
                     group.setParameterValue('width', this.width);
                     this.length = PD.Utils.toNumber(length, this.length);
                     group.setParameterValue('length', this.length);
                 }
             } break;

       }

 };

clone()

Creates a copy of this instance with different name and uuid.

Inherited From:
Overrides:
Returns:

Returns a new instance with copied values.

Type
PD.Base | null

deleteAttribute(name)

Removes an attribute from this entity.

Parameters:
Name Type Description
name string

The name of the attribute to remove.
Returns:

Returns this entity to support method chaining.

Type
PD.Base

fromJSON(data)

Safely copy properties from a source object.

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

This method is used in different ways by the framework, but the main purpose is to copy data from simple POJO objects, typically ones that have been created using the BIM.Entity#toJSON method and stores in a model file.

It first checks for the presence of each property in the host object and performs a range-protected copy of that data if it exists. This allows for safely copying data from JSON objects loaded from a file, subclassed or superclass objects, or objects that may have been saved with an earlier version of the framework and may not contain the same properties as the current version.

Parameters:
Name Type Description
data object

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

Returns this instance to support method chaining.

Type
BIM.Entity
Example
// Overriding this method.

class MyElement extends PD.Element {

    /// ...

    fromJSON(data) {

        super.fromJSON(data);

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

        if ('myNewIntegerProp' in data) {
            this.myNewIntegerProp = PD.Utils.toInteger(data.myNewIntegerProp, this.myNewIntegerProp);
        }

        if ('myNewBooleanProp' in data) {
            this.myNewBooleanProp = PD.Utils.toBoolean(data.myNewBooleanProp, this.myNewBooleanProp);
        }

        if ('myNewVectorProp' in data) {
            PD.Utils.copyVector3(data.myNewVectorProp, this.myNewVectorProp);
        }

        if ('myNewColorProp' in data) {
            PD.Utils.copyColor(data.myNewColorProp, this.myNewColorProp);
        }

        return this;

    };

    /// ...

};

getAttribute(name)

Retrieve an attribute stored on this entity, 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

getDynamicParameters( [host])

Provides a list of dynamic parameter groups to the UI.

This list is typically requested by the front-end framework whenever something is selected in the model and used to generate DOM components that allow the user to interactively edit each parameter.

Override this method in any derived classes to specify your own custom parameters and parameter groups. The array must only contain PD.ParamGroup objects for it to display the parameters it contains, as shown in the example below.

When the user modifies any a parameters, the updateDynamicParameters() method on the owner is called. As long as the name property of each parameter corresponds exactly to a property on the custom element, the default implementation of the update method can be used. This simply does some type and tolerance checking to see if the value has changed, before assigning the new value and calling the rebuild() method on the element. If you need to use names other than property names, or need to do your own type and/or tolerance checking, then you will need to also override the PD.Base#updateDynamicParameters` method.

Parameters:
Name Type Argument Description
host object <optional>

For components only, the parent or host object that called this method.
Inherited From:
Overrides:
Returns:

Returns an array of zero or more PD.ParamGroup objects.

Type
Array
Example
getDynamicParameters(host) {
     return [
         new PD.ParamGroup({
             name: 'mainParams',
             title: 'Table Parameters',
             target: this,
             params: [
                 new PD.Parameter({ name: 'height', title: 'Table Height', value: this.height, paramType: PD.ParamType.SmallDistance, description: 'The height from floor level to the top of the table.' }),
                 new PD.Parameter({ name: 'size', title: 'Table Top Size/Diameter', value: this.size, paramType: PD.ParamType.Distance, description: 'The size of the table top when not defined by a closed path.' }),
                 new PD.Parameter({ name: 'thickness', title: 'Table Top Thickness', value: this.thickness, paramType: PD.ParamType.SmallDistance, description: 'The thickness of the table top surface.' }),
                 new PD.Parameter({ name: 'offset', title: 'Offset From Path', value: this.offset, paramType: PD.ParamType.SmallDistance, description: 'The offset distance from the table path.' }),
                 new PD.Parameter({ name: 'swapSides', title: 'Swap Sides', value: this.swapSides, paramType: PD.ParamType.Boolean, description: 'Reverse the direction of the table relative to its path.' }),
                 new PD.Parameter({ name: 'isRound', title: 'Round Table', value: this.isRound, paramType: PD.ParamType.Boolean, description: 'Whether or not the table surface is round.'  }),
             ]
         }),
         new PD.ParamGroup({
             name: 'legParams',
             title: 'Leg Parameters',
             target: this,
             params: [
                 new PD.Parameter({ name: 'legCount', title: 'Number of Legs', value: this.legCount, paramType: PD.ParamType.Integer, description: 'The number of legs on the table.' }),
                 new PD.Parameter({ name: 'legSize', title: 'Leg Size', value: this.legSize, paramType: PD.ParamType.SmallDistance, description: 'The thickness of each leg of the table.' }),
                 new PD.Parameter({ name: 'legInset', title: 'Leg Edge Inset', value: this.legInset, paramType: PD.ParamType.SmallDistance, description: 'The inset distance of each leg from the table edge.' }),
                 new PD.Parameter({ name: 'legOffset', title: 'Leg Edge Offset', value: this.legOffset, paramType: PD.ParamType.Fraction, description: 'The relative distance of the leg along each edge span.' }),
                 new PD.Parameter({ name: 'legSpan', title: 'Max. Distance Between Legs', value: this.legSpan, paramType: PD.ParamType.Distance, description: 'The maximum distance between legs along each edge span.' })
             ]
         })
     ];
 };

intersectExtents(ray, intersection)

Determines if the given ray intersects the entity extents.

Parameters:
Name Type Description
ray THREE.Ray

The ray to find the intersection for.
intersection THREE.Vector3

The vector to store the intersection point, if any.
Returns:

Returns the intersection point, or null if no intersection.

Type
THREE.Vector3 | null

setAttribute(name, value)

Stores an attribute on this entity, or replaces it's existing value.

Parameters:
Name Type Description
name string

The name of the attribute to store.
value string

The attribute value to store.
Returns:

Returns this entity to support method chaining.

Type
PD.Base

setExtents(bbox)

Set the 3D extents of the element as a bounding box.

Override this method in bounding box driven building elements such as equipment, imported or parametric meshes to rescale or regenerate their underlying geometry whenever it changes.

Parameters:
Name Type Description
bbox THREE.Box3

The new bounding box extents to set.
Returns:

Returns this entity to support method chaining.

Type
PD.Base

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 toJSON method for more details.

Parameters:
Name Type Argument Description
data object <optional>

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

Returns a JSON object.

Type
object
Example
// Overriding this method.

class MyElement extends PD.Element {
    /// ...
    toJSON(data) {

        data = super.toJSON(data);

        data.myNewNumberProp = this.myNewNumberProp;
        data.myNewIntegerProp = this.myNewIntegerProp;
        data.myNewBooleanProp = this.myNewBooleanProp;
        data.myNewVectorProp = this.myNewVectorProp.toArray();
        data.myNewColorProp = this.myNewColorProp.toArray();
        return data;

    };
    /// ...
};

updateDynamicParameters(param, group)

Sets the dynamic parameter value and returns true if it changed.

Most subclasses don't need to override this method as it automatically detects changes and rebuilds the element/component and model when required. However, if you do need to add your own custom logic or intercept the return value, please read the following examples carefully and use whichever best suits your needs.

NOTE: When overriding this method, you may not want to call super.updateDynamicParameters(param, group) as the parent class may have added its own logic that may interfere with what you want to do. Instead, either use the static PD.Base.updateDynamicParametersOnHost method to check if the value changed, or base it on the third example which replicates the code in that static method.

Parameters:
Name Type Description
param PD.Parameter

The dynamic parameter that changed.
group PD.ParamGroup

The group that the dynamic parameter belongs to.
Inherited From:
Overrides:
Returns:

Returns true if the value actually changed.

Type
boolean
Examples
updateDynamicParameters(param, group) {

     /// When you want parent class to use its logic.
     if (super.updateDynamicParameters(param, group)) {
         if (param.name == 'i_am_special') this.doSomethingSpecial();
         return true;
     }

     return false;

 };
updateDynamicParameters(param, group) {

     /// When you don't want parent to handle parameter updates.
     if (PD.Base.updateDynamicParametersOnHost(param, group, this)) {

         /// Invalidate geometry.
         if (this.typeComponent) {
             ++this.typeComponent.updateIndex;
         }

         /// Rebuild element.
         this.hasChanged = true;
         this.update();

         /// Only update site mesh.
         if (this.onlyUsesSiteMesh) {
             const level = this.level;
             if (level) { // Don't trigger whole level update.
                 level.rebuildSiteMesh();
                 PD.GlobalActions.redrawAndUpdateSelection();
                 return false;
             }
         }

         return true;

     }

     return false;

 };
updateDynamicParameters(param, group) {

     /// The following three lines of code replicate
     /// `PD.Base.updateDynamicParametersOnHost()`, which you can
     /// use if you need to access `target` without having to call
     /// `group.getTarget() || this` twice.

     const target = group.getTarget() || this;
     target.checkDynamicParameter(param, group, this);
     if (param.setValueOnHostIfDifferent(target, group, this)) {

         /// You can now use `target`.
         if (target.myOwnMeshThatIsUpdatedDuringRebuild) {

             /// Rebuild element.
             this.hasChanged = true;
             this.update();

             /// If no level meshes or other elements are affected,
             /// simply update the target locally and return false.
             this.myOwnMeshThatIsUpdatedDuringRebuild.update();

             /// Update selection meshes if the
             /// element's highlight geometry changed.
             PD.GlobalActions.updateSelectionMeshes();
             return false;

         }

         return true;

     }

     return false;

 };

getClassDescription() <static>

A brief description of this class to accompany its icon.

Returns:

Returns a brief description.

Type
string

getClassName() <static>

The name of this class within the PD.Registry.

See getClassName() for more details as this is required for use with the PD.Registry.

Returns:

Returns the registered name of this class.

Type
string

getEntityType() <static>

Defines the type of BIM entity this class represents.

This value is used by the PD.Registry for finding and grouping like elements, as well as matching elements to components, etc.

Sub-classes that derive from core element subclasses (such as BIM.Space, BIM.Wall, BIM.Aperture, etc) will already return the appropriate entity type. However, any subclasses that derive directly from BIM.Element, BIM.Entity or PD.Base will need to override this static method to return the appropriate entity type.

Returns:

Returns the BIM entity type this class represents.

Type
BIM.ENTITY
Example
class MySpecialWall extends BIM.Element {
    /// ...
    static getEntityType() {
        return BIM.ENTITY.WALL;
    };
    /// ...
}

getNextEntityID(config) <static>

Retrieves the next incremented entity id index.

Parameters:
Name Type Description
config object
Returns:

Returns the next counter index.

Type
number

isEntity() <static>

Indicates that this is a BIM entity class.

Returns:

Returns true when the class is a BIM entity.

Type
boolean

resetEntityID() <static>

Resets the entity counter index to zero.

Only call this method when loading or creating a new model, otherwise you will end up with duplicate id values.

Returns:

Returns the next counter index.

Type
number