API Docs

Class: Geometric

BIM.Plants. Geometric

Generates simple primitive-based geometric tree forms.

new Geometric( [config] [, typeName])

Creates a new simple geometric tree representation.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
name string <optional>

A human-readable name for this component.
uuid string <optional>

A universally unique identifier of this component.
productRef string <optional>

A product reference number or identifier.
description string <optional>

A brief product or type description.
supplier BIM.Supplier <optional>

An optional supplier details data object.
foliageDensity number <optional>

The density of leaves on the canopy surface (0 to 20), defaults to 5.
foliageVariation number <optional>

The variation in leaf orientation from surface orientation (0 to 1), defaults to 0.0.
foliageOutlines number <optional>

Whether or not to show outlines of each leaf in the canopy, defaults to true.
bumpiness number <optional>

The amount of noise-driven perturbation of the canopy surface, defaults to 0.35.
bumpScale number <optional>

The relative scale of the bumpiness noise function, defaults to 0.25.
bumpOffset number <optional>

The relative offset within the noise function, defaults to 0.0.
seed number <optional>

A seed value for initialising the random number generator.
typeName string <optional>

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

Extends

Members

:number

bumpOffset

The offset within the noise function, defaults to 0.0.

Type
  • number
:number

bumpScale

The scale of the bumpiness noise function, defaults to 0.15.

Type
  • number
:number

bumpiness

The amount of noise-driven variation in the canopy surface, defaults to 0.25.

Type
  • number
Inherited From:
Overrides:
:number

canopyShape

The geometric shape of the tree (0:Cuboid, 1:Spherical, 2:Cylindrical, 3:Conical. 4:Bullet).

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

description

A brief product or type description, defaults to an empty string.

This description is typically used to provide additional information about the product to other team members, such as its reasons for selection. important features, specifications and/or intended use.

Type
  • string
Inherited From:
Overrides:
:string

displayName <readonly>

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

Type
  • string
Inherited From:
Overrides:
:number

foliageDensity

The density of leaves on the canopy surface (0 to 20), defaults to 5.

Type
  • number
Inherited From:
Overrides:
:number

foliageOrientation

Variation of leaf from surface orientation (0 to 1), defaults to 0.0.

Type
  • number
Inherited From:
Overrides:
:boolean

foliageOutlines

Whether or not to show outlines of each leaf in the canopy, defaults to true.

Type
  • boolean
Inherited From:
Overrides:
:number

foliageVariation

Variations in the regularity of leaf shape (0 to 1), defaults to 0.0.

Type
  • number
Inherited From:
Overrides:
:string

iconName <readonly>

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

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

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

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

isComponent <readonly>

A flag identifying this object as a shared BIM component.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isGeometricTree <readonly>

A flag identifying this object as a geometric tree.

Type
  • boolean
:boolean

isLocked

Whether or not this component's parameters are fixed.

This property is used by the UI and framework to indicate that the component's parameters are fixed and therefore not editable. It is typically set by a 3rd-party manufacturer or supplier on products that they can only provide in one configuration.

For example, there is no point specifying a particular manufacturer's fridge and then adjusting its width to fit a hole in your cabinetry if that manufacturer cannot actually supply a fridge of that width.

Thus, when this property is true, you will not be able to edit the parameters, but you can always duplicate the component (or its configuration), but without the supplier details if you really do want to modify it.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isPlantType <readonly>

A flag identifying this object as a type of plant.

Type
  • boolean
Inherited From:
Overrides:
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:string

productRef

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

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

Type
  • string
Inherited From:
Overrides:
:number

seed

A seed value for initialising the random number generator.

Type
  • number
Inherited From:
Overrides:
:number

subType <readonly>

An element-specific subtype.

Type
  • number
Inherited From:
Overrides:
:string

supplier

The product supplier/manufacturer, defaults to null.

This property contains details of the supplier or manufacturer of this product or component. Multiple components can share the same supplier instance to avoid unnecessary duplication of data.

Type
  • string
Inherited From:
Overrides:
:number

triangulate

Whether or not to render each leaf as separate triangles rather than quads or polygons, defaults to false.

Type
  • number
Inherited From:
Overrides:
:number

updateIndex

Stores an update index to use for shape validity testing.

This value is incremented whenever a shape-related parameter is changed and is then checked against the PD.BRep#updateIndex property on each junction's shape instance. If the junction's shape instance index is less than this value, the shape is considered stale and regenerated.

Type
  • number
Inherited From:
Overrides:
:string

uuid

A universally unique identifier for the item instance.

Type
  • string
Inherited From:
Overrides:
:object

icon <static>

The icon associated with this class in the PD.Registry.

See PD.Base.icon for more information on this object format.

Type
  • object

Methods

addQuadLeaf(brep, v1, v2, v3, v4, orientation, triangulate)

