API Docs

Class: Railings

BIM. Railings

A core class for parametrically generating railing systems.

This class provides basic parameters for defining a component railing system. Other classes can build in this infrastructure to define additional parameters and generate more detailed and specific parametric shapes.

Anatomy of a Railing

       .--.                                   .--.<------- Post Projection
    ---+  +-----------------------------------+  +---
    ---+  +----++----++----+-+----++----++----+  +---  <-- Hand Rail
       |  |    ||    ||    |/|    ||    ||    |  |
       |  |    ||    ||    |\|    ||    ||    |  |
       |  |    ||    ||    |/|    ||    ||<---| |-------- Baluster
       |  |    ||    ||    |\|    ||    ||    |  |
    --+|  |+---++----++----+/+----++----++---+|  |+--
    --+|  |+---++----++----+\+----++----++---+|  |+--  <-- Mid Rail
       |  |    ||    ||    |/|    ||    ||    |  |
       |  |    ||    ||    |\|    ||<---||----|  |-------- Baluster
       |  |    ||    ||    |/|    ||    ||    |  |
       |  |    ||    ||    |\|<---||----||----|  |-------- Support Post
       |  |    ||    ||    |/|    ||    ||    |  |
    --+|  |+---++----++----+\+----++----++---+|  |+--
    --+|  |+---------------+-+---------------+|  |+--  <-- Base Rai
_______+--+___________________________________+--+_______
       Post                                   Post

Simple Railing System

The key to the flexibility of this simple railing system is that the start and end posts are generated relatively independently, and the handrails, mid-posts and infill are simply generated between the faces of each post.

If you do it the other way and first extrude the handrail along the path between junctions, it is still relatively easy to position a post underneath to support it. However, if the handrail goes from horizontal to inclined, or changes in both altitude and azimuth angle at the same time, then it becomes necessary to cut the top of the post in all sorts of potentially weird angles so that the handrail sits exactly on top of it, as shown in the illustration below.

                     _.'   _.'                           _.'   _.'
                  _.'   _.'                           _.'   _.'
 ''--..__      _.'   _.'         ''--..__          _.'   _.'
 handrail''-..'   _.'            handrail''+-----+'   _.'
 ''--..__    :  _+'              ''--..__  |     | _.'
         ''+-_.' |                       ''+     +'
           |     |                         |     |
       post|  1  |                     post|  2  |

       Requires top of                Rails travel from
      post to be cut at            face to face, with the
      different angles.             top of the post flat.

Cutting posts to fit the railing is almost never actually done on-site as there are all sorts of systems for separating the handrail to make it more independent of posts, such as elevating it on thin spacer bars, etc. However, as the basis for a reasonably indicative but also highly customisable handrail system, having the top of each post flat is an appropriate approach for this core component, and allows for posts to be projected vertically above the handrail.

new Railings( [config] [, typeName])

Creates a new basic railing representation.

Parameters:
Name Type Argument Description
config object <optional>

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

A human-readable name for this component.
uuid string <optional>

A universally unique identifier of this component.
productRef string <optional>

The product reference number or identifier.
description string <optional>

A brief product or type description.
supplier BIM.Supplier <optional>

An optional supplier details data object.
railDepth number <optional>

The depth of the top handrail and posts in mm, defaults to 50mm or 2".
bottomGap number <optional>

The height between floor and bottom rail or infill in mm, defaults to 100mm or 4".
maxSpan number <optional>

The maximum span between support posts in mm, defaults to 2400mm or 8'.
hasTopRail number <optional>

Whether or not there is a handrail along the top of the railing, defaults to true.
topRailSize number <optional>

The depth/thickness of the top handrail in mm, defaults to 50mm or 2".
hasBaseRail number <optional>

Whether or not there is a base rail along the bottom of the railing, defaults to true.
baseRailSize number <optional>

The depth/thickness of the base handrail at the bottom in mm, defaults to 50mm or 2".
infillType BIM.INFILL <optional>

The type of infill between start, support and end posts.
infillSpacing number <optional>

The spacing between infill rails or panels in mm, defaults to 100mm or 4".
infillWidth number <optional>

The width of infill balusters, slats or panels in mm, defaults to 15mm or 9/16".
infillDepth number <optional>

The depth of infill balusters, slats or panels in mm, defaults to 15mm or 9/16".
typeName string <optional>

An additional parameter typically used by subclasses to set the component type name without modifying the config object.
Author:
  • drajmarsh

Extends

Members

:number

baseBoardHeight

The height of the base or toe board in mm, defaults to 100mm or 4".

Type
  • number
:number

baseBoardWidth

The width of the base or toe board in mm, defaults to 6mm or 1/4".

Type
  • number
:number

baseRailSize

The depth or thickness of the base rail along the bottom in mm, defaults to 50mm or 2".

Type
  • number
:number

bottomGap

The height between floor and bottom rail/infill in mm, defaults to 100mm or 4".

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

