ParaView
Major API Changes

This page documents major API/design changes between different versions since we started tracking these (starting after version 4.2).

Changes in 5.2

Removed pqStandardArrayColorMapsBehavior

Setting the default colormaps from a Qt Behavior was causing inconsistent results between the ParaView UI and pvpython/pvbatch. Adding these default settings was moved into the server manager. To override these defaults, use vtkSMSettings::AddCollectionFromX with a priority greater than 0. The settings affected are the default colormap for arrays with names vtkBlockColors and AtomicNumbers. With these settings moved, the Qt behavior pqStandardArrayColorMapsBehavior no longer does anything and so it has been removed.

Qt dependencies

Starting with 5.2, ParaView natively supports Qt 4 and Qt 5. To simplify writing code with either dependency, we now have a new CMake file ParaViewQt.cmake that gets included by PARAVIEW_USE_FILE. This provides new macros that be used to find qt (pv_find_package_qt), wrap cpp (pv_qt_wrap_cpp), ui (pv_qt_wrap_ui), or add resources (pv_qt_add_resources) instead of using qt4_ or qt4_ specific versions based on whether the app is being built with Qt4 or Qt5. pv_find_package_qt accepts optional QT5_COMPONENTS and QT4_COMPONENTS which can be used to list the Qt component dependencies for each of the versions. e.g.

include(ParaViewQt) # generally not needed, since auto-included
pv_find_package_qt(qt_targets
  QT4_COMPONENTS QtGui
  QT5_COMPONENTS Widgets)

pv_qt_wrap_cpp(moc_files ${headers})
pv_qt_wrap_ui(ui_files ${uis})

...
target_link_libraries(${target} LINK_PRIVATE ${qt_targets})

Multiple input ports with vtkPythonProgrammableFilter

vtkPythonProgrammableFilter can now accept multiple input ports if the number of input ports is defined in the XML plugin file with the input_ports attribute. The different input ports are then defined with InputProperty having each a different port_index:

<SourceProxy name="Name" class="vtkPythonProgrammableFilter" label="label" input_ports="2"> <InputProperty name="Source" command="SetInputConnection" port_index="0"> [...] </InputProperty> <InputProperty name="Target" command="SetInputConnection" port_index="1"> [...] </InputProperty> </SourceProxy>

Changes in 5.1

Removed Cube Axes

Cube axes, including support in UI, Python as well as the related ParaView specific classes e.g. vtkCubeAxesRepresentation, pqCubeAxesEditorDialog, and pqCubeAxesPropertyWidget have been removed. The cube axes was replaced by a generally preferred axes annotation implementation called Axes Grid. While the two are not compatible (API-wise or visually), using Axes Grid generates a more pleasing visualization.

Removed pqWriterDialog

pqWriterDialog was used by pqSaveDataReaction to show a dialog for the user to change the writer's properties. However, since the class was added, we have created a new, more generic, pqProxyWidgetDialog that also allows the user to save his choices to the application settings. pqSaveDataReaction now simply uses pqProxyWidgetDialog instead of pqWriterDialog. pqWriterDialog class has been removed.

Refactored 3DWidget panels

3DWidget panels were subclasses of pqObjectPanel, the Properties panel hierarchy that has been deprecated since 4.0. This version finally drops support for these old 3D widget panels. The new implementation simply uses the pqPropertyWidget infrastructure. A 3D widget panel is nothing more than a custom pqPropertyWidget subclass for a property-group (vtkSMPropertyGroup) which creates an interactive widget to be shown in the active view to help the users change the values for properties in the property-group using this interactive widget, in addition to standard Qt-based UI elements.

If you have a filter or proxy indicating that the Properties panel use one of the standard 3D widgets for controlling certain properties on that proxy, you specified that using <Hints> in the Proxy's XML definition.

For example, the **(implicit_functions, Plane)** proxy requested that pqImplicitPlaneWidget be used using the following XML hints.

<Proxy class="vtkPVPlane" name="Plane">
  <InputProperty is_internal="1" name="Input" />
  <DoubleVectorProperty command="SetOrigin"
                        default_values="0.0 0.0 0.0"
                        name="Origin"
                        number_of_elements="3">
  ...
  </DoubleVectorProperty>
  <DoubleVectorProperty command="SetNormal"
                        default_values="1.0 0.0 0.0"
                        name="Normal"
                        number_of_elements="3">
  ...
  </DoubleVectorProperty>
  <DoubleVectorProperty animateable="1"
                        command="SetOffset"
                        default_values="0.0"
                        name="Offset"
                        number_of_elements="1">
  </DoubleVectorProperty>
  <Hints>
    <PropertyGroup type="Plane">
      <Property function="Origin" name="Origin" />
      <Property function="Normal" name="Normal" />
    </PropertyGroup>
    <ProxyList>
      <Link name="Input" with_property="Input" />
    </ProxyList>
  </Hints>
</Proxy>

