API Docs

Class: External

BIM.Element. External

The base class for elements that are typically outside and optionally clip themselves to the building's external envelope.

External elements can also clip and/or cut-and-fill any overlapping BIM.Terrain elements.

External elements all store a footprint polygon that can be offset/inset from their main path, as well as a cached ClipperLib path that can be used by terrain elements to subtract the footprint from their area and potentially generate an area of cut/fill around the element.

new External( [config] [, typeName] [, typeComponent])

Creates a new external element.

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.
path BIM.Path <optional>

An optional path for this element's geometry to follow, defaults to an empty path.
shell PD.Shell <optional>

An optional shell to use when generating element geometry, defaults to a new shell.
height number <optional>

The height of this element if applicable, defaults to zero.
width number <optional>

The width to use if the element follows an open path in mm, defaults to 900mm or 3'.
systems BIM.SYSTEM <optional>

The building system(s) this element contributes to or draws from.
elementType BIM.ELEMENT <optional>

The BIM/IFC/gbXML element type enumerator for this element, defaults to BIM.ELEMENT.SHADE.
typeComponent BIM.Component <optional>

An optional component to define the type of element.
subType number <optional>

An optional element sub-type enumerator, defaults to zero.
outerOffset number <optional>

An offset around the external boundary of the element path in mm, defaults to zero.
innerOffset number <optional>

An offset around any internal boundaries within the element path in mm, defaults to zero.
faceUpwards number <optional>

Whether or not this element's surface should always face upwards, defaults to false.
clipToLevel number <optional>

Whether or not this element clips itself to the external building envelope, defaults to true.
cutAndFill number <optional>

Whether or not this element cuts and fills terrain elements on the same level, defaults to true.
typeName string <optional>

An additional parameter used by subclasses to set the element type name without modifying the config object.
typeComponent BIM.Component <optional>

An additional parameter used by subclasses to set the type component without modifying 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
Inherited From:
Overrides:
:PD.BRep|null

brep

An optional boundary representation defining the element shape.

Whilst some elements store all of their geometry in their shell, this is not always the most effective and efficient approach for all element types. For example, railings, fences and stairs have complex post, rail, infill and tread geometry between each path segment, which may add up to many thousands of surfaces. This would make interactive selection and collision detection more computationally expensive if all of that geometry had to be tested each time. Moreover, when selecting a railing, you would need to click exactly on one of its surfaces, which may not be easy if the post, rail and slat sizes are small compared to their spans.

To address this, such element types can store complex geometry in a PD.BRep instance, which uses less memory than a shell and can store curved surfaces as well as planar ones. To make selection easier, these elements can also store a simplified shell representation of their geometry, which is used for interactive selection and collision detection. This shell is typically composed of a few polygons that cover the main spans of the element, such as the vertical spans between each post in a railing, or the vertical and horizontal planes of a chair's seat and backrest. The rest of the detailed geometry is then stored in this brep.

Type
Inherited From:
Overrides:
:number

buildRef

A reference value used exclusively by the host level of the element.

This value is used by the level that hosts the element, or the level that hosts its parent element if it has one. It is used internally to determine if and when the level needs to update various parts of its own managed geometries.

Type
  • number
Inherited From:
Overrides:
:boolean

canBelongToSpace <readonly>

Whether or not this element can belong to a space.

When true, the element can be added to a BIM.Space by interactively dragging it into the volume of the space. When false, the element can only be added to a space programmatically, typically belonging only to a level.

For most element this property is true, but for elements such as roofs and footings, where they are typically dragged around above, below and through existing spaces, this property should be false.

addElement() method on the space instance.

Type
  • boolean
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:
:boolean

clipToLevel

Whether or not this element clips itself to the external building envelope, defaults to true.

Type
  • boolean
:boolean

cutAndFill

Whether or not this element cuts and fills terrain elements on the same level, defaults to true.

Type
  • boolean
:string

displayName <readonly>

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

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

elementType

The BIM element type for the element.

Whilst the entity type is very specific regarding the actual class of an element, the element type is a broader categorisation intended primarily for compatibility with gbXML element types and the various analysis tools that use them. However, it can also be a very useful internal filter when searching for elements of a particular type.

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

extents

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

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

faceUpwards

Whether or not this element's surface should always face upwards, defaults to false.

Type
  • boolean
:PD.Polygon|null

footprint

Stores the offset/inset boundary of the element form.

This is often the same shape as the path, but includes the outerOffset as well as projected segments between junctions and other offsets.

This is created in the BIM.Element.External#generateFootprint method and is a volatile reference to a facet within the element's shell. Prior to that its value will be null, so you should always check for a valid value before using the footprint directly.

Type
:PD.Clipper.Shape

footprintClipShape

A 2D ClipperLib shape for generating the footprint of the element.

This is primarily used for clipping the element if it intersects the level boundary, but can also be used by other elements when merging or clipping.

It is used within the BIM.Element.External#clipToLevelBoundary method, as well as the BIM.Element.External#rebuild method if the BIM.Element.External#clipToLevel option is false or the element is entirely inside a host space.

Type
: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:
:number

height

The height of the element in model units, if applicable.

Type
  • number
Inherited From:
Overrides:
: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 element 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 elements to see if they are the same.

Type
  • number
Inherited From:
Overrides:
:number

innerOffset

