API Docs

Class: Aperture

BIM. Aperture

Defines a parametric opening within the bounds of a building element.

An aperture defines the size and location of a void, window, door or panel relative to the surfaces of the wall, space, slab or plate to which it belongs. This class provides the basis for all windows and doors.

Apertures need to be treated a bit differently from elements and components as their detailed geometry cannot really be finalised until all the surfaces they are adjacent to and potentially shared with are known. For example, the internal/external offset of the frame of a window, or the opening direction of a door, really depends on whether it is adjacent to another space or not (internal/external) and the material properties of the adjacent surface (inner and outer thicknesses).

If a space is being interactively dragged by the user, the host BIM.Level needs to go through a complex process of checking for adjacencies with other spaces and walls, as well as recalculating its own external boundary facades surfaces, before it can begin working out which adjacent facets to insert each aperture into. Thus, the generation and rendering of aperture geometry has to occur as separate processes only after everything else on the level (and the level itself) has been rebuilt.

This means that the typical update()/rebuild() then render() cycle doesn't work with apertures. They still have an update() method, but this calculates and sets their position and orientation relative to their host junction. The more detailed component geometry must wait until late in the host level's rebuild process, after each aperture has been inserted into its inner and outer surface facets. Thus, the rebuild() method has a different signature and does both the rebuilding of the shell geometry and the rendering of 3D and plan-section views.

The important methods related to this are:

  • computePlanSectionClipperPath()
    This method needs to return an outline profile of the aperture area as cut by the plan-section plane of the host level. The resulting profile is subtracted from the solid area of the host level's footprint in order to provide a clear area in which the sectional profile of the aperture can be rendered. This method is only called when the level is in plan-section view.

  • rebuild()
    This method needs to generate and render the full 3D geometry of any internal framing and/or glazing panes, as well as mullions, transoms and other component geometry within or associated with the aperture. When called in plan-section view, it must also generate and render the sectional profile of any internal framing and/or glazing panes, as well as lines and polygons representing the edges and surfaces of framing and other geometry visible through the section plane.

All aperture type component classes must implement both of these methods in order to fully represent different window, door and panel geometry.

Composition

Apertures use their component type property to reference a BIM.Apertures object that determines what type of aperture it is as well as generating any geometry that occurs within its frame. For example, a door uses a BIM.Doors component to determine whether it is a swinging, sliding, folding, rolling, tilting or revolving door, and to generate the geometry of the resulting internal door panels. A window uses a BIM.Windows component to determine whether it is a fixed frame, casement, hopper or double-hung window type, and to generate the resulting window panels.

In addition, each aperture has a componentList array that can contain additional components such as handles, security grills, blinds, curtains, pelmets, louvres, casings or even external brise soleil and other shading devices.

new Aperture( [config] [, typeName])

Creates a new opening within a wall or other element.

The shape of the opening for the aperture defaults to rectangular, but you can provide a shape that will be mapped onto the wall surface to generate any shape you need. Alternatively the aperture type component can provide its own unique shape.

The nature of the aperture depends on the openingType property, and its geometry depends on the assigned aperture type component. If you do not assign a specific component, a simple void opening will be displayed.

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 element.
uuid string <optional>

A universally unique identifier of this element.
visible boolean <optional>

Whether or not the entity is visible in the model.
extents THREE.Box3 <optional>

The bounding box of the element in model space.
openingType BIM.OPENING <optional>

The type of opening this aperture represents.
typeComponent BIM.Component <optional>

The aperture, window, door or panel type instance.
junction BIM.Junction <optional>

The junction to which this aperture belongs.
alignment PD.ALIGN <optional>

Defines the alignment of the aperture within its host surface, defaults to bottom-left corner.
offsetHor number <optional>

The horizontal distance from the aligned edge of the wall to the side of the aperture.
offsetVer number <optional>

The vertical distance from the bottom/top of the wall to the bottom/top of the aperture.
width number <optional>

The horizontal dimension of the aperture opening area.
height number <optional>

The vertical dimension of the aperture opening area.
open number <optional>

The fraction the aperture is open, defaults to 1.
swapDirection boolean <optional>

Whether or not to flip the forward/backwards direction.
swapSides boolean <optional>

Whether or not to flip the inside/outside direction.
typeName string <optional>

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

Extends

Members

:number

_openFraction

Stores the fraction that the aperture is currently open.

The effect of this will vary between different aperture types, and very probably in unimaginable ways by externally developed classes. Thus, it is included as a private property and exposed through the getOpenFraction getter/setter which can be overridden.

Type
  • number
:PD.ALIGN

alignment

Defines the alignment of the aperture within its host surface, defaults to bottom-left corner.

