.. include:: ../macros.hrst .. include:: ../abbreviations.hrst .. _chapter:PythonProgrammableFilter: ``Programmable Filter`` ####################### A pipeline module in |ParaView| does one of two things: it either generates data or processes input data. To generate data, the module may use a mathematical model e.g. :guilabel:`Sources > Sphere` or read a file from disk. Processing data entails transforming input data by applying defined operations to generate a new output. |ParaView| provides a large set of readers, data sources and data filters that cover the needs of many users. For the cases where the available collection does not satisfy your needs, |ParaView| provides a mechanism to add new modules via plugins. Conventional plugins, however, are intended for hardcore developers. They are written in C++, using the data processing APIs provided by |ParaView| and VTK. The complexity of building and packaging C++ plugins that work on all distributed versions of |ParaView| can be daunting and thus a huge barrier for even advanced |ParaView| users. Python-based programmable filters and sources provide an easy alternative to this. New modules can be written as Python scripts that are executed by |ParaView| to generate and/or process data, just like conventional C++ modules. Since the scripts are standard Python scripts, you have access to Python packages such as NumPy that provide several numeric operations useful for data transformation. In this chapter, we will explore how to use Python to add new data processing modules to ParaView through examples. For additional explanation of the data processing API, see :numref:`chapter:VTKNumPyIntegration`. .. admonition:: **Common Errors** :class: error In this guide so far, we have been looking at examples of Python scripts for |pvpython|. These scripts are used to script the actions you would perform using the |paraview| UI. The scripts you would write for ``Programmable Source`` :index:`\ `\ and ``Programmable Filter`` :index:`\ `\ are entirely different. The data processing API executes within the data processing pipeline and, thus, has access to the data being processed. In client-server mode, this means that such scripts are indeed executed on the server side, potentially in parallel, across several MPI ranks. Therefore, attempting to import the ``paraview.simple`` :index:`\ `\ Python module in the ``Programmable Source`` :index:`\ `\ script, for example, is not supported and will have unexpected consequences. .. _sec:UnderstandingProgrammableModules: Understanding the programmable modules ====================================== With programmable modules, you are writing custom code for filters and sources. You are expected to understand the basics of a VTK (and |ParaView|) data processing pipeline, including the various stages of the pipeline execution as well as the data model. Refer to :numref:`sec:VTKDataModel` for an overview of the VTK data model. While a detailed discussion of the VTK pipeline execution model is beyond the scope of this book, the fundamentals covered in this section, along with the examples in the rest of this chapter, should help you get started and write useful modules. For a primer on the details of the VTK pipeline execution stages, see :cite:`VTKPipelinePrimer`. To create the programmable source or filter in |paraview|, you use the :guilabel:`Sources > Programmable Source` or :guilabel:`Filters > Programmable Filter` menus, respectively. Since the ``Programmable Filter`` :index:`\ `\ is a filter, like other filters, it gets connected to the currently active source(s), i.e., the currently active source(s) become the input to this new filter. ``Programmable Source`` :index:`\ `\ , on the other hand, does not have any inputs. .. figure:: ../images/ProgrammableFilterInParaView.png :name: fig:ProgrammableFilterInParaView :width: 80% :align: center ``Properties`` :index:`\ `\ panel for ``Programmable Filter`` :index:`\ `\ in |paraview|. One of the first things that you specify after creating any of these programmable modules is the ``Output Data Set Type`` :index:`\ `\ . This option lets you select the type of dataset this module will produce. The options provided include several of the data types discussed in :numref:`sec:VTKDataModel`. Additionally, for the ``Programmable Filter`` :index:`\ `\ , you can select ``Same as Input`` :index:`\ `\ to indicate that the filter preserves the input dataset type. Next is the primary part: the ``Script`` :index:`\