An offset around any internal boundaries within the element path in mm, defaults to zero.

Type
  • number
:boolean

isElement <readonly>

A flag identifying this object as a BIM element.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isEntity <readonly>

A flag identifying this object as an entity.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isExternalElement <readonly>

A flag identifying this object as an external element.

Type
  • boolean
:boolean

isSurfaceMounted <readonly>

Whether or not this element should be mounted on a surface.

When true, the element will try to attach itself to the nearest vertical surface within the model rather than being free-standing. This is mainly used when interactively dragging and dropping elements into the model.

Type
  • boolean
Inherited From:
Overrides:
:BIM.Renderable|BIM.Level|null

level <readonly>

The level within a building/structure that this element belongs to.

To add an element to a level, use the BIM.Level#addElement method on the level you wish to add the element to.

Type
Inherited From:
Overrides:
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:boolean

onlyUsesOwnMesh <readonly>

Whether or not this element exclusively renders to its own mesh and does not use any level meshes.

This value will be false for the majority of building and drawing elements as they use the primary level meshes to render themselves and will likely react to any changes in the built form. However, some analytical element classes such as BIM.SunPath3D and BIM.IsoVist use entirely their own meshes so can be updated completely independently of the rest of the building model.

Thus, a true value here allows elements that only use their own dedicated mesh to regenerate themselves without triggering a full level-wide model regeneration when their parameters are edited. This happens in the element's BIM.Element#updateDynamicParameters method which checks this property to determine whether to just call the PD.GlobalActions.updateSelectionMeshes method instead of returning true and rebuilding the entire level.

Type
  • boolean
Inherited From:
Overrides:
:boolean

onlyUsesSiteMesh <readonly>

Whether or not this element exclusively renders to its level site mesh.

This value will be false for the majority of building and drawing elements as they use the primary level meshes to render themselves and will likely react to any changes in the built form. However, some site elements such as plants, rocks, terrains and pots only use the on-demand site mesh, which can be updated completely independently of the rest of the building model.

Thus, a true value here allows elements that only use their level's site mesh to regenerate themselves without triggering a full level-wide model regeneration when their parameters are edited. This happens in the element's BIM.Element#updateDynamicParameters method which checks this property to determine whether to just call the BIM.Level#rebuildSiteMesh method instead of returning true and rebuilding the entire level.

Type
  • boolean
Inherited From:
Overrides:
:number

outerOffset

An offset around the external boundary of the element path in mm, defaults to zero.

Type
  • number
:BIM.Element|null

parent <readonly>

The container element that this element belongs to.

To add an element to a container element, use the addElement() method on the container you wish to add the element to.

Type
Inherited From:
Overrides:
:boolean

selectSegmentsByShell <readonly>

Whether to select path segments in 3D using each junction's shell.

Type
  • boolean
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
Inherited From:
Overrides:
:PD.LocalCoordinates

sharedLocalCoordinates <readonly>

A shared local coordinate system to use for generating geometry.

This coordinate system is shared with all elements and is intended only for temporary use when generating each element's geometry. Thus, it should be considered highly volatile and only safely used within the BIM.Element#rebuild method of each element. You must initialise it on every use and can then pass it around to other functions/methods called from within the initialising method. However, you should assume that it will be immediately used again by another element as soon as your rebuild method returns, so it will not hold or persist any particular value beyond that.

Type
Inherited From:
Overrides:
:PD.Shell|null

shell

Stores the 3D shell geometry for this element.

Shell geometry is typically used to represent the base shape of an element and is the default geometry for interactive selection testing and collision detection. Some elements, such as walls, slabs and columns, have relatively simple geometry so use their shell for both selection and visual representation. Other elements, such as railings, use their shell to store single vertical selection planes between each corner post, but store the more detailed post, rail and infill geometry in their brep property.

A shell is composed of one or more PD.Polygon instances, which are bounded planar surfaces that each store their own boundary contours, plane equations, center position and 3D extents, as well as fill and line colours. This makes them ideal for fast ray intersection and adjacency calculations, but means they use more memory than an equivalent PD.BRep.Face instance. Thus, rather than store thousands of post, rail and infill surfaces as shell polygons, the railings element stores all that in its PD.BRep, but just a few shell polygons to cover each span. As well as being much faster, this has the additional benefit of allowing selection by simply clicking anywhere on the span, rather than having to click directly on an actual post, rail or slat surface.

What Goes in a Shell

It is not always obvious what should go in the shell and what in the brep, so it will always be up to the element developer to decide. However, as an illustration, consider something like a wooden chair element. All it needs for selection and collision detection is a horizontal polygon for the seat and an inclined polygon for the backrest. This provides intuitive targets for user selection and sufficient geometry for determining if an avatar has bumped into it. It also allows the avatar to sit and lean against the backrest without falling through. All of the detailed leg, armrest and horizontal/vertical backrest supports can then be stored in the brep, with just the two planes stored in the shell.

A couch or sofa element on the other hand, may be a little different. It will likely need boxes for the spans of both the seat and backrest, but also for each armrest. For a simple low-poly visual representation this could be just enough, so it could all be stored in the shell and nothing in the brep. However, once you start adding curved padding, cushions and other embellishments, the shell representation could likely remain just boxes, but the more complex and curved geometry would likely be best added to the brep.