This property determines how the aperture's position offsets are interpreted relative to its host surface. The default is to align the aperture's bottom-left corner with the corresponding corner of the host surface, but other options allow it to be aligned centrally or to the right/top edges.

Type
:boolean

alwaysShowInPlan

Whether or not to always show this aperture in plan-section view.

When set, this window will always be shown within a plan-section view even if it does not actually cross the horizontal cutting plane.

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

brep

Stores the detailed frame and component geometry of this aperture.

This brep contains the detailed geometry of any frames, mullions, transoms, sills, heads, panels, handles, locks, hinges, hardware, and any other components that are part of the aperture.

Type
  • PD.Brep
: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

displayName <readonly>

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

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

followCurve

Whether or not a curved aperture should sync its own segments with the host curve's segmentation.

Type
  • boolean
:PD.Shell

glazingPanes

Stores any planar glazing panes belonging to this aperture.

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 vertical size of the aperture, in model units.

Type
  • number
:PD.Polygon

holeProfile

The actual shape of the hole to cut through its host element.

This is a crucial part of the aperture that gives its shape and is used as the basis for interactive selection when the model is viewed in 3D. It is automatically updated whenever the host junction or element changes. The positions of its vertices are given in absolute world coordinates, but will/must always be in the same virtual plane as its host surface.

Type
:string

iconName <readonly>

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

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

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

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

id

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

Type
  • number
:boolean

isAperture <readonly>

A flag identifying this object as an aperture.

Type
  • boolean
:boolean

isCurved

Whether or not the aperture sits in a curved wall.

Type
  • boolean
:boolean

isDoor <readonly>

A flag identifying this object as a door opening.

Type
  • boolean
:boolean

isEntity <readonly>

A flag identifying this object as an entity.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isExternal

Whether or not the aperture is on an external face of the building.

Type
  • boolean
:boolean

isFeature <readonly>

A flag identifying this object as a surface feature.

Type
  • boolean
:boolean

isGlazed

Whether or not the opening is glazed.

This is pretty obvious for a window and skylight, however when set for a door, the door itself is assumed to be glazed so will be shown as a frame-within-a-frame.

Type
  • boolean
:boolean

isInserted

Whether or not an adjacent face was found and a valid outer profile created.

Type
  • boolean
:boolean

isOpen <readonly>

Whether or not the aperture is more open than closed.

Type
  • boolean
:boolean

isOpening <readonly>

A flag identifying this object as a hole through the surface.

Type
  • boolean
:boolean

isOperable <readonly>

A flag indicating whether this entity responds to different values of BIM.Aperture#openFraction.

Type
  • boolean
:boolean

isPanel <readonly>

A flag identifying this object as a panel.

Type
  • boolean
:boolean

isSkylight <readonly>

A flag identifying this object as a skylight opening.

Type
  • boolean
:boolean

isTransparent

Whether or not the opening allows light to pass through.

This is pretty obvious for voids, windows and skylights, but doors and panels may or may not contain glass panes or or openings. This value is set by the particular aperture type component whenever the aperture is rebuilt.

Type
  • boolean
:boolean

isVertical

Whether or not the aperture is in a simple vertically extruded wall.

Type
  • boolean
:boolean

isVoid <readonly>

A flag identifying this object as a void opening.

Type
  • boolean
:boolean

isWindow <readonly>

A flag identifying this object as a window opening.

Type
  • boolean
:BIM.Junction

junction

The junction to which this aperture belongs.

The value of this property is automatically set whenever the aperture is updated and when assigned to junction.

Type
:number

maxHeight

The maximum height of the aperture in its junction, in model units.

Type
  • number
:number

maxWidth

The maximum width of the aperture in its junction, in model units.

Type
  • number
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:number

offsetHor

The horizontal distance of the anchor point from the aligned edge of the host surface.

The meaning of this value depends on the current alignment property value. For LEFT and RIGHT alignments, it is the distance of the aperture from the respective vertical edge of the host surface. For CENTER alignments, it is the minimum allowable offset from both LEFT and RIGHT edges.

Type
  • number
:number

offsetVer

The vertical distance of the anchor point from the aligned edge of the host surface.

The meaning of this value depends on the current alignment property value. For TOP and BOTTOM alignments, it is the distance of the aperture from the respective horizontal edge of the host surface. For MIDDLE alignments, it is the minimum allowable offset from both TOP and BOTTOM edges.

Type
  • number
:number

openFraction

Defines the fraction of the aperture that is open.

This value will affect different aperture types in different ways, and very likely in some completely unexpected ways with externally developed aperture types. It is a value that ranges from 0 to 1 for most kinds of aperture, and -1 to 1 for some doors that can open two ways.

