# Image cursor filter example

Excample using the UserDefined filter to paint a cross-shaped cursor on data, in order to point out a special position.

We use the UserDefined filter ImageCursor3D to create the cursor. A Gaussian data field is painted with the cursor, and then visualized using the ImagePlaneWIdget module.

ImageCursor3D is one example among many of the use of the UserDefined, which allows to use TVTK filters that are not. See Using the UserDefined filter for more details. Also, other examples using the UserDefined filter are provided in Mri example and Tvtk segmentation example.

Selecting the UserDefined filter in the Mayavi pipeline is a convenient way to look for additional filters. This pops up a dialog called TVTK class chooser, with a Search field that allows to search for desired actions or properties. For example, searching for cursor returns several filters, among which Cursor3D and ImageCursor3D. As a rule of thumb, the name of TVTK filters acting on TVTK ImageData dataset starts with Image (ImageData is the type of VTK data set created by e.g. mlab.pipeline.scalar_field. See Data representation in Mayavi for more details about VTK datasets). In the dialog used to interactively add the UserDefined filet, we can therefore select ImageCursor3D. The documentation of the filter is displayed when selecting its name within the Class name field of the dialog.

Python source code: `image_cursor_filter.py`

    # Authors: Emmanuelle Gouillart <emmanuelle.gouillart@normalesup.org>
    # and Gael Varoquaux <gael.varoquaux@normalesup.org>
    # Copyright (c) 2009, Enthought, Inc.
    # License: BSD Style.

    from mayavi import mlab
    import numpy as np

    # Define Gaussian data field
    x, y, z = np.ogrid[0:1:40j, 0:1:40j, 0:1:40j]
    sig = 0.5
    center = 0.5
    g = np.exp(-((x-center)**2 + (y-center)**2 + (z-center)**2)/(2*sig**2))

    ################################################################################

    mlab.figure(fgcolor=(0, 0, 0), bgcolor=(1, 1, 1))

    # Define the cursor
    s = mlab.pipeline.scalar_field(g)
    cursor = mlab.pipeline.user_defined(s, filter='ImageCursor3D')

    # The TVTK filter used by Mayavi is accessible as the '.filter'
    # attribute of the Mayavi filtered returned by user_defined.
    # We can set the graphical properties of the cross via attributes of
    # cursor.filter, and not of cursor itself. Here cursor is a Mayavi filter,
    # that is an object that inserts in the Mayavi pipeline, whereas
    # cursor.filter is the TVTK filter that actually does the work.

    # Put the cursor at the center of the field volume (default is (0, 0, 0))
    cursor.filter.cursor_position = np.array([20, 20, 20])
    # Define the value of the cursor (default is 255) so that there is
    # enough contrast between the cursor and the data values in the neighbourhood
    # of the cursor. The cursor value is within the data value range so that
    # the contrast of the data is not altered.
    cursor.filter.cursor_value = 0
    # Define the radius of the cross (the extent of the cross is 2xcursor_radius)
    cursor.filter.cursor_radius = 10

    # Display data and cursor using an image_plane_widget that intersects the
    # cursor.
    ipw = mlab.pipeline.image_plane_widget(cursor, plane_orientation='x_axes',
                slice_index=20)

    # View
    mlab.colorbar()
    mlab.view(15, 70, 100, [20, 20, 20])
    mlab.show()