Merge pull request #159 from ctw/addalpha

NF: added the option to specify alpha transparency for Brain binarized curvature rendering

Author: mwaskom

CHANGES

@@ -1,6 +1,25 @@
 PySurfer Changes
 ================
 
+Version 0.7
+-----------
+
+- A new ``alpha`` keyword to the ``Brain`` constructor now controls
+  opacity of the rendered brain surface.
+- The ``curv`` keyword to the ``Brain`` constructor has been
+  deprecated. To replicate previous behavior when ``curv`` was set to
+  ``True`` simply omit the ``curv`` keyword. To replicate previous
+  behavior when ``curv`` was set to ``False``, simply set the
+  ``cortex`` keyword to None. To ease transition the ``curv`` argument
+  will still be caught and processed, but it will be removed in a
+  future release.
+- The ``cortex`` keyword to the ``Brain`` constructor now also accepts
+  a valid color specification (such as a 3-tuple with RGB values or a
+  color name) to render the cortical surface in that color without
+  rendering binary curvature values. Additionally it now also accepts
+  a dictionary with keyword arguments that are passed on to the call
+  to ``mlab.pipeline.surface``.
+
 Version 0.6
 -----------
 

bin/pysurfer

@@ -73,9 +73,10 @@ if __name__ == '__main__':
         from surfer import Brain
 
         # Load  up the figure and underlying brain object
-        b = Brain(args.subject_id, args.hemi, args.surf, args.curv,
-                  args.title, views=args.views, size=args.size,
-                  background=args.background, cortex=args.cortex)
+        b = Brain(args.subject_id, args.hemi, args.surf, title=args.title,
+                  cortex=args.cortex, alpha=args.alpha, size=args.size,
+                  background=args.background, foreground=args.foreground,
+                  views=args.views)
 
         # Maybe load some morphometry
         if args.morphometry is not None:

examples/plot_transparent_brain.py

@@ -0,0 +1,40 @@
+"""
+=======================
+Plot Transparent Brain
+=======================
+
+Plot a transparent brain to visualize foci below the surface.
+
+"""
+import os
+from surfer import Brain
+
+print(__doc__)
+
+subject_id = "fsaverage"
+subjects_dir = os.environ["SUBJECTS_DIR"]
+
+"""To render a transparent brain, we are specifying an alpha <
+1.0. This allows us to visualize foci that are not on the cortical
+surface. When the brain see-through, rendering of binary curvature is
+distracting, so we specify a color, rather than a color map as the
+argument for cortex:
+
+"""
+brain = Brain(subject_id, "lh", "pial", cortex='ivory', alpha=0.5)
+
+"""Here's a set of stereotaxic foci in the MNI coordinate system that
+are not on the cortical surface which we want to display.
+
+"""
+
+coords = [[-20, 10, 10],
+          [-25, 22, 15],
+          [-18, 8, 20]]
+
+"""Now we plot the foci in the brain. Because the foci are not on the
+cortical surface, they are only visible when alpha is set to < 1.0 in
+the call to Brain.
+
+"""
+brain.add_foci(coords, color="red")

surfer/_commandline.py

@@ -38,8 +38,6 @@
                     help="hemisphere to load")
 parser.add_argument("surf",
                     help="surface mesh (e.g. 'pial', 'inflated')")
-parser.add_argument("-no-curv", action="store_false", dest="curv",
-                    help="do not display the binarized surface curvature")
 parser.add_argument("-morphometry", metavar="MEAS",
                     help="load morphometry file (e.g. thickness, curvature)")
 parser.add_argument("-annotation", metavar="ANNOT",
@@ -64,8 +62,12 @@
                     help="size of the display window (in pixels)")
 parser.add_argument("-background", metavar="COLOR", default="black",
                     help="background color for display")
+parser.add_argument("-foreground", metavar="COLOR", default="white",
+                    help="foreground color for display")
 parser.add_argument("-cortex", metavar="COLOR", default="classic",
-                    help="colormap for binary cortex curvature")
+                    help="colormap or color for rendering the cortex")
+parser.add_argument("-alpha", metavar="COLOR", default="1.0",
+                    help="specifies opacity for the cortical surface")
 parser.add_argument("-title",
                     help="title to use for the figure")
 parser.add_argument("-views", nargs="*", default=['lat'],

surfer/tests/test_viz.py

@@ -73,21 +73,28 @@ def test_brains():
     # testing backend breaks when passing in a figure, so we use 'auto' here
     # (shouldn't affect usability, but it makes testing more annoying)
     mlab.options.backend = 'auto'
-    surfs = ['inflated', 'white']
-    hemis = ['lh', 'rh']
-    curvs = [True, False]
-    titles = [None, 'Hello']
-    cortices = ["low_contrast", ("Reds", 0, 1, False)]
-    sizes = [500, (400, 300)]
-    backgrounds = ["white", "blue"]
-    foregrounds = ["black", "white"]
-    figs = [None, mlab.figure()]
-    subj_dirs = [None, subj_dir]
-    for surf, hemi, curv, title, cort, s, bg, fg, fig, sd \
-            in zip(surfs, hemis, curvs, titles, cortices, sizes,
-                   backgrounds, foregrounds, figs, subj_dirs):
-        brain = Brain(subject_id, hemi, surf, curv, title,
-                      cort, s, bg, fg, fig, sd)
+    surfs = ['inflated', 'white', 'white', 'white', 'white', 'white', 'white']
+    hemis = ['lh', 'rh', 'both', 'both', 'rh', 'both', 'both']
+    titles = [None, 'Hello', 'Good bye!', 'lut test',
+              'dict test', 'None test', 'RGB test']
+    cortices = ["low_contrast", ("Reds", 0, 1, False), 'hotpink',
+                ['yellow', 'blue'], dict(colormap='Greys'),
+                None, (0.5, 0.5, 0.5)]
+    sizes = [500, (400, 300), (300, 300), (300, 400), 500, 400, 300]
+    backgrounds = ["white", "blue", "black", "0.75",
+                   (0.2, 0.2, 0.2), "black", "0.75"]
+    foregrounds = ["black", "white", "0.75", "red",
+                   (0.2, 0.2, 0.2), "blue", "black"]
+    figs = [None, mlab.figure(), None, None, mlab.figure(), None, None]
+    subj_dirs = [None, subj_dir, subj_dir, subj_dir,
+                 subj_dir, subj_dir, subj_dir]
+    alphas = [1.0, 0.5, 0.25, 0.7, 0.5, 0.25, 0.7]
+    for surf, hemi, title, cort, s, bg, fg, fig, sd, alpha \
+            in zip(surfs, hemis, titles, cortices, sizes,
+                   backgrounds, foregrounds, figs, subj_dirs, alphas):
+        brain = Brain(subject_id, hemi, surf, title=title, cortex=cort,
+                      alpha=alpha, size=s, background=bg, foreground=fg,
+                      figure=fig, subjects_dir=sd)
         brain.close()
     assert_raises(ValueError, Brain, subject_id, 'lh', 'inflated',
                   subjects_dir='')