Adds a new four-sided leaf with possible orientation jitter.

Parameters:
Name Type Description
brep PD.BRep

The BRep to add the geometry to.
v1 Array.<number>

The first [x,y,z] vector array.
v2 Array.<number>

The second [x,y,z] vector array.
v3 Array.<number>

The third [x,y,z] vector array.
v4 Array.<number>

The fourth [x,y,z] vector array.
orientation number

The amount of reorientation away from surface.
triangulate number

Whether or not to triangulate the quad.
Inherited From:
Overrides:

addSelectionAsConvexHull(junction, vertices, trunkRadius, trunkHeight)

Adds canopy and trunk prisms for selection to the junction shell.

Parameters:
Name Type Description
junction BIM.Junction

The junction to add the selection prisms to.
vertices Array.<Array>

An array of [x,y,z] vector arrays to generate the convex hull from.
trunkRadius number

The radius of the trunk prism.
trunkHeight number

The height of the trunk prism.
Inherited From:
Overrides:

addSelectionGeometry(junction, canopyBBox, trunkRadius, trunkHeight)

Adds canopy and trunk prisms for selection to the junction shell.

Parameters:
Name Type Description
junction BIM.Junction

The junction to add the selection prisms to.
canopyBBox THREE.Box3

The bounding box of the plant/tree canopy area.
trunkRadius number

The radius of the trunk prism.
trunkHeight number

The height of the trunk prism.
Inherited From:
Overrides:

addSubdividedQuad(brep, quad, size, variation, orientation, triangulate)

Adds leaves distributed over a quad to the facet array.

Parameters:
Name Type Description
brep PD.BRep

The faceted BRep to add to.
quad PD.Polygon

The 4-sided polygon to subdivide.
size number

The size of the leaf, in model units.
variation number

The amount of positional variation to apply.
orientation number

The amount of reorientation.
triangulate number

Whether or not to triangulate the quad.
Inherited From:
Overrides:
Returns:

Returns true if one or more facets were generated.

Type
boolean

addSubdividedTriangle(brep, triangle, size, variation, orientation, triangulate)

Adds leaves distributed over a triangle to the facet array.

Parameters:
Name Type Description
brep PD.BRep

The faceted BRep to add to.
triangle PD.Polygon

The 3-sided polygon to subdivide.
size number

The size of the leaf, in model units.
variation number

The amount of positional variation to apply.
orientation number

The amount of reorientation.
triangulate number

Whether or not to triangulate the quad.
Inherited From:
Overrides:
Returns:

Returns true if one or more facets were generated.

Type
boolean

addTriangularLeaf(brep, v1, v2, v3, orientation)

Adds a new three-sided facet with possible orientation jitter.

Parameters:
Name Type Description
brep PD.BRep

The BRep to add the geometry to.
v1 Array.<number>

The first triangle point.
v2 Array.<number>

The second triangle point.
v3 Array.<number>

The third triangle point.
orientation number

The amount of reorientation away from surface.
Inherited From:
Overrides:

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

generateGeometry(plant, junction, brep, cache)

Rebuilds the geometry of a plant/tree ready for visualisation.

Parameters:
Name Type Description
plant BIM.Plant

The plant/tree element to rebuild.
junction BIM.Junction

The junction to generate geometry for.
brep PD.BRep

The shape to add trunk and canopy geometry to.
cache object

A cached configuration object with plant parameters.
Inherited From:
Overrides:
Returns:

Returns this plant/tree type to support method chaining.

Type
BIM.Plants

generateTaperedTrunk(brep, coords, size, trunk_height, taper_height, trunkColor)

Adds a tapered 3D prism for the trunk to he given shell.

Parameters:
Name Type Description
brep PD.BRep

The BRep to add the geometry to.
coords PD.LocalCoordinates

The local coordinate system to use.
size number

The size of the tree trunk in the local X/Y axis.
trunk_height number

The height of the tree trunk in the local Z-axis.
taper_height number

The height of the tapered section of the trunk.
trunkColor number

The color of the tree trunk.
Inherited From:
Overrides:

getDataCache(plant)

Retrieves a shared cache of computed data for the plant type.

This method creates, computes and stores a range of core properties for a plant or tree based on its dynamic parameters.

Some plants and trees need to do quite complex repetitive and/or iterative operations in order to generate their stem/trunk and foliage/canopy geometries. Many of these operations are based on derived values and inputs that require validation and limitation based on other inputs or junction-specific parameters.

Rather than passing each geometry creation method a plethora of pre-validated and/or pre-limited arguments, or requiring each method to validate and limit its own input internally, this class uses a volatile shared cache that contains all the necessary pre-validated and pre-limited input derived from the parameters of the component, its host element and individual junctions.