Since 3D widget panels are now simply custom pqPropertyWidget subclasses for a property-group, this code changes are follows:

<Proxy class="vtkPVPlane" name="Plane">
  <InputProperty is_internal="1" name="Input" />
  <DoubleVectorProperty command="SetOrigin"
                        default_values="0.0 0.0 0.0"
                        name="Origin"
                        number_of_elements="3">
  ...
  </DoubleVectorProperty>
  <DoubleVectorProperty command="SetNormal"
                        default_values="1.0 0.0 0.0"
                        name="Normal"
                        number_of_elements="3">
  ...
  </DoubleVectorProperty>
  <DoubleVectorProperty animateable="1"
                        command="SetOffset"
                        default_values="0.0"
                        name="Offset"
                        number_of_elements="1">
  </DoubleVectorProperty>
  <PropertyGroup label="Plane Parameters" panel_widget="InteractivePlane">
    <Property function="Origin" name="Origin" />
    <Property function="Normal" name="Normal" />
    <Property function="Input"  name="Input" />
  </PropertyGroup>
  <Hints>
    <ProxyList>
      <Link name="Input" with_property="Input" />
    </ProxyList>
  </Hints>
</Proxy>

Things to note:

The functions for properties in the group supported by each type 3D widget (or interactive widget as we now will call them) can be found by looking at the documentation of each of the custom widget listed below. For the most past, these have remained unchanged for previous function names.

Available custom property-widgets, the interactive widget they use and the obsolete 3DWidget they correspond to are given in the table below.

New Widget panel_widget Interactive Widget used Obsolete 3DWidget name
pqBoxPropertyWidget InteractiveBox BoxWidgetRepresentation pqBoxWidget
pqHandlePropertyWidget InteractiveHandle HandleWidgetRepresentation pqHandleWidget, pqPointSourceWidget
pqImplicitPlanePropertyWidget InteractivePlane ImplicitPlaneWidgetRepresentation pqImplicitPlaneWidget
pqLinePropertyWidget InteractiveLine LineSourceWidgetRepresentation pqLineWidget, pqDistanceWidget, pqLineSourceWidget
pqSpherePropertyWidget InteractiveSphere SphereWidgetRepresentation pqSphereWidget, pqOrbitWidget
pqSplinePropertyWidget InteractiveSpline or InteractivePolyLine SplineWidgetRepresentation or PolyLineWidgetRepresentation pqSplineWidget, pqPolyLineWidget

Changes to vtkDataArray Subclasses and In-Situ Arrays

vtkDataArray can now support alternate memory layouts via the vtkAOSDataArrayTemplate or other subclasses of vtkGenericDataArray. While the older (and slower) vtkTypedDataArray and vtkMappedDataArray interfaces still exist, they should not be used and direct vtkGenericDataArray subclasses are preferred. See http://www.vtk.org/Wiki/VTK/Tutorials/DataArrays for more details on working with the new arrays.

The following methods have been deprecated in vtkAOSDataArray:

void GetTupleValue(vtkIdType tupleIdx, ValueType *tuple)
void SetTupleValue(vtkIdType tupleIdx, const ValueType *tuple)
void InsertTupleValue(vtkIdType tupleIdx, const ValueType *tuple)
vtkIdType InsertNextTupleValue(const ValueType *tuple)

The replacements use TypedTuple in place of TupleValue.

Changes in 5.0.1

Changes to vtkSMInputArrayDomain

vtkSMInputArrayDomain has changed the meaning of **"any"** attribute type. It now includes field data arrays. To exclude field data arrays from the field selection, change this to **"any-except-field"**. This is also the default for vtkSMInputArrayDomain, hence simply removing the attribute_type field is also an acceptable solution and is the recommended approach so that the XML can work without changes in earlier versions of ParaView as well.

Changes in 5.0

Changed Source property to GlyphType on certain representations

Source property on representations, which was not exposed in the UI has been changed to GlyphType to better match its role. Since this property was not exposed earlier, this change should not affect any users except custom applications that explicitly used this property.

Changes to caching infrastructure in vtkPVDataRepresentation and subclasses

To avoid extra work and sync issues when propagating UseCache and CacheKey flags from a vtkPVView to vtkPVDataRepresentation, vtkPVDataRepresentation was updated to directly obtain thet values for these flags from the view. To enable this, vtkPVDataRepresentation saves a weak reference to the View it's being added to in vtkPVDataRepresentation::AddToView and vtkPVDataRepresentation::RemoveFromView. Subclasses of vtkPVDataRepresentation didn't consistently call the superclass implementation, hence any representation subclass should ensure that it calls the superclass implementations of AddToView and RemoveFromView for this to work correctly. vtkPVView::AddRepresentationInternal checks for this and will raise a runtime error if a representaiton is encountered that didn't properly set its View.

The above change also makes vtkPVDataRepresentation::SetUseCache and vtkPVDataRepresentation::SetCacheKey obsolete. Subclasses no longer need to provide any implementation for these methods and they should simply be removed.

