API Docs

Class: Gable

BIM.Roofs. Gable

Defines the geometric representation of a gable roof element.

new Gable( [config] [, typeName])

Creates a new gable roof 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.
ceilingStyle number <optional>

The style of ceiling to generate (0:Flat, 1:Inclined+Gutter, 2:Inclined+Normal, 3:Inclined+Hor, 4:Inclined+Ver), defaults to 0.
roofThickness number <optional>

The depth/thickness of the inclined roof in model units, defaults to PD.GlobalState.defaultSlabDepth.
eavesDepth number <optional>

The depth of the eaves, gutter board or vertical fascia in model units, defaults to PD.GlobalState.defaultSlabDepth.
eavesWidth number <optional>

The width of the eaves gutter or horizontal fascia in model units, defaults to 0.0.
fullHeightEaves boolean <optional>

Whether or not to project internal eaves vertically upwards to ceiling plane, defaults to true.
angle string <optional>

The pitch angle of the gable roof in degrees (0 to 75), defaults to 30deg.
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

angle

Defines the pitch angle of the gable roof in degrees, defaults to 30deg.

Type
  • number
:number

ceilingStyle

The style of ceiling to generate.

The supported styles are:

  • 0: Flat Ceiling with Gutter.
  • 1: Inclined Ceiling + Gutter.
  • 2: Inclined + 90 Degree Edge.
  • 3: Inclined + Horizontal Edge.
  • 4: Inclined + Vertical Edge.
Type
  • number
Inherited From:
Overrides:
:string

className <readonly>

The name of the subclass for this object instance.

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

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

Type
  • string
Inherited From:
Overrides:
:string

description

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

eavesDepth

The depth of the eaves, gutter board or vertical fascia in model units, defaults to PD.GlobalState.defaultSlabDepth.

Type
  • number
Inherited From:
Overrides:
:number

eavesWidth

The width of the eaves gutter or horizontal fascia in model units, defaults to 0.

Type
  • number
Inherited From:
Overrides:
:boolean

fullHeightEaves

Whether or not to project internal eaves vertically upwards to ceiling plane or just use eavesDepth, defaults to true.

Type
  • boolean
Inherited From:
Overrides:
:boolean

hasParapet

Whether or not to add a parapet around the roof.

Type
  • boolean
Inherited From:
Overrides:
:string

iconName <readonly>

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

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

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

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

isComponent <readonly>

A flag identifying this object as a shared BIM component.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isGableRoof <readonly>

A flag identifying this object as a gable roof type.

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

isRoofType <readonly>

A flag identifying this object as a roof type.

Type
  • boolean
Inherited From:
Overrides:
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:number

parapetHeight

The height of the parapet above level base in model units, defaults to 600mm or 2' (24").

Type
  • number
Inherited From:
Overrides:
:number

parapetWidth

The width of the parapet in model units, defaults to standard wall outer offset.

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

roofThickness

The depth/thickness of the inclined roof in model units, defaults to PD.GlobalState.defaultSlabDepth.

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

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

computeFourBaseVertices(roof, contour, junction, vertices)

Positions the first vertices to create a four-sided quadrilateral footprint.

This method derives a suitable four-sided quadrilateral footprint from the element path. Regardless of the number of items in the vertices array, only the first four (4) vertices are modified by this method.

Parameters:
Name Type Description
roof BIM.Roof

The roof element this component is controlling.
contour Array.<BIM.Junction>

The outermost element path contour.
junction BIM.Junction

The first junction in the path contour.
vertices Array.<PD.Point>

An array of at least four (4) vertices.
Inherited From:
Overrides:

generateEavesAndParapetProfile(style, start2D, end2D)

Generates a 2D profile for the eaves/gutter (if any) and a parapet wall around the perimeter of the roof.

                    +----+ <-- parapetHeight
                    |    |
      ' .           |    |
          ' .       |    |
    .         '+----+    | <-- roof.height
      ' .                |
          ' .            |
              '+---------+ <-- eavesDepth
               :<------->:
      max(eavesWidth, parapetWidth)
Parameters:
Name Type Description
style number

The style of eaves/gutter/fascia to generate (0:Flat, 1:Inclined+Gutter, 2:Inclined+Normal, 3:Inclined+Hor, 4:Inclined+Ver), defaults to 0.
start2D THREE.Vector2

The 2D start point at the ceiling edge.
end2D THREE.Vector2

The 2D end point at the roof edge.
Inherited From:
Overrides:
Returns:

Returns an anti-clockwise profile of 2D points, or an empty array if start/end points are coincident.

Type
Array.<THREE.Vector2>

getEavesParameterGroup(host [, fullHeight])

Provides a dynamic parameter group for the eaves/gutter/fascia parameters.

Subclasses can choose to override this method to provide additional parameters if they include the gutter/fascia components.

Parameters:
Name Type Argument Description
host BIM.Roof

The roof element this component is controlling.
fullHeight boolean <optional>

Whether or not to include full height eaves parameter, defaults to false.
Inherited From:
Overrides:
Returns:

Returns a parameter group with eaves/fascia parameters.

Type
PD.ParamGroup

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

getParapetParameterGroup(host)

Provides a dynamic parameter group defining a parapet wall.

Subclasses can choose to override this method to provide additional parameters if they include the parapet component.

Parameters:
Name Type Description
host BIM.Roof

The roof element this component is controlling.
Inherited From:
Overrides:
Returns:

Returns a parameter group with parapet parameters.

Type
PD.ParamGroup

handleOnAddJunction(host, contourIndex, junctionIndex)

Checks for an appropriate number of vertices.

Parameters:
Name Type Description
host BIM.Roof

The roof containing the path.
contourIndex number

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

The ordinal index of the junction within the contour.
Returns:

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

Type
boolean

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(roof)

Generates the geometry of a gable roof and its surfaces.

This method is called automatically by the host element when its rebuild() method is called. There is no need to clear/reset the element shell or BRep as this is done by the roof element.

This method generates BRep roof geometry based on the roof element's path and parameters. It also generates the footprint polygon defining the 2D outline of the roof at its base level.

Parameters:
Name Type Description
roof BIM.Roof

The element this component is controlling.
Inherited From:
Overrides:
Returns:

Returns true if geometry was successfully built.

Type
boolean

trimCeilingToHorizontalPlane(brep [, height] [, startIndex] [, endIndex])

Trims the ceiling of a BRep to a horizontal plane.

Parameters:
Name Type Argument Description
brep PD.BRep

The BRep that contains the faces to trim.
height number <optional>

The height of the horizontal trimming plane, defaults to 0.
startIndex number <optional>

The starting face index, defaults to 0.
endIndex number <optional>

The ending face index, defaults to the maximum face index.
Inherited From:
Overrides:
Returns:

Returns the number faces that were in front or trimmed.

Type
number

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 roof 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.ROOF