API Docs

Class: Structure

BIM. Structure

Defines a building, structure, road or railway within the project.

new Structure( [config] [, type])

Creates a new building or structure.

Parameters:
Name Type Argument Description
config object <optional>

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

The human-readable name for the structure.
visible boolean <optional>

Whether or not the structure is visible within the model.
ghosted boolean <optional>

Whether or not the structure is shown in transparent outline only.
project BIM.Project <optional>

The project to which this structure belongs.
type string <optional>

An optional human-readable type name.
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
Inherited From:
Overrides:
: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

description

The human-readable description of this structure.

Type
  • string
:string

displayName <readonly>

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

Type
  • string
Inherited From:
Overrides:
:Map

entityMap

A map of entities indexed by universally unique identifier (UUID).

This map contains all entities that are part of this structure, including levels, spaces and elements. It provides a more convenient way to quickly lookup referenced entities without having to traverse the entire structure hierarchy.

Type
  • Map
: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
Inherited From:
Overrides:
:THREE.Box3

extents

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

Type
  • THREE.Box3
Inherited From:
Overrides:
:boolean

geometryChanged

A flag set whenever a level's geometry is marked as changed.

This flag is set by the child levels of a structure whenever their geometry changes and is used by the PD.ModelManager to know when to update ray-tracing octrees.

Type
  • boolean
:number

getNextCounterIndex

Retrieves an incremented ordinal index for use in the default name of levels.

Type
  • number
:boolean

ghosted

Whether or not the structure is shown in transparent outline only.

This is typically used to show non-editable background structures when editing levels or elements within an editable structure.

Type
  • boolean
: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
Inherited From:
Overrides:
: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();
    };
    /// ...
 };
:number

id

A unique integer identifier for fast discovery and/or equality checking.

This identifier is unique within the current project data and is primarily intended to facilitate fast lookup and equality checking. It is assigned automatically when the structure is created and should not change. It is much simpler than the uuid property, being a numeric integer rather than a long string of characters, and is the preferred way of comparing structure entities to see if they are the same.

Type
  • number
:boolean

isEntity <readonly>

A flag identifying this object as an entity.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isStructure <readonly>

A flag identifying this object as a structure or building.

Type
  • boolean
:Array

levelList

The list of levels that make up the structure.

This is an ordered list of BIM.Level objects that belong to this structure. The order is determined by their floor elevation in the sortLevels() method, which lowest to highest by default.

Type
  • Array
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:BIM.Project|null

project

The project this building/structure belongs to.

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

icon <static>

The icon associated with this class in the PD.Registry.

See PD.Base.icon for more information on this object format.

Type
  • object

Methods

addLevel(level [, index])

Add a level to this structure.

Parameters:
Name Type Argument Description
level BIM.Level

The level to add.
index number <optional>

An optional ordinal index at which to insert it.
Returns:

Returns this structure to support method chaining.

Type
BIM.Structure

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;

       }

 };

clear()

Clears everything from this structure so it can be reused.

Returns:

Returns this structure to support method chaining.

Type
BIM.Structure

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

computeExtents(all)

Calculates the extents of the structure from all its level.

If the level is empty it defaults to a 1mm cube.

Parameters:
Name Type Description
all boolean

An optional flag to include all levels even if not visible.
Returns:

Returns the newly computed bounding box.

Type
THREE.Box3

deleteAttribute(name)

Removes an attribute from this entity.

Parameters:
Name Type Description
name string

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

Returns this entity to support method chaining.

Type
PD.Base

findLevelByName(name)

Searches for a matching level in the structure.

Parameters:
Name Type Description
name string

The name of the level to find.
Returns:

Returns the matching level or null.

Type
BIM.Level | null

findLevelByUUID(uuid)

Searches for a matching level in the structure.

Parameters:
Name Type Description
uuid string

The UUID of the level to find.
Returns:

Returns the matching level or null.

Type
BIM.Level | null

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

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

Type
any | undefined

getDynamicParameters( [host])

Provides a list of dynamic parameter groups for editing this structure.

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

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 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.' })
             ]
         })
     ];
 };

getHeightOfNextLevel()

Returns the height of the next floor level.

Returns:

Returns this next level height.

Type
number

getLevelsAtElevation(list, ref_level, height)

Fills the given list with any levels ate the same height.

Parameters:
Name Type Description
list Array

The list to add the same-height levels to.
ref_level BIM.Level

The level to check against.
height number

The elevation height to check.
Returns:

Returns the given list array.

Type
Array

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

Returns the intersection point, or null if no intersection.

Type
THREE.Vector3 | null

markGeometryAsChanged()

Tells each level in the structure that its geometry has changed.

Returns:

Returns this structure to support method chaining.

Type
BIM.Structure

removeLevel(level)

Removes a level from this structure.

Parameters:
Name Type Description
level BIM.Level

The level to remove.
Returns:

Returns the ordinal index of the removed level, or -1 if not found in this structure.

Type
number

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

Returns this entity to support method chaining.

Type
PD.Base

showShadows(state)

Toggles the display of shadows within this structure.

Parameters:
Name Type Description
state boolean

Whether or not to show shadows.
Returns:

Returns this structure to support method chaining.

Type
BIM.Structure

sortLevels()

Sorts all the levels in the structure by their floor level.

Returns:

Returns this structure to support method chaining.

Type
BIM.Structure

sortLevelsByLevel()

Sorts all the levels in the structure by floor level relative to given level.

Returns:

Returns this structure to support method chaining.

Type
BIM.Structure

update( [forceUpdate])

Updates all levels and checks to rebuild their geometry.

Parameters:
Name Type Argument Description
forceUpdate boolean <optional>

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

Returns this structure to support method chaining.

Type
BIM.Structure

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;

 };

updateExtents(all)

Updates the existing extents of the structure based on the current floor level.

This method modifies the extents of the structure to reflect any changes in PD.GlobalState.currentFloorLevelOffset when a new level is moved onto the edit plane.

It differs from computeExtents() in that it uses the existing level displayExtents rather than recomputing them, so is much quicker. Also, if the level is empty it uses the default model extents rather than a 1mm cube.

Parameters:
Name Type Description
all boolean

An optional flag to include all levels even if not visible.
Returns:

Returns the newly updated bounding box.

Type
THREE.Box3

updateLevelsAboveAndBelow()

Returns levels in the structure sorted by floor level.

Returns:

Returns an array of sorted levels.

Type
Array

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 PD.Base.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.

See BIM.Entity.getEntityType for more details as this is required for use with the PD.Registry.

Returns:

Returns the BIM entity type this class represents.

Type
BIM.ENTITY