Developer introduction to ParaViewWeb
Introduction
ParaViewWeb is a framework which expose VTK or ParaView processing and visualization capabilities through Web protocols. This allow the creation of Web Server or Web Sites that generate interactive 3D rendering as well as interactive processing capabilities. ParaViewWeb is distributed along the ParaView binaries which allow local testing or deployment without any code compilation.
Let's look at the components that are used within that framework and see how they interact in order to build the ParaViewWeb framework.
Server side of ParaViewWeb
Thirdparty
Python Thirdparty libraries:
- Autobahn: WAMP implementation using WebSocket and Long Polling.
- Twisted: Web server used by autobahn to expose its WebSocket resource.
- Six: Used by Autobahn to handle Python 2 and 3.
- ZopeInterface: Library used by Twisted to provide abstract interface.
Components
ParaViewWeb components:
- server.py
- protocols.py
- vtkWebApplication / vtkPVWebApplication
- Your server application (i.e.: pv_web_visualizer.py, vtk_web_cone.py...)
server.py
The server module provides helper functions that will register standard arguments and handle them when the start_webserver method will be called. This main function will configure and use Twisted to start a Web server on a given port. The protocol argument of that function will be use to create a WebSocket endpoint.
The following arguments are used to configure that web server:
- --port (default:8080): Which port to start the Web Server on and listen to.
- --content (optional): If provided, the web server will serve the content of the provided directory.
- --authKey (default: vtkweb-secret): Key that should be used to authenticate the client with the server.
- --timeout (default: 300 seconds): Timeout that will stop the server/process when the last connected user leave or if nobody connects.
- --debug: Will enable debug output on the server side.
- --nosignalhandlers: Will prevent default signal handling when the server needs to be started within a thread.
protocols.py
The protocols module provides a set of implementation of vtkWebProtocol classes that can be use to build your server application. Some common classes are the one that handle mouse interaction and rendering.
- ParaView
- ParaViewWebMouseHandler
- ParaViewWebViewPortImageDelivery
- ParaViewWebViewPortGeometryDelivery
- ...
- VTK
- vtkWebMouseHandler
- vtkWebViewPortImageDelivery
- vtkWebViewPortGeometryDelivery
- ...
All available protocols for ParaView are listed here.
vtkWebApplication / vtkPVWebApplication
The vtkWebApplication is a C++ class which is use inside the rendering protocols listed earlier. That class provides easy to use and optimized method to capture images from VTK and ParaView views as well as convinient mouse event handling.
Your server application
This part is generaly a Python module that contains a main section which will trigger the starting of a Web Server. In that module, you usually find an internal class that list all the existing protocols that you want to use and expose along the ones you want to add yourself.
A good example is either {VTK_SRC}/Web/Applications/Cone/server/vtk_web_cone.py or {PV_SRC}/Web/Applications/Visualizer/server/pv_web_visualizer.py.
Launcher
The launcher is nothing more than a WebServer that expose a RESTful API that is used to run a specific command line base on a specific request with some pattern replacement.
This is used to dynamically start a new visualization session at the request of a Web Client which will then allow each client to work independently from each other.
Client side
As a framework VTK/ParaView Web provides a set of JavaScript libraries that rely on JQuery to ease its usage.
A typical ParaViewWeb or vtkWeb web page will look like that:
<!DOCTYPE html>
<html>
<body class="page" onbeforeunload="stop()" onunload="stop()">
<div class="viewport-container">
</div>
<script src="../../lib/core/vtkweb-loader-min.js" load="core-min"></script>
<script type="text/javascript">
var config = {
sessionManagerURL: vtkWeb.properties.sessionManagerURL,
application: "cone"
},
stop = vtkWeb.NoOp,
start = function(connection) {
// Create viewport
var viewport = vtkWeb.createViewport({session:connection.session});
viewport.bind(".viewport-container");
// Handle window resize
$(window).resize(function() {
if(viewport) {
viewport.render();
}
}).trigger('resize');
// Update stop method to use the connection
stop = function() {
connection.session.call('application.exit');
}
};
// Try to launch the Viz process
vtkWeb.smartConnect(config, start, function(code,reason){
alert(reason);
});
</script>
</body>
</html>
This will first try to request a new visualization session using the Launcher RESTful API, and will fall back to a direct WebSocket connection using the current host and port information in case of lack of launcher.
The Client initialization step can be decomposed as follow:
- vtkweb-loader-min.js is used to automate the loading of ParaViewWeb JavaScript libraries and dependencies. This will load JQuery, Autobahn.js and all vtkWeb code base.
- We define a start method that will be called onced a connection to the server side has been establised. The connection provided as argument will give us an handle on the session which will allow us to make Remote Procedure Call (RPC) on the server side.
- Then we try to connect to the remote server using the convinient method vtkWeb.smartConnect.
- In the start method, we override the stop function which will be automatically called if the user quit his browser or close its tab. And we attach to the ".viewport-container"
<div>an interactive 3D renderer.