API Docs

Class: SceneManager

PD. SceneManager

Creates an interactive WebGL view canvas and manages the rendered scene.

A scene manager is intended for use as the primary model editor at the forefront of the host application. It includes all the functionality of the PD.SceneEditor and PD.SceneViewer, but adds controllable skylight, sunlight, shadows and ambient occlusion, as well as more complex simulated skies.

Inheriting from the PD.SceneViewer class, this class handles the creation and initialisation of a THREE.js WebGL renderer, adding a render canvas to the container element in the host document, controlling render settings and resizing the canvas whenever its container element changes size. It creates and manages the current camera view as well as the lights that light the scene. Also, in order to dynamically optimise the front and rear clipping planes as the model is being edited, this class also manages model objects within the main scene.

Inheriting from the PD.SceneEditor class, this class also provides the infrastructure for interactively editing both 2D and 3D model geometry within a view canvas. It can be paired with a PD.SelectionManager to provide interactive selection and editing capabilities.

A scene manager creates, renders and manages three different scenes:

  • scene
    This is the main 3D scene that includes all model geometry and drawing elements, as well as any other geometry that uses the depth buffer for proper visual occlusion and hidden line rendering.

  • sceneOverlay
    This is a 3D scene that uses the same 3D projection as the main scene, but does not use the depth buffer or depth testing. This means that all geometry will be visible regardless of whether it is in front of or behind other geometry. This is exactly what is required for things like the 3D cursor (which still needs to be seen and selected no matter where it is), snap indicators (that may link to a wall at the back of the model) and dynamic dimension lines (that show the size of an element as you drag).

  • sceneHUD
    This is a flat 2D scene that serves as a head-up-display overlaid on top of all the other scenes. This is used to display dynamic graphical and textual information in the 2D screen-space as well as WebGL-based user interface elements such as popup buttons or option trees.

new SceneManager( [config])

Creates a new scene manager.

Parameters:
Name Type Argument Description
config object <optional>

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

The DOM element or id attribute of the host container, defaults to 'view-panel'.
renderer THREE.WebGLRenderer <optional>

The THREE WebGL renderer instance to use, creates a new WebGL renderer if not given.
renderTarget THREE.WebGLRenderer <optional>

An optional render target to render output to, defaults to the renderer's canvas.
canvas HTMLCanvasElement <optional>

An optional canvas DOM element to render to, defaults to the renderer's canvas.
camera THREE.Camera <optional>

An optional camera to view the scene when rendering to the canvas.
background THREE.Color | number <optional>

The background colour of the view canvas, defaults to global background color.
fog THREE.Fog | number <optional>

The background fog object or colour, defaults to global background color.
lights Array | THREE.Light <optional>

An optional light or array of lights to illuminate the scene.
objects Array | THREE.Object3D <optional>

An optional object or array of objects to render in the scene.
viewAxis PD.AXIS <optional>

The view axis to render the scene from, defaults to PD.AXIS.Z_POS.
showSky boolean <optional>

Whether to display a sky hemisphere within the canvas. defaults to false.
callbackOnDragSelect function <optional>

An optional callback for handling interactive region-based selection events.
callbackOnClickSelect function <optional>

An optional callback for handling interactive click-based selection events.
callbackOnPreSelect function <optional>

An optional callback for handling interactive pre-selection events.
callbackOnPreSelectClear function <optional>

An optional callback for handling the clearing of pre-selection events.
callbackOnContextMenu function <optional>

An optional callback for handling long-press/right-click pointer events.
callbackOnDblClick function <optional>

An optional callback for handling double-click pointer events.
Author:
  • drajmarsh

Extends

Members

:Array.<THREE.AnimationMixer>

animations

An array of animations mixers, if any are present.

Type
  • Array.<THREE.AnimationMixer>
Inherited From:
Overrides:
:THREE.Box3

boundingBox

Stores the bounding box of all objects in the main scene.

Type
  • THREE.Box3
Inherited From:
Overrides:
:THREE.Sphere

boundingSphere

Stores the bounding sphere of all objects in the main scene.

Type
  • THREE.Sphere
Inherited From:
Overrides:
:function|null

callbackOnClickSelect

A callback for handling interactive click-based selection events.

This callback function takes as arguments a THREE.RayCaster with the selection ray already set up and the event that triggered the callback.

It should return a boolean that is true if something changed and the view needs updating, otherwise false.

Type
  • function | null
Inherited From:
Overrides:
:function|null

callbackOnContextMenu

A callback for handling long-press/right-click pointer events.

This callback function takes as arguments the event that triggered the callback.

Type
  • function | null
Inherited From:
Overrides:
:function|null

callbackOnDblClick

A callback for handling double-click pointer events.

This callback function takes as arguments the event that triggered the callback.

Type
  • function | null
Inherited From:
Overrides:
:function|null

callbackOnDragSelect

A callback for handling interactive region-based selection events.

This is invoked when the user drags a rectangular region of the canvas.

This callback function takes as arguments the selection frustum and the event that triggered the callback.

It should return a boolean that is true if something was selected and the view needs updating, otherwise false.

Type
  • function | null
Inherited From:
Overrides:
:function|null

callbackOnPreSelect

A callback for handling interactive pre-selection events.

When working with touch or pen-based interaction, we can't just use a pointer button index to work out whether the user wanted to select something or start dragging the view around. Thus, we need to wait until the user either releases the pointer without dragging or actually starts dragging.