Type
  • number
:BIM.OPENING

openingType

Defines the type of opening, defaults to a plain void.

This property determines the gbXML nature of the aperture, whether it is a void, window, door, panel or feature. The assigned aperture type component must be compatible with this gbXML opening type.

Type
:THREE.Vector2

pos

The actual position of the aperture relative to its host surface.

This gives the final calculated relative position of the aperture. These may be different to preferred offsetHor and offsetVer values as the aperture may need to be modified if its size would extend beyond the extents of the surface it belongs to. Preference is always given to maintaining the size and shape of the aperture, with its position adjusted first to make it fit.

Type
  • THREE.Vector2
: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:
:Array.<PD.Element>

shadingComponents

Stores a list of associated shading components.

These components are typically external shading devices such as brise soleil, louvers, overhangs, fins, awnings, canopies, shutters, or other similar devices that are associated with the aperture.

Type
  • Array.<PD.Element>
:THREE.Shape|null

shape

An optional 2D shape from which to generate the profile.

The bottom-left corner of this shape, or the minimum extents of its bounding box, should ideally start at the origin in order to be positioned accurately within the aperture's host surface(s).

Type
  • THREE.Shape | null
:PD.Shell

shell

Stores the jamb surfaces of the aperture as well as any frame geometry.

This shell contains the internal surfaces of the aperture jambs, as well as any frame geometry that may be part of the aperture.

Type
:PD.Polygon|null

sillProfile

The outline of the aperture when viewed in plan-section view.

This is also a crucial part of the aperture that gives the shape of the hole when viewed in plan-section view, and is used as the basis for interactive selection when in plan view. It is automatically updated whenever the host junction or element changes. The positions of its vertices are given in absolute world coordinates, but will/must always be in a horizontal plane located immediately below the aperture.

Type
:THREE.Vector2

size

The size of the aperture within the plane of its host surface.

This gives the final calculated size of the aperture. This may be different from the preferred width and height values as the aperture may need to be modified if its size would extend beyond the extents of the surface it belongs to. Preference is always given to maintaining the size and shape of the aperture and adjusting its position first to make it fit. However, if the host surface is smaller than the preferred size, the actual size will be then reduced to fit.

Type
  • THREE.Vector2
:boolean

swapDirection

Whether or not to flip the forward/backwards direction.

Type
  • boolean
:boolean

swapSides

Whether or not to flip the inside/outside direction.

Type
  • boolean
:BIM.Component|null

typeComponent

A type component reference.

The assigned BIM.Windows, BIM.Doors or BIM.Panels type component provides the aperture with all its geometric characteristics. Without an assigned aperture type, the aperture is rendered as a simple void through an element.

Type
:string

typeDisplayName <readonly>

Retrieves the display name of the assigned type component.

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

width

The horizontal size of the aperture, in model units.

Type
  • number
:object

frameOffsetParamType <static>

Stores a parameter type for dynamically setting frame offset.

The allowable range of frameOffset values depends on both the thickness of the element/material the aperture sits is as well as the frameDepth. Using this parameter type, it is possible to dynamically update the allowable range whenever the frameDepth value is changed.

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

addProfileToPolyMesh(mesh, side)

Adds an outline of the given aperture profile to the mesh.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to add the profile outline to.
side PD.SIDE | Array

Either the side of the profile, or the profile itself as an array of points.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

addToArbitraryPolygon(polygon)

Inserts the aperture as a hole within the given polygon.

Parameters:
Name Type Description
polygon PD.Polygon

The polygon to insert the aperture in.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

addToExtrudedPolygon(polygon)

Inserts the aperture as a hole within the given polygon.

This method assumes that the polygon is extruded vertically by some amount and that the vertices are in an anti-clockwise order, when viewed from same side as its surface normal, with the first vertex being the bottom-left, the second being bottom-right and the third top-right, etc.

Parameters:
Name Type Description
polygon PD.Polygon

The polygon to insert the aperture in.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

alignCoordsWithCurvedOpening(coords)

Aligns the given local coordinates to the curved opening of this aperture and returns the direct linear distance between left and right sides.

If this aperture is curved, and its curved path has been generated, this method will modify the given local coordinates so that the X-axis is aligned to the tangent of the curved opening, and the Y-axis is aligned to the normal of the curved opening. The Z-axis is not modified.

It also computes the distance between the left and right sides of the opening. If the aperture is planar, this is simply the size.x value. However, if the aperture is curved, this will be the linear distance between the start and end points of the curved aperture path.

Parameters:
Name Type Description
coords PD.LocalCoordinates

The local coordinates to align.
Returns:

