API Docs

Class: DaySchedule

BIM. DaySchedule

Defines a series of temporal values for a single day.

Day schedules store a series of values at periodic time increments over a single 24hr day. The default is to store 24 hourly values, but you can use any time increment that evenly divides into 24hrs, limited to between 1 minute (1440 values) and 6 hours (4 values).

Day schedules are used by BIM.Schedule instances and are assigned to one or more days of the year to provide a detailed map of how a value changes throughout the year.

    +-----------------------------------------------+- 1
    |                            __                 |
    |       +       +       +   /  \        +       +- V
    |                 ______   /    \               |  A
    |       +       +/      \_/      \      +       +- L
    |               /                 \             |  U
    |       +    __/                   \    +       +- E
    |___________/                       \___________|
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- 0
    0       4       8      12      16      20      24
                    HOURS OF THE DAY

To make day schedules as flexible as possible, they are always stored as fractional values in the range 0 to 1. This allows them to be used for pretty well any purpose and easily mapped to any other value range or unit types defined by their host schedule. The display and editor UI components usually reflect the values as mapped to the schedule value range, however they are always stored internally as fractions.

new DaySchedule( [config] [, typeName])

Creates a new BIM day schedule.

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

A universally unique identifier of this day schedule.
description string <optional>

A human-readable description of this day schedule.
category any <optional>

Optional keywords for the kind of activities or operations this day schedule controls.
dayType any <optional>

One or more optional comma-separated day-types this day schedule applies to.
timeStep any <optional>

The number of minutes between data values, defaults to 60min (0 to 360).
color any <optional>

An optional hexadecimal CSS color string.
data any <optional>

An optional array of fractional data values for each time step (0 to 1).
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

:BIM.SCHEDULE.CATEGORY

category

Describes the kind of activities or operations this day schedule controls.

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

color

A hexadecimal color value.

Type
  • number
:Array

data

An array of fractional data values for each time step in the day (0 to 1).

This defaults to an array of 24 hourly fractional data values.

Type
  • Array
:string

dataAsCSV

Converts the data to/from comma-separated values.

Type
  • string
:number

dataPointCount

The number of data points in the day.

Type
  • number
:string

dayType

The day-type(s) this day schedule applies to.

Type
  • string
:string

description

The human-readable description of this day schedule.

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

isDaySchedule <readonly>

A flag identifying this object as a day schedule.

Type
  • boolean
:string

name

A human-readable name for this item instance.

Type
  • string
Inherited From:
Overrides:
:number

timeStep

The number of minutes between data values, defaults to 60min (1 to 360).

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

changeResolution(resolution)

Interpolates/extrapolates the profile into a different number of time steps.

A profile must have at least 1 value (which creates a flat profile over the whole day) and a maximum 1440 (which is one for each minute of the day). Time increments of less than one minute are not yet supported.

If the number of time steps is greater than 24 (one per hour) then the number of steps will be adjusted to some multiple of 24 to ensure that the values occur at the same minute in each consecutive hour. This is done to be compatible with the majority of analysis tools.

Parameters:
Name Type Description
resolution number

The new number of time steps over a 24hr day (1 to 1440).
Returns:

Returns this instance to support method chaining.

Type
PD.DaySchedule

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

computeValueRange()

Cycles through the data array to calculate minimum and maximum values.

Returns:

Returns an array in the form [min,max].

Type
Array

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 day schedule.

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

getHourlyValue(hour)

Computes the value for the given hour period from the profile data.

Parameters:
Name Type Description
hour number

The integer hour to compute the value for.
Returns:

Returns the value for the given hour.

Type
number

getInterpolatedValue(time_of_day)

Computes the value at the exact time of day from the profile data.

Parameters:
Name Type Description
time_of_day number

The decimal hour to compute the value for (0.0 to 24.0).
Returns:

Returns the value for the given time of day.

Type
number

interpolateBetween(new_data)

Interpolates/extrapolates the profile into a different number of time steps.

A profile must have at least 1 value (which creates a flat profile over the whole day) and a maximum 1440 (which is one for each minute of the day). Time increments of less than one minute are not yet supported.

If the number of time steps is greater than 24 (one per hour) then the number of steps will be adjusted to some multiple of 24 to ensure that the values occur at the same minute in each consecutive hour. This is done to be compatible with the majority of analysis tools.

Parameters:
Name Type Description
new_data Array

An array to receive the interpolated data.
Returns:

Returns the given array with the interpolated data.

Type
Array

setData(data)

Set the fractional data values in the day schedule and calculates the time step.

This method takes either a day schedule or an array of fractional data values for each time step across the day. The time step is calculated automatically from the number of values in the array. For an hourly profile, ensure that there are exactly 24 values in the array. For a 15min time step, ensure there are 96 values in the array (24 * (60 / 15)).

A day schedule must have at least 1 value (which creates a flat profile over the whole day) and a maximum 1440 (which is one for each minute of the day). Time increments of less than one minute are not yet supported.

If the number of time steps is greater than 24 (one per hour) then the number of steps will be adjusted to some multiple of 24 to ensure that the values occur at the same minute in each consecutive hour. This is done to be compatible with the majority of analysis tools.

Parameters:
Name Type Description
data Array

The daily profile or data array to copy.
Returns:

Returns this day schedule instance to support method chaining.

Type
BIM.DaySchedule

toJSON( [data])

Converts the day schedule data to a simple POJO for JSON storage.

This method is used to copy, store and save the data for this day schedule, 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 of the given day schedule 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;

 };

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