To provide some visual feedback to the user, the initial press can display some type of transient visual indicator of what would be selected if the pointer was immediately released, giving the user an option to drag the pointer to cancel that selection if it is not what was desired.

This callback allows the host application to display something like a ghost image of the potential selection while the press is active and before a drag is made.

This callback function takes as arguments a THREE.RayCaster with the selection ray already set up and the event that triggered the callback.

It should return a boolean that is true if something changed and the view needs updating, otherwise false.

Type
  • function | null
Inherited From:
Overrides:
:function|null

callbackOnPreSelectClear

A callback for handling the clearing of pre-selection events.

This is invoked after a pre-selection has been displayed, but the user then drags the pointer beyond the threshold to change the view instead. This callback should clear any pre-selection information and or simply hide the mesh.

This callback function takes as an argument the event that triggered the callback.

It should return a boolean that is true if something changed and the view needs updating, otherwise false.

Type
  • function | null
Inherited From:
Overrides:
:THREE.Camera

camera

The camera that generates perspective and orthographic views of the model.

Type
  • THREE.Camera
Inherited From:
Overrides:
:THREE.OrthographicCamera

cameraHUD

A camera for the head-up display (HUD) scene.

Type
  • THREE.OrthographicCamera
Inherited From:
Overrides:
:HTMLCanvasElement

canvas

Stores the HTML5 canvas element the WebGL view is rendered to.

Type
  • HTMLCanvasElement
Inherited From:
Overrides:
:number

canvasHeight

The height of the display canvas in pixels, modified to fit within the container element.

This value is typically slightly smaller than the container in order to accommodate its border.

Type
  • number
Inherited From:
Overrides:
:THREE.Vector3

canvasPos

The canvas pixel position used by the computeCanvasCoordinates() and computePageCoordinates() methods.

Type
  • THREE.Vector3
Inherited From:
Overrides:
:THREE.Vector2

canvasPosOnClick

The canvas pixel position of the last pointer down.

Type
  • THREE.Vector2
Inherited From:
Overrides:
:THREE.Vector2

canvasPosOnDrag

The canvas pixel position of the current drag event.

Type
  • THREE.Vector2
Inherited From:
Overrides:
:number

canvasWidth

The width of the display canvas in pixels, modified to fit within the container element.

This value is typically slightly smaller than the container in order to accommodate its border.

Type
  • number
Inherited From:
Overrides:
:THREE.Clock

clock

A clock for tracking animation time.

Type
  • THREE.Clock
Inherited From:
Overrides:
:THREE_ADDONS.EffectComposer

composer

Compose model view postprocessing passes.

Type
  • THREE_ADDONS.EffectComposer
:Element

container

The HTML element that hosts the view canvas.

Type
  • Element
Inherited From:
Overrides:
:DOMRect

containerRect

The top, left, width and height of the container element.

This is updated whenever the container/canvas size changes and is used to compute normalised canvas coordinates from pointer positions as well as converting canvas to page coordinates.

Type
  • DOMRect
Inherited From:
Overrides:
:PD.Cursor|null

cursor

A cursor for interactively manipulating objects.

Type
Inherited From:
Overrides:
:number

frameCount

Counts the number of rendered frames.

Type
  • number
Inherited From:
Overrides:
:THREE.Frustum

frustum

The current view frustum.

This is used to determine if points or parts of the model can be seen within the current camera view.

Type
Inherited From:
Overrides:
:PD.GridMesh|null

grid

A floor/ground grid for indicating the working plane.

Type
Inherited From:
Overrides:
:THREE_ADDONS.GTAOPass

gtaoPass

The ground truth ambient occlusion shader.

Type
  • THREE_ADDONS.GTAOPass
:THREE.Vector2

hoverPos

The current pointer hover position.

This is used mainly by scene editors to track the pointer as it hovers over cursors or hotspots in the model. However, it is also used by scene viewers when zooming to the pointer position.

Type
  • THREE.Vector2
Inherited From:
Overrides:
:PD.HUDController|null

hudController

A controller for managing and arranging HUD items.

Type
Inherited From:
Overrides:
:number

intensityModifier

A modifier used to scale skylight and sunlight intensity.

This is used to adjust the lighting in the scene based on the global view settings.

Type
  • number
:boolean

isPlanView

Stores whether or not the current view axis is +Z.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isSceneEditor <readonly>

A flag identifying this object as a scene editor.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isSceneManager <readonly>

A flag identifying this object as a scene manager.

Type
  • boolean
:boolean

isSceneViewer <readonly>

A flag identifying this object as a scene viewer.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isViewAxiallyAligned

Stores whether or not the current view axis is aligned with one of the cartesian axis.

When an orthogonal view is aligned with an axis, it is considered to be an elevation or plan view, in which interactive rotation is replaced by interactive pan. As a result, this value is used a lot by the PD.SceneViewer#viewController.

Type
  • boolean
Inherited From:
Overrides:
:Array

lights

An array of lights to illuminate the scene.

Type
  • Array
Inherited From:
Overrides:
:boolean

logCanvasSize

A flag to allow the scene to log its canvas size to the browser console.

This is used mainly for ensuring the canvas is the right size for video capture.

Type
  • boolean
Inherited From:
Overrides:
:string

name

The human-readable name for this view panel.

