ENH: Add terrain interaction (#178)

Author: larsoner

examples/plot_meg_inverse_solution.py

@@ -13,6 +13,8 @@
 
 print(__doc__)
 
+path = os.path.dirname(__file__)
+
 """
 define subject, surface and hemisphere(s) to plot
 """
@@ -22,7 +24,8 @@
 """
 create Brain object for visualization
 """
-brain = Brain(subject_id, hemi, surface, size=(800, 400))
+brain = Brain(subject_id, hemi, surface, size=(800, 400),
+              interaction='terrain')
 
 """
 label for time annotation in milliseconds
@@ -37,7 +40,7 @@ def time_label(t):
 read MNE dSPM inverse solution
 """
 for hemi in ['lh', 'rh']:
-    stc_fname = os.path.join('example_data/meg_source_estimate-' +
+    stc_fname = os.path.join(path, 'example_data', 'meg_source_estimate-' +
                              hemi + '.stc')
     stc = read_stc(stc_fname)
 

surfer/tests/test_viz.py

@@ -101,8 +101,13 @@ def test_brains():
                       alpha=alpha, size=s, background=bg, foreground=fg,
                       figure=fig, subjects_dir=sd)
         brain.close()
+    brain = Brain(subject_id, hemi, surf, subjects_dir=sd,
+                  interaction='terrain')
+    brain.close()
     assert_raises(ValueError, Brain, subject_id, 'lh', 'inflated',
                   subjects_dir='')
+    assert_raises(ValueError, Brain, subject_id, 'lh', 'inflated',
+                  interaction='foo', subjects_dir=sd)
 
 
 @requires_fsaverage

surfer/viz.py

@@ -19,6 +19,7 @@
 from mayavi.core.ui.mayavi_scene import MayaviScene
 from traits.api import (HasTraits, Range, Int, Float,
                         Bool, Enum, on_trait_change, Instance)
+from tvtk.api import tvtk
 
 from . import utils, io
 from .utils import (Surface, verbose, create_color_lut, _get_subjects_dir,
@@ -189,7 +190,8 @@ def _force_render(figures, backend):
         _gui.process_events()
 
 
-def _make_viewer(figure, n_row, n_col, title, scene_size, offscreen):
+def _make_viewer(figure, n_row, n_col, title, scene_size, offscreen,
+                 interaction='trackball'):
     """Triage viewer creation
 
     If n_row == n_col == 1, then we can use a Mayavi figure, which
@@ -219,6 +221,11 @@ def _make_viewer(figure, n_row, n_col, title, scene_size, offscreen):
             else:
                 window = _MlabGenerator(n_row, n_col, w, h, title)
                 figures, _v = window._get_figs_view()
+            if interaction == 'terrain':  # "trackball" is default
+                for figure in figures:
+                    for f in figure:
+                        f.scene.interactor.interactor_style = \
+                            tvtk.InteractorStyleTerrain()
     else:
         if isinstance(figure, int):  # use figure with specified id
             figure = [mlab.figure(figure, size=scene_size)]
@@ -351,6 +358,9 @@ class Brain(object):
         If True, rendering will be done offscreen (not shown). Useful
         mostly for generating images or screenshots, but can be buggy.
         Use at your own risk.
+    interaction : str
+        Can be "trackball" (default) or "terrain", i.e. a turntable-style
+        camera.
 
     Attributes
     ----------
@@ -362,7 +372,8 @@ def __init__(self, subject_id, hemi, surf, title=None,
                  cortex="classic", alpha=1.0, size=800, background="black",
                  foreground="white", figure=None, subjects_dir=None,
                  views=['lat'], offset=True, show_toolbar=False,
-                 offscreen=False, config_opts=None, curv=None):
+                 offscreen=False, interaction='trackball',
+                 config_opts=None, curv=None):
 
         # Keep backwards compatability
         if config_opts is not None:
@@ -392,6 +403,10 @@ def __init__(self, subject_id, hemi, surf, title=None,
             if not curv:
                 cortex = None
 
+        if not isinstance(interaction, string_types) or \
+                interaction not in ('trackball', 'terrain'):
+            raise ValueError('interaction must be "trackball" or "terrain", '
+                             'got "%s"' % (interaction,))
         col_dict = dict(lh=1, rh=1, both=1, split=2)
         n_col = col_dict[hemi]
         if hemi not in col_dict.keys():
@@ -433,7 +448,8 @@ def __init__(self, subject_id, hemi, surf, title=None,
         # deal with making figures
         self._set_window_properties(size, background, foreground)
         figures, _v = _make_viewer(figure, n_row, n_col, title,
-                                   self._scene_size, offscreen)
+                                   self._scene_size, offscreen,
+                                   interaction)
         self._figures = figures
         self._v = _v
         self._window_backend = 'Mayavi' if self._v is None else 'TraitsUI'