API Docs

Class: HUDController

PD. HUDController

A class for managing a head-up display (HUD).

A head-up display allows you to overlay 2D graphical information on top of a 3D scene. Such information can be text-based annotations, performance metrics, charts and graphs, legends or anything else that may be required.

The role of the HUD controller class is to manage one or more PD.HUDItem instances so that they can be arranged in different areas of the canvas and reordered based on a tracked 3D position in the underlying scene.

The HUD controller is used to create, add, remove, clear and arrange HUD items. It can also be used to update the positions of items, render indicator lines that link items toi their 3D model positions, and respond to changes in the canvas size or view.

new HUDController(editor [, config])

Creates a new head-up display (HUD) manager.

Parameters:
Name Type Argument Description
editor PD.SceneEditor

The scene editor that owns this controller.
config object <optional>

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

The size of the X-axis of the HUD, in pixels.
height number <optional>

The size of the Y-axis of the HUD, in pixels.
Author:
  • drajmarsh

Members

:function|null

debouncedUpdate

A debounced item arrangement update callback.

This callback is used to debounce the update() method so that it is not called too frequently when the canvas size and/or camera view changes. It updates 250 milliseconds after last being called.

Type
  • function | null
:object

height

The size of the Y-axis of the HUD, in pixels.

This value tracks the host scene editor canvas size.

Type
  • object
:PD.PolyMesh

indicatorMesh

A renderable mesh for displaying indicator lines/arrows that link HUD items to their associated 3D model position.

Type
:boolean

isHudController <readonly>

A flag identifying this object as a HUD controller.

Type
  • boolean
:Array.<PD.HUDItem>

items

Stores a list of all HUD items that this HUD controls.

This array is used to store all HUD items that are managed by this controller. You should not modify this array directly, but instead use the addItem and removeItem methods to add and remove items from the HUD. This way, items will be automatically added to the rendered HUD scene when they are created and removed when they are deleted.

Type
:Array.<Array.<PD.HUDItem>>

itemsByRegion

Stores all HUD items arranged by alignment areas.

This array is used to store each HUD item in the region to which it assigned or arranged to. You should not modify this array directly as it is automatically built and rebuilt by the update method.

     +------------+------------+------------+
     |  TOP_LEFT  |    TOP     |  TOP_RIGHT |
     |     1      |     2      |      3     |
     +------------+------------+------------+
     |    LEFT    |    NONE    |    RIGHT   |
     |     8      |     0      |      4     |
     +------------+------------+------------+
     |  BOT_LEFT  |   BOTTOM   |  BOT_RIGHT |
     |     7      |     6      |      5     |
     +------------+------------+------------+
Type
:number

rightOffset

An additional offset in pixels to allow for right-aligned floating offcanvas or panels in the UI.

Type
  • number
:object

sceneEditor

The scene editor that owns this controller.

This value is set automatically when the controller is created by its host scene editor. It is used to automatically update the HUD size when the canvas size changes and to add the indicator mesh to the HUD scene.

Type
  • object
:function|null

throttledUpdateIndicators

A debounced indicator line update callback.

This callback is used to throttle the updateIndicators() method so that it is only called periodically during interactive drag operations, updating every 50 milliseconds while it is being called.

Type
  • function | null
:object

width

The size of the X-axis of the HUD, in pixels.

This value tracks the host scene editor canvas size.

Type
  • object

Methods

addItem( [config])

Creates and adds a new item to the HUD controller.

You should use this method to create new HUD items and add them to the HUD controller rather than accessing the items array directly.

Parameters:
Name Type Argument Description
config object <optional>

An optional PD.HUDItem constructor configuration object.
Returns:

Returns the newly created HUD item or null if out of memory.

Type
PD.HUDItem | null

clear()

Removes all HUD items and clears the editor scene.

You should use this method to remove all HUD items from the HUD controller rather than accessing the items array directly.

Returns:

Returns this HUD controller to support method chaining.

Type
PD.HUDController

clearNewItemCache()

Call this method to cancel a loading process and clear the temporary item cache.

You can call this method to cancel and clear any cached items when a project is loaded for purposes other than display.

See the PD.HUDController#startNewItemCache method for more details.

Returns:

Returns this HUD controller to support method chaining.

Type
PD.HUDController

deferredUpdate(faster)

Schedules an update of all HUD items after a short delay.

This method is used to debounce calls to the update() method so that it is not called too frequently when the canvas size and/or camera view changes. By default it calls the debouncedUpdate() method which updates after 250 milliseconds. If the faster parameter is true, it calls a faster internal method instead which updates after only 50 milliseconds.