Returns the computed width of the opening.

Type
number

alignCursor(cursor)

Rotates the cursor to align with this aperture.

Parameters:
Name Type Description
cursor PD.Cursor

The cursor to align.
Returns:

Returns true if cursor is valid and was aligned.

Type
boolean

checkDynamicParameter(param, group)

Checks the dynamic parameter value and rebuilds the element if required.

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

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

computeAllowableFrameOffset(frameDepth, offset)

Limits the given frame offset to an allowable range.

Parameters:
Name Type Description
frameDepth number

The depth of the frame.
offset number

The frame offset value to check.
Returns:

Returns a frame offset limited by frame and junction depth.

Type
number

computeAllowableFrameOffsetMax(frameDepth)

Calculates the maximum allowable frame offset and limits the value.

Parameters:
Name Type Description
frameDepth number

The depth of the frame.
Returns:

Returns a maximum frame offset limited by frame and junction depth.

Type
number

computeAllowableFrameOffsetMin(frameDepth)

Calculates the minimum allowable frame offset and limits the value.

Parameters:
Name Type Description
frameDepth number

The depth of the frame, in model units.
Returns:

Returns a minimum frame offset limited by frame and junction depth.

Type
number

computePlanSectionClipperPath(level)

Generates the outline of the aperture hole in plan-section view.

Parameters:
Name Type Description
level BIM.Level

The level with the section plane.
Returns:

Returns an array of clipper path points.

Type
Array

computeSharedLocalCoordinates()

Sets up a shared local coordinate set for the given aperture.

As this returns shared local coordinates, you must assume that these computed settings are only valid when used within the method or function that called this method, or within any methods directly invoked by the calling method/function. If you try to update another aperture after calling this method, or use promises or await where that might happen, then there is a very real risk that something else may change them in the interim.

This method assumes that the update() method has already been called on the given aperture after any changes to it so that its core profile has already been computed.

The origin of the local coordinates is set to the bottom-left corner of the aperture opening profile. The U-axis is set to the direction of travel from the given junction to the next, and the V-axis to the normal to that direction. The W-axis is set to the normal of the path that the junction belongs to or, if it doesn't belong to a path, its own upVector.

Returns:

Returns the updated local coordinates.

Type
PD.LocalCoordinates

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 aperture when selected.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to render to.
size number

The size of dimension in model units.
Returns:

Returns true if anything was added to the mesh.

Type
boolean

findByRay(selection)

Checks if the given ray intersects the aperture.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Returns:

Returns the aperture shell facet that was intersected, or null.

Type
PD.Polygon | null

fromJSON(data)

Safely copy properties from a source object.

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

Parameters:
Name Type Description
data object

The source object containing data to copy.
Overrides:
Returns:

Returns this instance to support method chaining.

Type
BIM.Aperture

generateCurvedAperturePath()

Generates the horizontal path of an aperture within a curved surface.

This method generates a path that, as much as possible, follows the segmentation of the junction curve. However, if the aperture starts or ends between two curve segments, additional points may be generated to ensure a smooth transition.

Returns:

Returns the aperture path within the curved surface.

Type
PD.Path

generateCurvedHorizontalProfile(inset, outset)

Generates the horizontal profile of an aperture in a curved surface.

This method generates two contours, one inset and one outset from the junction curve. The contours are generated so that, as much as possible, they follow the segmentation of the junction curve. However, if the aperture starts or ends between two curve segments, additional points may be generated to ensure a smooth transition.

Parameters:
Name Type Description
inset number

The offset of the internal profile.
outset number

The offset of the external profile.
Returns:

Returns an array of [x,y,z] vector arrays defining the sill boundary, or an empty array if it failed.

Type
Array.<Array.<number>>

generateDoorFrameGeometry(coords, frameWidth, frameDepth, frameHeight, frameOffset)

Add a frame around the top and sides of a door aperture.

     15-------------------------14
   7---------------------------6 |
   | :   10 - - - - - - - - 11 | |
   | : 2-------------------3 : | |
   | : | |                 | : | |
   | : | |                 | : | |
   | : | |                 | : | |
   | : | |                 | : | |
   | 8 | 9 -  -  -  -  -  -|12 |13
   0---1 -  -  -  -  -  -  4---5
Parameters:
Name Type Description
coords PD.LocalCoordinates

The local coordinate system to use.
frameWidth number

The size of the frame in the local X axis.
frameDepth number

The size of the frame in the local Y axis.
frameHeight number

The size of the frame in the local Z axis.
frameOffset number

The offset of the frame from the path line.
Returns:

Returns an array of 11 facets.

Type
Array

