API Docs

Class: Legend

PD. Legend

A class for converting data values to colors.

This class also contains settings for the display of stepped data values and contour lines/bands. These values can be used by grids and other analysis data visualisations to govern their display.

new Legend( [config] [, typeName])

Creates a converter of data values to display colors.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
colorType number <optional>

The type of color gradient to use, default to 0 (rainbow).
units string <optional>

The units of the metric the legend is displaying, defaults to percentage (%).
steps number <optional>

The number of steps in the color chart (1 to 128), defaults to 20.
min number <optional>

The absolute value representing the bottom of the scale, defaults to 0.
max number <optional>

The absolute value representing the top of the scale, defaults to 1.
displacement number <optional>

A maximum displacement to offset cells from their grid plane by their values in mm, defaults to 0.
showSmooth boolean <optional>

Whether to show data as a continuous smooth surface rather than as block values, defaults to true.
showGridLines boolean <optional>

Whether to show grid lines or triangulation edges, defaults to false.
showContourLines boolean <optional>

Whether to show contour lines at the current step values, defaults to false.
showContourBands boolean <optional>

Whether to show contours in block colors at the current step values, defaults to false.
colorType number <optional>

The type of color gradient to use, defaults to 0 (rainbow).
typeName string <optional>

This additional parameter is typically used by subclasses to pass in a default name without altering the config object.
Author:
  • drajmarsh

Extends

Members

:number

_colorType

The type of color gradient to use, defaults to 0 (rainbow).

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

colorType

The type of color gradient to use, default to 0 (rainbow).

Type
  • number
:number

displacement

A maximum displacement to offset cells from their grid plane by their values in mm, defaults to 0.

Type
  • number
:string

displayName <readonly>

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

Type
  • string
Inherited From:
Overrides:
:boolean

hasChanged

Whether or not the scale range has changed.

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

isLegend <readonly>

A flag identifying this object as a grid legend.

Type
  • boolean
:boolean

isSet <readonly>

A flag indicating if the scale range has been specifically set yet.

Type
  • boolean
:number

max

The absolute value representing the top of the scale, defaults to 1.

Type
  • number
:number

min

The absolute value representing the bottom of the scale, defaults to 0.

Type
  • number
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:boolean

showContourBands

Whether to show contours in block colors at the current step values.

Type
  • boolean
:boolean

showContourLines

Whether to show contour lines at the current step values.

Type
  • boolean
:boolean

showGridLines

Whether to show grid lines or triangulation edges.

Type
  • boolean
:boolean

showSmooth

Whether to show data as a continuous smooth surface rather than as block values, defaults to true.

Type
  • boolean
:number

steps

The number of steps in the color chart (1 to 128), defaults to 20.

Type
  • number
:string

units

The units of the metric the legend is displaying, defaults to percentage (%).

Type
  • string
:string

uuid

A universally unique identifier for the item instance.

Type
  • string
Inherited From:
Overrides:

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

computeColour(value [, result])

Calculates the legend colour from the absolute value.

Parameters:
Name Type Argument Description
value number

The value to calculate the colour for.
result THREE.Color <optional>

An optional colour value, defaults to internal shared color.
Returns:

Returns a shared color value.

Type
THREE.Color

computeDisplacement(value)

Calculates the displacement of a cell value in model units.

Parameters:
Name Type Description
value number

The value to calculate the displacement for.
Returns:

Returns the displacement distance.

Type
number

computeFraction(value)

Calculates the normalised scale fraction from the given absolute value.

Parameters:
Name Type Description
value number

The value to calculate the fraction for.
Returns:

Returns the normalised scale fraction.

Type
number

copyToPolyMesh(mesh, width, height)

Add geometry representing the legend to the given WebGL mesh.

Parameters:
Name Type Description
mesh PD.PolyMesh

The mesh to add the legend to.
width number

The horizontal width of the legend in virtual pixels.
height number

The vertical height of the legend in virtual pixels.
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

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
PD.Legend

getContourIncrement()

Computes the value range divided by steps.

Returns:

Returns the computed contour increment.

Type
number

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:
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.' })
             ]
         })
     ];
 };

getValueRange()

Retrieves the range of values, effectively max minus min.

includeInRange(value)

Expands the value range to accommodate the given value.

Parameters:
Name Type Description
value number

The value to accommodate in range.
Returns:

Returns true if the range changed.

Type
boolean

reset()

Resets the value range to begin accommodating new values.

This method initialises the scale range that you can call the includeInRange() method to set the range based on multiple values. After you have finished setting the range, call the update() method.

Returns:

Returns this legend instance to support method chaining.

Type
PD.Legend

setRange(min, max)

Sets the new value range.

Parameters:
Name Type Description
min number

The new minimum value.
max number

The new minimum value.
Returns:

Returns true if the range changed.

Type
boolean

toJSON( [data])

Converts the object instance to a simple POJO for JSON storage.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety 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

update( [forceUpdate])

Validates the value range and sets the color function.

Parameters:
Name Type Argument Description
forceUpdate boolean <optional>

Whether or not to update even if legend has not changed, defaults to false.
Returns:

Returns this legend instance to support method chaining.

Type
PD.Legend

updateDynamicParameters(param, group)

Sets the dynamic parameter value and rebuilds the element if changed.

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 element 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;

 };

validRange()

Determines if the legend has a valid and useable scale.

A usable scale is when the maximum value is greater the minimum, which is basically what this method checks for.

Returns:

Returns true if the maximum value is greater the minimum.

Type
boolean