Changes in 4.4

Refactored pqView widget creation mechanisms

pqView now adds a pure virtual method pqView::createWidget(). Subclasses should override that method to create the QWidget in which the view is rendered. In the past the subclasses implemented their own mechanisms to create the widget and return it when getWidget() was called the first time.

pqView::getWidget() is now deprecated. Users should use pqView::widget() instead. This method internally calls the pqView::createWidget() when appropriate.

Removed vtkPVGenericRenderWindowInteractor, vtkPVRenderViewProxy

ParaView was subclassing vtkRenderWindowInteractor to create vtkPVGenericRenderWindowInteractor to handle interaction. That piece of code was potentially derived from an older implementation of vtkRenderWindowInteractor and hence did what it did. Current implementation of vtkRenderWindowInteractor lets the vtkInteractionStyle (and subclasses) do all the heavy lifting. ParaView did that to some extent (since it has a vtkPVInteractorStyle), but will was relying on vtkPVGenericRenderWindowInteractor, vtkPVRenderViewProxy to propagate interaction/still renders and other things. This has been refactored. ParaView no longer uses a special vtkRenderWindowInteractor. All logic is handled by observers on the standard vtkRenderWindowInteractor.

This change was done to make it easier to enable interactivity in pvpython.

See also: vtkSMRenderViewProxy::SetupInteractor(). Subclasses of pqView now pass the interactor created by QVTKWidget to this method to initialize it.

See also: vtkSMViewProxyInteractorHelper.

Refactored Color Preset Management (and UI)

The color preset management has been completely refactored for this release. This makes presets accessible to Python clients. vtkSMTransferFunctionPresets is the class that manages the presets in the ServerManager layer.

On the UI side, pqColorPresetModel, pqColorPresetManager, and pqColorMapModel no longer exist. They have been replaced by pqPresetDialog. Since the UI is completely redesigned, tests in custom applications that used the color preset dialog will need to be updated as well.

The preset themselves are now serialized as JSON in the same form as the settings JSON. ColorMaps in legacy XML format are still loadable from the UI. At the same time, a tool vtkLegacyColorMapXMLToJSON is available to convert such XMLs to JSON.

Changes to pqViewFrame

Commit afaf6a510 changes the internal widgets created in pqViewFrame to add a new QFrame named CentralWidgetFrame around the rendering viewport. While this shouldn't break any code, this will certainly break tests since the widgets have changed. The change to the testing XML is fairly simple. Just add the CentralWidgetFrame to the widget hierarchy at the appropriate location. See the original merge request for details.

Changes to vtkSMProxyIterator

vtkSMProxyIterator::Begin(const char* groupName) now additionally sets the iterator mode to iterate over one group. This will likely break any code that uses this method, since the iterated data list will change. To recover the original functionality of the iterator, simply call vtkSMProxyIterator::SetModeToAll() after calling vtkSMProxyIterator::Begin(const char* groupName).

Changes in 4.3

Replaced pqCurrentTimeToolbar with pqAnimationTimeWidget

pqCurrentTimeToolbar was a QToolbar subclass designed to be used in an application to allow the users to view/change the animation time. We reimplemented this class as pqAnimationTimeWidget making it a QWidget instead of QToolbar to make it possible to use that in other widgets e.g. pqTimeInspectorWidget. pqAnimationTimeToolbar was also changed to use pqAnimationTimeWidget instead of pqCurrentTimeToolbar.

Besides just being a cleaner implementation (since it uses pqPropertyLinks based linking between ServerManager and UI), pqAnimationTimeWidget also allows applications to change the animation play mode, if desired. The rest of the behavior of this class is similar to pqCurrentTimeToolbar and hence should not affect applications (besides need to update any tests since the widget names have now changed).

Removed the need for plugins to specify a GUI_RESOURCE_FILE

It is cleaner and easier to update one xml file for each plugin. Hints in the server manager xml file already perform the same functionality and the GUI xml file was deprecated. Sources are now added to the Sources menu and filters are added to the Filters menu when they are detected in the server xml file. To place sources/filters in a category, add the following hint to the Proxy XML element (category and icon attributes are optional):

<SourceProxy ...>
  ...
  <Hints>
    <ShowInMenu category="<category-name>" icon="<qt-image-resource>" />
  </Hints>
</SourceProxy>

The ability to add filters to the sources menu (as done by a few plugins) is removed by this change.

This change also modifies how readers are detected. Readers now must provide a hint to the ReaderManager in the server xml file to be detected as readers rather than sources. The backwards compatibility behavior that assumed any source with a FileName attribute was a reader has been removed.

Removed pqActiveView (use pqActiveObjects instead)

pqActiveView was a long deprecated class which internally indeed used pqActiveObjects. pqActiveView has now been removed. Any code using pqActiveView can switch to using pqActiveObjects with very few code changes.