generateFrameGeometry(coords, frameWidth, frameDepth, frameHeight, frameOffset [, glazing])

Generates a simple frame around the aperture and adds it to aperture shell.

     11--------------------------10
    3---------------------------2 |
    | :  15 -  -  -  -  -  - 14 | |
    | : 7-------------------6 : | |
    | : | |                 | : | |
    | : | |                 | : | |
    | : |12-----------------|13 | |
    | : 4-------------------5   | |
    | 8 -  -  -  -  -  -  -  -  | 9
    0---------------------------1
Parameters:
Name Type Argument Description
coords PD.LocalCoordinates

The local coordinate system to use.
frameWidth number

The size of the frame in the local X axis.
frameDepth number

The size of the frame in the local Y axis.
frameHeight number

The size of the frame in the local Z axis.
frameOffset number

The offset of the frame from the path line.
glazing boolean <optional>

Whether or not to include a glazing pane, defaults to false.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

generateHoleAsSolid()

Generates the 3D aperture shape as a PD.Solid so that it can be subtracted from a wall/space surface.

Returns:

Returns a solid representation of the aperture.

Type
PD.Solid

generateJambGeometry( [frameDepth] [, frameOffset])

Generates simple jamb facets and adds them to the shell.

Parameters:
Name Type Argument Description
frameDepth number <optional>

The depth of the internal frame, defaults to zero.
frameOffset number <optional>

The offset of the frame from the path line, defaults to zero.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

generatePlanSection()

Generates the geometry of a simple opening with no frame in plan-section view.

generatePlanSectionClipperPath(level [, frameDepth] [, frameOffset])

Generates a profile shape for creating holes in plan section polygons.

When the plan section cutting plane of a level cuts through an aperture within a surface, that particular area of the section needs to be removed to create an opening through which a normal view of the sill can be generated. In the illustration below, the 'XXXX's mark the area of the filled section polygon after subtracting the required hole for the aperture.

        :                                 :
      : :         _  _  _  _  _ _       : :
      : :       .:_  _  _  _  _ .:      : :
      : :      : :             : :      : :
      : :      : :             : :      : :
      : :      : :+------------:-:+     : :
      : +------:-+    Shape of : +--------+
      :/XXXXXXXX/|  hole to be :/XXXXXXXX/|
      +--------+ |  removed.   +--------+ |
      |       +---------------+|        | |
      |        | +-------------|        | |
      |        |/              |        | |
      |        +---------------+        | |
      |                                 | +
      |                                 |/
      +---------------------------------+

To ensure that the cut opening is clean and does not create tiny shards due to rounding errors, this method generates the shape of the sill profile with the inner and outer lines extended out slightly, as shown in the illustration below.

  |            |
  |        '   |                                                       : extend
  |        '   +-----------------+         +-----------------------+ - + - -
  |        '  _+ . inner . . . . |---------| . . . . inner . . . . |---+-----
  |        '_/                   |         |                       |   :
  |        + - - - -path - - - - + - - - - | - - - - path - - - - -|
  |        |                     |         |                       |
  |        |                     |         |                       |   :
  +--------| ' ' ' outer ' ' ' ' |---------| ' ' ' ' outer ' ' ' ' |---+-----
           +---------------------+         +-----------------------+ - + - -
                                                                       : extend

NOTE: This method calls the generateSillProfile() method to compute the plan profile of the aperture, so you do not need to call it beforehand. When a level updates, it either calls this method or generateJambGeometry(), but never both.

Parameters:
Name Type Argument Description
level BIM.Level

The level to get section plane.
frameDepth number <optional>

The depth of the internal frame.
frameOffset number <optional>

The offset of the frame from the path line, defaults to zero.
Returns:

Returns an array of ClipperLib points.

Type
Array

generateSillProfile( [frameDepth] [, frameOffset])

Generates the horizontal profile of the aperture.

The horizontal profile is basically the shape of the sill of the aperture when viewed in plan. It is used for interactive selection in plan view, for generating plan-section holes in the host level's footprint and is extruded to generate the side and head jamb surfaces.

In a wall between two angled corners, the inside and outside surfaces may well be of different lengths, and both different from the path length the wall segment follows. This means that, if either side of the aperture is near one the corners, the inner aperture hole may be different from the outer aperture hole. This means that the sill may need additional vertices, as shown in the diagram below.

  ---------+........inner........+---------
           |                     |
  -  - - - | - - - -path - - - - | - - - -
           |                     |
           |                     |
  ---------+''''''''outer''''''''+---------


  |            |
  |        '   |
  |        '  _+......inner......+---------
  |        '_/                   |
  |        + - - - -path - - - - + - - - -
  |        |                     |
  |        |                     |
  +--------+''''''''outer''''''''+---------

