Merge pull request #82 from nipy/better_colormaps

Better colormaps

Author: larsoner

CHANGES

@@ -1,8 +1,15 @@
 PySurfer Changes
 ================
 
+Version 0.5
+-----------
+
+- The visual display of the surfaces was improved by using surface normals
+- Made colormap specification in Brain.add_data and Brain.add_contour_overlay
+  more flexible, with better defaults
+
 Version 0.4
--------------
+-----------
 
 Enhancements
 ~~~~~~~~~~~~

examples/plot_freesurfer_normalization.py

@@ -28,7 +28,8 @@
     curv_bin = (curv.get_data() > 0).squeeze()
 
     # Add the data as a contour overlay, but turn off the colorbar
-    brain.add_contour_overlay(curv_bin, 0, 1.15, 2, 3, hemi=hemi)
+    brain.add_contour_overlay(curv_bin, min=0, max=1.5, n_contours=2,
+                              line_width=3, hemi=hemi)
     brain.contour_list[-1]["colorbar"].visible = False
 
 brain.show_view("dorsal")

examples/plot_resting_correlations.py

@@ -50,17 +50,8 @@
 We'll also plot the map with some transparency so that we can see through to the
 underlying anatomy.
 """
-brain.add_data(surf_data_lh, -.7, .7, colormap="RdBu", alpha=.75, hemi='lh')
-brain.add_data(surf_data_rh, -.7, .7, colormap="RdBu", alpha=.75, hemi='rh')
-
-"""
-We'll next flip the colormap so negative correlations are blue and positive
-correlations are red, which is better aligned with the conventions in fMRI
-visualization.
-"""
-for hemi in ["lh", "rh"]:
-    for cbar in brain.data_dict[hemi]["colorbars"]:
-        cbar.reverse_lut = True
+brain.add_data(surf_data_lh, -.7, .7, colormap="coolwarm", alpha=.75, hemi='lh')
+brain.add_data(surf_data_rh, -.7, .7, colormap="coolwarm", alpha=.75, hemi='rh')
 
 """
 This overlay represents resting-state correlations with a

surfer/tests/test_utils.py

@@ -1,6 +1,7 @@
 from os.path import join as pjoin
 
 import numpy as np
+import nose.tools as nt
 from numpy.testing import assert_array_almost_equal, assert_array_equal
 
 from surfer import utils
@@ -64,3 +65,29 @@ def test_huge_cross():
     z = np.cross(x, y)
     zz = utils._fast_cross_3d(x, y)
     assert_array_equal(z, zz)
+
+
+def test_create_color_lut():
+    """Test various ways of making a colormap."""
+    # Test valid lut
+    cmap_in = (np.random.rand(256, 4) * 255).astype(np.int)
+    cmap_out = utils.create_color_lut(cmap_in)
+    assert_array_equal(cmap_in, cmap_out)
+
+    # Test mostly valid lut
+    cmap_in = cmap_in[:, :3]
+    cmap_out = utils.create_color_lut(cmap_in)
+    assert_array_equal(cmap_in, cmap_out[:, :3])
+    assert_array_equal(cmap_out[:, 3], np.ones(256, np.int) * 255)
+
+    # Test matplotlib lut
+    cmap_out = utils.create_color_lut("BuGn_r")
+    nt.assert_equal(cmap_out.shape, (256, 4))
+
+    # Test list of colors lut
+    cmap_out = utils.create_color_lut(["purple", "pink", "white"])
+    nt.assert_equal(cmap_out.shape, (256, 4))
+
+    # Test that we can ask for a specific number of colors
+    cmap_out = utils.create_color_lut("Reds", 12)
+    nt.assert_equal(cmap_out.shape, (12, 4))

surfer/utils.py

@@ -10,6 +10,8 @@
 import nibabel as nib
 from scipy import sparse
 from scipy.spatial.distance import cdist
+import matplotlib as mpl
+from matplotlib import cm
 
 from .config import config
 
@@ -413,6 +415,60 @@ def mesh_edges(faces):
     return edges
 
 
