API Docs

Class: Timber

BIM.Stairs. Timber

A core class for parametrically generating timber stair geometry. geometry.

             :  tread  :                           _.-'=======+--------->
            -+---------+-                      _.-'     ║     |
             |         |                   _.-'==========  _.-2--------->
             |       : :               _.-'     ║      _.-'
             |      -+-+- nosing   _.-'==========  _.-'
             : going : :        .-'     ║       .-'
           - + - - - + +   _.-'==========  _.-'
         :   |         _.-'     ║      _.-'
       - + - + - - _.-'==========  _.-'
   riser |     _.-'     ║      _.-'
       - + - +'==========  _.-'
         :   |  ║      _.-'
       <-----0-------+'---------->

new Timber( [config] [, typeName])

Creates a new timber stair 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.
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

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

iconName <readonly>

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

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

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

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

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

isStairType <readonly>

A flag identifying this object as a stairs type.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isTimberStairs <readonly>

A flag identifying this object as timber stairs.

Type
  • boolean
:number

landingMin

The minimum horizontal landing size between flights in mm, defaults to 920mm or 36".

Type
  • number
Inherited From:
Overrides:
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:number

nosing

Horizontal distance from the front of the tread to the riser underneath, in mm.

It is the overhang of the tread beyond the rear of the tread immediately beneath.

Type
  • number
Inherited From:
Overrides:
:number

preferredGoing

The preferred horizontal distance from front of one tread to front of next tread, in mm.

The tread length is supposed to be equal for all steps of the stair or stair flight at the walking line.

Type
  • number
Inherited From:
Overrides:
:number

preferredRiser

The preferred vertical distance from top of one tread to top of next tread, in mm.

The riser height is supposed to be equal for all steps of a stair or stair flight.

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

riserBoardHeight

The height of the riser board supporting each tread in mm, defaults to 1.0 or full height.

If riserBoardHeight is less than 0, the generated height will be the stair riser height minus this value. If riserBoardHeight is less than or equal to 1mm, it is assumed to be a relative fraction of the riser height rather than an absolute size. A value of zero will always result in no riser board being included.

Type
  • number
:number

riserBoardThickness

The width of the riser board supporting each tread in mm, defaults to 18mm or 0.75".

It is the overhang of the tread beyond the rear of the tread immediately beneath.

Type
  • number
:number

stringerInset

The inset distance of the stringer boards in mm, defaults to 50mm or 2".

Type
  • number
:number

stringerThickness

The thickness of the stringer boards in mm, defaults to 40mm or 1.5".

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

treadThickness

The height of the timber tread board, if any in mm, defaults to 25mm or 1".

Type
  • number
Overrides:
:string

uuid

A universally unique identifier for the item instance.

Type
  • string
Inherited From:
Overrides:

Methods

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

computeConnectionHeights(element)

Computes the heights of each connection/landing.

Parameters:
Name Type Description
element BIM.Ramp

The ramp/stair element being built.
Inherited From:
Overrides:
Returns:

Returns true if heights were successfully set.

Type
boolean

computeFlightData(element, fromConnector, toConnector)

Calculates the number of steps and in-line landings required, based on the current ruleset.

The from and to connectors each contain the two points defining their incoming and outgoing faces. If a flight is to be added between landings from and to, as shown in the illustration below, then its profile in plan view would join from.outgoingEdge[0], from.outgoingEdge[1], to.incomingEdge[1] and to.incomingEdge[0] to form the bottom facet with a downward facing surface normal (as per the right-hand rule).

            ^ Y
            :
            1---------1  -  -  -  -  -  -  -  1---------1
            |         |                       |         |
 incoming > |  from   | outgoing : incoming > |   to    | outgoing >
            |         |                       |         |
            0---------0  -  -  -  -  -  -  -  0---------0 - - > X
             connector                         connector

The horizontal and vertical travel distances can be computed directly from the line between from.outgoingEdge[0] and to.incomingEdge[0], which runs along the inner boundary.

Parameters:
Name Type Description
element BIM.Stair

The stair element being built.
fromConnector StairConnection

The starting connection to flight spans from.
toConnector StairConnection

The ending connection to flight spans to.
Inherited From:
Overrides:
Returns:

Returns a data object containing flight data.

Type
object

generateConnections(element, path)

Set up a landing at each junction and add incoming/outgoing connectors.

This is the first phase of generating the ramp/stair, where horizontal landings are created for each junction and incoming/outgoing connectors for each flight are computed and stored.

The connector created for each landing is simply an array of six (6) points ordered in a clockwise direction around its base. If a flight is to be added between landings 1 and 2 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 flight would run between connector1[4] and connector2[1].

    ^ Y
    :
    2---------3  -  -  -  -  -  2---------3
    |         |                 |         |
    1    1    4  -  -  -  -  -  1    2    4
    |         |                 |         |
    0---------5  -  -  -  -  -  0---------5 - - > X
     connector     clockwise     connector

Landings can be any shape, however connector points are generated only for the incoming and outgoing edges. Thus, flights need only know about with the outgoing connector points of the current junction and the incoming connector points of the next junction, even if the platform is any arbitrary shape, as shown below.

             ^ Y
             :
             +----1  -  -  -  -  -  1-----+
          _/      |                 |       \_
       _/     outgoing  -  -  -  incoming      \_
    _/            |                 |             \_
  +               0  -  -  -  -  -  0               +
  |  incoming   _/                    \_  outgoing  |
  1-----------0                         0-----------1 - - > X
    connector                             connector
Parameters:
Name Type Description
element BIM.Ramp

The ramp/stair element being built.
path PD.Path

The path to generate landings along.
Inherited From:
Overrides:

generateFlight(element, fromConnector, toConnector)

Generates the shell geometry for a single flight of timber boarded stairs.

Parameters:
Name Type Description
element BIM.Stair

The stair element being built.
fromConnector StairConnection

The starting connection the flight spans from.
toConnector StairConnection

The ending connection the flight spans to.
Overrides:
Returns:

Returns true if flight geometry was added.

Type
boolean

generateFlights(element)

Generates the flights between landings and connections.

Parameters:
Name Type Description
element BIM.Ramp

The ramp element being rebuilt.
Inherited From:
Overrides:
Returns:

Returns true if flight geometry was added.

Type
boolean

generateLanding(element, clipPath, height, depth)

Builds a landing platform based on the given plan profile.

This method simply creates a monolithic landing platform by converting the clip path to a horizontal shell facet defining the top surface of the landing at the given height, and then extruding it downwards by the specified depth.

Subclasses can override this method to provide more complex landing geometry, such as adding railings or other features.

Parameters:
Name Type Description
element BIM.Ramp

The ramp element being rebuilt.
clipPath Array.<Array.<PD.ClipPt2D>>

The ClipperLib paths defining the landing plan profile.
height number

The height of the landing top surface above floor level.
depth number

The vertical thickness of the landing.
Inherited From:
Overrides:
Returns:

Returns true if landing geometry was added.

Type
boolean

generateLandings(element)

Builds all landing platforms after prior processing.

Parameters:
Name Type Description
element BIM.Ramp

The ramp/stair element being rebuilt.
Inherited From:
Overrides:
Returns:

Returns true if landing geometry was added.

Type
boolean

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

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

subType() <static>

Retrieves the sub-type of stair 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.STAIR