This way, the derivation of dependant, validated and limited input is done only once and is then able to be passed between methods as a single argument.

There is only one cache object stored as a static property on this component type, and shared between all instances of this class. Thus, the cache should be considered highly volatile and should only be used within the BIM.Plants#rebuild method and passed to whatever other geometry creation methods are invoked by it. You cannot assume that any values will persist outside the rebuild method as the next component of this type being rebuilt will immediate overwrite them.

Parameters:
Name Type Description
plant BIM.Plant

The plant/tree element being generated.
Inherited From:
Overrides:
Returns:

Returns a new data cache object.

Type
object

getNameAndSupplierParameters()

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

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

Inherited From:
Overrides:
Returns:

Returns an array of PD.ParamGroup objects.

Type
Array

hasMethod(component, methodName)

Determines if this component has a callable method with the given name.

This method is useful for checking if the component has a particular method before attempting to call it, thereby avoiding potential runtime errors. It is used within the framework to check for the presence of life-cycle methods in an element's type component before delegating them.

Parameters:
Name Type Description
component BIM.Component

The component to check.
methodName string

The case-sensitive name of the function/method to check for.
Inherited From:
Overrides:
Returns:

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

Type
boolean

highlight(mesh, view, plant)

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.
plant PD.Plant

The plant/tree element being highlighted.
Inherited From:
Overrides:
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:
Overrides:
Returns:

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

Type
boolean

render(meshes, view, level, plant)

Render a view of the tree 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.
plant BIM.Plant

The plant/tree to render.
Inherited From:
Returns:

Returns true if anything was added to any mesh.

Type
boolean

renderAbstractCircle(mesh, center, radius, variation [, inset])

Adds a circular 2D plant/tree symbol to the given mesh.

Parameters:
Name Type Argument Description
mesh PD.PolyMesh

The mesh to render abstract view to.
center THREE.Vector3

The position of the circle center.
radius number

The average radius of the circle.
variation number

The radial variation of the circle.
inset number <optional>

The depth of regular insets in the circle.
Inherited From:
Overrides:

renderAbstractPlanView(outline_mesh, plant)

Renders an abstract plan view of the given plant.

Parameters:
Name Type Description
outline_mesh PD.PolyMesh

The mesh to render abstract representation to.
plant BIM.Plant

The plant element being rendered.
Inherited From:
Overrides:

renderCanopyOutline2D(mesh, junction)

Renders the 2D canopy outline to the given mesh.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to render the outline to.
junction BIM.Junction

The junction to show the outline.
Inherited From:
Overrides:
Returns:

Returns true if an outline was rendered, otherwise false.

Type
boolean

renderCanopyShape3D(mesh, junction, surfaces, outlines, simple)

Renders the canopy to the given mesh.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to render the outline to.
junction BIM.Junction

The junction to show the outline.
surfaces boolean

Whether to show shape surfaces.
outlines boolean

Whether to show shape outlines.
simple boolean

Whether to show simple outlines.
Inherited From:
Overrides:

renderDetailedPlanView(outline_mesh, surface_mesh, plant)

Renders a detailed plan view of the given plant.

Parameters:
Name Type Description
outline_mesh PD.PolyMesh

The mesh to render outlines to.
surface_mesh PD.PolyMesh

The mesh to render surfaces to.
plant BIM.Plant

The plant element being rendered.
Inherited From:
Overrides:

renderOutlinePlanView(outline_mesh, plant)

Renders an outline plan view of the given plant.

Parameters:
Name Type Description
outline_mesh PD.PolyMesh

The mesh to render outlines to.
plant BIM.Plant

The plant element being rendered.
Inherited From:
Overrides:

updateDataCacheForJunction(plant, junction, config)

Updates the cache based on individual junction parameters.

Parameters:
Name Type Description
plant BIM.Plant

The plant/tree element being generated.
junction BIM.Junction

A path junction of the plant/tree element.
config object

The cached configuration data to update.
Inherited From:
Overrides:
Returns:

Returns the updated data cache 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;

 };

updatePosition(plant, junction, brep)

Moves the generated geometry into position with the junction.

Parameters:
Name Type Description
plant BIM.Plant

The plant element to rebuild.
junction BIM.Junction

The junction to update the shell of,
brep PD.BRep

The foliage BRep to update.
Inherited From:
Overrides:

usesJunctionOrientation(junction)

Whether this plant type uses junction orientation.

Parameters:
Name Type Description
junction BIM.Junction

The junction to apply the logic to.
Inherited From:
Overrides:
Returns:

Return true to show a rotation cursor manipulator.

Type
boolean

variegatedColor()

Generates a random color based on the host plant's color variegation values.

This method takes no arguments and returns a hexadecimal color number.

Inherited From:
Overrides:

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

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 tree 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.PLANT