API Docs Class: Rocks

new Rocks( [config] [, typeName])

Creates a new simple rock representation.

Parameters:

Name Type Argument Description

config

object

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.
`variegation`	number	<optional>	The fraction of variegation in foliage color in summer (0 to 1), defaults to 0.25.
`baseColor`	number	<optional>	The base colour of the canopy foliage in summer as a hexadecimal number, defaults to 0xCCCCCC.
`variColor`	number	<optional>	The variegation colour of the foliage in summer as a hexadecimal number, defaults to 0x887766.
`seed`	number	<optional>	A seed for initialising the random number generator.

typeName

string

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

Author:

drajmarsh

Extends

BIM.Component

Classes

Spherical
StoneWall

Members

:number baseColor

The base colour of the canopy foliage as a hexadecimal number, defaults to 0x008000.

Type

number

:string className <readonly>

The name of the subclass for this object instance.

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

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

Type

string

Inherited From:

PD.Base#className

Overrides:

BIM.Component#className

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

BIM.Component#description

Overrides:

BIM.Component#description

:string displayName <readonly>

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

Type

string

Inherited From:

PD.Base#displayName

Overrides:

BIM.Component#displayName

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

PD.Base#iconName

Overrides:

BIM.Component#iconName

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:

BIM.Component#isComponent

Overrides:

BIM.Component#isComponent

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

BIM.Component#isLocked

Overrides:

BIM.Component#isLocked

:boolean isRockType <readonly>

A flag identifying this object as a rock type.

Type

boolean

:string name

A human-readable name for this item instance.

Type

string

Inherited From:

PD.Base#name

Overrides:

BIM.Component#name

:number outlines

Whether or not to draw an outline of each individual facet, defaults to false.

Type

number

:string productRef

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

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

Type

string

Inherited From:

BIM.Component#productRef

Overrides:

BIM.Component#productRef

:number seed

Caches a seed number to ensure that randomisation is consistent.

Type

number

:number smoothness

How smooth or rounded to make the edges (0 to 1).

Type

number

:number sphericity

How closely the rock surface is to a sphere (0 to 1).

Type

number

:number subType <readonly>

An element-specific subtype.

Type

number

Inherited From:

BIM.Component#subType

Overrides:

BIM.Component#subType

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

BIM.Component#supplier

Overrides:

BIM.Component#supplier

:number updateIndex

Stores an update index to use for shape validity testing.

Type

number

:string uuid

A universally unique identifier for the item instance.

Type

string

Inherited From:

PD.Base#uuid

Overrides:

BIM.Component#uuid

:number variColor

The variegation colour of the foliage in summer as a hexadecimal number, defaults to 0x887766.

Type

number

:number variegation

The fraction of variegation in foliage color (0 to 1), defaults to 0.25.

This is stored as a property to support the BIM.Rock#variegatedColor method.

Type

number

:string SURFACE_ATTRIB <static, readonly>

The name of the attribute for storing rock PD.BRep data.

Rocks generate their geometry as complex surfaces with multiple facets of different shapes. Separate surface geometry is created for each junction in the element's path. This surface data is stored as an attribute of each junction using this string value as the key.

Type

string

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

Checks the allowable range of element parameter values.

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

Parameters:

Name	Type	Description
`param`	PD.Parameter	The parameter that is being interactively changed.
`group`	PD.ParamGroup	The group that the dynamic parameter belongs to.
`host`	BIM.Element	The host element this component is controlling.

Inherited From:

PD.Base#checkDynamicParameter

Overrides:

BIM.Component#checkDynamicParameter

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:

PD.Base#clone

Overrides:

BIM.Component#clone

Returns:

Returns a new instance with copied values.

Type: PD.Base | null

generateGeometry(rock, junction, brep, config)

Generates the geometry of the rock.

Parameters:

Name	Type	Description
`rock`	BIM.Rock	The rock element to rebuild.
`junction`	BIM.Junction	The junction to generate geometry for.
`brep`	PD.BRep	The BRep to add rock geometry to.
`config`	object	A configuration object with rock parameters.

Returns:

Returns this rock type to support method chaining.

Type: BIM.Rocks

getColorCallback()

Retrieves a curried function for variegating rock surface colors.

Internally this method calls the BIM.Rock#variegatedColor method. The aim of wrapping this method as a callback function is to ensure that it is always invoked with this plant element as this, regardless of how and from where the wrapper function is called.

Like the BIM.Rock#variegatedColor method, the returned function takes no arguments and returns a hexadecimal color value.

Returns:

Returns a function that provides hexadecimal color values.

Type: function

getDynamicParameters(host)

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

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

