# Volume slicer example

Example of an elaborate dialog showing a multiple views on the same data, with 3 cuts synchronized.

This example shows how to have multiple views on the same data, how to embedded multiple scenes in a dialog, and the caveat in populating them with data, as well as how to add some interaction logic on an ImagePlaneWidget.

The order in which things happen in this example is important, and it is easy to get it wrong. First of all, many properties of the visualization objects cannot be changed if there is not a scene created to view them. This is why we put a lot of the visualization logic in the callback of scene.activated, which is called after creation of the scene. Second, default values created via the ‘_xxx_default’ callback are created lazyly, that is, when the attributes are accessed. As the establishement of the VTK pipeline can depend on the order in which it is built, we trigger these access by explicitely calling the attributes. In particular, properties like scene background color, or interaction properties cannot be set before the scene is activated.

The same data is exposed in the different scenes by sharing the VTK dataset between different Mayavi data sources. See the Sharing the same data between scenes tip for more details.

In this example, the interaction with the scene and the various elements on it is strongly simplified by turning off interaction, and choosing specific scene interactor styles. Indeed, non-technical users can be confused with too rich interaction.

Python source code: `volume_slicer.py`

    # Author: Gael Varoquaux <gael.varoquaux@normalesup.org>
    # Copyright (c) 2009, Enthought, Inc.
    # License: BSD Style.

    import numpy as np

    from traits.api import HasTraits, Instance, Array, \
        on_trait_change
    from traitsui.api import View, Item, HGroup, Group

    from tvtk.api import tvtk
    from tvtk.pyface.scene import Scene

    from mayavi import mlab
    from mayavi.core.api import PipelineBase, Source
    from mayavi.core.ui.api import SceneEditor, MayaviScene, \
                                    MlabSceneModel

    ################################################################################
    # Create some data
    x, y, z = np.ogrid[-5:5:64j, -5:5:64j, -5:5:64j]
    data = np.sin(3*x)/x + 0.05*z**2 + np.cos(3*y)

    ################################################################################
    # The object implementing the dialog
    class VolumeSlicer(HasTraits):
        # The data to plot
        data = Array()

        # The 4 views displayed
        scene3d = Instance(MlabSceneModel, ())
        scene_x = Instance(MlabSceneModel, ())
        scene_y = Instance(MlabSceneModel, ())
        scene_z = Instance(MlabSceneModel, ())

        # The data source
        data_src3d = Instance(Source)

        # The image plane widgets of the 3D scene
        ipw_3d_x = Instance(PipelineBase)
        ipw_3d_y = Instance(PipelineBase)
        ipw_3d_z = Instance(PipelineBase)

        _axis_names = dict(x=0, y=1, z=2)

        #---------------------------------------------------------------------------
        def __init__(self, **traits):
            super(VolumeSlicer, self).__init__(**traits)
            # Force the creation of the image_plane_widgets:
            self.ipw_3d_x
            self.ipw_3d_y
            self.ipw_3d_z

        #---------------------------------------------------------------------------
        # Default values
        #---------------------------------------------------------------------------
        def _data_src3d_default(self):
            return mlab.pipeline.scalar_field(self.data,
                                figure=self.scene3d.mayavi_scene)

        def make_ipw_3d(self, axis_name):
            ipw = mlab.pipeline.image_plane_widget(self.data_src3d,
                            figure=self.scene3d.mayavi_scene,
                            plane_orientation='%s_axes' % axis_name)
            return ipw

        def _ipw_3d_x_default(self):
            return self.make_ipw_3d('x')

        def _ipw_3d_y_default(self):
            return self.make_ipw_3d('y')

        def _ipw_3d_z_default(self):
            return self.make_ipw_3d('z')

        #---------------------------------------------------------------------------
        # Scene activation callbaks
        #---------------------------------------------------------------------------
        @on_trait_change('scene3d.activated')
        def display_scene3d(self):
            outline = mlab.pipeline.outline(self.data_src3d,
                            figure=self.scene3d.mayavi_scene,
                            )
            self.scene3d.mlab.view(40, 50)
            # Interaction properties can only be changed after the scene
            # has been created, and thus the interactor exists
            for ipw in (self.ipw_3d_x, self.ipw_3d_y, self.ipw_3d_z):
                # Turn the interaction off
                ipw.ipw.interaction = 0
            self.scene3d.scene.background = (0, 0, 0)
            # Keep the view always pointing up
            self.scene3d.scene.interactor.interactor_style = \
                                     tvtk.InteractorStyleTerrain()

        def make_side_view(self, axis_name):
            scene = getattr(self, 'scene_%s' % axis_name)

            # To avoid copying the data, we take a reference to the
            # raw VTK dataset, and pass it on to mlab. Mlab will create
            # a Mayavi source from the VTK without copying it.
            # We have to specify the figure so that the data gets
            # added on the figure we are interested in.
            outline = mlab.pipeline.outline(
                                self.data_src3d.mlab_source.dataset,
                                figure=scene.mayavi_scene,
                                )
            ipw = mlab.pipeline.image_plane_widget(
                                outline,
                                plane_orientation='%s_axes' % axis_name)
            setattr(self, 'ipw_%s' % axis_name, ipw)

            # Synchronize positions between the corresponding image plane
            # widgets on different views.
            ipw.ipw.sync_trait('slice_position',
                                getattr(self, 'ipw_3d_%s'% axis_name).ipw)

            # Make left-clicking create a crosshair
            ipw.ipw.left_button_action = 0
            # Add a callback on the image plane widget interaction to
            # move the others
            def move_view(obj, evt):
                position = obj.GetCurrentCursorPosition()
                for other_axis, axis_number in self._axis_names.items():
                    if other_axis == axis_name:
                        continue
                    ipw3d = getattr(self, 'ipw_3d_%s' % other_axis)
                    ipw3d.ipw.slice_position = position[axis_number]

            ipw.ipw.add_observer('InteractionEvent', move_view)
            ipw.ipw.add_observer('StartInteractionEvent', move_view)

            # Center the image plane widget
            ipw.ipw.slice_position = 0.5*self.data.shape[
                        self._axis_names[axis_name]]

            # Position the view for the scene
            views = dict(x=( 0, 90),
                         y=(90, 90),
                         z=( 0,  0),
                         )
            scene.mlab.view(*views[axis_name])
            # 2D interaction: only pan and zoom
            scene.scene.interactor.interactor_style = \
                                     tvtk.InteractorStyleImage()
            scene.scene.background = (0, 0, 0)

        @on_trait_change('scene_x.activated')
        def display_scene_x(self):
            return self.make_side_view('x')

        @on_trait_change('scene_y.activated')
        def display_scene_y(self):
            return self.make_side_view('y')

        @on_trait_change('scene_z.activated')
        def display_scene_z(self):
            return self.make_side_view('z')

        #---------------------------------------------------------------------------
        # The layout of the dialog created
        #---------------------------------------------------------------------------
        view = View(HGroup(
                      Group(
                           Item('scene_y',
                                editor=SceneEditor(scene_class=Scene),
                                height=250, width=300),
                           Item('scene_z',
                                editor=SceneEditor(scene_class=Scene),
                                height=250, width=300),
                           show_labels=False,
                      ),
                      Group(
                           Item('scene_x',
                                editor=SceneEditor(scene_class=Scene),
                                height=250, width=300),
                           Item('scene3d',
                                editor=SceneEditor(scene_class=MayaviScene),
                                height=250, width=300),
                           show_labels=False,
                      ),
                    ),
                    resizable=True,
                    title='Volume Slicer',
                    )

    m = VolumeSlicer(data=data)
    m.configure_traits()