.. include:: ../macros.hrst
.. include:: ../abbreviations.hrst
.. _chapter:FilteringData:
.. _ch:FilteringData:
Filtering Data
##############
Visualization can be characterized as a process of transforming raw data
produced from experiments or simulations until it takes a form in which it can be
interpreted and analysed. The visualization pipeline introduced in
:numref:`sec:BasicsOfVisualization` formalizes this concept as a data flow
paradigm where a pipeline is set up of sources, filters, and sinks
(collectively called pipeline modules or algorithms). Data *flows*
through this pipeline, being transformed at each node until it is in a form where
it can be consumed by the sinks. In previous chapters, we saw how to ingest data
into |ParaView| (:numref:`chapter:LoadingData`) and how to display it in
views (:numref:`chapter:DisplayingData`). If the data ingested into |ParaView|
already has all the relevant attribute data, and it is in the form that can be directly
represented in one the existing views, then that is all you would need.
The true power of the visualization process, however, comes from leveraging the
various visualization techniques such as slicing, contouring, clipping, etc.,
which are available as filters. In this chapter, we look at constructing
pipelines to transform data using such filters.
Understanding filters
=====================
In |ParaView|, filters are pipeline modules or algorithms that have inputs and
outputs. They take in data on their inputs and produce transformed data or
results on their outputs. A filter can have multiple input and output ports.
:index:`\ `\ :index:`\ `\ The
number of input and output ports on a filter is fixed. Each input port accepts
input data for a specific purpose or role within the filter. (E.g., the
``Resample With Dataset`` :index:`\ `\ filter has two input ports. The one called ``Input`` :index:`\ `\
is the input port through which the dataset providing the attributes to
interpolate is ingested. The other, called ``Source`` :index:`\ `\ , is the input port
through which the dataset used as the mesh on which to re-sample is accepted.)
.. figure:: ../images/UnderstandingFilters.png
:name: fig:UnderstandingFilters
:width: 40%
:align: center
A filter is a pipeline module with inputs and outputs.
Data enters a filter through the inputs. The filter transforms the data and
produces the resulting data on its outputs. A filter can have one or more input
and output ports. Each input port can optionally accept multiple input
connections.
An input port itself can optionally accept multiple input connections, e.g., the
``Append Datasets`` :index:`\ `\ filter, which appends multiple datasets to create a single
dataset only has one input port (named ``Input`` :index:`\ `\ ). However, that port can accept
multiple connections for each of the datasets to be appended :index:`\ `\ . Filters define
whether a particular input port can accept one or many input connections.
Similar to readers, the properties on the filter allow you to control the
filtering algorithm. The properties available depend on the filter itself.
.. \fixme{talk a little more about how different filters do different or similar things
and which filter to pick greatly depends on your memory etc etc e.g. difference in Clip
and Extract Subset and Slice etc.}
Creating filters in ``paraview``
================================
All available filters in |paraview| are listed under the :guilabel:`Filters`
menu. These are organized in various categories. To create a filter to transform
the data produced by a source or a reader, you select the source in the ``Pipeline
Browser`` :index:`\ `\
to make it active, and then click on the corresponding menu item in the
:guilabel:`Filters` menu. If a menu item is disabled, it implies that the active source
does not produce data that can be transformed by this filter.
.. admonition:: **Did you know?**
:class: tip
If a menu item in the :guilabel:`Filters` menu is disabled, it implies that the active
source(s) is not producing data of the expected type or the characteristics needed
by the filter. On Windows and Linux machines, if you hover over the disabled
menu item, the status bar will show the reason why the filter is not available.
.. figure:: ../images/DisabledFilterStatusBar.png
:width: 70%
:align: center
Multiple input connections
^^^^^^^^^^^^^^^^^^^^^^^^^^
When you create a filter, the active source is connected to the first input port
of the filter. Filters like ``Append Datasets`` :index:`\ `\ can take multiple input
connections on that input port. In such a case, to pass multiple pipeline
modules as connections on a single input port of a filter, select all the
relevant pipeline modules in the ``Pipeline Browser`` :index:`\ `\ . You can select multiple
items by using the |CTRL| (or |CMD|) and |SHIFT| key
modifiers. When multiple pipeline modules are selected, only the filters that
accept multiple connections on their input ports will be enabled in the
:guilabel:`Filters` menu.
.. \fixme{We need a chapter in the Reference Manual on Pipeline
browser explaining how to interpret pipelines in the Pipeline browser and how to
use it e.g. right clicking, selections etc.}
.. figure:: ../images/PipelineBrowserMultipleConnections.png
:name: fig:PipelineBrowserMultipleConnections
:width: 30%
:align: center
The ``Pipeline Browser`` :index:`\ `\ showing a pipeline with multiple input
connections. The ``Append Datasets`` :index:`\ `\ filter has two input connections on its
only input port, ``Sphere0`` :index:`\ `\ and ``Cone0`` :index:`\ `\ .
Multiple input ports
^^^^^^^^^^^^^^^^^^^^
Most filters have just one input port. Hence, as soon as you click on the filter
name in the :guilabel:`Filters` menu, it will create a new filter instance and that
will show up in the ``Pipeline Browser`` :index:`\ `\ . Certain filters, such as ``Resample
With Dataset`` :index:`\ `\ , have multiple inputs that must be set up before the filter can be
created. In such a case, when you click on the filter name, the ``Change Input
Dialog`` :index:`\ `\ will pop up, as seen in :numref:`fig:ChangeInputDialog`.
This dialog allows you to select the pipeline modules to be
connected to each of the input ports. The active source(s) is connected by
default to the first input port. You are free to change those as well.
.. figure:: ../images/ChangeInputDialog.png
:name: fig:ChangeInputDialog
:width: 80%
:align: center
The ``Change Input Dialog`` :index:`\ `\ is shown to allow you to pick inputs for
each of the input ports for a filter with multiple input ports. To use this
dialog, first select the ``Input Port`` :index:`\ `\ you want to edit on the left side, and
select the pipeline module(s) that are to be connected to this input port.
Repeat the step for the other input port(s). If an input port can accept
multiple input connections, you can select multiple modules, just like in the
``Pipeline Browser`` :index:`\ `\ .
Changing input connections
^^^^^^^^^^^^^^^^^^^^^^^^^^
|paraview| allows you to change the inputs to a filter after the
filter has been created. To change inputs to a filter, right-click on the filter
in the ``Pipeline Browser`` :index:`\ `\ to get the context menu, and then select ``Change
Input...`` :index:`\ `\ . This will pop up the same ``Change Input Dialog`` :index:`\ `\ as when creating a
filter with multiple input ports. You can use this dialog to set new inputs
for this filter.
.. figure:: ../images/ChangeInputContextMenu.png
:name: fig:ChangeInputContextMenu
:width: 80%
:align: center
The context menu in the ``Pipeline Browser`` :index:`\ `\ showing the option to
change inputs for a filter.
.. admonition:: **Did you know?**
:class: tip
While the :guilabel:`Filters` menu is a handy way to create new filters, with the long list
of filters available in |ParaView|, manually finding a particular filter in this
menu can be very challenging. To make it easier, |ParaView| incorporates a quick
launch mechanism. When you want to create a new filter (or a source), simply type
|CTRL| + |SPACE| or |ALT| + |SPACE|. This will pop up
the quick-launch dialog. Now, start typing the name of the filter you want. As
you type, the dialog will update to show the filters and sources that match the
typed text. You can use the arrow keys to navigate and use the |ENTER| key
to create the selected filter (or source). Note that filters may be disabled,
as was the case in the :guilabel:`Filters` menu but by default the selected item
will be the first enabled filter.
You can use |ESC| to clear the text you have typed so far. Hit the
|ESC| a second time, and the dialog will close without creating any new
filter.
You can also display the quick-launch dialog using
|CTRL| + |SHIFT| + |SPACE|, |ALT| + |SHIFT| + |SPACE|, or |CMD| + |SHIFT| + |SPACE|.
In this case, the selected filter will be automatically applied once created i.e. equivalent to
creating the filter and then clicking the ``Apply`` :index:`\ `\ button.
.. figure:: ../images/QuickLaunchDialog.png
:width: 50%
:align: center
Creating filters in ``pvpython``
================================
To create a filter in |pvpython|, you simply create the object by
using its name as a constructor function.
.. code-block:: python
>>> from paraview.simple import *
...
>>> filter = Shrink()
Similar to |paraview|, the filter will use the active source(s) as
the input. Additionally, you can explicitly specify the input in the function
arguments.
.. code-block:: python
>>> reader = OpenDataFile(...)
...
>>> shrink = Shift(Input=reader)
Multiple input connections
^^^^^^^^^^^^^^^^^^^^^^^^^^
To setup multiple input connections, you can specify the connections as follows:
.. code-block:: python
>>> sphere = Sphere()
>>> cone = Cone()
# Simply pass the sources as a list to the constructor function.
>>> appendDatasets = AppendDatasets(Input=[sphere, cone])
>>> print(appendDatasets.Input)
[, ]
Multiple input ports
^^^^^^^^^^^^^^^^^^^^
Setting up connections to multiple input ports is similar to the multiple input
connections, except that you need to ensure that you name the input ports properly.
.. code-block:: python
>>> sphere = Sphere()
>>> wavelet = Wavelet()
>>> resampleWithDataSet = ResampleWithDataset(Input=sphere, Source=wavelet)
.. _subsection:ChangingInputConnectionsPython:
Changing input connections
^^^^^^^^^^^^^^^^^^^^^^^^^^
Changing inputs in Python is as simple as setting any other property on the
filter.
.. code-block:: python
# For filter with single input connection
>>> shrink.Input = cone
# for filters with multiple input connects
>>> appendDatasets.Input = [reader, cone]
# to add a new input.
>>> appendDatasets.Input.append(sphere)
# to change multiple ports
>>> resampleWithDataSet.Input = wavelet2
>>> resampleWithDataSet.Source = cone
Changing filter properties in ``paraview``
==========================================
Filters provide properties that you can change to control the processing
algorithm employed by the filter. Changing and viewing properties on filters is
the same as with any other pipeline module, including readers and sources.
You can view and change these properties, when available, using the
``Properties`` :index:`\ `\ panel.
:numref:`chapter:PropertiesPanel` covers how to effectively use the
``Properties`` :index:`\ `\ panel. Since this panel only shows the properties present on the
*active source* :index:`\ `\ , you must ensure that the filter
you are interested in is active. To make the filter active, use the ``Pipeline
Browser`` :index:`\ `\ to click on the filter and select it.
Changing filter properties in ``pvpython``
==========================================
With |pvpython|, the available properties are accessible as properties
on the filter object, and you can get or set their values by name (similar to
changing the input connections
(:numref:`subsection:ChangingInputConnectionsPython`)).
.. code-block:: python
# You can save the object reference when it's created.
>>> shrink = Shrink()
# Or you can get access to the active source.
>>> Shrink() # <-- this will make the Shrink the active source.
>>> shrink = GetActiveSource()
# To figure out available properties, you can always use help.
>>> help(shrink)
Help on Shrink in module paraview.servermanager object:
class Shrink(SourceProxy)
| The Shrink filter
| causes the individual cells of a dataset to break apart
| from each other by moving each cell\'s points toward the
| centroid of the cell. (The centroid of a cell is the
| average position of its points.) This filter operates on
| any type of dataset and produces unstructured grid
| output.
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| Input
| This property specifies the input to the Shrink
| filter.
|
| ShrinkFactor
| The value of this property determines how far the points
| will move. A value of 0 positions the points at the centroid of the
| cell; a value of 1 leaves them at their original
| positions.
....
# To get the current value of a property:
>>> sf = shrink.ShrinkFactor
>>> print sf
0.5
# To set the value
>>> shrink.ShrinkFactor = 0.75
In the rest of this chapter, we will discuss some of the commonly used filters
in detail. They are grouped under categories based on the type of operation that they
perform.
Filters for sub-setting data
============================
These filters are used for extracting subsets from an input dataset. How this
subset is defined and how it is extracted depends on the type of the filter.
Clip
^^^^
``Clip`` :index:`\ `\ is used to clip any dataset using either an implicit function (such as
a plane, sphere, or a box) or using values of a scalar data array in the input
dataset. A scalar array is a point or cell attribute array with a single
component. Clipping involves iterating over all cells in the input dataset and then
removing those cells that are considered *outside* of the space defined by
the implicit function or that have an attribute values less than the selected value.
For cells that straddle the clipping surface, these are *clipped* to pass
through the part of the cell that is truly inside the specified implicit
function (or greater than the scalar value).
This filter converts any dataset into an unstructured grid
(:numref:`sec:VTKDataModel:UnstructuredGrid`) or a multi-block of
unstructured grids (:numref:`sec:MultiblockDataset`) in the case of composite
datasets.
Clip in ``paraview``
--------------------
.. figure:: ../images/CrinkleClipComparison.png
:name: fig:CrinkleClipComparison
:width: 80%
:align: center
Comparison between results produced by the ``Clip`` :index:`\ `\ filter with
``Crinkle Clip`` :index:`\ `\ unchecked (left) and checked (right) when clipping with an
implicit plane. The image on the left also shows the 3D widget used to
interactivly place the implicit plane for the clipping operation.
To create the ``Clip`` :index:`\ `\ filter, you can use the :guilabel:`Filters > Common` or
the :guilabel:`Filters > Alphabetical` menu. This filter is also accessible from the
``Common`` :index:`\ `\ filters toolbar. You can click the |pqClip24| button to create
this filter.
.. |pqClip24| image:: ../images/pqClip24.png
:width: 0.5cm
.. figure:: ../images/CommonFiltersToolbar.png
:name: fig:CommonFiltersToolbar
:width: 80%
:align: center
The ``Common`` :index:`\ `\ filters toolbar in |paraview| for quick
access to the commonly used filters.
On the ``Properties`` :index:`\ `\ panel, you will see the available properties for this
filter. One of the first things that you should select is the ``Clip Type`` :index:`\ `\ .
``Clip Type`` :index:`\ `\ is used to specify the type of implicit function to use for the
clipping operations. The available options include ``Plane`` :index:`\ `\ , ``Box`` :index:`\ `\ ,
``Sphere`` :index:`\ `\ , and ``Scalar`` :index:`\ `\ . Selecting any one of these options will update
the panel to show properties that are used to define the implicit function, e.g.,
the ``Origin`` :index:`\ `\ and the ``Normal`` :index:`\ `\ for the ``Plane`` :index:`\ `\ or the ``Center`` :index:`\ `\ and
the ``Radius`` :index:`\ `\ for the ``Sphere`` :index:`\ `\ . If you select ``Scalar`` :index:`\ `\ , the panel will let
you pick the data array and the value with which to clip. Remember, cells with the
data value greater than or equal to the selected value are considered *in*
and are passed through the filter.
.. admonition:: **Did you know?**
:class: tip
When clipping with implicit functions, |ParaView| renders widgets in the active
view that you can use to interactively control the implicit function, called
``3D widgets`` :index:`\ <3D widgets>`\ . As you interact with the 3D widget, the panel will update to
reflect the current values. The 3D widget is considered as an aid and not as a part
of the actual visualization scene. Thus, if you change the active source and the
``Properties`` :index:`\ `\ panel navigates away from this filter, the 3D widget will
automatically be hidden.
The ``Inside Out`` :index:`\ `\ option can be used to invert the behavior of this filter.
Basically, it flips the notion of what is considered inside and outside of the given
clipping space.
Check ``Crinkle Clip`` :index:`\ `\ if you don't want this filter to truly clip cells on the
boundary, but want to preserve the input cell structure and to pass the entire cell on through the
boundary (:numref:`fig:CrinkleClipComparison`).
This option is not available when clipping by ``Scalar`` :index:`\ `\ .
Clip in ``pvpython``
--------------------
This following script demonstrates various aspects of using the ``Clip`` :index:`\ `\ filter
in |pvpython|.
.. code-block:: python
# Create the Clip filter.
>>> clip = Clip(Input=...)
# Specify a 'ClipType' to use.
>>> clip.ClipType = 'Plane'
# You can also use the SetProperties API instead.
>>> SetProperties(clip, ClipType='Plane')
>>> print(clip.GetProperty('ClipType').GetAvailable())
['Plane', 'Box', 'Sphere', 'Scalar']
# To set the plane origin and normal
>>> clip.ClipType.Origin = [0, 0, 0]
>>> clip.ClipType.Normal = [1, 0, 0]
# If you want to change to Sphere and set center and
# radius, you can do the following.
>>> clip.ClipType = 'Sphere'
>>> clip.ClipType.Center = [0, 0, 0]
>>> clip.ClipType.Radius = 12
# Using SetProperties API, the same looks like
>>> SetProperties(clip, ClipType='Sphere')
>>> SetProperties(clip.ClipType, Center=[0, 0, 0],
Radius = 12)
# To set Crinkle clipping.
>>> clip.Crinkleclip = 1
# For clipping with scalar, you pick the scalar array
# and then the value as follows:
>>> clip.ClipType = 'Scalar'
>>> clip.Scalars = ('POINTS', 'Temp')
>>> clip.Value = 100
.. code-block:: python
# As always, to get the list of available properties on
# the clip filter, use help()
>>> help(clip)
Help on Clip in module paraview.servermanager object:
class Clip(SourceProxy)
| The Clip filter
| cuts away a portion of the input dataset using an
| implicit plane. This filter operates on all types of data
| sets, and it returns unstructured grid data on
| output.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| ClipType
| This property specifies the parameters of the clip
| function (an implicit plane) used to clip the dataset.
|
| Crinkleclip
| This parameter controls whether to extract entire cells
| in the given region or clip those cells so all of the output one stay
| only inside that region.
|
| Input
| This property specifies the dataset on which the Clip
| filter will operate.
|
| InsideOut
| If this property is set to 0, the clip filter will
| return that portion of the dataset that lies within the clip function.
| If set to 1, the portions of the dataset that lie outside the clip
| function will be returned instead.
...
# To get help on a specific implicit function type, make it the active
# ClipType and then use help()
>>> clip.ClipType = 'Plane'
>>> help(clip.ClipType)
Help on Plane in module paraview.servermanager object:
class Plane(Proxy)
...
.. \fixme{Missing GetAvailable API on ArraySelectionProperty. Also the API to get the available values is terrible. Need to fix it}
.. admonition:: **Common Errors**
:class: error
It is very easy to forget that clipping a structured dataset such as image
data can dramatically increase the memory requirements, since this filter will
convert the structured dataset into an unstructured grid due to the nature of
the clipping operation itself. For structured dataset, think about using
``Slice`` :index:`\ `\ or ``Extract Subset`` :index:`\ `\ filters instead, whenever appropriate. Those
are not entirely identical operations, but they are often sufficient.
Slice
^^^^^
.. figure:: ../images/SliceComparisons.png
:name: fig:SliceComparisons
:width: 80%
:align: center
Comparison between results produced by the ``Slice`` :index:`\ `\ filter
when slicing image data with an implicit plane with different options.
The lower-left image shows the output produced by the ``Clip`` :index:`\ `\ filter
when clipping with the same implicit function, for contrast.
The ``Slice`` :index:`\ `\ filter slices through the input dataset with an implicit function
such as a plane, a sphere, or a box. Since this filter returns data elements along
the implicit function boundary, this is a dimensionality reducing filter (except
when crinkle slicing is enabled), i.e., if
the input dataset has 3D elements like tetrahedrons or hexahedrons, the output
will have 2D elements, line triangles, and quads, if any. While slicing through a
dataset with 2D elements, the result will be lines.
The properties available on this filter, as well as the way of setting this
filter up, is very similar to the ``Clip`` :index:`\ `\ filter with a few notable
differences. What remains similar is the set up of the implicit function --
you have similar choices: ``Plane`` :index:`\ `\ , ``Box`` :index:`\ `\ , ``Sphere`` :index:`\ `\ , and ``Cylinder`` :index:`\ `\ , as well as the
option to toggle ``Crinkle slice`` :index:`\ `\ (i.e., to avoid cutting through cells,
pass complete cells from the input dataset that intersects the implicit function).
What is different includes the lack of slicing by ``Scalar`` :index:`\ `\ (for that, you
can use the ``Contour`` :index:`\ `\ filter) and a new option, ``Triangulate the slice`` :index:`\ `\ .
:numref:`fig:SliceComparisons`
shows the difference in the generated meshes when various slice properties are
changed.
The ``Slice`` :index:`\ `\ filter is more versatile than the ``Slice`` :index:`\ `\ representation. First,
the ``Slice`` :index:`\ `\ representation is available for image datasets only, whereas the
``Slice`` :index:`\ `\ filter can be used on any type of 3D dataset. Second, the representation
extracts a subset of the image consisting of a 2D slice oriented in the XY,
YZ, or XZ planes at the image voxel locations while the plane used by the filter
can be placed arbitrarily. Third, since the ``Slice`` :index:`\ `\ representation always
shows a flat object and lighting may interfere with interpretation of data values
on the slice, lighting is not applied to the ``Slice`` :index:`\ `\ representation. Lighting
is applied, however, to results from the ``Slice`` :index:`\ `\ filter. Lastly, the ``Slice`` :index:`\ `\
representation may be faster than the filter to update and scrub through different
slices because it does not need to compute the intersection of a plane with cells
in the dataset.
In |paraview|, this filter can be created using the
|pqSlice24| button on the ``Common`` :index:`\ `\ filters toolbar, besides the
:guilabel:`Filters` menu.
.. |pqSlice24| image:: ../images/pqSlice24.png
:width: 0.5cm
Extract Subset
^^^^^^^^^^^^^^
.. figure:: ../images/ExtractSubsetPanel.png
:name: fig:ExtractSubsetPanel
:width: 60%
:align: center
The ``Properties`` :index:`\ `\ panel for the ``Extract Subset`` :index:`\ `\ filter showing all
available properties (including the advanced properties).
For structured datasets such as
image datasets (:numref:`sec:VTKDataModel:UniformRectilinearGrid`), rectilinear grids
(:numref:`sec:VTKDataModel:RectilinearGrid`), and
curvilinear grids (:numref:`sec:VTKDataModel:CurvilinearGrid`), ``Extract
Subset`` :index:`\ `\ filter can be used to extract a region of interest or a subgrid. The
region to extract is specified using structured coordinates, i.e., the
:math:`i`, :math:`j`, :math:`k` values. Whenever possible, this filter should be preferred over
``Clip`` :index:`\ `\ or ``Slice`` :index:`\ `\ for structured datasets, since it preserves the input
data type. Besides extracting a subset, this filter can also be used to resample
the dataset to a coarser resolution by specifying the sample rate along each of
the structured dimensions.
Extract Subset in ``paraview``
------------------------------
This is one of the filters available on the ``Common`` :index:`\ `\ filters toolbar |pqExtractGrid24|
To specify the region of interest, use the ``VOI`` :index:`\ `\ property. The values are
specified as min and max values for each of the structured dimensions (:math:`i`, :math:`j`,
:math:`k`,) in each row. ``Sample Rate I`` :index:`\ `\ , ``Sample Rate J`` :index:`\ `\ ,
and ``Sample Rate K`` :index:`\ `\ specify the sub-sampling rate. Set it to a value greater than one to sub-sample.
``Include Boundary`` :index:`\ `\ is used to determine if the boundary slab should be
included in the extracted result, if the sub-sampling rate along that dimension
is greater than 1, and the boundary slab would otherwise have been skipped.
.. |pqExtractGrid24| image:: ../images/pqExtractGrid24.png
:width: 0.5cm
Threshold
^^^^^^^^^
.. figure:: ../images/ThresholdResult.png
:name: fig:ThresholdResult
:width: 80%
:align: center
Results from using the ``Threshold`` :index:`\ `\ filter on the *iron_protein.vtk* dataset from |ParaView| data.
The ``Threshold`` :index:`\ `\ filter
extracts the portions of the input dataset whose
scalars lie within the specified range. This filter operates on either
point-centered or cell-centered data. This filter operates on any type of
dataset and produces an unstructured grid output. To use this filter, you select
the ``Scalars`` :index:`\ `\ with which to threshold, and then specify the data range that
selects which cells are included in the output.
When thresholding with cell data, all cells that have scalars within the
specified range will be passed through the filter. When thresholding with point
data, cells with *all* points with scalar values within the range are passed
through if ``All Scalars`` :index:`\ `\ is checked; otherwise, cells with *any* point
that passes the thresholding criteria are passed through.
Threshold in ``paraview``
-------------------------
.. figure:: ../images/ThresholdPanel.png
:name: fig:ThresholdPanel
:width: 40%
:align: center
The ``Properties`` :index:`\ `\ panel for the ``Threshold`` :index:`\ `\ filter.
This filter is represented as |pqThreshold24| on the ``Common`` :index:`\ `\ filters
toolbar. After selecting the ``Scalars`` :index:`\ `\ with which to threshold from the combo-box, you
select the ``Minimum`` :index:`\ `\ and ``Maximum`` :index:`\ `\ values to specify the range. If the
range shown by the sliders is not sufficient, you can manually type the values
in the input boxes. The values are deliberately not clamped to the current data
range. The ``Scalars`` :index:`\ `\ combo-box uses icons to help you differentiate between
point data arrays |pqNodalData16| and cell data arrays |pqCellData16|
.. |pqThreshold24| image:: ../images/pqThreshold24.png
:width: 0.5cm
.. |pqNodalData16| image:: ../images/pqNodalData16.png
:width: 0.5cm
.. |pqCellData16| image:: ../images/pqCellData16.png
:width: 0.5cm
Threshold in ``pvpython``
-------------------------
.. code-block:: python
# Create the filter. If Input is not specified, the active source will be
# used as the input.
>>> threshold = Threshold(Input=...)
# Here's how to select a scalar array.
>>> threshold.Scalars = ("POINTS", "scalars")
# The value is a tuple with first value as the association:
# either "POINTS" or "CELLS" and the second value is the name of the selected
array.
>>> print(threshold.Scalars)
['POINTS', 'scalars']
>>>> print(threshold.Scalars.GetArrayName())
'scalars'
>>> print(threshold.Scalars.GetAssociation())
'POINTS'
# The threshold range is specified as:
>>> threshold.ThresholdRange = [63.75, 252.45]
To determine the types of arrays available in the input dataset, and their
ranges, refer to the discussion on data information in
:numref:`sec:DataInformationInPython`.
Iso Volume
^^^^^^^^^^
The ``Iso Volume`` :index:`\ `\ filter is similar to ``Threshold`` :index:`\ `\ in that you use this to
create an output dataset from an input where the cells that satisfy the
specified range are scalar values. In fact, the filter is identical to
``Threshold`` :index:`\ `\ when the cell data scalars are selected. For point data scalars,
however, this filter acts similar to the ``Clip`` :index:`\ `\ filters when clipping with
scalars, in that cells are clipped along the iso-surface formed by the scalar range.
.. \fixme{this explanation could be improved.}
Extract Selection
^^^^^^^^^^^^^^^^^
``Extract Selection`` :index:`\ `\ is a general-purpose filter to extract selected elements
from a dataset. There are several ways of making selections in |ParaView|. Once
you have made the selection, this filter allows you to extract the selected
elements as a new dataset for further processing. We will cover this filter in
more detail when looking at selections in |ParaView| in
:numref:`sec:ExtractingSelections`.
Filters for geometric manipulation
==================================
These filters are used to transform the geometry of the dataset without affecting its topology or its connectivity.
Transform
^^^^^^^^^
The ``Transform`` :index:`\ `\ can be used to arbitrarily translate, rotate, and scale a
dataset. The transformation is applied by
scaling the dataset, rotating it, and then translating it
based on the values specified.
As this is a geometric manipulation filter, this filter does not affect
connectivity in the input dataset. While it tries to preserve the input dataset
type, whenever possible, there are cases when the transformed dataset can no
longer be represented in the same data type as the input. For example, with
image data (:numref:`sec:VTKDataModel:UniformRectilinearGrid`) and
rectilinear grids (:numref:`sec:VTKDataModel:RectilinearGrid`) that are
transformed by rotation, the output dataset can be non-axis aligned and, hence,
cannot be represented as either data types. In such cases, the dataset is
converted to a structured, or curvilinear, grid
(:numref:`sec:VTKDataModel:CurvilinearGrid`). Since curvilinear grids are
not as compact as the other two, the need to store the results in a more general
data type implies a considerable increase in the memory footprint.
Transform in ``paraview``
^^^^^^^^^^^^^^^^^^^^^^^^^
You can create a new ``Transform`` :index:`\ `\ from the :guilabel:`Filters > Alphabetical` menu.
Once created, you can set the transform as the translation, rotation, and scale
to use utilizing the ``Properties`` :index:`\ `\ panel. Similar to ``Clip`` :index:`\ `\ , this filter also
supports using a 3D widget to interactively set the transformation.
.. figure:: ../images/TransformWithWidget.png
:name: fig:TransformWithWidget
:width: 40%
:align: center
The ``Transform`` :index:`\ `\ filter showing the 3D widget that can be used to interactively set the transform.
Transform in ``pvpython``
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python
# To create the filter(if Input is not specified, the active source will be
# used as the input).
>>> transform = Transform(Input=...)
# Set the transformation properties.
>>> transform.Translate.Scale = [1, 2, 1]
>>> transform.Transform.Translate = [100, 0, 0]
>>> transform.Transform.Rotate = [0, 0, 0]
Reflect
^^^^^^^
.. figure:: ../images/ReflectFilter.png
:name: fig:ReflectFilter
:width: 40%
:align: center
The ``Reflect`` :index:`\ `\ filter can be used to reflect a dataset along a specific axis plane.
``Reflect`` :index:`\ `\ can be used to reflect any dataset across an axis plane. You can
pick the axis plane to be one of the planes formed by the bounding box of the
dataset. For that, set ``Plane`` :index:`\ `\ as ``X Min`` :index:`\ `\ , ``X Max`` :index:`\ `\ , ``Y Min`` :index:`\ `\ , ``Y Max`` :index:`\ `\ ,
``Z Min`` :index:`\ `\ , or ``Z Max`` :index:`\ `\ . To reflect across an arbitrary axis plane,
select ``X`` :index:`\ `\ , ``Y`` :index:`\ `\ , or ``Z`` :index:`\ `\ for the ``Plane`` :index:`\ `\ property, and then set the
``Center`` :index:`\ `\ to the plane offset from the origin.
This filter reflects the input dataset and produces an unstructured grid
(:numref:`sec:VTKDataModel:UnstructuredGrid`). Thus, the same caveats for
``Clip`` :index:`\ `\ and ``Threshold`` :index:`\ `\ filter apply here when dealing with structured
datasets.
Warp By Vector
^^^^^^^^^^^^^^
.. figure:: ../images/WarpByVector.png
:name: fig:WarpByVector
:width: 40%
:align: center
The ``Warp By Vector`` :index:`\ `\ filter can be used to
displace points in original data shown on the left, using the
*displacement* vectors (indicated by arrow glyphs :numref:`sec:Glyph`) to
produce the result shown on the right.
``Warp By Vector`` :index:`\ `\ can be used to displace point coordinates in an input mesh
using vectors in the dataset itself. You select the vectors to use utilizing the
``Vectors`` :index:`\ `\ property on the ``Properties`` :index:`\ `\ panel. ``Scale Factor`` :index:`\ `\ can be
used to scale the displacement applied.
Warp By Scalar
^^^^^^^^^^^^^^
``Warp By Scalar`` :index:`\ `\ is similar to ``Warp By Vector`` :index:`\ `\ in the sense that it warps
the input mesh. However, it does so using a scalar array in the input dataset. The
direction of displacement can either be explicitly specified using the
``Normal`` :index:`\ `\ property, or you can check ``Use Normal`` :index:`\ `\ to use normals at the
point locations.
Filters for sampling
====================
These filters compute new datasets that represent some essential features from
the datasets that they take as input.
.. _sec:Glyph:
Glyph
^^^^^
``Glyph`` :index:`\ `\ is used to place markers or glyphs at point locations in the input
dataset. The glyphs can be oriented or scaled based on vector and
scalar attributes on those points.
To create this filter in |paraview|, you can use the :guilabel:`Filters` menu,
as well as the |pqGlyph24|
button on the ``Common`` :index:`\ `\ filters toolbar. You first select
the type of glyph using one of the options in ``Glyph Type`` :index:`\ `\ . The choices
include ``Arrow`` :index:`\ `\ , ``Sphere`` :index:`\ `\ , ``Cylinder`` :index:`\ `\ , etc. Next, you select the point
arrays to use as the ``Orientation Array`` :index:`\ `\ (selecting ``No orientation array`` :index:`\ `\
will result in the glyphs not being oriented). Similarly, you select a point array
to serve as the glyph ``Scale Array`` :index:`\ `\ (no scaling is performed if ``No scale array`` :index:`\ `\
is chosen).
.. |pqGlyph24| image:: ../images/pqGlyph24.png
:width: 0.5cm
If the ``Scale Array`` :index:`\ `\ is set to a vector array, the ``Vector Scale Mode`` :index:`\ `\
property is available to select which properties of the vector should be used
to transform each glyph. If ``Scale by Magnitude`` :index:`\ `\ is chosen, then the glyph
at a point will be scaled by the magnitude of the vector at that point. If
``Scale by Components`` :index:`\ `\ is chosen, glyphs will be scaled separately in each
dimension by the vector component in that dimension.
.. figure:: ../images/GlyphPropertiesPanel.png
:name: fig:GlyphPropertiesPanel
:width: 80%
:align: center
The ``Properties`` :index:`\ `\ panel for the ``Glyph`` :index:`\ `\ filter.
The ``Scale Factor`` :index:`\ `\ is used to apply a constant scaling to all the glyphs,
independent of the ``Scale Array`` :index:`\ `\ and ``Vector Scale Mode`` :index:`\ `\ properties.
Choosing a good scale factor depends on
several things including the bounds on the input dataset, the ``Scale Array`` :index:`\ `\
and ``Vector Scale Mode`` :index:`\ `\ selected, and the range for the array selected as the
``Scale Array`` :index:`\ `\ . You can use the |ReloadButton|
button next to the ``Scale Factor`` :index:`\ `\ widget to have |paraview|
pick a usually reasonable scale factor value based on the current dataset and
scaling properties.
.. |ReloadButton| image:: ../images/ReloadButton.png
:width: 0.5cm
The ``Masking`` :index:`\ `\ properties control which points from the input
dataset get glyphed. The ``Glyph Mode`` :index:`\ `\ controls how points are selected to be
glyphs (:numref:`fig:GlyphModesComparison`). The available options are as follows:
* ``All Points`` :index:`\ `\ : This selects all points in the input dataset for glyphing.
Use this mode with caution and only when the input dataset has relatively few
points. Since all points in the input dataset are glyphed, this can not only
cause visual clutter, but also clog up memory and take a long to time to
generate and render the glyphs.
* ``Every Nth Points`` :index:`\ `\ : This elects every :math:`n^{th}` point in the input dataset
for glyphing, where :math:`n` can be specified using ``Stride`` :index:`\ `\ . Setting
``Stride`` :index:`\ `\ to 1 will have the same effect as ``All Points`` :index:`\ `\ .
* ``Uniform Spatial Distribution`` :index:`\ `\ : This selects a random set of points. The
algorithm works by first computing up to ``Maximum Number of Sample Points`` :index:`\ `\
in the space defined by the bounding box of the input dataset. Then, points
in the input dataset that are close to the point in this set of sample points
are glyphed. The ``Seed`` :index:`\ `\ is used to seed the random number generator used to
generate the sample points. This ensures that the random sample points are
reproducible and consistent.
.. figure:: ../images/GlyphModesComparison.png
:name: fig:GlyphModesComparison
:width: 80%
:align: center
Comparison between various ``Glyph Mode`` :index:`\ `\ s when applied to the same
dataset generated by the ``Wavelet`` :index:`\ `\ source.
.. admonition:: **Did you know?**
:class: tip
The ``Glyph`` :index:`\ `\ representation can be used for many of the same visualizations
where a ``Glyph`` :index:`\ `\ filter might be used. It may offer faster rendering and consume
less memory than the ``Glyph`` :index:`\ `\ filter with similar capabilities. In circumstances
where generating a 3D geometry is required, e.g., when exporting glyph geometry
to a file, the ``Glyph`` :index:`\ `\ filter is required.
Glyph With Custom Source
^^^^^^^^^^^^^^^^^^^^^^^^
``Glyph With Custom Source`` :index:`\ `\ is the same as ``Glyph`` :index:`\ `\ , except that instead of a limited
set of ``Glyph Type`` :index:`\ `\ , you can select any data source producing a polygonal
dataset (:numref:`sec:VTKDataModel:PolyData`) available in the ``Pipeline
Browser`` :index:`\ `\ . To use this filter, select the data source you wish to glyph in the
``Pipeline Browser`` :index:`\ `\ and attach this filter to it. You will be presented a dialog
where you can set the ``Input`` :index:`\ `\ (which defaults to the source you selected) and
the ``Glyph Source`` :index:`\ `\ .
.. figure:: ../images/GlyphWithCustomSourceInputDialog.png
:width: 80%
:align: center
Setting the ``Input`` :index:`\ `\ and ``Glyph Source`` :index:`\ `\ in the ``Glyph With Custom Source`` :index:`\ `\ filter.
Stream Tracer
^^^^^^^^^^^^^
.. figure:: ../images/StreamlinesInParaView.png
:name: fig:StreamlinesInParaView
:width: 80%
:align: center
Streamlines generated from the ``disk_out_ref.ex2`` dataset
using the ``Point Source`` :index:`\ `\ (left) and the ``High Resolution Line Source`` :index:`\ `\
(right). On the left, we also added the ``Tube`` :index:`\ `\ filter to the output of the
``Stream Tracer`` :index:`\ `\ filter to generate 3D tubes rather than 1D polygonal lines,
which can be hard to visualize due to lack of shading.
The ``Stream Tracer`` :index:`\ `\ filter is used to generate streamlines for vector fields.
In visualization, streamlines refer to curves that are instanteneously
tangential to the the vector field in the dataset. They provide an indication of
the direction in which the particles in the dataset would travel at that instant
in time. The algorithm works by taking a set of points, known as *seed*
points, in the dataset and then integrating the streamlines starting at these seed
points.
In |paraview|, you can create this filter using the :guilabel:`Filters`
menu, as well as the |pqStreamTracer24| button on the ``Common`` :index:`\ `\
filters toolbar. To use
this filter, you first select the attribute array to use as the ``Vectors`` :index:`\ `\ for
generating the streamline. ``Integration Parameters`` :index:`\ `\ let you fine tune the
streamline integration by specifying the direction to integrate,
``Integration Direction`` :index:`\ `\ , as well as the type of integration algorithm to
use, ``Integrator Type`` :index:`\ `\ . Advanced integration parameters are available in the
advanced view of the ``Properties`` :index:`\ `\ panel that let you further tune the
integration, including specifying the step size and others. You use the
``Maximum Streamline Length`` :index:`\ `\ to limit the maximum length for the streamline --
the longer the length, the longer the generated streamlines.
.. |pqStreamTracer24| image:: ../images/pqStreamTracer24.png
:width: 0.5cm
.. figure:: ../images/StreamlinesPropertiesPanel.png
:width: 80%
:align: center
The ``Properties`` :index:`\ `\ panel showing the default properties for the
``Stream Tracer`` :index:`\ `\ filter.
``Seeds`` :index:`\ `\ group lets you set how the seed points for generating the streamlines
are produced. You have two options: ``Point Source`` :index:`\ `\ , which produces a point
clound around the user-specified ``Point`` :index:`\ `\ based on the parameters specified,
and ``High Resolution Line Source`` :index:`\ `\ , which produces seed points along the user-specified
line. You can use the 3D widgets shown in the active ``Render View`` :index:`\ `\
to interactively place the center for the point cloud or for defining the line.
.. admonition:: **Did you know?**
:class: tip
The ``Stream Tracer`` :index:`\ `\ filter produces a polydata with 1D lines for each of the
generated streamlines. Since 1D lines cannot be shaded like surfaces in the
``Render View`` :index:`\ `\ , you can get visualizations where it is hard to follow the
streamlines. To give the streamlines some 3D structure, you can apply the
``Tube`` :index:`\ `\ filter to the output of the streamlines. The properties on the
``Tube`` :index:`\ `\ filter let you control the thickness of the tubes. You can also vary
the thickness of the tubes based on data array, e.g., the magnitude of the
vector field at the sample points in the streamline!
A script using the ``Stream Tracer`` :index:`\ `\ filter in |paraview| typically
looks like this:
.. code-block:: python
# find source
>>> disk_out_refex2 = FindSource('disk_out_ref.ex2')
# create a new 'Stream Tracer'
>>> streamTracer1 = StreamTracer(Input=disk_out_refex2,
SeedType='Point Source')
>>> streamTracer1.Vectors = ['POINTS', 'V']
# init the 'Point Source' selected for 'SeedType'
>>> streamTracer1.SeedType.Center = [0.0, 0.0, 0.07999992370605469]
>>> streamTracer1.SeedType.Radius = 2.015999984741211
# show data in view
>>> Show()
# create a new 'Tube'
>>> tube1 = Tube(Input=streamTracer1)
# Properties modified on tube1
>>> tube1.Radius = 0.1611409378051758
# show the data from tubes in view
>>> Show()
Stream Tracer With Custom Source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``Stream Tracer`` :index:`\ `\ allows you to specify the seed points either as a point cloud
or as a line source. However, if you want to provide your own seed points from
another data producer, use the ``Stream Tracer With Custom Source`` :index:`\ `\ . Similar to
``Glyph With Custom Source`` :index:`\ `\ , this filter allows you to pick a second input
connection to use as the seed points.
.. figure:: ../images/StreamTracerWithCustomSource.png
:name: fig:StreamTracerWithCustomSource
:width: 80%
:align: center
Streamlines generated from the ``disk_out_ref.ex2`` dataset using the output of the ``Slice`` :index:`\ `\ filter as the ``Source`` :index:`\ `\ for seed points.
Resample With Dataset
^^^^^^^^^^^^^^^^^^^^^
.. figure:: ../images/ResampleWithDataset.png
:name: fig:ResampleWithDatasetExample
:width: 80%
:align: center
An example of ``Resample With Dataset`` :index:`\ `\ . On the left is
a multiblock tetrahedra mesh ( ``Input`` :index:`\ `\ ). The middle shows
a multiblock unstructured grid ( ``Source`` :index:`\ `\ ). The outline of ``Input`` :index:`\ `\ is
also shown in this view. The result of applying the filter is shown on
the right
``Resample With Dataset`` :index:`\ `\ samples the point and cell attributes of one dataset
on to the points of another dataset. The two datasets are supplied to the
filter using its two input ports: ``Input`` :index:`\ `\ , which is the dataset that
provides the attributes to resample, and ``Source`` :index:`\ `\ , which is the dataset that
provides the points to sample at. This filter is available under the
:guilabel:`Filters` menu.
Resample To Image
^^^^^^^^^^^^^^^^^
``Resample To Image`` :index:`\ `\ is a specialization of ``Resample With Dataset`` :index:`\ `\ .
The filter takes one input and samples its point and cell attributes onto a
uniform grid of points. The bounds and extents of the uniform grid can be
specified using the properties panel. By default, the bounds are set to the
bounds of the input dataset. The output of the filter is an Image dataset.
.. figure:: ../images/ResampleToImageProperties.png
:name: fig:ResampleToImageProperties
:width: 80%
:align: center
The ``Properties`` :index:`\ `\ panel for ``Resample To Image`` :index:`\ `\ filter.
.. figure:: ../images/ResampleToImageExample.png
:name: fig:ResampleToImageExample
:width: 80%
:align: center
An example of ``Resample To Image`` :index:`\ `\ . The left portion shows the input
(unstructured grid), and the middle displays the output image data.
On the right is a volume rendering of the resampled data.
Some operations can be performed more efficiently on uniform grid datasets.
Volume rendering is one such operation. The ``Resample to Image`` :index:`\ `\ filter can
be used to convert any dataset to Image data before performing such operations.
Probe
^^^^^
``Probe`` :index:`\ `\ samples the input dataset at a specific point location to obtain the
cell data attributes for the cell containing the point as well as the interpolated point
data attributes. You can either use the ``SpreadSheet View`` :index:`\ `\ or the
``Information`` :index:`\ `\ panel to inspect the probed values. The probe location can be
specified using the interactive 3D widget shown in the active ``Render View`` :index:`\ `\ .
Plot over line
^^^^^^^^^^^^^^
.. figure:: ../images/PlotOverLineInParaView.png
:name: fig:PlotOverLineInParaView
:width: 80%
:align: center
The ``Plot Over Line`` :index:`\ `\ filter applied to the ``disk_out_ref.ex2``
dataset to plot values at sampled locations along the line. Gaps in the line correspond
to the locations in the input dataset where the line falls outside the dataset.
``Plot Over Line`` :index:`\ `\ will sample the input dataset along the specified line and
then plot the results in ``Line Chart View`` :index:`\ `\ . Internally, this filter uses the
same mechanism as the ``Probe`` :index:`\ `\ filter, probing along the points in the
line to get the containing cell attributes and interpolated point attributes.
Using the ``Resolution`` :index:`\ `\ property on the ``Properties`` :index:`\ `\ panel, you can control
the number of sample points along the line.
Filters for attribute manipulation
==================================
The filters covered in this section are used to add new attribute arrays to the
dataset, which are typically used to add derived quantities to use in pipelines for
further processing.
Calculator
^^^^^^^^^^
The ``Calculator`` :index:`\ `\ filter computes a new data array or new point coordinates as a
function of existing input arrays. If point-centered arrays are used
in the computation of a new data array, the resulting array will also be
point-centered. Similarly, computations using cell-centered arrays will produce
a new cell-centered array. If the function is computing point coordinates
(requested by checking the ``Coordinate Results`` :index:`\ `\ property on the
``Properties`` :index:`\ `\ panel) , the
result of the function must be a three-component vector. The ``Calculator`` :index:`\ `\
interface operates similarly to a scientific calculator. In creating the
function to evaluate, the standard order of operations applies. Each of the
calculator functions is described below. Unless otherwise noted, enclose the
operand in parentheses using the ``(`` and ``)`` buttons.
* ``Clear`` :index:`\ `\ : Erase the current function.
* ``/``: Divide one scalar by another. The operands for this function are not required to be enclosed in parentheses.
* ``*``: Multiply two scalars, or multiply a vector by a scalar (scalar multiple). The operands for this function are not required to be enclosed in parentheses.
* ``-``: Negate a scalar or vector (unary minus), or subtract one scalar or vector from another. The operands for this function are not required to be enclosed in parentheses.
* ``+``: Add two scalars or two vectors. The operands for this function are not required to be enclosed in parentheses.
* ``sin`` :index:`\ `\ : Compute the sine of a scalar.
* ``cos`` :index:`\ `\ : Compute the cosine of a scalar.
* ``tan`` :index:`\ `\ : Compute the tangent of a scalar.
* ``asin`` :index:`\ `\ : Compute the arcsine of a scalar.
* ``acos`` :index:`\ `\ : Compute the arccosine of a scalar.
* ``atan`` :index:`\ `\ : Compute the arctangent of a scalar.
* ``sinh`` :index:`\ `\ : Compute the hyperbolic sine of a scalar.
* ``cosh`` :index:`\ `\ : Compute the hyperbolic cosine of a scalar.
* ``tanh`` :index:`\ `\ : Compute the hyperbolic tangent of a scalar.
* ``min`` :index:`\ `\ : Compute minimum of two scalars.
* ``max`` :index:`\ `\ : Compute maximum of two scalars.
* ``x^y`` :index:`\ `\ : Raise one scalar to the power of another scalar. The operands for this function are not required to be enclosed in parentheses.
* ``sqrt`` :index:`\ `\ : Compute the square root of a scalar.
* ``e^x`` :index:`\ `\ Raise e to the power of a scalar.
* ``log10`` :index:`\ `\ : Compute the logarithm of a scalar to the base 10.
* ``ln`` :index:`\ `\ : Compute the logarithm of a scalar to the base :math:`e`.
* ``ceil`` :index:`\ `\ : Compute the ceiling of a scalar.
* ``floor`` :index:`\ `\ : Compute the floor of a scalar.
* ``abs`` :index:`\ `\ : Compute the absolute value of a scalar.
* ``v1.v2`` :index:`\ `\ : Compute the dot product of two vectors. The operands for this function are not required to be enclosed in parentheses.
* ``cross`` :index:`\ `\ : Compute cross product of two vectors.
* ``mag`` :index:`\