API / geotoolkit3d / Plot / Plot
geotoolkit3d.Plot.Plot
A Plot with 3D capabilities.
Unlike a geotoolkit 2D plot, this plot requires a DIV element to be passed and not a canvas.
Requires WebGL2 device support (since Toolkit v4.1), see WebGL Report.
The plot is internally structured as a SceneGraph using THREE.Scene.
It uses a camera system to represent user's eye location in 3D space.
This camera position can be moved anywhere in the plot and can look in any direction (although controller are encouraged to limit this freedom to ensure meaningful displays)
The camera type and option can be configured at creation or on the fly using setOptions().
To increase rendering accuracy the plot will try to compute ideal near/far planes positions and simplify transformation matrices.
This mechanism relies on the fact that the plot can compute its own modellimits and that those limits are reasonably small.
The rendering accuracy might suffer if modellimits are too big because of GPU floating point computing accuracy.
To render its content to the plot a render cycle made is of the following steps:
- Call updateObject on all nodes: Offers a chance to each node to update its status before rendering occurs. This should not trigger any invalidation event though.
- Call prepareRender: Simplifies transformation matrices, move near/far planes to increase accuracy.
- Call beforeRender on visible nodes. This can be used to update nodes 'on the fly' in the render pass. However be careful when overriding this function as it heavily impacts the rendering logic.
- Render: The WebGLRenderer traverses the scene, rendering node using WebGL (all GL operations occur at this stage).
- Call finishRender: Restores the matrices, revert near/far planes.
The updateObject phase differs from beforeRender as it is executed before the plot's matrices/transformation have been simplified&optimized.
Which means that its implementation modifies a transformation that will be taken into account during this render pass for the simplification step.
However beforeRender is executed after the simplification, any modification done in this function will be rendered but will not be used for simplification.
Also, beforeRender expose a bit more of the internal plot logic and usage of those elements that are not part of the public API should be done with caution.
Generally, updateObject is used to implement application level changes.
And beforeRender is generally used to execute low level operations like GPU resource loading and management.
The plot also exposes some rendering options like anti-aliasing, clear-color or preferred GPU precision.
Some of them cannot be changed on the fly though like the transparency of the background.
A notification system using EventDispatcher exposes the events occurring in the plot (object added, removed, invalidate, camera changes, etc).
One could listen to events occurring on any node of the plot by listening to the Plot's events.
Note that you can also send custom events from your nodes to implement your application's logic.
See geotoolkit3d.Event.Type for the built-in events.
When an event is fired and caught by the plot, it marks itself as dirty.
Whenever the next renderCycle occurs (based on requestanimationframe), this flag will be checked.
If it's true then a render cycle will occur, otherwise the plot will hibernate until the next requestanimationframe lands.
That's why one may need to manually call invalidateObject() on a node after modifying it through direct access (like position, scale, rotation, etc).
It will flag the plot as dirty (through the event notification system), resulting in a render.
Note that because the rendering is asynchronous, during invalidate several time in a row will trigger only one render.
The plot also offers some useful features like built-in lighting (ambient light and camera headlight) and global scale.
Those options can be enabled/disabled and configured through the setOptions().
Like a geotoolkit widget, the plot uses a Tool system to catch, process and dispatch user input. (See [AbstractTool](../classes/geotoolkit3d.tool.abstracttool.abstracttool.md)).
One of those tools is the controller, it's a special tool that allow the user to manipulate the camera using an input device (mouse, touch screen, ...).
The plot will also have a compass added to it (as an overlay).
This compass can be configured/changed and also replaced by a custom one.
The plot provides postprocessing effects like anti-aliasing and outline highlighting. Since post processing is enabled by default, an EffectComposer will be created and will replace WebGLRenderer in animation loop.
It renders scene into a 2D image on a render target, and applies some passes to the result before drawing it to the canvas.
Throws
Will throw an error if the browser does not support WebGL
↳
Plot
Constructors
Methods
Constructors
• new Plot(options)
Create plot
| Name | Type | Description |
|---|---|---|
options | Options | options to create plot |
EventDispatcher.constructor
Methods
▸ addMultipass(pass): void
Add postprocessing pass to the renderer.
The pass to be added must inherit AbstractPass.
The order of passes affects the final output, please use getMultipass and setOptions for ordering.
Deprecated
since 4.1, please use addPostProcessingPass instead.
| Name | Type | Description |
|---|---|---|
pass | AbstractPass | the postprocessing pass |
void
▸ addPostProcessingPass(pass): void
Add postprocessing pass to the renderer.
The pass to be added must inherit AbstractPass.
The order of passes affects the final output, please use getMultipass and setOptions for ordering.
| Name | Type | Description |
|---|---|---|
pass | AbstractPass | the postprocessing pass |
void
▸ addTool(tool): Plot
Adds and initializes the given tool.
The tool will be notified it has been added, and it will attach its system-event listeners.
| Name | Type | Description |
|---|---|---|
tool | AbstractTool | The tool to initialize and add. |
this
▸ dispose(): void
Disposes the plot and all its resources.
To do so, all objects contained in the scene will be disposed.
The tools registered on this plot will also be disposed.
void
▸ fitCamera(direction?, animate?, animationDuration?, distanceFactor?, ignoreZScale?): Plot
This function will try to adjust the camera position along the direction axis so that most of the scene fits into the view. It will also change the camera anchor point to the scene center. If the there is no visible geometry in the scene this function will silently fail.
| Name | Type | Description |
|---|---|---|
Optional direction | Vector3 | Direction to move the camera in, will use scene center to camera if null. |
Optional animate | boolean | Animate the camera change |
Optional animationDuration | number | Duration of the animation in milliseconds |
Optional distanceFactor | number | Distance factor when fitting the camera. Greater than 1 means further from scene center. |
Optional ignoreZScale | boolean | If true, z scale will be ignored |
this
▸ getAnimationManager(): AnimationManager
Returns the scene graph animation manager.
This manager should be used to perform smooth animations in the plot.
See AnimationManager for more details.
The animation manager
▸ getCamera(): PerspectiveCamera | OrthographicCamera
Gets camera
PerspectiveCamera | OrthographicCamera
▸ getCameraLocation(target?): Vector3
Returns camera location in user coordinates.
| Name | Type | Description |
|---|---|---|
Optional target | Vector3 | Optional target vector |
Vector3
The camera location
▸ getCameraLookAt(target?): Vector3
Returns the camera lookat point in user coordinates IF such information is available (depends on the controller used).
Otherwise returns camera.location + camera.direction.
| Name | Type | Description |
|---|---|---|
Optional target | Vector3 | Optional target vector |
Vector3
The camera lookat
▸ getCanvasElement(): HTMLCanvasElement
Gets canvas element where the scene is drawn
HTMLCanvasElement
canvas element where the scene is drawn
▸ getClassName(): string
string
▸ getCompass(): Compass
Returns the compass object.
The returned compass can be configured/modified.
See Compass for more details.
The compass object
▸ getContainer(): HTMLElement
Gets container where canvas is added
HTMLElement
container
▸ getDefaultAA(pixelScale, screen): AntiAliasing
Get the default antialiasing method according to the pixel scale, screen size and device type The default AA for retina and 2K (2560x1440) and above monitor is fast approximate AA (FXAA), and super-resolution AA (SRAA) for lower resolution. The FXAA requires less computing power hence it is the default AA mode for a mobile
Deprecated
since 4.1, it was not meant to be public. Default AntiAliasing mode is the default plot mode, unless specified by users. To have the plot use the default AntiAliasing mode, use Plot.setOptions with advancedrendering.antialias.mode: AntiAliasing.AUTO instead
| Name | Type |
|---|---|
pixelScale | number |
screen | Screen |
antialiasing type
▸ getModelLimits(viewModelLimits?, filter?): Box3
Returns a copy of the modellimits in world coordinates.
The returned limits are either the one provided through the setOptions() or the one automatically computed by the plot.
Deprecated
since 5.0, because this method would inconsistently return the result with and without the Plot's scale reverted. Please use Plot.getSceneBoundingBox instead.
| Name | Type | Description |
|---|---|---|
Optional viewModelLimits | boolean | gets the modelLimits that includes grid sprites and children of objects with a getWorldBoundingBox |
Optional filter | FilterCallback | that gets applied to the compute the model limits |
Box3
The model limits
▸ getModelOrigin(): Vector3
Returns a copy of the model origin in world coordinates.
The model origin is the center of the modellimits.
Vector3
The model origin
▸ getMultipass(): AbstractPass[]
Get the current user custom postprocessing passes as an array. This return the original array so the order can be modified.
Deprecated
since 4.1, please use getPostProcessingPasses() instead. If getMultipass() was used to enable highlight on an object, please instead use highlightObject().
▸ getOptions(): Options
Get the Plot options
▸ getPerformanceMetrics(): PerformanceMetrics
Get performance metrics
Plot.PerformanceMetrics
▸ getPostProcessingPasses(): AbstractPass[]
Get the current user custom postprocessing passes as an array. This return the original array so the order can be modified.
▸ getRenderer(): WebGLRenderer
Gets the WebGLRenderer
WebGLRenderer
renderer
▸ getRoot(): Object3D<Object3DEventMap>
Returns the scene graph root.
One should use it to append nodes to the scene using the add() function.
Object3D<Object3DEventMap>
The root node
▸ getScene(): Scene
Returns the scene.
Recommended uses are limited to:
- Insert 'absolute' positioned objects like directional lights.
- Used as parameter to [Grid#getMode](../classes/geotoolkit3d.scene-3.grid-1.grid.grid.md#getmode)().
Scene
▸ getSceneBoundingBox(target?, options?): Box3
Returns a copy of the scene bounding box based on specified SceneBoundingBoxOptions.
The returned scene bounding box are either the one provided through the setOptions() or the one automatically computed by the plot.
By default, it returns the bounding box in Business coordinates, which has inverse plot scale applied.
To get the bounding box in world coordinate, set options.coordinate to Coordinate.World.
| Name | Type | Description |
|---|---|---|
Optional target | Box3 | Target bounding box |
Optional options | SceneBoundingBoxOptions | SceneBoundingBoxOptions |
Box3
the scene bounding box
▸ getSize(target?): Dimension
Returns the 'virtual device' size of the plot.
This returns the raw size given at initialization or through the setSize function.
Ignoring any pixelRatio that could have been set on the WebGL renderer.
| Name | Type | Description |
|---|---|---|
Optional target | Dimension | optional object to store the dimensions |
The plot size
▸ getToolByName(name): AbstractTool
Finds the tool matching the given name.
If several tool match this name, the 'first' is returned.
| Name | Type | Description |
|---|---|---|
name | string | The name of the tool to look for |
▸ getUsageStatistics(): WebGLInfo
Returns usage statistics like WebGl calls per frame or amount of vertices rendered per frame.
WebGLInfo
The statistics see THREE.WebGLRenderer.info for more details.
▸ hasEventListener(type, callback?): boolean
Check if a list of event listeners for this type contains this listener
| Name | Type | Description |
|---|---|---|
type | string | type of event or property |
Optional callback | Function | to be called, if null, check if any callback is registered |
boolean
EventDispatcher.hasEventListener
▸ highlightObject(object?): void
Manually set the given object to be highlighted.
Passing 'null' or an empty parameter will remove the highlight of the currently highlighted object.
Conditions required for highlight:
- The advanced rendering option is enabled in the plot (enabled by default, unless the browser is not WebGL2 compliant)
- The given object exist in the scene, and have of highlight capabilities.
| Name | Type |
|---|---|
Optional object | Object3D<Object3DEventMap> |
void
▸ invalidateObject<T>(event?): Plot
Set the plot as 'dirty' so it gets redrawn during the next render phase.
This also propagates an event notifying the plot's listeners that an invalidation has occurred.
See Type for built-in events, custom event types can also be used.
| Name |
|---|
T |
| Name | Type | Description |
|---|---|---|
Optional event | Event<T> | The event that should be propagated as the reason of the invalidation |
this
▸ isDisposed(): boolean
Returns whether this object has been disposed
boolean
▸ isGPUPerformanceSupported(): boolean
Check if GPU Performance Metric is supported
boolean
true if supported, otherwise false
▸ isSilent(): boolean
Return true if the event dispatcher doesn't notify any events
boolean
▸ listTool(): AbstractTool[]
List all tools in the plot
tools
▸ moveCamera(position?, lookAt?, animate?, animationDuration?, upVector?): Plot
Moves the camera to the given position and rotate it to look at the given lookat.
Note that the given points should be in user coordinates (world coordinates without global scaling).
| Name | Type | Description |
|---|---|---|
Optional position | Vector3 | The position to move to in USER coordinates |
Optional lookAt | Vector3 | The point to look at (in USER coordinates) |
Optional animate | boolean | Animate the camera change |
Optional animationDuration | number | Duration of the animation in milliseconds |
Optional upVector | Vector3 | up vector |
this
▸ notify<E>(type, source, args?): Plot
Notify listeners
| Name | Type |
|---|---|
E | extends string |
| Name | Type | Description |
|---|---|---|
type | E | event types |
source | Plot | of the event |
Optional args | EventMap[E] | arguments of the event |
this
▸ off<E>(type?, callback?): Plot
Detach listener on event. Calling .off() with no arguments removes all attached listeners. Calling .off(type) with no callback removes all attached listeners for specific type.
| Name | Type |
|---|---|
E | extends string |
| Name | Type | Description |
|---|---|---|
Optional type | E | type of the event |
Optional callback | (eventType: E, sender: Plot, args: EventMap[E]) => void | function to be called |
this
▸ on<E>(type, callback): Plot
Attach listener on event that will be called whenever the specified event is delivered to the target
If the callback function is already in the list of event listeners for this target, the function is not added a second time.
If a particular anonymous function is in the list of event listeners registered for a certain target, and then later in the code, an identical anonymous function is given in an "on" call, the second function will also be added to the list of event listeners for that target.
| Name | Type |
|---|---|
E | extends string |
| Name | Type | Description |
|---|---|---|
type | E | type of event or property |
callback | (eventType: E, sender: Plot, args: EventMap[E]) => void | to be called |
this
▸ project(point): Vector3
Project the given (world) point to virtual screen space in place.
| Name | Type | Description |
|---|---|---|
point | Vector3 | The point to project in world coordinates. |
Vector3
The projected point
▸ removeTool(tool): Plot
Removes a tool (and disposes it).
The given tool will be disposed only if it does belong to this plot.
| Name | Type | Description |
|---|---|---|
tool | AbstractTool | The tool to remove and dispose |
this
▸ renderQualityPass(): void
Force plot to trigger quality pass
void
▸ resetCamera(animate?, animationDuration?): Plot
This function will try to reset the camera position along the y-axis so most of the scene fits into the view.
It will also change the camera anchor point to the scene center.
If the there is no visible geometry in the scene this will silently fail.
| Name | Type | Description |
|---|---|---|
Optional animate | boolean | Animate the camera change |
Optional animationDuration | number | Duration of the animation in milliseconds |
this
▸ rootScale(vector3): Vector3
Converts user coordinates to world coordinates in place (modifies the given object).
User coordinates are world coordinates without global scaling applies.
Use .setOptions({ scale: ... }) to change the global scaling.
| Name | Type | Description |
|---|---|---|
vector3 | Vector3 | Source AND target vector3 |
Vector3
The converted coordinates
▸ rootScaleInv(vector3): Vector3
Converts world coordinates to user coordinates in place (modifies the given object).
User coordinates are world coordinates without global scaling applies.
Use #setOptions({ scale: ... }) to change the global scaling.
| Name | Type | Description |
|---|---|---|
vector3 | Vector3 | Source AND target vector3 |
Vector3
The converted coordinates
▸ setCameraLocation(position, animate?, animationDuration?): Plot
Sets camera location in user coordinates.
It is recommended to use #moveCamera() instead as it handles both the location and the direction of the camera.
| Name | Type | Description |
|---|---|---|
position | Vector3 | The position to move to (in USER coordinates) |
Optional animate | boolean | Animate the camera change |
Optional animationDuration | number | Duration of the animation in milliseconds |
this
▸ setCameraLookAt(lookat, animate?, animationDuration?): Plot
Sets camera target in user coordinates.
It is recommended to use #moveCamera() instead as it handles both the location and the direction of the camera.
| Name | Type | Description |
|---|---|---|
lookat | Vector3 | The point to look at (in USER coordinates) |
Optional animate | boolean | Animate the camera change |
Optional animationDuration | number | Duration of the animation in milliseconds |
this
▸ setOptions(options): Plot
Set options, the given json will be merged with the object's state so that only the given options will be changed.
| Name | Type | Description |
|---|---|---|
options | OptionsBase | options to set on this object |
this
▸ setOriginTranslation(enabled): void
Apply a translation to the root and camera for higher precision.
Because renderer has a high precision error when working with large positions, set the root and camera closer to origin improves the accuracy. Note that it temporarily changes camera's position, i.e. during beforeRender().
| Name | Type | Description |
|---|---|---|
enabled | boolean | to enable |
void
▸ setSilent(bool): Plot
Set silent mode
| Name | Type | Description |
|---|---|---|
bool | boolean | flag to enable silent mode |
this
▸ setSize(width, height, pixelDeviceRatio?): Plot
Set size of the Plot.
This increase the rendering-area size (canvas) to the given dimension.
It also notifies the WebGl renderer.
The given pixelDeviceRatio can be used to take into account the current Browser zoom level.
| Name | Type | Description |
|---|---|---|
width | number | The new width that should be set |
height | number | The new height that should be set |
Optional pixelDeviceRatio | number | The pixel device ratio, if unset, will use the value provided by the window if available. |
this
▸ setWatermark(watermark): Plot
Set watermark to draw over plot 3d
| Name | Type | Description |
|---|---|---|
watermark | AnchoredShape | watermark |
this
▸ updateModelLimits(filter?, alwaysTraverseChildren?): Plot
Updates the model limits of the Plot by computing it using the current scene state.
If 'autoupdatemodellimits' is enabled, this should be called automatically when some operations occur (adding, removing a node, etc).
However it should be called manually if an object in the scene is moved outside the current modellimits manually.
For example by changing its position attribute.
The modellimits are used internally to improves accuracy of rendering & picking.
Note: this method can have side effects if non-standard filter was used.
| Name | Type | Description |
|---|---|---|
Optional filter | FilterCallback | gets applied to the compute of model limits |
Optional alwaysTraverseChildren | boolean | Forces the calculation to traverse children to get the extents of the whole view |
this
▸ Static getClassName(): string
string