Parameters:
Name Type Description
faster boolean

When true, uses a shorter delay for the update (50ms).
Returns:

Returns this HUD controller to support method chaining.

Type
PD.HUDController

dispose()

Cleans up the sun-path and removes all event listeners.

NOTE: Only call this method when the sun-path is no longer needed and you wish to free all its resources.

findItemInCanvas(canvasX, canvasY)

Searches for an element at the given canvas position.

If found, the element is stored internally and, when required, you can used the PD.HUDController#selectLastItem method to actually select it.

Parameters:
Name Type Description
canvasX number

The X-axis pixel position of the event in the view canvas.
canvasY number

The Y-axis pixel position of the event in the view canvas.
Returns:

Returns true if an element associated with an item was found.

Type
boolean

removeItem(item)

Removes an item from the HUD controller.

You should use this method to remove HUD items from the HUD controller rather than accessing the items array directly.

Parameters:
Name Type Description
item PD.HUDItem

The HUD item to remove.
Returns:

Returns the newly created HUD item.

Type
boolean

selectLastItem()

Selects the recently found element associated with a selected item.

This method selects the last element found by the most recent call to the PD.HUDController#findElementAtCanvasPos method. It first checks for a valid element and then calls the PD.GlobalActions.selectElement method.

Returns:

Returns true if the found element was selected in the model.

Type
boolean

setRightOffset(offset)

Sets the right-hand side offset in pixels, and updates the display.

Adding a right-hand side offset allows the UI framework to display a temporary floating offcanvas or overlay panel, that may contain controls for editing the HUD, whilst still letting the user to see all HUD items.

Parameters:
Name Type Description
offset number

The right-hand side offset in pixels.
Returns:

Returns true if the offset was changed.

Type
boolean

startNewItemCache()

Starts the loading process for a new project.

This method is called automatically by the framework when a new project is loaded to prevent items from being added to the HUD controller until the loading is complete.

HUD items are typically created and added to the HUD controller when the mounted method of each new element is called. This method is called on each element in a project is it being built, which happens when a project is loaded from JSON. We need to facilitate the asynchronous loading of projects in the background, without having to first remove all the existing HUD items, which we want to continue being displayed until the new project is fully loaded and ready to be displayed.

Thus, the BIM.Project constructor calls this method, after which any new HUD items are temporarily cached in this array and only added to the HUD controller when the project is fully loaded and the PD.HUDController#useNewItemCache method is called.

If the project is being loaded for purposes other than display, you can call the PD.HUDController#clearNewItemCache method instead.

Returns:

Returns this HUD controller to support method chaining.

Type
PD.HUDController

update( [refresh])

Arranges all HUD items based on their alignment settings.

This method is called automatically by the framework when the host scene is resized, the view is changed, or when items are added and/or removed. It is typically called via the PD.HUDController#debouncedUpdate method to ensure that updates do not occur too frequently when the view is rotated or multiple items are added/removed by a script.

Parameters:
Name Type Argument Default Description
refresh boolean <optional>
 false

When true, requests a redraw of the scene editor after updating.
Returns:

Returns this HUD controller to support method chaining.

Type
PD.HUDController

updateIndicators( [refresh])

Updates the indicator mesh when items are rotated.

This method is called whenever the view changes to update the indicator lines that link to the 3D position of each HUD item.

Parameters:
Name Type Argument Default Description
refresh boolean <optional>
 false

When true, requests a redraw of the scene editor after updating.
Returns:

Returns this HUD controller to support method chaining.

Type
PD.HUDController

updatePositions()

Updates the positions of all HUD items if they are changing.

This method is called periodically by the host PD.SceneEditor to check if items need animating into a new position.

useNewItemCache()

Replaces the current HUD item list with any cached items recently loaded.

This method is called automatically by the framework when a new project is loaded and becomes the current project.

HUD items are typically created and added to the HUD controller when the mounted method of each new element is called. This method is called on each element in a project is it being built, which happens when a project is loaded from JSON. We need to facilitate the asynchronous loading of projects in the background, without having to first remove all the existing HUD items, which we want to continue being displayed until the new project is fully loaded and ready to be displayed.

Thus, the BIM.Project constructor calls the PD.HUDController#startNewItemCache method, after which any new HUD items are temporarily cached in this array and only added to the HUD controller when the project is fully loaded and this method is called.

If the project is being loaded for purposes other than display, you can call the PD.HUDController#clearNewItemCache method instead.

Returns:

Returns this HUD controller to support method chaining.

Type
PD.HUDController

checkToCreateDarkModeCallback() <static>

Checks to create a callback update the shared outline material for dark mode.