scene-viewers

Set of classes and mixins for creating a basic three.js viewer with convenience functions.

Use

Basic Viewer

import { Viewer } from '@gov.nasa.jpl.honeycomb/scene-viewers';

const viewer = new Viewer();
document.body.appendChild( viewer.domElement );

Dirty Viewer

// TODO

Label Viewer

// TODO

Optimized Viewer

// TODO

API

ViewerOptions

The options for the viewer. All options for the WebGLRenderer are valid.

.showStats

showStats = false : boolean

Whether or not to init stats with the viewer.

Viewer

extends EventDispatcher

Wraps and sets up the three.js WebGLRenderer and implements a render loop.

Events

before-render

Fired before a frame is rendered.

after-render

Fired after a frame is rendered.

enabled

Fired when the viewer is enabled.

disabled

Fired when the viewer is disabled.

added

Fired whenever an object is added anywhere in the scene. The child is available on the child field of the event.

removed

Fired whenever an object is removed anywhere in the scene. The child is available on the child field of the event.

.domElement

domElement : CanvasElement

A handle to the domElement from the WebGLRenderer.

.renderer

renderer : WebGLRenderer

A handle to the WebGLRenderer.

.enabled

enabled = true : boolean

Whether or not to render the scene. If false the scene will not be rendered.

.scene

scene : Scene

A handle to Scene being rendered.

.world

world : Group

A child object of scene with rotations applied to adjust the scenes "up", as defined by the setUp function.

.orthographic

orthographic = false : boolean

Whether to render the scene using an orthographic camera or not.

.perspectiveCamera

perspectiveCamera : PerspectiveCamera

The camera used to render the scene when .orthographic is false.

.orthographicCamera

orthographicCamera : OrthographicCamera

The camera used to render the scene when .orthographic is true. This camera is synced with the position, rotation, and zoom of .perspectiveCamera before rendering. It can be manually updated using the syncCameras function.

.composer

composer : EffectComposer

.resolution

resolution : Vector2

The resolution of the current display. The size of the renderer is not updated automatically on window resize. setSize must be called.

.getCamera

getCamera() : PerspectiveCamera | OrthographicCamera

Returns the currently active camera based on the value of .orthographic.

.gridVisibility

gridVisibility = false : Boolean

Whether or not to display a floor grid in the world at the origin.

.syncCameras

syncCameras() : void

Updates the orthographic camera to be in sync with the position, rotation, and zoom of the perspective camera and vice versa.

.setSize

setSize( width : number, height : number ) : void

Sets the resolution of the rendered canvas.

.setTargetScale

setTargetScale( scale : number ) : void

Sets the render multiplier ratio, which can be used for manual super sample antialiasing (or lowering the resolution to improve performance).

.setPixelRatio

setPixelRatio( pixelRatio : number ) : void

Sets the pixel ratio of the renderer. See WebGLRenderer.setPixelRatio.

.initStats

initStats() : void

Intializes a framerate display on the page.

DirtyViewerMixin

A function that adds behavior for rendering only on scene changes. The class is expected to inherit from Viewer.

.dirty

dirty = false : boolean

Marks the viewer as dirty and schedules a draw for the next frame if set to true. It is expected that this is set to true when something in the scene is changed.

.staticRender

overrideable

staticRender(
    renderer : WebGLRenderer,
    scene : Scene,
    camera : Camera,
    iteration : number
) : boolean

Called for subsequent frames after a fresh draw has been made until the function returns false. iteration is incremented for every frame after the original draw is done.

This can be used to progressively draw new data on top of the canvas while the scene isn't updating.

LabelLayerMixin

A function that adds behavior for displaying HTML dom element labels on top of 3d objects. The class is expected to inherit from Viewer.

A div layer is added on top of the canvas for housing the labels. A label is added to the scene by creating an instance of an object that adhere's to the following interface and adding it to the scene:

class extends Object3D {

    isLabel = true : boolean;
    label : DomElement;
    updateLabelPosition( renderer : WebGLRenderer, scene : Scene, camera : Camera ) : void;

}

The label element is added to the view layer and is expected to update it's position based on the objects projection relative to the camera when updateLabelPosition is called.

OptimizedViewerMixin

A function that adds behavior for incrementally optimizing the performance of the 3d viewer and adds the FXAAPass and BloomPass screen effects by default.

The BloomPass and FXAAPass will be incrementally made more performant or disabled until the target framerate of at least 35 is reached. The render resolution will also be incrementally updated.

.optimizer

optimizer : Optimizer

The Optimizer instance from framerate-optimizer package.

World

extends Group

Events

orientation-changed

Fired whenever the up direction is changed.

getUpDirection

getUpDirection(  ) : String

Returns the up direction of the world object in the form of [+-][XYZ].

setUpDirection

setUpDirection( upString : String ) : void

Takes the up axis orientation as a string in the form of [+-][XYZ].