Internal Frames

The sill needs to adapt even further if it is to accommodate an internal frame. In such cases, it needs to know the frame offset from the path line and the frame depth. This allows it to ensure that the frame always abuts an area of side jamb that is perpendicular to the path line.

Thus, this method can be used by aperture type components to generate sill and jamb geometry that is compatible with their own frame dimensions and positions.

     |              |
     |          '   |                              :
     |          +-+-+-inner_frame---+-+---------   : frameOffset < 0
     |          |X|                 |X|  - - - - - + -
     |          +-+---outer_frame---+-+  - -path - + -
     |          |                     |            :
     |          |                     |
     +----------+''''''''outer''''''''+---------


     |              |
     |          '   |
     |          '  _+......inner......+---------   :
     |          +'+---inner_frame---+-+            : frameOffset = 0
     |          |X| - - -path - - - |X|  - - - - - + -
     |          +-+---outer_frame---+-+            :
     |          |                     |
     |          |                     |
     +----------+''''''''outer''''''''+---------


     |              |
     |          '   |
     |          '  _+......inner......+---------
     |          '_/                   |            :
     |          +-+---inner_frame---+-+  - -path - + -
     |          |X|                 |X|  - - - - - + -
     |          +-+---outer_frame---+-+            :  frameOffset > 0
     |          |                     |            :
     +----------+''''''''outer''''''''+---------


     |              |
     |          '   |
     |          '   +......inner......+---------
     |          ' _/                  |            :
     |          '/ - - - path - - - - |  - - - - - + -
     |          +-+---inner_frame---+-+            :
     |          |X|                 |X|  - - - - - + -
     |          +-+---outer_frame - + +            : frameOffset > 0
     +----------+''''''''outer''''''''+---------   :


     |              |
     |          '   |
     |          '   +......inner......+---------
     |          '  /                  |            :
     |          ' / - - - path - - - -|  - - - - - + -
     |          '/                    |            :
     |          +-+---inner_frame---+-+            :
     |          |X|                 |X|  - - - - - + -
     +----------+-+---outer_frame---+-+---------   : frameOffset > 0
                                                   :
Parameters:
Name Type Argument Description
frameDepth number <optional>

The depth of the internal frame, defaults to zero.
frameOffset number <optional>

The offset of the frame from the path line, defaults to zero.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

getAirFlowArea()

Retrieves the total area of the aperture that is currently open for air to flow though.

The value returned by this method depends upon the aperture's size, its type component, the frame area ratio and the current open fraction if the aperture is operable.

Returns:

Returns the open area fraction for this aperture in m2.

Type
number

getAlignmentReferencePos(point)

Sets the given point to the alignment reference point in the aperture.

Parameters:
Name Type Description
point THREE.Vector3

The point to set the position of.
Returns:

Returns the given point to support method chaining.

Type
THREE.Vector3

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

getCurvePath()

Retrieves the curved path for a curved aperture.

This will return null if the aperture is not curved, or if no curved path has yet been created.

Returns:

Returns the curved path or null if none exists.

Type
PD.Path | null

getDynamicParameters( [host])

Provides a list of dynamic parameter groups for this aperture.

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

Parameters:
Name Type Argument Description
host object <optional>

For components only, the parent or host object that called this method.
Inherited From:
Overrides:
Returns:

Returns an array of PD.ParamGroup objects.