Parameters:

Name	Type	Description
`host`	BIM.Element	The host element this component is controlling.

Inherited From:

PD.Base#getDynamicParameters

Overrides:

BIM.Component#getDynamicParameters

Returns:

Returns an array of PD.ParamGroup objects.

Type: Array

Example

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

getNameAndSupplierParameters()

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

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

Inherited From:

BIM.Component#getNameAndSupplierParameters

Overrides:

BIM.Component#getNameAndSupplierParameters

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:

BIM.Component#hasMethod

Overrides:

BIM.Component#hasMethod

Returns:

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

Type: boolean

highlight(mesh, view, rock)

Renders a highlighted view of the element to show it as selected.

Parameters:

Name	Type	Description
`mesh`	PD.PolyMesh	The selection mesh to render highlighting to.
`view`	PD.ViewData	The view definition to render the model within.
`rock`	PD.Plant	The rock element being highlighted.

Returns:

Returns true if anything was added to the mesh.

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:

BIM.Component#isCompatibleWith

Overrides:

BIM.Component#isCompatibleWith

Returns:

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

Type: boolean

rebuild(rock)

Rebuilds the geometry of a rock ready for visualisation.

Parameters:

Name	Type	Description
`rock`	BIM.Rock	The rock element to rebuild.

Inherited From:

BIM.Rocks#rebuild

Overrides:

BIM.Component#rebuild

Returns:

Returns this rock type to support method chaining.

Type: BIM.Rocks

render(meshes, view, level, rock)

Render a view of the element using the given meshes.

Parameters:

Name	Type	Description
`meshes`	BIM.Meshes	The collection of meshes to render to.
`view`	PD.ViewData	The view definition to render the model within.
`level`	BIM.Level	The level currently being rebuilt and rendered.
`rock`	BIM.Rock	The rock being rendered.

Returns:

Returns true if anything was added to any mesh.

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:

PD.Base#updateDynamicParameters

Overrides:

BIM.Component#updateDynamicParameters

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;

 };

usesJunctionOrientation(junction)

Whether this rock type uses junction orientation.

Parameters:

Name	Type	Description
`junction`	BIM.Junction	The junction to apply the logic to.

Returns:

Return true to show a rotation cursor manipulator.

Type: boolean

variegatedColor()

Generates a random color based on foliage variegation values.

NOTE: This method uses an internal random number cache to ensure that color allocations are reasonably stable even with different numbers of facets or adding variation or orientation which may disrupt the standard random number generator.

Returns:

Returns a randomly interpolated hexadecimal color number.

Type: number

getClassDescription() <static>

A brief description of this class to accompany its icon.

Returns:

Returns a brief description.

Type: string

getClassName() <static>

The name of this class within the PD.Registry.

See PD.Base.getClassName for more details as this is required for use with the PD.Registry.

Returns:

Returns the registered name of this class.

Type: string

getDisplayName() <static>

The name to display within the user interface.

Returns:

Returns the display name.

Type: string

getHostElementClass() <static>

Retrieves the class of the host element for this component.

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

Returns:

Returns the element class this component requires as a host.

Type: BIM.Rock

isCompatibleWith(obj) <static>

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

Parameters:

Name	Type	Description
`obj`	BIM.ENTITY \| BIM.Entity	The entity type or object to check for compatibility with.

Returns:

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

Type: boolean

subType() <static>

Retrieves the sub-type of rock 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.ROCK

Class: Rocks

new Rocks( [config] [, typeName])

Parameters:

Properties of config:

Extends

Classes

Members

baseColor

Type

className <readonly>

Type

description

Type

displayName <readonly>

Type

iconName <readonly>

Type

Example

isComponent <readonly>

Type

isLocked

Type

isRockType <readonly>

Type

name

Type

outlines

Type

productRef

Type

seed

Type

smoothness

Type

sphericity

Type

subType <readonly>

Type

supplier

Type

updateIndex

Type

uuid

Type

variColor

Type

variegation

Type

SURFACE_ATTRIB <static, readonly>

Type

icon <static>

Type

Methods

checkDynamicParameter(param, group, host)

Parameters:

Example

clone()

Returns:

generateGeometry(rock, junction, brep, config)

Parameters:

Returns:

getColorCallback()

Returns:

getDynamicParameters(host)

Parameters:

Returns:

Example

getNameAndSupplierParameters()

Returns:

hasMethod(component, methodName)

Parameters:

Returns:

highlight(mesh, view, rock)

Parameters:

Returns:

isCompatibleWith(obj)

Parameters:

Returns:

rebuild(rock)

Parameters:

Properties of `config`: