API Docs

Class: HUDItem

PD. HUDItem

A base class for defining items to show in the head-up display (HUD).

A HUD item is a 2D graphical object that can be positioned and overlaid in canvas coordinates (as opposed to model coordinates) on top of the 3D model. They can be used to show legends in a particular region of the canvas, or to track a 3D model position and display information about it in the HUD.

HUD items can be used to display any THREE.JS object, such as a chart, graph, text, icon, image or any other 2D graphical content that is needed to overlay on the 3D scene. Items can be moved, resized, aligned, rotated, hidden, shown, faded and animated into position.

new HUDItem(controller [, config])

Creates a new head-up display item to be managed by a controller.

Parameters:
Name Type Argument Description
controller PD.HUDController

The HUD controller that manages this item.
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
mesh THREE.Object3D <optional>

The THREE.JS renderable object representing this item.
width number <optional>

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

The size of the item in the Y-axis of the HUD, in pixels.
callbackOnSelected function <optional>

A function to call when the user selects the item in the canvas.
preferredAlignment PD.ALIGN <optional>

The preferred alignment of the item relative to the canvas extents.
centerOffset THREE.Vector2 <optional>

The center offset of the item relative to its bottom-left corner.
startXY THREE.Vector2 <optional>

An optional initial 2D canvas position of the item, defaults to the canvas center.
element BIM.Element <optional>

An optional BIM element associated with this HUD item, if any.
trackPos THREE.Vector3 <optional>

An optional 3D position that this item tracks within the model.
Author:
  • drajmarsh

Members

:PD.ALIGN

actualAlignment

The actual alignment determined by the host controller.

This value is automatically set by the HUD controller this item belongs to when the item is arranged. It is used to store the closest canvas edge to the model position when the preferredAlign is set to PD.ALIGN.NONE.

Type
:function

callbackOnSelected

A function to call when the user selects the item in the canvas.

The function is called with the HUD item as the only argument and should return true if the call was handled or false if rejected.

Type
  • function
:THREE.Vector3

canvasXYZ

The normalised canvas position of the 3D model position being tracked.

This stores the normalised canvas-space coordinates of the 3D model position being tracked. This means that it's X, Y and Z values are in the range of -1 to 1 rather than in pixels.

It is automatically computed by the HUD controller this item belongs to when the item is arranged. It is used to determine the closest canvas edge to the model position when the preferredAlign value is set to PD.ALIGN.NONE.

Type
  • THREE.Vector3
:THREE.Vector2

centerOffset

The center offset of the item relative to its bottom-left corner.

This value is used to offset the item from its target position when it is arranged by the controller it belongs to.

Type
  • THREE.Vector2
:object

controller

The HUD controller that manages this item.

Type
  • object
:BIM.Element|null

element

The BIM element associated with this HUD item, if any.

Type
:object

height

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

Type
  • object
:boolean

isHUDItem <readonly>

A flag identifying this object as a HUD item.

Type
  • boolean
:THREE.Object3D|PD.PolyMesh

mesh

A WebGL-renderable object representing this item.

Type
:PD.ALIGN

preferredAlignment

The preferred alignment of the item relative to the canvas extents.

When this value is set to PD.ALIGN.NONE, the item will automatically move to the nearest canvas edge to the model position based on the current view. You can lock an item in position by setting the preferred alignment to a specific canvas region such as PD.ALIGN.TOP_LEFT or PD.ALIGN.RIGHT.

Type
:THREE.Vector2

startXY

The 2D canvas position of the item at the start of a HUD animation.

This value is used to animate the item from its start position to its target position when the item is moved by the controller. You can set this value manually, however it is typically set automatically by the HUD controller this item belongs to during arrangement.

Type
  • THREE.Vector2
:THREE.Vector2

targetXY

The 2D canvas position the item should move to within a HUD animation.

When this position is different to the PD.HUDItem#start2 position, the item will automatically animate towards the new position.

You can set this value manually, however it is typically set automatically by the HUD controller this item belongs to during arrangement.

Type
  • THREE.Vector2
:THREE.Vector3|null

trackPos

An optional 3D model position that this item should track.

When a HUD item is tracking a 3D model position, an indicator line will automatically be drawn to join the item to the model position.

If the preferredAlign is set to PD.ALIGN.NONE, the item will automatically move to the nearest canvas edge to the model position based on the current view. You can lock an item in position by setting the preferred alignment to a specific canvas region such as PD.ALIGN.TOP_LEFT or PD.ALIGN.RIGHT.

Type
  • THREE.Vector3 | null
:object

width

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

Type
  • object

Methods

moveTo(pos [, immediate])

Moves the item to a new canvas position within the HUD.

This method is used by the HUD controller to set the target position of the item. If the distance from startXY position is more than 1.0 pixel, and the immediate value is not set to true, the item will animate smoothly to the new position.

Parameters:
Name Type Argument Default Description
pos THREE.Vector2

The new canvas position to move the item to.
immediate boolean <optional>
 false

Whether or not the item should jump immediately to its new position.
Returns:

Returns true if this item needs to move from its current position.

Type
boolean

needsUpdate()

Checks if this item is currently moving, or needs to move, towards its target position.

This method is used by the HUD controller to determine if the item needs to be updated and animated into position.

Returns:

Returns true if item needs to move towards its target position.

Type
boolean

updatePosition()

Updates the display position of this item if different from its target position.

This method is called by the HUD controller to update the display position of this item if it is moving towards its target position. It uses a cubic easing function to animate the item smoothly into position.

Returns:

Returns true if this item was moved or false if it has reached its final target position.

Type
boolean