# Probe filter example

Using the probe filter to visualize a scalar field along an arbitrary surface.

This example shows how a data set can be ‘projected’ (or interpolated) on another given source using the probe filter. It is also an example of a complex VTK pipeline and shows how to inspect it with the PipelineBrowser.

In this example, a function is sampled on a regular grid and can be visualized using an ImagePlaneWidget. The function we are interested is independent of the distance to the origin and a function only of the angle. This is why it may be interesting to visualize its value sampled on a sphere center at the origin, but we have the data sampled throughout the volume on a regular grid.

We create a sphere with the BuiltinSurface source and use the VTK ProbeFilter to sample the data on this surface. The ProbeFilter takes one input, which is the data structure to project the data on, and a ‘source’, which is where the data values come from.

We need to use the UserDefined filter to insert this VTK filter in the Mayavi pipeline (see Using the UserDefined filter as well as Image cursor filter example and Tvtk segmentation example). Specifying its input is done automatical when it is inserted on the pipeline, be its source needs to be specified explicitly. As it is a VTK filter, the source is the VTK dataset output by the Mayavi object: we can find it in .outputs[0].

Note that this filter violates slightly the simple pipeline model that Mayavi tries to expose to the users: it has two entries. As a result, the Mayavi pipeline is not longer really a tree. However, if you open up the Mayavi pipeline view, you can see that the ProbeFilter has only one parent in the view. To inspect the actually VTK pipeline underlying this visualization, we use the TVTK PipelineBrowser at the end of the example. You can see that the VTK pipeline is much more complex that the pipeline represented in Mayavi: actors, data mappers, and other elements of the VTK pipeline are collapsed in the Mayavi filters and modules.

Note that, as we know the expression of the function, it would be simpler and more efficient to directly sample it on the sphere.

Python source code: `probe_filter.py`

    import numpy as np

    from mayavi import mlab
    from tvtk.api import tvtk
    from tvtk.common import configure_source_data, configure_input

    # The angular par of the spherical harmonic (3, 2)
    x, y, z = np.mgrid[-.5:.5:100j, -.5:.5:100j, -.5:.5:100j]
    Phi = np.angle((x+y*1j)**2*z)

    field = mlab.pipeline.scalar_field(x, y, z, Phi)
    ipw = mlab.pipeline.image_plane_widget(field)
    mlab.outline(field)

    surface = mlab.pipeline.builtin_surface()
    surface.source = 'sphere'
    surface.data_source.radius = .4
    surface.data_source.phi_resolution = 200
    surface.data_source.theta_resolution = 200
    probe_filter = tvtk.ProbeFilter()
    configure_input(probe_filter, surface.data_source)
    configure_source_data(probe_filter, field.outputs[0])
    probe = mlab.pipeline.user_defined(surface, filter=probe_filter)

    surf = mlab.pipeline.surface(probe)

    fig = mlab.gcf()

    ################################################################################
    # Finally, to inspect the VTK Pipeline (and not the Mayavi one, we
    # use the TVTK pipeline browser)
    # Note that for Mayavi version < 3.4.1, there is a bug in the
    # PipelineBrowser preventing a good display of this pipeline.
    from tvtk.pipeline.browser import PipelineBrowser
    browser = PipelineBrowser(fig.scene)
    browser.show()

    mlab.show()