Type
  • string
Inherited From:
Overrides:
:THREE.Vector2

normalisedCanvasCoords

The normalised canvas coordinates of the last pointer down.

Type
  • THREE.Vector2
Inherited From:
Overrides:
:Array

objects

An array of 3D objects to display in the scene.

Type
  • Array
Inherited From:
Overrides:
:THREE_ADDONS.OutlinePass

outlinePass

Generate outlines of selected elements.

Type
  • THREE_ADDONS.OutlinePass
:THREE.Raycaster

rayCaster

The ray casting object used for interactive selection.

Type
  • THREE.Raycaster
Inherited From:
Overrides:
:THREE.WebGLRenderTarget

renderTarget

Stores the render target to use.

If a render target is given, the renderer will render to this target rather than directly to the canvas.

Type
  • THREE.WebGLRenderTarget
Inherited From:
Overrides:
:THREE.WebGLRenderer

renderer

The WebGL renderer for displaying the scene.

Type
  • THREE.WebGLRenderer
Inherited From:
Overrides:
:THREE.Scene

scene

The scene that is viewed by the camera and displayed in the view canvas.

This is the main scene and where model meshes and lights are added. It is also the scene used to generate shadows.

Type
  • THREE.Scene
Inherited From:
Overrides:
:THREE.Scene

sceneHUD

The scene that contains 2D head-up display (HUD) information.

This scene is where 2D graphical information such as charts, graphs and indicators are added.

Type
  • THREE.Scene
Inherited From:
Overrides:
:THREE.Scene

sceneOverlay

The scene that contains 3D overlay information.

This scene is where model-based overlay information such as selection, cursor and dimension meshes are added.

Type
  • THREE.Scene
Inherited From:
Overrides:
:THREE.Mesh|null

sky

Store a simple gradient sky.

Type
  • THREE.Mesh | null
Inherited From:
Overrides:
:THREE.AmbientLight

skyLight

An ambient light level used to simulate diffuse sky conditions.

Type
  • THREE.AmbientLight
:THREE_ADDONS.SSAOPass

ssaoPass

The screen-space ambient occlusion shader.

Type
  • THREE_ADDONS.SSAOPass
:THREE.DirectionalLight

sunLight

The directional light used to simulate direct sunlight.

Type
  • THREE.DirectionalLight
:PD.ViewOrbital

view

The current camera view of the model.

Type
Inherited From:
Overrides:
:PD.AXIS

viewAxis

The view axis the scene is being rendered from.

Type
Inherited From:
Overrides:
:PD.ViewController

viewController

The camera view controller for interacting with the view.

Type
Inherited From:
Overrides:
:number

shadowBias <static>

The shadow bias to apply to the directional light to help with shadow artifacts, defaults to -0.0001.

Type
  • number
:number

shadowMapSize <static>

The default size of the shadow map texture, defaults to 2048.

Type
  • number

Methods

_fakePointerArrowVisible(state)

Show or hide the fake pointer arrow when the mouse/pointer enters or leaves the canvas.

Parameters:
Name Type Description
state boolean

The visibility state.

addAnimation(animation)

Adds one or more animations to the scene.

Parameters:
Name Type Description
animation THREE.AnimationMixer | Array

The new animation or array of animations to add to the scene.
Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

addEventListener(type, listener)

Adds or replaces a listener function.

This method returns the listener function which allows a caller to use an unnamed or arrow function defined within the call and still store it for later removal.

Parameters:
Name Type Description
type string

The type of event to listen to.
listener function

The function that gets called when the event is fired.
Inherited From:
Overrides:
Returns:

Returns the listener function so it can be stored for later removal.

Type
function
Example
let event_listener;

onMounted() {
    event_listener = PD.GlobalEvents.addEventListener(PD.EVENT.SITE_LOCATION, (location) => {
        this.doSomethingWithTheLocation(location);
    });
};

onUnmounted() {
    if (event_listener) {
        PD.GlobalEvents.removeEventListener(PD.EVENT.SITE_LOCATION, event_listener);
        event_listener = null;
    }
};

addLight(light)

Adds one or more lights to the scene.

Parameters:
Name Type Description
light THREE.Light | Array

The new light or array of lights to add to the scene.
Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

addObject(object)

Adds one or more geometry objects to the scene.

Parameters:
Name Type Description
object THREE.Object3D | Array

The new object or array of objects to add to the scene.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

checkPixelRatio()

Checks for any changes in the maximum allowable device pixel ratio and updates.

Inherited From:
Overrides:
Returns:

Returns true if the pixel ratio changed, otherwise false.

Type
boolean

checkToUpdateShadowMap(extents)

Check to fit the near and far frustum clipping planes to given point.

Parameters:
Name Type Description
extents THREE.Box3 | boolean

The bounding box of an element to check, or true to update floor grid.
Returns:

Returns this manager to support method chaining.

Type
PD.SceneManager

clearAnimations()

Removes all animations from the scene.

Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

clearHUD()

Clears all items from the HUD and HUD controller.

Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

clearLights()

Removes all lights from the scene.

Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

clearObjects()

Removes all geometry objects from the scene.

Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

computeBoundingBox( [action])

Computes the bounding box of the currently displayed model.

NOTE: If you have manually set the scene bounding box, you can give an action value of less than zero to update the view and scene size using the existing boundingBox.

Parameters:
Name Type Argument Description
action number <optional>