Type
Inherited From:
Overrides:
:BIM.Space|null

space <readonly>

The space that this element belongs to.

To add an element to a space, use the BIM.Space#addElement method on the space you wish to add the element to.

Type
Inherited From:
Overrides:
:BIM.Structure|null

structure <readonly>

The building/structure that this element belongs to.

This is dynamically extracted from either the level or the space that the element belongs to within the model.

Type
Inherited From:
Overrides:
:number

subType

Stores a sub-type enumerator for this element.

Sub-types are specific to each entity type and are primarily used to assign an appropriate type component. Each entity type for which sub-types are defined will have its own set of sub-type enumerators, typically with the same name as the entity type but in all-caps.

For example, a BIM.Chair entity uses sub-types given by the BIM.CHAIR enumerator, and maps to various BIM.Chairs classes as type components. These sub-types include office chairs, dining chairs, lounge chairs, benches, stools, etc.,

Type
  • number
Inherited From:
Overrides:
:BIM.SYSTEM

systems

The building system(s) this element contributes to or draws from.

Systems essentially categorise elements based on the purpose they serve. The can be holding the building up, delivering water, clearing waste, conducting electricity or managing operations. They can also be used to differentiate between different domains of interest, professions or trades. For example, a wall is part of the structural system, a sink is part of the plumbing system, a light fitting is part of the electrical system, and a radiator is part of the HVAC system.

Elements can belong to multiple systems, for example a heating boiler is part of both the plumbing and HVAC systems. This property is therefore a bitwise OR combination of the different BIM.SYSTEM enumerators.

Type
Inherited From:
Overrides:
:boolean

trackSpaceBoundary

Whether or not to check for path alignment relationships with parent space path, defaults to false.

When true and belonging to a parent space, the element checks each of its path junctions to see if they are coincident with the host space boundary path junctions or lie along any of its boundary segments. If a coincident or inline relationship is found, a BIM.Relation is created and stored on both the element and space junctions. This allows the space to update each element when it is moved and the user to remove the link by simply moving the element junction away from the space boundary.

This value is primarily intended for use by elements such as cupboards, switches, sockets, radiators, wall lights and other fixtures that are typically mounted on or against walls and need to track/update their position relative to the space boundary as it changes.

Type
  • boolean
Inherited From:
Overrides:
:BIM.Component|null

typeComponent

A type component reference.

This is typically determined by the subType property and assigned when a new instance is created.

Different entity types use type components differently, and some not at all. However, the referenced component typically defines a sub-type for the entity and either influences or entirely dictates its overall parametric form or shape. For example, a wall can reference a BIM.Walls type component, which defines its thickness, surface properties and material layers via a BIM.Construction. A chair references a BIM.Chairs type component to actually generate the entire geometry of each chair instance as laid out by its path junctions.

Type
Inherited From:
Overrides:
:string

typeDisplayName <readonly>

Retrieves the display name of this element or its assigned type component.

Type
  • string
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:
:boolean

wasRebuilt

Stores whether or not the element's geometry has recently been rebuilt, which may affect the host level's geometry.

This value must be set to true whenever the element's geometry changes and is used by the host level to determine if it needs to update level geometry as a result. The host level itself will reset this value to false once it has processed the change, so no other method or action anywhere should ever set this value to anything other than true.

NOTE: It is the responsibility of the element's own update() method to set this value to true when calling its rebuild() method. The reason this is not left to the rebuild() method is that virtually every element subclass requires its own specific rebuild() method to generate its geometry, making this one of the most overridden methods in the entire framework. Thus, to avoid the risk of having custom class developers forget to set this flag in every single overridden rebuild() method, it is left to the update() method which is overridden far less often and is also responsible for managing other element state such as the hasChanged flag.

Type
  • boolean
Inherited From:
Overrides:
:number

width

The width of the element in mm if path not closed, defaults to 900mm or 3'.

If the element's path is not closed, this value will be used to determine the width of the generated footprint. If the path is a closed loop, this value will be ignored.

Type
  • number

Methods

addJunction(junction [, contour_index] [, ordinal_index])

Adds a new junction at the given index within the given contour.

Parameters:
Name Type Argument Description
junction BIM.Junction

The junction to be inserted.
contour_index number <optional>

The ordinal index of the path contour to insert the junction in, defaults to 0.
ordinal_index number <optional>

The ordinal index of the junction within the specified contour, defaults to the end.
Inherited From:
Overrides:
Throws:

Throws an exception if the element has no path.

Type
Error
Returns:

Returns true if a new vertex was successfully inserted.

Type
boolean

checkJunctionRelationships(space, junctions)

Checks the element for junction relationships.

This method is only called on elements when their BIM.Element#trackSpaceBoundary property is true.

Parameters:
Name Type Description
space BIM.Space

The parent space of the element.
junctions BIM.Junction

The junction to check for relationships for.
Inherited From:
Overrides:

checkToSelectElementByRay(selection)

Checks if the given ray intersects this element, but don't actually select it yet.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if the element should/would be selected, otherwise false.

Type
boolean

clearSelection()

Deselects the element path and all its points.

Inherited From:
Overrides:
Returns:

Returns this path to support method chaining.

Type
BIM.Element

clipToLevelBoundary(levelBoundaryPath, level)

Clips the external element to the building footprint on the level.

