ParaView is a pipeline-based framework: the user loads in data and then applies one or more filters forming a pipeline. The pipeline can further process, render, or save the result. Users often find themselves applying the same set of filters with some minor parameter tweaks for a few filters in the pipeline to different datasets. With what we call custom filters, it is possible for the user to combine the pipeline into a single filter while exposing a set a properties from the internal filters that need tweaking. Additionally, the user can then share his custom filter's with other users.
This document describes how to create and use custom filters.
One very commonly asked question on the mailing list is how to create surface streamlines. The pipeline for that looks like this:
In this example we'll create a new filter to create surface streamlines. As a first step, we set up the pipeline in ParaView. The image below shows the pipeline browser for the pipeline. Here the vector field source is "Slice1". One custom filter is going comprise of the sub-pipeline after "Slice1" which has been highlighted in following image.
|| To create a custom filter, first select the sub-pipline in the pipeline browser. One can use Ctrl or Shift keys for multiple selection. With the pipeline selected, open the Create Custom Filter wizard accessible through the Tools menu.
|| The wizard will ask use to choose a name for the filter. We are calling this "SurfaceStreamlines". If the name conflicts with any existing filter, you should get an error message. Click "Next" to continue.
|| On the next page, we need to choose the input to this custom filter i.e. identify the filter that marks the start of the pipeline and choose its input property which will be used to set the input. For simple pipelines, ParaView will automatically detect the first filter and add it as the input. In our case, we select the SurfaceVector4 in the tree on the left side, then choose the input property to expose in the Input Property combo-box (generally there will only be one), give it some name, say "Input" and then hit the + button to export the property. On success, you should see the exposed property in the list box. A custom filter may have more than one inputs.
|| Next, we select the output from this filter. Since ours is a streamline tracer filter, our output is the output of the StreamTracer(CustomSource)3 filter. So select the filter in the tree widget, then as before choose the output-port from this filter in the Output Port combo-box (generally there will only be one option), assign it a name (say Streamlines) and then hit the + button to add it. A custom filter may have multiple outputs as well. Say in this case, we want the user to be able to see the points used as seed points for the stream tracer. In that case, we should expose the output from the MaskPoints2 filter as well. Following the same steps as before, expose the MaskPoints2 filters Output-0 as "SeedPoints". Click "Next" to continue.
|| Next page allows us to expose properties from the filters in the pipeline which the user can tweak at run-time. Let's say we want the user to be able to choose the interpolation technique as well as the maximum number of seed points genearated by the MaskPoints filter. Similar to before, select the corresponding filters, locate the properties to expose, assign then some name and the click +. Now hit "Finish".
On success the Custom Filter Manager will popup showing the newly created filter. Close this dialog. Now, if you look under the Filters|Alphabetical menu, you'll see the SurfaceStreamlines filter. It can now be used just like any other filter. Following image shows our custom filter applied to a vector field input.
Managing Custom Filters
The Custom Filter Manager, accessible through Tools | Manage Custom Filters menu option, can be used to remove/import/export custom filters. Exporting allows users to share custom filter definitions. Such exported definitions can be imported this manager. Custom filters need to be imported only once. Once imported, they get saved with other ParaView settings and hence are preserved across sessions. When saving state files involving custom filters, the custom filter definition gets saved in the state file, hence the state can be loaded on by any user even if he doesn't have the custom filter definition.