An optional fit action (0:CHECK, 1:EXTENTS, 2:VIEW), defaults to 0.
Inherited From:
Overrides:
Returns:

Returns this scene manager to support method chaining.

Type
PD.SceneManager

computeCanvasCoordinates(model_pos [, canvas_pos])

Computes the canvas position of the 3D point, in pixels.

The resulting point is given in canvas coordinates, relative to the top-left corner of the 3D model drawing canvas. If you want actual page coordinates, use the computePageCoordinates() instead.

If only a single argument is given, this method returns the canvasPos property of the scene manager set to the new position.

Parameters:
Name Type Argument Description
model_pos THREE.Vector3

The 3D model-space position.
canvas_pos THREE.Vector3 <optional>

An optional vector to receive the screen-space position.
Inherited From:
Overrides:
Returns:

Returns the given canvas position, or a shared vector.

Type
THREE.Vector3

computePageCoordinates(model_pos [, page_pos])

Computes the page position of the 3D point, in pixels.

The resulting point is given in page coordinates, relative to the top-left corner of the web page content area. If you want actual canvas coordinates, use the computeCanvasCoordinates() instead.

If only a single argument is given, this method returns the canvasPos property of the scene manager set to the new position.

Parameters:
Name Type Argument Description
model_pos THREE.Vector3

The 3D model-space position.
page_pos THREE.Vector3 <optional>

An optional vector to receive the screen-space position.
Inherited From:
Overrides:
Returns:

Returns the given canvas position, or a shared vector.

Type
THREE.Vector3

computeScreenSpaceScale(pos)

Computes the multiplier required to maintain the same screen-space size.

if PD.GlobalState.cursorDynamicResize is true, this method calculates the distance from the point to the camera and returns the scale factor required to ensure something at that point remains roughly the same size in screen coordinates. If not set, a one-to-one scale is returned.

This is primarily used by the PD.Cursor and PD.Dimensions classes to dynamically resize their arrows and text when the view is zoomed.

Parameters:
Name Type Description
pos THREE.Vector3

A point in model space.
Inherited From:
Overrides:
Returns:

Returns the screen-space scaling.

Type
number

computeSelectionFrustum(coord1, coord2)

Computes a selection frustum from the given canvas points.

A selection frustum is typically based on a rectangular sub-region of the model canvas that the user has dragged or which has been set programmatically. The six (6) planes of the frustum are computed in the order 0:Right, 1:Left, 2:Bottom, 3:Top, 4:Far and 5:Near.

Parameters:
Name Type Description
coord1 THREE.Vector2

The first canvas point in pixels.
coord2 THREE.Vector2

The second canvas point in pixels.
Inherited From:
Overrides:
Returns:

Returns the computed frustum.

Type
THREE.Frustum

computeViewAxis()

Calculates the view axis from current view angles.

Inherited From:
Overrides:
Returns:

Returns the computed axis.

Type
PD.AXIS

computeWorldCoordinates(canvas_pos, model_pos [, depth])

Computes a 3D world-space position given a 2D canvas coordinate in pixels.

The canvas position must ve given in canvas coordinates, relative to the top-left corner of the 3D model drawing canvas. If using a pointer event position, you may have to subtract the PD.SceneViewer#containerRect left and top offsets from the clientX and clientY event properties.

Parameters:
Name Type Argument Default Description
canvas_pos THREE.Vector2

A 2D vector defining the canvas position in pixels.
model_pos THREE.Vector3

The vector to receive 3D model-space position.
depth number <optional>
 0.5

An optional fractional depth value (0 to 1), defaults to 0.5.
Inherited From:
Overrides:
Returns:

Returns the given model_pos set to model-space position.

Type
THREE.Vector3

dispatch(type, args)

Invokes all the listeners for the given event type with the given arguments.

NOTE: This method is different to the standard dispatchEvent() method on THREE.EventDispatcher that you may be used to. The THREE.js method requires a bespoke event object with the event arguments as properties of that object. It also modifies that object by adding an additional target property prior to sending, and creates a copy of the listener array on every call.

In our case, events may be generated many times a second as the view, location and/or sun-position are changed dynamically. The listener methods are all called in a tight loop and, given the nature of framework events, they do not remove themselves when called, so changes to the listener array during iteration are unlikely enough for the risk to be tolerable. Also, the dispatching object is typically static and globally available, so there is no need to send a reference to each listener. Whilst having to create a transitory event object, modify it and then copy the array may be a relatively small overhead, it is still an unnecessary one.

As a result, this method simply passes on the given event arguments to each listener without requiring a custom object, modifying it or copying the listener array each time.

Parameters:
Name Type Argument Description
type string

The event type identifier.
args any <repeatable>

The additional arguments that correspond to the given event type.
Inherited From:
Overrides:
Returns:

Returns true if at least one event listener was invoked, otherwise false.

Type
boolean

dispatchCanvasResizeEvent()

Notifies any listeners of a CANVAS_SIZE event.

This method is called automatically by the resize() method. It is provided as a public method for direct use by subclasses that use their own custom resize logic/methods.

Inherited From:
Overrides:

dispose()

Cleans up the scene viewer and removes all event listeners.

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

Inherited From:
Overrides:

ensurePointIsWithinView(point)

Checks whether or not the given point is within the view frustum and, if not, moves the point to the center of the current view.