A brief product or type description, defaults to an empty string.

This description is typically used to provide additional information about the product to other team members, such as its reasons for selection. important features, specifications and/or intended use.

Type
  • string
Inherited From:
Overrides:
:string

displayName <readonly>

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

Type
  • string
Inherited From:
Overrides:
:boolean

hasBaseBoard

Whether or not to include a toe-board at the base of the railing, defaults to false.

Type
  • boolean
:boolean

hasBaseRail

Whether or not to include a base or bottom rail, defaults to true.

Type
  • boolean
:boolean

hasTopRail

Whether or not to include a top or hand rail, defaults to true.

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();
    };
    /// ...
 };
:number

infillDepth

The depth (local Y) of infill balusters, slats or panels in mm, defaults to 15mm or 9/16".

Type
  • number
:number

infillSpacing

The spacing between infill rails or panels in mm, defaults to 100mm or 4".

Type
  • number
:BIM.INFILL

infillType

The type of infill between start, end and support posts.

Type
:number

infillWidth

The width (local X/Z) of infill balusters, slats or panels in mm, defaults to 15mm or 9/16".

Type
  • number
:boolean

isComponent <readonly>

A flag identifying this object as a shared BIM component.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isLocked

Whether or not this component's parameters are fixed.

This property is used by the UI and framework to indicate that the component's parameters are fixed and therefore not editable. It is typically set by a 3rd-party manufacturer or supplier on products that they can only provide in one configuration.

For example, there is no point specifying a particular manufacturer's fridge and then adjusting its width to fit a hole in your cabinetry if that manufacturer cannot actually supply a fridge of that width.

Thus, when this property is true, you will not be able to edit the parameters, but you can always duplicate the component (or its configuration), but without the supplier details if you really do want to modify it.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isRailingType <readonly>

A flag identifying this object as a railing type.

Type
  • boolean
:number

maintainDepth

Strategy for maintaining full post depth at acute angled corners (0:None, 1:Sideways, 2:Inwards), defaults to 1 (Sideways).

Type
  • number
:number

maxSpan

The maximum span between support posts in mm, defaults to 2400mm or 8'.

Type
  • number
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:number

postProjection

The projection height of the corner posts above the handrail in mm, defaults to zero.

Type
  • number
:number

postWidth

The width of posts in mm, defaults to BIM.Railings#railDepth.

Type
  • number
:string

productRef

The product reference number or identifier, defaults to an empty string.

The product reference is typically used to store a serial number, model number, SKU or other identifier provided by the manufacturer or supplier to uniquely identify this product.

Type
  • string
Inherited From:
Overrides:
:number

railDepth

The depth of rails and posts in mm, defaults to 50mm or 2".

Type
  • number
:number

subType <readonly>

An element-specific subtype.

Type
  • number
Inherited From:
Overrides:
:string

supplier

The product supplier/manufacturer, defaults to null.

This property contains details of the supplier or manufacturer of this product or component. Multiple components can share the same supplier instance to avoid unnecessary duplication of data.

Type
  • string
Inherited From:
Overrides:
:number

topRailSize

The depth or thickness of the top handrail in mm, defaults to 50mm or 2".

Type
  • number
:string

uuid

A universally unique identifier for the item instance.

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

infillDataCache <static>

A temporary volatile cache for passing infill segment data between internal methods when (re)building each element';'s geometry.

Type
  • object

Methods

addBackingRail(infill, z, size)

Adds a thinner locally horizontal rail at the given height between support post connectors.

Parameters:
Name Type Description
infill object

A cached data object defining the current rail span.
z number

The height in the local Z axis to the bottom of the rail.
size number

The size of the rail in the local Z axis.

addBaseRail(infill)

Adds a locally horizontal bottom rail between support post connectors.

Parameters:
Name Type Description
infill object

A cached data object defining the current rail span.

addMidSpanPost(infill)

Generates a mid-span support post at the current coordinates.

This method requires that the given local coordinates are already positioned at the center of the base of the post, and oriented appropriately.

Mid-span posts are not just prisms, as the four vertices at their base need to be horizontal to sit directly on a slab or stair, but their top four vertices need to be in line with the slope of the top handrail.

Parameters:
Name Type Description
infill object

A cached data object defining the current rail span.

checkDynamicParameter(param, group, host)

Checks the allowable range of element parameter values.

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

Parameters:
Name Type Description
param PD.Parameter

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

The group that the dynamic parameter belongs to.
host BIM.Element

The host element this component is controlling.
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

generatePosts(path, infill)

Sets up a post at each junction and creates connectors on each side of it.

This is the first phase of generating the railing, where posts are created for each junction and incoming/outgoing connectors for the infill rail segments are computed and stored.

