3D Widgets in ParaView

Overview

This documents talks about the handling on 3D Widgets in the ParaView's ServerManager. 3D Widgets are different from other VTK objects because of one major difference, the user can affect 3D Widget properties by two means: setting then directly using the API, interacting with the widget. (This is also true with some 2D Widget like Plots, Scalar Bars. However, in ServerManager, they are handled differently as displays.)

 NOTE: This discussion explains about current ParaView design, not the direction for future.

Design

What are 3D Widgets?

• 3D Widgets include the Point/Line/Implicit Plane/Sphere/Box widgets. These are typically used where we want to make it possible for the user to set/change some properties of VTK entities like clip surfaces, point/line sources interactively --- by directly interacting with the RenderWindow.
• Hence, whenever there is a 3D Widget used, we typically have a VTK object that is controlled by that 3D widget. In ParaView, both the 3D Widget and the controller object are separate proxies. The linking between the two is maintained by the GUI.

3D Widget Proxy Behaviour

• The proxy created for a 3D widget is a special proxy. It doesn't merely convey commands to the server objects, but also does some processing on the client side. Why this processing is necessary and what processing is done will be clear soon.
• 3D Widget proxy creates the 3D Widget object on RenderServer and the Client. Whenever a property is modified on the client side (and the user calls UpdateVTKObjects on the proxy), the changes to the property(or properties) are conveyed to both the client and the server object by the Proxy (just as any other proxy).
• Now, the user can also interact with the 3D widget. In VTK, for the 3D widget object to know that the user is interacting with it, it needs to know the interactor. Now, in ParaView, the interactor only exists on the client. Hence, only the client side 3D widget can detect the interaction events and reposition/reorient (etc) itself accordingly. This implies that on every interaction with a 3D Widget, only the client side object is updated and not the serverside objects.
• To update the server side objects on interaction, the 3D Widget proxy has code to listen to interaction events on the vtk 3D Widget object on the client. On every interaction event, the proxy obtains the changed property values from the client object (eg in line widget the two endpoint positions) and pushes it down to the Server Object.
• Note that this pushing of updated values happens on every interaction, and has nothing to do with accept/reset buttons on the GUI.
• Properties on a Proxy are uni-directional. Hence, the 3D Widget proxy does not have the liberty to change the values in the property (eg. Normal for the implicit plane widget) on every interaction. Instead, 3D Widget proxies provide information properties (eg NormalInfo) that can be used to get the value from the proxy.
• On every interaction the 3D widget proxies raise a vtkCommand::WidgetModifiedEvent.

GUI Behaviour

• The GUI keeps the linking betweeen the 3D Widget proxy and the controlled VTK object proxy (which is typically an implicit function).
• Every 3D widget has some GUI elements (such as Normal, Position for an Implicit Plane Widget). Whenever the user changes such these GUI values, the GUI immediately pushes them down to the 3D widget proxy and call UpdateVTKObjects on it. The GUI also makes the Accept button green. Note that propagation of changes in GUI to the proxy, in case of 3D Widgets, does not wait for the Accept button.
• The GUI observers vtkCommand::WidgetModifiedEvent for every 3D Widget it controls. Whenever, this event it received, the GUI calls vtkSMProxy::UpdateInformation() on the 3D Widget proxy to update all the information properties of the proxy and then uses the Info properties to detemine values for the GUI elements (eg. the enrty boxes for Normal will be updated using NormalInfo property for the implicit plane widget).
• On Accept, the GUI transfers the values from the 3D Widget info properties to the corresponding properties on the controlled Implicit function.
• On Reset, the GUI transfers the values from the controlled Implicit function (which are the values that were last accepted) to the corresponding properties on the 3D Widget proxy.