Parameters:
Name Type Description
point THREE.Vector3

The point to check and move.
Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

fitFrustumToExtents(extents [, forceUpdate])

Check if the bounding box is within the view extents and expands it if required.

Parameters:
Name Type Argument Default Description
extents THREE.Box3

The bounding box to check.
forceUpdate boolean <optional>
 false

When true, the bounding box will update to the given extents, defaults to false.
Returns:

Returns this scene manager to support method chaining.

Type
PD.SceneViewer

fitFrustumToPoint(point [, tolerance])

Check to extend the near and far frustum clipping planes to given point.

Parameters:
Name Type Argument Default Description
point THREE.Vector3

The point to check near and far distance.
tolerance number <optional>
 1

An optional tolerance around the point.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

fitGridToModel( [padding])

Resizes the background grid to fit the extents of the current model.

Parameters:
Name Type Argument Description
padding number <optional>

The padding around the model extents, defaults to PD.GlobalState.floorGridPadding multiplied by PD.GlobalState.gridCellMajor.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

fitViewToModel( [instant])

Animates the current view so that it fits to the visible model.

Parameters:
Name Type Argument Description
instant boolean <optional>

An optional flag to force an instant update rather than an animated transition.
Inherited From:
Overrides:

generateSky()

Generates a realistic spherical sky mesh with dynamic clouds.

Inherited From:
Overrides:
Returns:

Return a mesh that is added to the scene.

Type
THREE.Mesh

getClosestViewAxis()

Determine the closest cartesian axis to the current view vector.

This uses the current vector between target to camera to determine which is the closest cartesian axis.

Inherited From:
Overrides:
Returns:

Returns the closest artesian axis to the view.

Type
PD.AXIS

getDefaultSkyColor()

Retrieve the current default sky color.

This can be used by subclasses to access the default sky color object that is shared by all scenes.

Inherited From:
Overrides:
Returns:

Returns the default sky color.

Type
THREE.Color

getGridExtents()

Retrieve the bounding box of the floor/shadow grid.

Inherited From:
Overrides:
Returns:

Returns the bounding box.

Type
THREE.Box3 | null

getModelDashSize()

Retrieve the dynamic virtual dashed line size, relative to the model.

Inherited From:
Overrides:
Returns:

Returns the relative size of a dash lines, in model units.

Type
number

getPointSizeModel()

Retrieve the dynamic virtual point size, relative to the model.

This value is based on the current model size and is not affected by view zoom.

Inherited From:
Overrides:
Returns:

Returns the relative size of a model point, in model units.

Type
number

getPointSizeView()

Retrieve the dynamic virtual point size, relative to the model view.

This value is used to dynamically resize things like 3D cursors and dimension text when the view zooms in and out.

Inherited From:
Overrides:
Returns:

Returns the current zoom-moderated relative point size, in model units.

Type
number

getSkyShader(uniforms)

Generates a sky shader based on PD.GlobalView.skyShaderType.

Parameters:
Name Type Description
uniforms object

A data object containing uniform values.
Inherited From:
Overrides:
Returns:

Return a shader material.

Type
THREE.ShaderMaterial

getSkyShaderRealistic(uniforms)

Generates a more physically accurate sky shader with dynamic clouds.

See the PD.SKYDOME.REALISTIC_SHADER class for more details.

Parameters:
Name Type Description
uniforms object

A data object containing uniform values.
Returns:

Return a shader material.

Type
THREE.ShaderMaterial

getUpdatedViewFrustum()

Updates and returns the current view frustum.

Inherited From:
Overrides:
Returns:

Returns the updated view frustum.

Type
THREE.Frustum

handleClickSelection(canvasPos, event)

Uses ray casting to determine if the user has selected anything.

This function automatically renders the view to show the selection if it changes.

Parameters:
Name Type Description
canvasPos THREE.Vector2

The X and Y position of the pointer relative to the WebGL canvas.
event object

The event that triggered this handler.
Inherited From:
Overrides:
Returns:

Returns true if a selection was found.

Type
boolean

handleCursorDrag(canvasPos, event)

Updates the cursor when it is selected and dragged.

Parameters:
Name Type Description
canvasPos THREE.Vector2

The X and Y position of the pointer relative to the WebGL canvas.
event object

The event that triggered this handler.
Inherited From:
Overrides:
Returns:

Returns true if cursor was dragged.

Type
boolean

handleCursorDragEnd(event)

Updates the cursor when the pointer is released after a drag.

Parameters:
Name Type Description
event object

The event that triggered this handler.
Inherited From:
Overrides:
Returns:

Returns true if cursor was updated.

Type
boolean

handleCursorRelease()

Clears any cursor selection when the pointer is released.

Inherited From:
Overrides:

handleDragSelection(canvasPos, event)

Updates the selection region when the pointer is dragged.

Parameters:
Name Type Description
canvasPos THREE.Vector2

The X and Y position of the pointer relative to the WebGL canvas.
event object

The event that triggered this handler.
Inherited From:
Overrides:
Returns:

Returns true if the region was dragged.

Type
boolean

handleDragSelectionEnd(event)

Updates the selection region when the pointer is released after a drag.

This method removes the selection region from the canvas, computes the selection frustum and then calls the callbackOnDragSelect() method if it is set.

Parameters:
Name Type Description
event object

The event that triggered this handler.
Inherited From:
Overrides:
Returns:

Returns true if cursor was updated.

Type
boolean

handlePreSelection(canvasPos, event)

Use ray casting to check if the user has clicked/pressed on a selectable object.

The aim of preselection is to render a transient visual indictor of what will be selected if the user releases the pointer without dragging. If the user then drags beyond a threshold amount, the handlePreSelectionClear() method will be called to clear the visual indication. If the user releases without dragging, the handleClickSelection() method will be called, which should also clear any pre-selection.

This function automatically renders the view to if a pre-selection was found.

Parameters:
Name Type Description
canvasPos THREE.Vector2

The X and Y position of the pointer relative to the WebGL canvas.
event object

The event that triggered this handler.
Inherited From:
Overrides:
Returns:

Returns true if a pre-selection was found.

Type
boolean

handlePreSelectionClear(event)

This called when a pointer is dragged after a successful pre-selection event.

This function automatically renders the view if pre-selection changes.

Parameters:
Name Type Description
event object

The event that triggered this handler.
Inherited From:
Overrides:
Returns:

Returns true if pre-selection was active and cleared.

Type
boolean

handleResize()

Handles window and container size changes.

Inherited From:
Overrides:

hasAnimation(animation)

Checks if the given animation mixer is already present in the scene.

Parameters:
Name Type Description
animation THREE.AnimationMixer

The animation mixer to check.
Inherited From:
Overrides:
Returns:

Returns true if the mixer is already present, otherwise false.

Type
boolean

hasEventListener(type, listener)

Determines if the given listener function is associated with the given event type.

Parameters:
Name Type Description
type string

The type of event to listen to.
listener function

The function that gets called when the event is fired.
Inherited From:
Overrides:
Returns:

Returns true if the listener function exists.

Type
boolean

hasEventListeners(type)

Determines if an event has any registered listeners.

Parameters:
Name Type Description
type string

The type of event to check.
Inherited From:
Overrides:
Returns:

Returns true if there is more than one listener for the given event.

Type
boolean

initialiseLights( [lights])

Sets up an initial lighting configuration.

Parameters:
Name Type Argument Description
lights Array <optional>

An optional list of lights to add.
Inherited From:
Overrides:

initialiseObjects(objects)

Add any THREE objects to the scene.

Parameters:
Name Type Description
objects THREE.Object3D | Array

A list of objects to add.
Inherited From:
Overrides:

moveBy(vector, amount)

Pan or dolly the view by moving the camera.

Parameters:
Name Type Description
vector THREE.Vector3

The vector direction to move in.
amount number

The amount to move in the vector direction.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

processPointerDown(primary, canvasX, canvasY, event)

Acts on pointer button press/touch events within the canvas.

Parameters:
Name Type Description
primary boolean

Whether or not the primary button was pressed.
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.
event object

The HTML/Custom event that invoked this action.
Inherited From:
Overrides:

processPointerMove(canvasX, canvasY, event)

Acts on pointer move/drag events when pressed within the canvas.

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.
event object

The HTML/Custom event that invoked this action.
Inherited From:
Overrides:

processPointerUp(primary, event)

Acts on pointer release events within the canvas.

Parameters:
Name Type Description
primary boolean

Whether or not the primary button was released.
event object

The HTML/Custom event that invoked this action.
Inherited From:
Overrides:

removeAnimation(animation, action, clip)

Removes one or more existing animations from the scene.

Parameters:
Name Type Description
animation THREE.AnimationMixer

The existing animation or array of animations to delete from the scene.
action THREE.AnimationAction

The existing animation action to delete from the scene.
clip THREE.AnimationClip

The existing animation clip to delete from the scene.
Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

removeEventListener(type, listener)

Removes the given listener function from the given event type.

Parameters:
Name Type Description
type string

The type of event to listen to.
listener function

The function that gets called when the event is fired.
Inherited From:
Overrides:
Returns:

Returns true if the listener function was found and removed.

Type
boolean

removeLight(light)

Removes one or more existing lights from the scene.

Parameters:
Name Type Description
light THREE.Light | Array

The existing light or array of lights to delete from the scene.
Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

removeObject(object)

Removes one or more existing geometry objects from the scene.

Parameters:
Name Type Description
object THREE.Object3D | Array

The existing object or array of objects to delete from the scene.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

rotateBy(azi, alt)

Rotates the current view by the given poler increments.

Parameters:
Name Type Description
azi number

The azimuth angle increment, in degrees.
alt number

The altitude angle increment, in degrees.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

setAndSelectCursor(pos)

Positions the cursor at the given point and selects it ready for dragging.

Parameters:
Name Type Description
pos THREE.Vector3

The new position of the cursor in model coordinates.
Inherited From:
Overrides:
Returns:

Returns true if the cursor was set and selected.

Type
boolean

setBaseLevel(height)

Sets the base level height for the scene.

Parameters:
Name Type Description
height number

The new base height height to animate to.

setCameraFOV(fov [, immediate])

Sets the field of view of the camera.

Parameters:
Name Type Argument Default Description
fov number

The new camera field of view, in decimal degrees (0.1 to 160).
immediate boolean <optional>
 false

Whether or not to apply immediately rather than transition, defaults to false.
Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

setCameraView(axis, dx, dy, dz)

Sets the new view direction of the camera.

Parameters:
Name Type Description
axis PD.AXIS

