API Docs

Class: Material

BIM. Material

Defines a basic material and its physical properties.

new Material( [config] [, typeName])

Creates a new BIM material.

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 material.
description string <optional>

A human-readable description of this material.
uuid string <optional>

A universally unique identifier of this material.
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:
:THREE.Color|null

color

An optional color to use for material surfaces.

Type
  • THREE.Color | null
:number

defaultThickness

The default thickness of this material, in mm.

This should be the default dimension of a layer of this material within a construction, measured in a direction perpendicular to the main path of heat conduction through the construction. This default thickness value for a material must be greater than zero, even if it is something like 0.000001mm.

Type
  • number
:number

density

The density of this material, in kg/m3.

Density is a quantitative expression of the amount of mass contained per unit volume. The standard unit is the kilogram per meter cubed (kg/m3) and the value for a material must be greater than zero.

Type
  • number
:string

description

The human-readable description of this material.

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

isMaterial <readonly>

A flag identifying this object as a material.

Type
  • boolean
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:number

roughness

The surface roughness of this material (0 to 5).

Surface roughness is a measure of the finely spaced micro- irregularities within the surface texture. This property only influences the convection coefficients, or more specifically the exterior convection coefficient.

The available integer values are:

  • 0: VerySmooth,
  • 1: MediumSmooth,
  • 2: Smooth,
  • 3: Rough,
  • 4: MediumRough,
  • 5: VeryRough.
Type
  • number
:number

solarAbsorptance

The solar absorptance of this material (0 to 1).

Solar absorptance is the fraction of incident solar radiation that is absorbed by the material. Solar radiation includes the visible spectrum as well as infrared and ultraviolet wavelengths. This property is used when calculating the amount of incident solar radiation absorbed by various surfaces and affects the surface heat balances. If solar reflectance (or reflectivity) data is available, then absorptance is equal to 1 minus reflectance (for opaque materials). Values for this field must be between 0 and 1.

Type
  • number
:number

specificHeat

The specific heat of this material, in J/(kg-K).

Specific heat is the amount of heat that must be added to one unit of mass of the material to increase its temperature by one degree Kelvin.

The units for specific heat are joules per kelvin per kilogram (J/(kg-K)) and only values of 100 or more are allowed. Typical ranges are from 800 to 2000 J/(kg-K).

Type
  • number
:number

thermalAbsorptance

The thermal absorptance of this material (0 to 1).

Thermal absorptance is the fraction of incident long wavelength (infra-red) radiation that is absorbed by the material. This is used when calculating the long wavelength radiant exchange between various surfaces and affects the surface heat balances. For long wavelength radiant exchange, thermal emissivity and thermal emittance are equal to thermal absorptance. Values for this field must be between 0 and 1, where 1 represents a 'black body' absorber.

Type
  • number
:number

thermalConductivity

The thermal conductivity of this material, in W/(m-K).

Conductivity is a measure of of a material's ability to conduct heat. Thermal conduction is basically the transport of energy due to random molecular motion across a temperature gradient. It is distinguished from other energy transport by convection and molecular work in that it does not involve macroscopic flows or work-performing internal stresses.

The units for thermal conductivity are watts per meter-kelvin (W/(m-K)) and the value for a material must be greater than zero.

Type
  • number
:number

thermalResistance

The thermal resistance or R-value of this material, in m2-K/W.

This value is typically used for lightweight materials with very low mass and density, such as air gaps, films and/or voids.

Thermal resistance is a measure of the ratio of the temperature difference between the two faces of a material to the rate of heat flow per unit area. Thermal resistance determines the heat insulation property of a material. The higher the thermal resistance, the lower is the heat loss.

The units for thermal resistance are meters-squared-kelvin per watt ((m2-K)/W) and the value for a material must be greater than zero.

NOTE: Most R-values in the USA are calculated in Inch-Pound units and must be converted to the SI equivalent for use here.

Type
  • number
:string

uuid

A universally unique identifier for the item instance.

Type
  • string
Inherited From:
Overrides:
:number

visibleAbsorptance

The visible light absorptance of this material (0 to 1).

Visible absorptance is the fraction of incident visible wavelength radiation that is absorbed by the material. Visible wavelength radiation is slightly different than solar radiation in that the visible band of wavelengths is much more narrow, while solar radiation includes the visible spectrum as well as infrared and ultraviolet wavelengths.

This property is used when calculating the amount of incident visible radiation absorbed by various surfaces and affects the surface heat balances as well as daylighting calculations. If visible reflectance (or reflectivity) data is available, then absorptance is equal to 1.0 minus reflectance (for opaque materials). Values for this field must be between 0 and 1.

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

checkDynamicParameter(param, group [, host])

Provides an opportunity to dynamically limit the value and/or range of each parameter.

This method is called whenever a dynamic parameter is interactively changed. The param argument gives access to the parameter being changed whilst the group argument gives access to other parameters within the same parameter group.

NOTE: Range validation in this method is not absolutely required, but doing so can prevent unnecessary model rebuilds due to out-of-range parameters being different from their previous values, even though the object's geometry will not actually change due to range constraints within the subclasses rebuild() method. Thus, it is usually best to do them here so that someone's future airport model is not entirely rebuilt each time they try to set a too-large length in your custom door handle component.

Parameters:
Name Type Argument Description
param PD.Parameter

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

The group that the dynamic parameter belongs to.
host object <optional>

For components only, the parent or host object that called this method.
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

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

getDynamicParameters( [no_title])

Provides a list of dynamic parameter groups for this supplier.

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

Parameters:
Name Type Argument Description
no_title boolean <optional>

If true, the group is displayed without a section title.
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.' })
             ]
         })
     ];
 };

toJSON( [data])

Converts the supplier data to a simple POJO for JSON storage.

This method is used to copy, store and save the data for this supplier, so the returned object must have all the properties required be able to be able to fully rebuild it when passed to the class constructor.

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

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Overrides:
Returns:

Returns a JSON 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