Type
Array
Example
getDynamicParameters(host) {
     return [
         new PD.ParamGroup({
             name: 'mainParams',
             title: 'Table Parameters',
             target: this,
             params: [
                 new PD.Parameter({ name: 'height', title: 'Table Height', value: this.height, paramType: PD.ParamType.SmallDistance, description: 'The height from floor level to the top of the table.' }),
                 new PD.Parameter({ name: 'size', title: 'Table Top Size/Diameter', value: this.size, paramType: PD.ParamType.Distance, description: 'The size of the table top when not defined by a closed path.' }),
                 new PD.Parameter({ name: 'thickness', title: 'Table Top Thickness', value: this.thickness, paramType: PD.ParamType.SmallDistance, description: 'The thickness of the table top surface.' }),
                 new PD.Parameter({ name: 'offset', title: 'Offset From Path', value: this.offset, paramType: PD.ParamType.SmallDistance, description: 'The offset distance from the table path.' }),
                 new PD.Parameter({ name: 'swapSides', title: 'Swap Sides', value: this.swapSides, paramType: PD.ParamType.Boolean, description: 'Reverse the direction of the table relative to its path.' }),
                 new PD.Parameter({ name: 'isRound', title: 'Round Table', value: this.isRound, paramType: PD.ParamType.Boolean, description: 'Whether or not the table surface is round.'  }),
             ]
         }),
         new PD.ParamGroup({
             name: 'legParams',
             title: 'Leg Parameters',
             target: this,
             params: [
                 new PD.Parameter({ name: 'legCount', title: 'Number of Legs', value: this.legCount, paramType: PD.ParamType.Integer, description: 'The number of legs on the table.' }),
                 new PD.Parameter({ name: 'legSize', title: 'Leg Size', value: this.legSize, paramType: PD.ParamType.SmallDistance, description: 'The thickness of each leg of the table.' }),
                 new PD.Parameter({ name: 'legInset', title: 'Leg Edge Inset', value: this.legInset, paramType: PD.ParamType.SmallDistance, description: 'The inset distance of each leg from the table edge.' }),
                 new PD.Parameter({ name: 'legOffset', title: 'Leg Edge Offset', value: this.legOffset, paramType: PD.ParamType.Fraction, description: 'The relative distance of the leg along each edge span.' }),
                 new PD.Parameter({ name: 'legSpan', title: 'Max. Distance Between Legs', value: this.legSpan, paramType: PD.ParamType.Distance, description: 'The maximum distance between legs along each edge span.' })
             ]
         })
     ];
 };

getDynamicParametersForHandle()

Provides a list of dynamic parameter groups for this aperture's handle.

Returns:

Returns an array of PD.ParamGroup objects.

Type
Array

getDynamicParametersForPanel()

Provides a list of dynamic parameter groups for this aperture's panel.

Returns:

Returns an array of PD.ParamGroup objects.

Type
Array

getLightFlowArea()

Retrieves the total area of the aperture that is currently open for light to pass though either glazing or void.

The value returned by this method depends upon the aperture's size, its type component, the frame area ratio and the current open fraction if the aperture is operable.

Returns:

Returns the open area fraction for this aperture in m2.

Type
number

getRefHeight()

Retrieve the last stored reference height in model units.

This value is set by calling the storeRefData() method.

Returns:

Returns the reference height.

Type
number

getRefOffsetX()

Retrieve the last stored reference X offset in model units.

This value is set by calling the storeRefData() method.

Returns:

Returns the reference X offset.

Type
number

getRefOffsetY()

Retrieve the last stored reference Y offset in model units.

This value is set by calling the storeRefData() method.

Returns:

Returns the reference Y offset.

Type
number

getRefOpenFraction()

Retrieve the last stored reference open fraction.

This value is set by calling the storeRefData() method.

Returns:

Returns the reference open fraction value.

Type
number

getRefWidth()

Retrieve the last stored reference width in model units.

This value is set by calling the storeRefData() method.

Returns:

Returns the reference width.

Type
number

getReferenceDepth()

Retrieves the depth of the host surface material.

Returns:

Returns the host surface material depth, in model units.

Type
number

getTypeComponentParameters()

Provides a list of component parameter groups for this element.

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

Returns:

Returns an array of PD.ParamGroup objects.

Type
Array

intersectExtents(ray, intersection)

Determines if the given ray intersects the entity extents.

Parameters:
Name Type Description
ray THREE.Ray

The ray to find the intersection for.
intersection THREE.Vector3

The vector to store the intersection point, if any.
Inherited From:
Overrides:
Returns:

Returns the intersection point, or null if no intersection.

Type
THREE.Vector3 | null

intersectLightRay(ray, result)

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

This method typically intersects the ray with its BIM.Aperture#glazingPanes, if it has any, and then with its BIM.Aperture#shell. Override this method in your custom aperture 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.
Returns:

Returns true if the light ray hit an opaque surface and updated results.

Type
boolean

moveAlignmentReferencePos(point)

Constrains the aperture to be within host junction.

Parameters:
Name Type Description
point THREE.Vector3

The point to constrain inside the junction.
Returns:

Returns true if the point was constrained.

Type
boolean

rebuild(view, level)

Displays the frame of the aperture as 3D geometry.

NOTE: This method also generates the actual geometry of the jambs and frames. This has to be done during the level rebuild process as only then can we be sure that all of the extruded external wall geometry has been created. It also ensures that the aperture geometry matches the 'as-rendered' condition so that interactive selection is accurate by default.

Parameters:
Name Type Description
view PD.ViewData

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

The level currently being rebuilt.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

render(view, level)

Displays the frame of the aperture as 3D geometry.

Parameters:
Name Type Description
view PD.ViewData

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

The level currently being rebuilt.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

renderDoorFrameInPlanSection(level, coords, frameWidth, frameDepth, frameOffset)