The camera view axis to use.
dx number | THREE.Vector3

The new X component of the view, or a vector.
dy number

The new Y component of the view vector.
dz number

The new Z component of the view vector.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

setCursor(new_cursor [, visible])

Set a new cursor within the scene.

Parameters:
Name Type Argument Description
new_cursor PD.Cursor

The new 3D cursor to set in the scene.
visible boolean <optional>

Whether or not to show the new 3D cursor.
Inherited From:
Overrides:
Returns:

Returns this scene editor to support method chaining.

Type
PD.SceneManager

setOrbitLocus( [vec])

Sets the position of the orbit center if different to view target.

Parameters:
Name Type Argument Description
vec THREE.Vector3 | null <optional>

The new centre position of view orbits.
Inherited From:
Overrides:

setRayCaster(canvas_pos)

Updates the internal raycaster based on the given 2D canvas coordinates.

This method computes a ray from the current camera position into the current scene based on the 2D screen-space coordinates. This is typically used by scene editors for interactive selection of elements in the model, but also by scene viewers when zooming to pointer position.

Parameters:
Name Type Description
canvas_pos THREE.Vector2

The X and Y position of the pointer relative to the WebGL canvas.
Inherited From:
Overrides:
Returns:

Returns the shared raycaster set to the given canvas coordinates.

Type
THREE.Raycaster

setVectorToCamera( [instant])

Sets the new view direction of the camera.

Parameters:
Name Type Argument Description
instant boolean <optional>

An optional flag to force an instant update.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

showCursor(state)

Toggles the display of the 3D cursor, if assigned.

Parameters:
Name Type Description
state boolean

Whether or not to show the current 3D cursor.
Inherited From:
Overrides:
Returns:

Returns this scene editor to support method chaining.

Type
PD.SceneManager

showShadowPlane(state)

Show/hide a shadow plane at ground level in the model.

Parameters:
Name Type Description
state boolean

Whether or not to show shadows.
Returns:

Returns this scene manager to support method chaining.

Type
PD.SceneManager

showShadows(state)

Show/hide the display of shadows within the model.

Parameters:
Name Type Description
state boolean

Whether or not to show shadows.
Returns:

Returns this scene manager to support method chaining.

Type
PD.SceneManager

showSky(state)

Toggles the display of the background sky.

If state is true and there is no previous sky, a new sky will be created.

Parameters:
Name Type Description
state boolean

Whether or not to show the sky.
Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneManager

simulatePointerArrow( [state])

Shows or hides simulated pointer arrow in the scene.

When displayed, the simulated pointer arrow is shown instead of the system pointer so that it can be recorded along with the canvas. It tracks the system pointer and will show small animations on pointer down and up.

To redisplay the system pointer, set the state to false.

Parameters:
Name Type Argument Description
state boolean <optional>

Whether or not to use the simulated pointer arrow.
Returns:

Returns this scene editor to support method chaining.

Type
PD.SceneManager

simulatePointerDown(canvasX, canvasY [, button] [, options])

Simulates a mousedown event and propagates it through the model.

This method must be called as part of a sequence that begins with simulatePointerDown(), followed by any number of simulatePointerDrag() calls, then concluding with a simulatePointerUp() call.

For every call to simulatePointerDown() there must be a corresponding call to simulatePointerUp().

Parameters:
Name Type Argument Default 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.
button button <optional>
 0

The mouse button pressed (0:Left/Primary, 1:Middle, 2:Right), defaults to 0.
options object <optional>

Any additional options to add to the event, based on Event.
Inherited From:
Overrides:

simulatePointerDrag(canvasX, canvasY [, event])

Simulates a mousemove event with button pressed and propagates it through the model.

This method must be called as part of a sequence that begins with simulatePointerDown(), followed by any number of simulatePointerDrag() calls before concluding with a simulatePointerUp() call.

Parameters:
Name Type Argument 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.
event object <optional>

Any additional options to add to the event, based on Event.
Inherited From:
Overrides:

simulatePointerEvent(type, canvasX, canvasY [, button] [, event])

Initialises a shared mouse event object.

Parameters:
Name Type Argument Default Description
type string

The type of mouse event ('mousedown', 'mousemove', or 'mouseup').
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.
button button <optional>
 0

The mouse button pressed (0:Left/Primary, 1:Middle, 2:Right), defaults to 0.
event object <optional>

Any additional options to add to the event, based on Event.
Properties of event:
Name Type Argument Description
shiftKey boolean <optional>

Whether or not the Shift key is pressed.
ctrlKey boolean <optional>

Whether or not the Control key is pressed.
metaKey boolean <optional>

Whether or not the Meta key is pressed.
altKey boolean <optional>

Whether or not the Alt key is pressed.
Inherited From:
Overrides:
Returns:

Returns a shared event object for model propagation.

Type
boolean

simulatePointerUp( [options])

Simulates a mouseup event and propagates it through the model.

This method must be called as part of a sequence that begins with simulatePointerDown(), followed by any number of simulatePointerDrag() calls, then concluding with a simulatePointerUp() call.

For every call to simulatePointerDown() there must be a corresponding call to simulatePointerUp().

Parameters:
Name Type Argument Description
options object <optional>

Any additional options to add to the event, based on Event.
Inherited From:
Overrides:

snapshot(callback)

Creates a snapshot image of the current canvas and passes it to a callback function.