NOTE: When a railing segment is inclined (i.e.: the base of the post at each end have different positions in the Z-axis), you cannot base the local coordinate system on the junction-to-junction vectors. This is because the start and end posts must be the exact same width and depth so that the rail can turn corners without changing the width of the top rail. This means that the angle of the handrail does not run from the centre of the first post to the centre of the second, but rather from the outgoing face of the first post to the incoming face of the second. This creates a slightly different incline, as shown in the illustration below.

               |   |                     |   |
    +---+      |   |          +---+      |   |
    |   |      1-+-+          |   |      +-1-+
    |   |     /               |   |      _/
    |   |    /                |   |     /
    |   |   /                 |   |   _/
    |   |  /                  |   |  /
    |   | /                   |   |_/
    |   |/                    |  /|
    +-+-0                     +-0-+
    CORRECT ANGLE             WRONG ANGLE
    BETWEEN POST FACES        BETWEEN POST CENTERS

The connector created for each post is simply an array of 6 points ordered in a clockwise direction around its base. If a rail is to be added between posts 1 and 2, as in the illustration below, then its profile in plan view would join connector1[5], connector1[3], connector2[2] and connector2[0] to form the bottom facet with a normal facing downwards (as per the right-hand rule). The center line of the infill would run between connector1[4] and connector2[1].

    ^ Y
    : connector                    connector
    2-----------3  -  -  >  -  -  2-------+._
    |           |                 |          '-.3 _
    1     1     4  -  -  >  -  -  1      2      /   ' - _
    |           |                 |           4 _         ' - _
    0-----------5  -  -  >  -  -  0-----+._  /    ' - _
      clockwise                            '5 _         '
                                               ' - _
Parameters:
Name Type Description
path PD.Path

The path to generate posts along.
infill object

A shared data cache set by rebuild method.

generateRailings(path, infill)

Generates the railings with infill between each post.

This is the second phase of the process where rails are joined between the outgoing connectors on one post and the incoming ones on the next. It also adds the infills between the posts.

Parameters:
Name Type Description
path PD.Path

The path containing connectors to infill between.
infill object

A shared data cache set by rebuild method.

getDynamicParameters(host)

Provides a list of element-based dynamic parameter groups for this element.

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

Parameters:
Name Type Description
host BIM.Element

The host element this component is controlling.
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.' })
             ]
         })
     ];
 };

getNameAndSupplierParameters()

Provides a list of dynamic parameter groups for the component name, description and supplier.

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

Inherited From:
Overrides:
Returns:

Returns an array of PD.ParamGroup objects.

Type
Array

hasMethod(component, methodName)

Determines if this component has a callable method with the given name.

This method is useful for checking if the component has a particular method before attempting to call it, thereby avoiding potential runtime errors. It is used within the framework to check for the presence of life-cycle methods in an element's type component before delegating them.

Parameters:
Name Type Description
component BIM.Component

The component to check.
methodName string

The case-sensitive name of the function/method to check for.
Inherited From:
Overrides:
Returns:

Returns true if the component is valid and has the function name as a method, otherwise false.

Type
boolean

isCompatibleWith(obj)

Determines if this component can be added to the given entity.

Whilst a small number of components may be compatible with multiple entity types, most components are designed to be used only by a specific entity type, and will not allow you to assign them to an incompatible entity.

Parameters:
Name Type Description
obj BIM.ENTITY | BIM.Entity

The entity type or object instance to check for compatibility with.
Inherited From:
Overrides:
Returns:

Returns true if the component can be added to the object, otherwise false.

Type
boolean

rebuild(element)

Rebuilds the geometry of a railing ready for visualisation.

Parameters:
Name Type Description
element BIM.Railing

The railing element to rebuild.
Inherited From:
Overrides:
Returns:

Returns this railing type to support method chaining.

Type
BIM.Railings

render(meshes, view, level, element)

An opportunity for the railing type to render anything additional.

If defined on a railing type class, this method is called at the start of the element's own render() method.

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.
element BIM.Element

The element being rendered.

setSharedInfillDataCache(element)

Sets up the shared infill data cache with initial values from the this component and the given element.

Parameters:
Name Type Description
element BIM.Railing

The railing element being built.
Returns:

The BIM.Railings.infillDataCache object.

Type
object

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 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

getDisplayName() <static>

The name to display within the user interface.

Returns:

Returns the display name.

Type
string

getHostElementClass() <static>

Retrieves the class of the host element for this component.

See BIM.Component#getHostElementClass for more details on this static method.

Returns:

Returns the element class this component requires as a host.

Type
BIM.Railing

isCompatibleWith(obj) <static>

Determines if this component can be added to the given object.

Parameters:
Name Type Description
obj BIM.ENTITY | BIM.Entity

The entity type or object to check for compatibility with.
Returns:

Returns true if the component can be added to the object, otherwise false.

Type
boolean

subType() <static>

Retrieves the sub-type of railing this class represents.

See BIM.Component#subType for more details on this static method.

Returns:

Returns the sub-type enumerator of this class.

Type
BIM.RAILING