This method is called automatically by the level this element belongs to in order to clip its footprint to the outer boundary of spaces and walls.

Parameters:
Name Type Description
levelBoundaryPath Array

The level boundary to trim the ground to.
level BIM.Level

The level the boundary belongs to.
Returns:

Returns true if the slab was clipped.

Type
boolean

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

closestPoint3D(snapper, ray, test_pt)

Checks for points in the element path near the 3D ray.

Parameters:
Name Type Description
snapper PD.Snapper

The snap helper object.
ray THREE.Ray

The ray through the 3D cursor.
test_pt THREE.Vector3

The point to find the closest snap to.
Inherited From:
Overrides:
Returns:

Returns true if a feature in the element was found and added to the snapper, otherwise false.

Type
boolean

closestPointOnAperture(snapper, ray, point [, selected_aperture])

Checks for points in the element path near the 3D ray.

Parameters:
Name Type Argument Default Description
snapper PD.Snapper

The snap helper object.
ray THREE.Ray

The ray through the 3D cursor.
point THREE.Vector3

The point to find the closest snap to.
selected_aperture BIM.Aperture <optional>
 null

The currently selected aperture, defaults to null.
Inherited From:
Overrides:
Returns:

Returns true if a feature in an aperture was found and added to the snapper, otherwise false.

Type
boolean

closestPointXY(snapper, test_pt)

Checks for points in the element path near the given point in the XY plane.

Parameters:
Name Type Description
snapper PD.Snapper

The snap helper object.
test_pt THREE.Vector3

The point to find the closest snap to.
Inherited From:
Overrides:
Returns:

Returns true if a feature in the element was found and added to the snapper, otherwise false.

Type
boolean

computeHeight()

Calculates the absolute height of the element.

Default element heights vary wildly. For example, a structural wall should run from the top of the floor slab of its level to the bottom of the floor slab of the level above, whereas an internal partition should run from the top of the floor slab to the bottom of the ceiling on its level. A kitchen cabinet should default to around 900mm or 36", but you may want a built-in cabinet to be full floor-to-ceiling height.

To support this, element heights can be given as either absolute model units (mm) or as a fractional value (0 to 1). The role of this method is to detect any fractional values and convert them to absolute values relative to the value returned by the BIM.Element#getReferenceHeight method.

Inherited From:
Overrides:
Returns:

Returns the calculated height of the element.

Type
number

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

dimension(mesh, size)

Adds dimension lines around an element when selected.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to render to.
size number

The size of dimension in model units.
Inherited From:
Overrides:
Returns:

Returns true if anything was added to the mesh.

Type
boolean

ensureValidBRep()

Retrieves the element's boundary representation (BRep), ensuring that it has a valid one.

If the element does not currently have a BRep, this method will create a new empty one and assign it to it. If it does have a BRep, it is simply returned. If you do not want to create a new BRep if one does not already exist, simply access the brep property instead.

Inherited From:
Overrides:
Returns:

Returns the element's BRep, creating one if necessary.

Type
PD.BRep
Example
/// Rather than using:
const brep = element.brep;
if (!brep) {
    element.brep = new PD.BRep();
}

/// You can simply use:
const brep = element.ensureValidBRep();
/// Now safe to use `brep` without having to check if it exists first.

ensureValidPath()

Retrieves the element's path, ensuring that it has a valid one.

If the element does not currently have a path, this method will create a new empty one and assign it to it. If it does have a path, it is simply returned. If you do not want to create a new path if one does not already exist, simply access the path property instead.

If a new path is created, the element's hasChanged property is also set to true to indicate that the element needs to be updated.

Inherited From:
Overrides:
Returns:

Returns the element's path, creating one if necessary.

Type
BIM.Path
Example
/// Rather than using:
const path = element.path;
if (!path) {
    element.path = new BIM.Path();
}

/// You can simply use:
const path = element.ensureValidPath();
/// Now safe to use `path` without having to check if it exists first.

ensureValidShell()

Retrieves the element's shell, ensuring that it has a valid one.

If the element does not currently have a shell, this method will create a new empty one and assign it to it. If it does have a shell, it is simply returned. If you do not want to create a new shell if one does not already exist, simply access the shell property instead.

Inherited From:
Overrides:
Returns:

Returns the element's shell, creating one if necessary.

Type
PD.Shell
Example
/// You can simply use:
const shell = element.ensureValidShell();
/// Now safe to use `shell` without having to check if it exists first.

/// Rather than using:
const shell = element.shell;
if (!shell) {
    element.shell = new PD.Shell();
}

findApertureByRay(selection)

Checks if the given ray intersects any apertures belonging to this element and, if so, updates the selection with the intersected aperture details.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if an aperture in the element was selected and the selection updated, otherwise false.

Type
boolean

findAperturesByFrustum(selection)

Searches for apertures inside the given frustum and, if found, adds them to the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if any apertures within the element were added to the selection, otherwise false.

Type
boolean

findBRepByFrustum(selection)

Checks if element's boundary representation is inside the frustum and updates the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if the boundary of the element was selected and the selection updated, otherwise false.

Type
boolean

findBRepEdgeByRay(selection)

Checks if the given ray intersects a boundary edge in this element and updates the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if a boundary edge within the element was selected and the selection updated, otherwise false.

Type
boolean

findBRepFaceByRay(selection)