The image will be passed back as a binary large object block (blob) formatted as a PNG encoded image with the same resolution as the current canvas. If the image cannot be created for some reason, a null value may be passed back.

Parameters:
Name Type Description
callback function

A callback function with the resulting Blob object as a single argument.
Inherited From:
Overrides:

startTransition( [instant])

Initiates an animated transition when the current view has changed.

Parameters:
Name Type Argument Description
instant boolean <optional>

An optional flag to force an instant update.
Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

update()

Requests that the view be re-rendered as soon as practical.

Scene viewers start an animation loop that checks 60 times a second for changes to the view controller and head-up display manager, as well as a flag that indicates that the scene needs to be re-rendered. This method simply sets that flag and returns. This allows multiple events and/or actions to call this update method as often as required without rendering the scene every time, but will still be fast enough for most animations and updates to feel fully responsive.

Inherited From:
Overrides:
Returns:

Returns this scene viewer to support method chaining.

Type
PD.SceneViewer

updateCameraPosition( [model_radius])

Updates the position of the camera based on field of view.

Parameters:
Name Type Argument Description
model_radius number <optional>

The radius of the current view sphere.
Inherited From:
Overrides:

updateCursor()

Redraws the 3D cursor, if assigned and visible.

Inherited From:
Overrides:
Returns:

Returns this scene editor to support method chaining.

Type
PD.SceneManager

updateCursorSize()

Update 3D cursor size after a global state change, if assigned and visible.

Inherited From:
Overrides:
Returns:

Returns this scene editor to support method chaining.

Type
PD.SceneManager

updateExtents( [action] [, instant])

Check extents of the scene to fit the camera.

NOTE: If you have manually set the scene bounding box, you can give an action value of less than zero to update the view and scene size using the existing boundingBox.

Parameters:
Name Type Argument Description
action PD.FIT <optional>

An optional fit action (0:CHECK, 1:EXTENTS, 2:VIEW), defaults to 0.
instant boolean <optional>

An optional flag to force an instant update rather than an animated transition, defaults to false.
Inherited From:
Overrides:
Returns:

Returns this scene manager to support method chaining.

Type
PD.SceneManager

updateExtentsAfterDrag()

Updates the scene after an interactive drag event.

updateFrustumRange( [extents])

Update the near and far frustum clipping planes to include the model bounding box and, if displayed, any projected shadows.

This method needs to be called whenever the camera position, model bounding box or sunlight direction vector changes. If shadows are displayed, if also updates the size of the shadow projection plane to ensure that it fits all shadows.

Parameters:
Name Type Argument Description
extents THREE.Box3 <optional>

An optional set of extents to check.
Inherited From:
Overrides:
Returns:

Returns this scene manager to support method chaining.

Type
PD.SceneManager

updatePostProcessingEffects()

Checks to create the post-processor.

updateSelectRegion()

Updates the selection region mesh when required.

This method displays a rectangular region within the viewport. When dragged from left to right, the outline is shown as solid with an orange fill color to indicate bounded selection (only select items completely inside the region).

When dragged from right to left, the outline is shown as dashed with a red fill color to indicate an intersection selection (select items completely inside or whose edges cross the selection region).

Inherited From:
Overrides:

updateShading( [twilight])

Changes the background color of the scene to match the current light/dark mode and twilight effects for the current time of day.

The canvas color is obtained using PD.GlobalActions.getCanvasColorAsHex rather than accessing PD.GlobalView.canvasColor directly. This allows the PD.GlobalView.canvasColor value to be negative, indicating that the default canvas color values should be used. The actual canvas color (default or otherwise) is stored in PD.SceneViewer#view so we can access its numeric value.

Parameters:
Name Type Argument Description
twilight number <optional>

The twilight fraction (0:Night, 1:Day), defaults to current solar altitude.
Inherited From:
Overrides:

updateShadowMap(radius)

Updates the Sun's light and the shadow map.

Parameters:
Name Type Description
radius number

The bounding sphere radius.

updateSkyColors(background, twilight)

Sets the background colour

Parameters:
Name Type Description
background THREE.Color

The background color for the canvas.
twilight number

The twilight fraction.
Inherited From:
Overrides:

updateSkyShaderType()

Updates the shader to use for the sky hemisphere.

Returns:

Returns this scene manager to support method chaining.

Type
PD.SceneManager

updateViewAxis()

Update the camera view axis state properties.

Inherited From:
Overrides:

zoomBy(factor)

Zooms in by moving the camera.

Parameters:
Name Type Description
factor number

The multiplier factor.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

zoomToPointer(factor, event)

Zooms in by moving the camera towards the pointer.

Parameters:
Name Type Description
factor number

The multiplier factor.
event Event

The pointer event to get the canvas position from.
Inherited From:
Overrides:
Returns:

Returns this manager to support method chaining.

Type
PD.SceneViewer

disposeHierarchy(parent [, callback]) <static>

Disposes of all children in a THREE.js object or group.

Parameters:
Name Type Argument Description
parent THREE.Object3D

The parent object to dispose all children im.
callback function <optional>

An optional callback function for each child.

disposeMesh(mesh) <static>

A brute force approach to freeing all resources in a mesh.

Only use this method on meshes that have been removed form the scene or their parent object in the scene.

Parameters:
Name Type Description
mesh THREE.Mesh

The mesh to absolutely get rid of.