+def create_color_lut(cmap, n_colors=256):
+    """Return a colormap suitable for setting as a Mayavi LUT.
+
+    Parameters
+    ----------
+    cmap : string, list of colors, n x 3 or n x 4 array
+        Input colormap definition. This can be the name of a matplotlib
+        colormap, a list of valid matplotlib colors, or a suitable
+        mayavi LUT (possibly missing the alpha channel).
+    n_colors : int, optional
+        Number of colors in the resulting LUT. This is ignored if cmap
+        is a 2d array.
+    Returns
+    -------
+    lut : n_colors x 4 integer array
+        Color LUT suitable for passing to mayavi
+    """
+    if isinstance(cmap, np.ndarray):
+        if np.ndim(cmap) == 2:
+            if cmap.shape[1] == 4:
+                # This looks likes a LUT that's ready to go
+                lut = cmap.astype(np.int)
+            elif cmap.shape[1] == 3:
+                # This looks like a LUT, but it's missing the alpha channel
+                alpha = np.ones(len(cmap), np.int) * 255
+                lut = np.c_[cmap, alpha]
+
+            return lut
+
+    # Otherwise, we're going to try and use matplotlib to create it
+
+    if cmap in dir(cm):
+        # This is probably a matplotlib colormap, so build from that
+        # The matplotlib colormaps are a superset of the mayavi colormaps
+        # except for one or two cases (i.e. blue-red, which is a crappy
+        # rainbow colormap and shouldn't be used for anything, although in
+        # its defense it's better than "Jet")
+        cmap = getattr(cm, cmap)
+
+    elif np.iterable(cmap):
+        # This looks like a list of colors? Let's try that.
+        colors = list(map(mpl.colors.colorConverter.to_rgb, cmap))
+        cmap = mpl.colors.LinearSegmentedColormap.from_list("_", colors)
+
+    else:
+        # If we get here, it's a bad input
+        raise ValueError("Input %s was not valid for making a lut" % cmap)
+
+    # Convert from a matplotlib colormap to a lut array
+    lut = (cmap(np.linspace(0, 1, n_colors)) * 255).astype(np.int)
+
+    return lut
+
+
 @verbose
 def smoothing_matrix(vertices, adj_mat, smoothing_steps=20, verbose=None):
     """Create a smoothing matrix which can be used to interpolate data defined

surfer/viz.py

@@ -15,7 +15,7 @@
 
 from . import utils, io
 from .config import config
-from .utils import Surface, verbose, _get_subjects_dir
+from .utils import Surface, verbose, create_color_lut, _get_subjects_dir
 
 
 import logging
@@ -757,7 +757,7 @@ def add_overlay(self, source, min=None, max=None, sign="abs", name=None,
         self._toggle_render(True, views)
 
     def add_data(self, array, min=None, max=None, thresh=None,
-                 colormap="blue-red", alpha=1,
+                 colormap="RdBu_r", alpha=1,
                  vertices=None, smoothing_steps=20, time=None,
                  time_label="time index=%d", colorbar=True,
                  hemi=None):
@@ -788,10 +788,10 @@ def add_data(self, array, min=None, max=None, thresh=None,
             max value in colormap (uses real max if None)
         thresh : None or float
             if not None, values below thresh will not be visible
-        colormap : str | array [256x4]
-            name of Mayavi colormap to use, or a custom look up table (a 256x4
-            array, with the columns representing RGBA (red, green, blue, alpha)
-            coded with integers going from 0 to 255).
+        colormap : string, list of colors, or array
+            name of matplotlib colormap to use, a list of matplotlib colors,
+            or a custom look up table (an n x 4 array coded with RBGA values
+            between 0 and 255).
         alpha : float in [0, 1]
             alpha level to control opacity
         vertices : numpy array
@@ -841,16 +841,9 @@ def add_data(self, array, min=None, max=None, thresh=None,
         # Copy and byteswap to deal with Mayavi bug
         mlab_plot = _prepare_data(array_plot)
 
-        # process colormap argument
-        if isinstance(colormap, basestring):
-            lut = None
-        else:
-            lut = np.asarray(colormap)
-            if lut.shape != (256, 4):
-                err = ("colormap argument must be mayavi colormap (string) or"
-                       " look up table (array of shape (256, 4))")
-                raise ValueError(err)
-            colormap = "blue-red"
+        # Process colormap argument into a lut
+        lut = create_color_lut(colormap)
+        colormap = "Greys"
 
         data = dict(array=array, smoothing_steps=smoothing_steps,
                     fmin=min, fmid=(min + max) / 2, fmax=max,
@@ -1256,7 +1249,8 @@ def add_foci(self, coords, coords_as_verts=False, map_surface=None,
         self._toggle_render(True, views)
 
     def add_contour_overlay(self, source, min=None, max=None,
-                            n_contours=7, line_width=1.5, hemi=None):
+                            n_contours=7, line_width=1.5, colormap="YlOrRd_r",
+                            hemi=None):
         """Add a topographic contour overlay of the positive data.
 
         Note: This visualization will look best when using the "low_contrast"
@@ -1274,6 +1268,10 @@ def add_contour_overlay(self, source, min=None, max=None,
             number of contours to use in the display
         line_width : float
             width of contour lines
+        colormap : string, list of colors, or array
+            name of matplotlib colormap to use, a list of matplotlib colors,
+            or a custom look up table (an n x 4 array coded with RBGA values
+            between 0 and 255).
         hemi : str | None
             If None, it is assumed to belong to the hemipshere being
             shown. If two hemispheres are being shown, an error will
@@ -1294,14 +1292,17 @@ def add_contour_overlay(self, source, min=None, max=None,
                 c['surface'].remove()
                 c['colorbar'].visible = False
 
+        # Process colormap argument into a lut
+        lut = create_color_lut(colormap)
+
         views = self._toggle_render(False)
         cl = []
         for brain in self._brain_list:
             if brain['hemi'] == hemi:
                 cl.append(brain['brain'].add_contour_overlay(scalar_data,
                                                              min, max,
                                                              n_contours,
-                                                             line_width))
+                                                             line_width, lut))
         self.contour_list = cl
         self._toggle_render(True, views)
 
@@ -2258,7 +2259,7 @@ def add_foci(self, foci_coords, scale_factor, color, alpha, name):
         return points
 
     def add_contour_overlay(self, scalar_data, min=None, max=None,
-                            n_contours=7, line_width=1.5):
+                            n_contours=7, line_width=1.5, lut=None):
         """Add a topographic contour overlay of the positive data"""
         # Set up the pipeline
         mesh = mlab.pipeline.triangular_mesh_source(self._geo.x, self._geo.y,
@@ -2271,6 +2272,8 @@ def add_contour_overlay(self, scalar_data, min=None, max=None,
         thresh = mlab.pipeline.threshold(mesh, low=min)
         surf = mlab.pipeline.contour_surface(thresh, contours=n_contours,
                                              line_width=line_width)
+        if lut is not None:
+            surf.module_manager.scalar_lut_manager.lut.table = lut
 
         # Set the colorbar and range correctly
         bar = mlab.scalarbar(surf,