Checks if the given ray intersects a boundary facet in this element and updates the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if a boundary facet within the element was selected and the selection updated, otherwise false.

Type
boolean

findBRepVertexByRay(selection)

Checks if the given ray intersects a BRep vertex in this element and updates the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if a boundary vertex within the element was selected and the selection updated, otherwise false.

Type
boolean

findByFrustum(selection)

Checks if element is inside frustum and updates the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if a path segment in the element was selected and the selection updated, otherwise false.

Type
boolean

findByRay(selection)

Checks if the given ray intersects this element and updates the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if a path segment in the element was selected and the selection updated, otherwise false.

Type
boolean

findFacetByRay(selection [, front])

Checks if the given ray intersects any shell facets belonging to this element's path junctions and, if found, updates the selection with the intersected facet details.

Parameters:
Name Type Argument Description
selection PD.Selection

The interactive selection accumulator.
front THREE.Vector3 <optional>

An optional position that must be in front of the plane.
Inherited From:
Overrides:
Returns:

Returns true if a path segment in the element was selected and the selection updated, otherwise false.

Type
boolean

findJunctionByRay(selection)

Checks if the given ray hits or passes close to any junctions and, if found, updates the selection with the closest junction details.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if a vertex in the element was selected and the selection updated, otherwise false.

Type
boolean

findJunctionsByFrustum(selection)

Searches for path junctions inside frustum and, if found, adds them to the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if any junctions within the element path were added to the selection, otherwise false.

Type
boolean

findSegmentByRay(selection [, shallow])

Checks if the given ray hits or passes close to any path segments and, if found, updates the selection with the closest segment details.

Parameters:
Name Type Argument Default Description
selection PD.Selection

The interactive selection accumulator.
shallow boolean <optional>
 false

When true, only segments checked, not any aperture elements.
Inherited From:
Overrides:
Returns:

Returns true if a path segment in the element was selected and the selection updated, otherwise false.

Type
boolean

findSegmentsByFrustum(selection)

Searches for path segments inside the given frustum and, if found, adds them to the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Inherited From:
Overrides:
Returns:

Returns true if any segments within the element path were added to the selection, otherwise false.

Type
boolean

generateFootprint(shell [, clipPath] [, clipZ])

Creates the footprint from either the given path or the element path.

When no clip path is given as an argument, the element's own path is used to generate the footprint, applying the current offset and inset values. This is typically done using the BIM.Path#generateShellFacet method.

If a clipped path is given, it will be a ClipperLib path containing one or more arrays of 2D {X,Y} points defining the new path that has been clipped to the level boundary. This clipper path is typically converted to a polygon using the PD.Polyline#fromClipperPathsByAxis method, as a horizontal plane located at the same height as the footprint.

In the element rebuild sequence, this method is usually called first without a clipper path, to generate the unclipped footprint, and then a second time with a clipper path if it intersects a boundary.

Override this method in your custom subclasses to generate your own footprint. When doing so, use the example method given below as a guide.

Parameters:
Name Type Argument Description
shell PD.Shell

The shell to use when generating the footprint.
clipPath Array.<Array> <optional>

If given, this is the element footprint clipped to the level boundary.
clipZ number <optional>

An optional Z axis height when using clip path, defaults to path center point z value.
Returns:

Returns this element to support method chaining.