Add a frame around the top and sides of a door aperture.

   -------+  -  -  -  -  -  -  -  -  -  -  -  -  -  +-------
          |                                         |
          0---4                                 6---3  -  +  -
          |   |                                 |   |     : frameDepth
          1---5                                 7---2  -  +  -
          |                                         |
   -------+  -: -  -  -  -  -  -  -  -  -  -  - :-  +-------
          :   :                                 :   :
        - + - + -                             - + - + -
        frameWidth                           frameWidth
Parameters:
Name Type Description
level BIM.Level

The level to render the frame to.
coords PD.LocalCoordinates

The local coordinate system to use.
frameWidth number

The width of the frame in the local U axis.
frameDepth number

The depth of the frame in the local V axis.
frameOffset number

The offset of the frame in the local U axis.
Returns:

Returns true if an outline was to rendered.

Type
boolean

renderFrameInPlanSection(mesh, coords, frameWidth, frameDepth, frameOffset [, outline])

Displays a plan-section view of a vertical frame inside the aperture.

   ---+ - - - - - - - - - - - - - - - - - - - - - +---
      |                                           |
      0---4-----------------------------------6---3 - - + -
      |   |                                   |   |     : frameDepth
      1---5-----------------------------------7---2 - - + -
      |   :                                   :   |
   ---+ - - - - - - - - - - - - - - - - - - - - - +---
      :   :                                   :   :
    - + - + -                               - + - + -
    frameWidth                             frameWidth
Parameters:
Name Type Argument Description
mesh PD.PolyMesh

The mesh to render the section to.
coords PD.LocalCoordinates

The local coordinate system to use.
frameWidth number

The width of the frame in the local X axis.
frameDepth number

The depth of the frame in the local Y axis.
frameOffset number

The offset of the frame from the path line.
outline boolean <optional>

Whether to only show sectional outline.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

renderInPlanSection(level)

Displays the geometry of a simple opening with no frame in plan-section view.

Parameters:
Name Type Description
level BIM.Level

The level to render the apertures to.
Returns:

Returns true if the aperture is cut by the section plane.

Type
boolean

renderToSVG(width, height, planView)

Constructs a plan or elevation view of this aperture as SVG elements.

Plan-Section View
   ---+ - - - - - - - - - - - - - - - - - - - - - +---
      |                                           |
      +---+-----------------------------------+---+
      |   |                                   |   |
      +---+-----------------------------------+---+
      |                                       :   |
   ---+ - - - - - - - - - - - - - - - - - - - - - +---

Elevation View
      +-------------------------------------------+
      |                                           |
      |   +-----------------------------------+   |
      |   |                                   |   |
      |   |                                   |   |
      |   |                                   |   |
      |   |                                   |   |
      |   |                                   |   |
      |   |                                   |   |
      |   +-----------------------------------+   |
      |                                           |
      +-------------------------------------------+
Parameters:
Name Type Default Description
width number

The width of the available SVG viewBox.
height number

The height of the available SVG viewBox.
planView boolean true

Whether to render in plan view instead of elevation, defaults to true.
Returns:

Returns a vector image of this aperture as SVG elements.

Type
string

selectByFrustum(selection)

Checks if aperture is inside frustum and updates the selection.

Parameters:
Name Type Description
selection PD.Selection

The interactive selection accumulator.
Returns:

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

Type
boolean

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

setCurvePath(path)

Sets the curved path for a curved aperture.

Parameters:
Name Type Description
path PD.Path | null

The curved path to set, or null to clear it.
Returns:

Returns this aperture instance to support method chaining.

Type
BIM.Aperture

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

storeRefData()

Snapshots the position and size of an aperture ready for a move.

Returns:

Returns this aperture to support method chaining.

Type
BIM.Path

update(junction [, segments])

Updates the profile and shell of the aperture relative to the junction.

Parameters:
Name Type Argument Description
junction BIM.Junction

The junction that owns the aperture.
segments number <optional>

The number of segments to divide shape curves.
Returns:

Returns this aperture to support method chaining.

Type
BIM.Aperture

updateDynamicParameters(param, group)

Checks the dynamic parameter value and rebuilds the component if required.

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

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 component was rebuilt and a model update is required.

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

getEntityType() <static>

Defines the type of BIM entity this class represents.

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

Returns:

Returns the BIM entity type this class represents.

Type
BIM.ENTITY

getSharedArrayOf8Vector3() <static>

Retrieves an array of eight shared 3D vectors.

These are used when generating plan-section views. As apertures can be dynamically resized, aperture classes can use these shared temporary vectors to avoid having to constantly allocate memory.

Returns:

Returns an array of eight shared 3D vectors.

Type
Array