Type
BIM.Element
Example
generateFootprint(shell, clipPath) {

    if (this.path) {

        /// A clipper path is typically given in a second call
        /// to this method, after the original footprint has been
        /// generated and clipped to a boundary path.
        if (Array.isArray(clipPath)) {
            this.footprint = shell.addEmptyFacet();
            this.footprint.fromClipperPathsByAxis(clipPath, this.path.center.z, shell);
            this.footprint.ensureDownwardsNormal();
            this.footprint.update(true);
        }

        else { // Generate from path.

            /// Ensure footprint faces downwards as this will
            /// serve as the bottom surface of the extruded form.
            const reverse_orientation = (this.path.normal.z >= 0.0);

            /// Generate footprint from the path, as
            /// a shell polygon, applying both offsets.
            this.footprint = this.path.generateShellFacet(
                shell,
                reverse_orientation,
                PD.SIDE.MIDDLE,
                this.outerOffset,
                this.innerOffset
            );

        }

    }

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

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

Type
any | undefined

getJunctionParameters(junction)

Provides a list of parameter groups for the given element junction.

This methods provides each element an opportunity to store junction-specific parameters that can be used when generating their geometry. Exactly what these parameters are will depend on the nature of each element. For example, a cabinet may allow each junction to define the height of its segment and whether it has swinging doors, sliding doors or open shelves. A tree on the other hand, may allow each junction to override any of the procedural tree parameters as well as defining a rotation angle and relative scale.

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

Parameters:
Name Type Description
junction BIM.Junction

The junction to create dynamic parameters for.
Inherited From:
Overrides:
Returns:

Returns an array of PD.ParamGroup objects.

Type
Array

getReferenceHeight()

Calculates the reference height for this element.

The default height for typical elements is either the element's bounding space height or the height of the level on which it sits. This method determines which of those values to use.

Inherited From:
Overrides:
Returns:

Returns the reference height for this element.

Type
number

getTypeComponentParameters()

Provides a list of component parameter groups for this element.

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

Inherited From:
Overrides:
Returns:

Returns an array of PD.ParamGroup objects.

Type
Array

handleAfterMove( [junction])

Called when a transformation sequence has completed.

This method will always be called as part of a sequence, which starts with handleBeforeMove, followed by one or more calls to handleMove, handleMoveByQuaternion or handleMoveByMatrix and finishes with handleAfterMove.

If the trackSpaceBoundary property is true, and the element is owned by a space, the element's path junctions will be checked and their relationships updated.

Parameters:
Name Type Argument Description
junction BIM.Junction <optional>

If moving a single junction, that junction.
Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Element

handleBeforeMove()

Initialises reference positions just prior to an interactive drag.

For safety and stability, interactive movement is done using an absolute drag vector, matrix or quaternion rather than incrementally each frame. Thus the main function of this method is to store reference positions for all parts of the element that will move as part of an interactive drag or transform.

This method will always be called as part of a sequence, which starts with handleBeforeMove, followed by one or more calls to handleMove, handleMoveByQuaternion or handleMoveByMatrix and finishes with handleAfterMove.

Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Element

handleMove(vector)

Moves the element by the given vector from its reference position(s).

This method will always be called as part of a sequence, which starts with handleBeforeMove, followed by one or more calls to handleMove and finishes with handleAfterMove.

Parameters:
Name Type Description
vector THREE.Vector

The absolute direction vector of the current drag.
Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Element

handleMoveByMatrix(matrix [, about])

Transforms the element by applying the given matrix from its reference position(s).

This method will always be called as part of a sequence, which starts with handleBeforeMove, followed by one or more calls to handleMoveByMatrix and finishes with handleAfterMove`.

Parameters:
Name Type Argument Description
matrix THREE.Matrix4

The transform matrix to apply to the path.
about THREE.Vector3 <optional>

An optional point about which to apply the transform.
Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Element

handleMoveByQuaternion(quat [, about])

Rotates the element by applying the given quaternion from its reference position(s).

This method will always be called as part of a sequence, which starts with handleBeforeMove, followed by one or more calls to handleMoveByQuaternionand finishes with handleAfterMove.

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 element to support method chaining.

Type
BIM.Element

handleOnAddJunction(contour_index, junction_index)

Provides an opportunity to elements to restrict their number of junctions.

Some elements, such as sensors and sun-path diagrams, only need a single junction to define their 3D position. Others may require just two junctions to give a center point and direction.

This method is always called just prior to a new junction being added, either during interactive creation or when inserting in a selected segment.

Parameters:
Name Type Description
contour_index number

The ordinal index of the contour being added to.
junction_index number

The ordinal index of the junction within the contour.
Inherited From:
Overrides:
Returns:

Returns true if the junction can be added, or false if not.

Type
boolean

handleOnCursorMove(new_pos, cursor [, junction])

Provides an opportunity for elements to constrain cursor movements.

This method is called whenever an interactive cursor is moved with this element selected. If one of the element's junctions is selected, it will be included as the last argument. If the element itself is being moved, the last argument will be undefined.

The default implementation simply returns false. Override this method to perform whatever checking is required and modify new_pos to constrain the movement.

Parameters:
Name Type Argument Default Description
new_pos THREE.Vector3

The proposed new position of the cursor.
cursor PD.Cursor

The cursor that is being interactively dragged.
junction BIM.Junction <optional>
 null

The junction that is being dragged, if selected.
Inherited From:
Overrides:
Returns:

Returns true if the point was changed, otherwise false.

Type
boolean

handleOnCursorSelect(cursor [, junction])

Provides an opportunity for elements to initialise the cursor when selected.

This method is called whenever the element or one of its junction is selected. If one of the element's junctions is selected, it will be included as the last argument. If the element itself is selected, the 'junction' argument will be null.

The default implementation simply calls the cursor.clearRotation() method. Override it to orient the cursor as appropriate.

Parameters:
Name Type Argument Default Description
cursor PD.Cursor

The cursor that is being interactively dragged.
junction BIM.Junction <optional>
 null

The junction that was selected, defaults to null.
Inherited From:
Overrides:
Returns:

Returns true if the cursor orientation was changed.

Type
boolean

handleOnJunctionChange()

Provides an opportunity for elements to react to junction property changes.

This method is called whenever the height or orientation values of a junction are changed using either a cursor manipulator or an interactive UI component with this element selected.

The default implementation simply returns false to indicate that the height or orientation hss not been constrained or changed in any way. Override this method to perform whatever checking is required and only return true if the junction's property was modified as a result.

Inherited From:
Overrides:

highlight(mesh, view)

Renders a highlighted view of the element to show it as selected.

Parameters:
Name Type Description
mesh PD.PolyMesh

The selection mesh to render highlighting to.
view PD.ViewData

The view definition to render the model within.
Inherited From:
Overrides:
Returns:

Returns true if anything was added to the mesh.

Type
boolean

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

intersectLightRay(ray, result)

Handles the intersection of a light or shading ray with this element.

This method typically intersects the ray with the BIM.Element#shell if it has one. If the ray intersects an opaque surface, the transmittance value is set to zero, the reflectance and color are set using surface properties, and the method returns true.

If the ray hits a non-opaque surface, the transmittance is multiplied by the visible light transmittance of the surface and the method returns false. If nothing is hit, result is not changed and the method returns false.

Override this method in your custom element if it needs to handle light ray intersections differently.

Parameters:
Name Type Description
ray THREE.Ray

The ray defining the origin and direction of the light ray.
result object

An object containing information about the light ray.
Properties of result:
Name Type Description
intersection THREE.Vector3

Stores the triangle intersection point as a {x,y,z} vector.
transmittance number

Stores the accumulated transmittance of all intersected surfaces.
reflectance number

Stores the accumulated reflectance from all intersected surfaces.
color number

Stores the color of the primary intersected surface.
Inherited From:
Overrides:
Returns:

Returns true if the light ray hit an opaque surface and stops here.

Type
boolean

mounted(parent)

Called when the element is added to the given level or space.

NOTE: This life cycle method is called just after the element has been prepared and added to the level and just before the BIM.Element#update method is called for the first time on the element with this parent. You may still call the BIM.Element#update method within this method if you need to, but know that the later call will be ignored as any change indicators (such as BIM.Element#hasChanged and BIM.Path#hasChanged) should have already been reset during the initial call.

Parameters:
Name Type Description
parent BIM.Level | BIM.Space

The level or space that the element is being added to.
Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Element

moveByMatrix4(matrix)

Transforms the element by applying the matrix to it.

NOTE: This is not an interactive method that is part of a transform sequence. Rather it is one that is meant to reposition, scale and/or rotate the element with a single call. As such, it first calls BIM.Element#handleBeforeMove on the element, followed by BIM.Element#handleMoveByMatrix and then BIM.Element#handleAfterMove.

Parameters:
Name Type Description
matrix THREE.Matrix4

The transform matrix to apply to the element.
Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Path

moveByVector3(vector)

Move the element by a relative vector.

NOTE: This is not an interactive method that is part of a move sequence. Rather it is one that is meant to reposition the element with a single call. As such, it first calls BIM.Element#handleBeforeMove on the element, followed by BIM.Element#handleMove and then BIM.Element#handleAfterMove.

Parameters:
Name Type Description
vector THREE.Vector3

The relative movement vector.
Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Path

moveJunctionListByVector(list, vector [, undo])

Moves the list of junctions within the element.

This method is used when dragging one or more junctions and during the undo/redo of that process. It checks for any specific settings or rules (such as a rectangular shape) and tries to comply whenever possible.

Parameters:
Name Type Argument Description
list Array.<BIM.Junction>

A list of one or more junctions belonging to this element.
vector THREE.Vector3

The movement vector to apply.
undo boolean <optional>

Whether or not this is being called by undo/redo.
Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Element

moveSegmentListByVector(list, vector [, undo])

Moves the list of path segments within the element.

This method is used when dragging one or more segments and during the undo/redo of that process. It checks for any specific settings or rules (such as a rectangular shape) and tries to comply whenever possible.

Parameters:
Name Type Argument Description
list Array.<BIM.Junction>

A list of one or more segments belonging to this element.
vector THREE.Vector3

The movement vector to apply.
undo boolean <optional>

Whether or not this is being called by undo/redo.
Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Element

rebuild()

Rebuilds the geometry of this shape ready for visualisation.

See the BIM.Element#rebuild method for more details.

Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Element
Example
rebuild() {

    /// Create shell.
    this.ensureValidShell();
    this.shell.reuseStart();

    if (this.typeComponent && this.path) {

        /// Build shell geometry.
        this.typeComponent.rebuild(this);

        /// Link shell to this path.
        this.shell.linkedToPath = this.path;

    }

    /// Expand with shell extents.
    this.extents.union(this.shell.extents);
    this.shell.reuseEnd();
    return this;

};

removeJunction(junction [, contour_index])

Removes a junction from the element path.

If the contour or ordinal index is not given, the path will be searched for the given point.

Parameters:
Name Type Argument Description
junction BIM.Junction

The junction to be removed.
contour_index number <optional>

The ordinal index of the path contour to remove the junction from.
Inherited From:
Overrides:
Returns:

Returns the index of the junction removed, or -1.

Type
number

render(meshes, view, level)

Render a view of the element using the given meshes.

Parameters:
Name Type Description
meshes BIM.Meshes

The collection of meshes to render to.
view PD.ViewData

The view definition to render the model within.
level BIM.Level

The level currently being rebuilt and rendered.
Inherited From:
Overrides:
Returns:

Returns true if anything was added to any mesh.

Type
boolean
Example
render(meshes, view, level) {

   /// Delegate to type component.
   if (this.typeComponent?.render) {
       return this.typeComponent.render(meshes, view, level, this);
   }

   return this.renderShell(meshes, view, level);

};

renderBoundaryRepresentation(mesh, view)

Renders the boundary representation of the element if it has one.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to render the boundary representation to.
view PD.ViewData

The view definition to render the model within.
Inherited From:
Overrides:
Returns:

Returns true if anything was added to the mesh.

Type
boolean

renderExtraShellToMesh(shell, mesh, view, level)

Renders the given shell to the given mesh using the same handling of view as in the element's own shell.

NOTE: This method must only be called from somewhere within the BIM.Element#render method of the subclassed element. Otherwise any additions to the shell won't make it to the canvas as they will be overridden on the next render when the shell is reinitialised.

Parameters:
Name Type Description
shell PD.Shell

The shell to render.
mesh PD.PolyMesh

The mesh to add shell geometry to.
view PD.ViewData

The view definition to render the model within.
level BIM.Level

The level currently being rebuilt and rendered.
Inherited From:
Overrides:
Returns:

Returns true if anything was added to the mesh.

Type
boolean

renderShell(meshes, view, level)

An alternative render method to support furnishing and fixtures.

This is a utility method that subclasses can use instead fo the default render method. It renders the shell of the element and not its path.

Parameters:
Name Type Description
meshes BIM.Meshes

The collection of meshes to render to.
view PD.ViewData

The view definition to render the model within.
level BIM.Level

The level currently being rebuilt and rendered.
Inherited From:
Overrides:
Returns:

Returns true if anything was added to any mesh.

Type
boolean

selectedSnapBehavior(selMan)

Provides the base snap behavior when an element is selected and dragged.

By default, the element will snap to the junctions of its outer path boundary, if it has one. If you would like your element to snap against something other than its path, you can override this method.

See also snapPointToPath.

If you do override this method, the following example shows the default snap behavior as a basis for you to use.

Parameters:
Name Type Description
selMan PD.SelectionManager

The selection manager that is handling the snap.
Inherited From:
Overrides:
Example
selectedSnapBehavior(selMan) {

       /// Temporarily show the snap paths of other elements as
       /// dotted lines so you can see what you are snapping to.
       selMan.showSnapPaths = true;

       /// Don't use the dragged cursor as a snap point
       /// as the element centroid is often not relevant.
       selMan.snapper.directSnap = false;

       if (this.path) { /// Snap to each boundary point.
           for (const junction of this.path.getContour(0)) {
               selMan.modelManager.snapLineToNearestElement(selMan.snapper, junction, selMan.selectionSet);
           }
       }

   };

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

snapPointToPath(snapper, test_pt)

Checks for points to snap to within the element path.

Parameters:
Name Type Description
snapper PD.Snapper

The snap helper object.
test_pt THREE.Vector3

The point to find the closest snap.
Inherited From:
Overrides:
Returns:

Returns true if a feature in the element was found and added to the snapper, otherwise false.

Type
boolean

unmounted(parent)

Called when the element is removed from the given level or space.

NOTE: This life cycle method is called just after the element has been removed from a level or space. If the element is moving from one level/space to another, this will be immediately followed by a call to mounted() with the new level/space.

Parameters:
Name Type Description
parent BIM.Level | BIM.Space

The level or space that the element is being removed from.
Inherited From:
Overrides:
Returns:

Returns this element to support method chaining.

Type
BIM.Element

update( [forceUpdate])

Updates the element and checks to rebuild its geometry.

Elements should override this method to implement whatever custom logic is required to determine if their geometry needs to be rebuilt. If so, then this method should call the element's own rebuild() method before returning. It is also an opportunity for the element to modify its own extents.

The default implementation checks the hasChanged flags on both the element itself and its path. If either are set to true, the element's rebuild() method is called before both flags are cleared. This is suitable for most elements as the editor will set the path changed flag whenever it is changed and the dynamic parameter system will update the element's changed flag whenever a value is changed.

The default implementation sets the element's bounding box to match its path extents and adds the element's height property if non-zero.

NOTE: All overridden versions of this method must set the element's hasChanged and wasRebuilt properties appropriately when calling the rebuild() method, as shown in the example below. When rebuilt, the hasChanged property must be set to false and the wasRebuilt property must be set to true.

Parameters:
Name Type Argument Description
forceUpdate boolean <optional>

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

Returns this element to support method chaining.

Type
BIM.Element
Example
update(forceUpdate) {

   const path = this.path;
   if (path) {

       path.element = this;

       if (forceUpdate || path.hasChanged) {
           this.hasChanged = true;
           if (forceUpdate) path.hasChanged = true;
           path.update();
       }

       /// Use path extents as the default for the element extents.
       this.extents.copy(path.extents);
       if (!PD.Utils.closeToZero(this.height)) {
           const extents = this.extents;
           if (this.height < 0) extents.min.z = Math.min(extents.min.z, this.height);
           else extents.max.z = Math.max(extents.max.z, this.height);
       }

   }

   if (forceUpdate || this.hasChanged) {
       this.hasChanged = false; // ? <-- IMPORTANT: Must clear this flag when rebuilt.
       this.wasRebuilt = true;  // ? <-- IMPORTANT: Must set this flag when rebuilt.
       this.rebuild();
   }

   return this;

};

updateRelativeHeight()

Updates the element's computed height if it is given as a relative value rather than an absolute dimension.

Inherited From:
Overrides:
Returns:

Returns true if the computed height changed, otherwise false.

Type
boolean

usesJunctionOrientation(junction)

Determines if this element responds to the orientation of the given junction.

Use this method to define the logic for determining if the element uses the given junction's orientation attribute value when computing the geometry at each of its junctions. The result is used by the interactive selection process to display a cursor rotation manipulator with which to set the value.

When overriding this method on an element, you should also override the BIM.Element#handleOnJunctionChange method to moderate or constrain any orientation angle changes as they occur.

Parameters:
Name Type Description
junction BIM.Junction

The junction being checked for orientation.
Inherited From:
Overrides:
Returns:

Return true to show a rotation cursor manipulator.

Type
boolean