Accept "ignore" keyword for bad/non-data values in rendering functions.

If the "ignore" keyword value is specified, the corresponding value will not
be used for calculating RGB limits for default color limits or user-specified
histogram stretches. This is useful when bad pixels are assigned a unique data
value.

* algorithsm/spymath.py:
  (get_histogram_cdf_points): Accept "ignore" keyword.
* graphics/graphics.py:
  (get_rgb_meta): Pass "ignore" ignore keyword on to `get_histogram_cdf_points`.
  _get_rgb_kwargs: Add "ignore" to list of accepted keywords.

Author: tboggs

spectral/algorithms/spymath.py

@@ -80,7 +80,7 @@ def matrix_sqrt(X=None, symmetric=False, inverse=False, eigs=None):
         return V.dot(SRV).dot(np.linalg.inv(V))
 
 
-def get_histogram_cdf_points(data, cdf_vals):
+def get_histogram_cdf_points(data, cdf_vals, ignore=None):
     '''Returns input values corresponding to the data's CDF values.
 
     Arguments:
@@ -96,16 +96,24 @@ def get_histogram_cdf_points(data, cdf_vals):
             example, to get the values of `data` corresponding to the 1% lower
             tail and 5% upper tail, this argument would be (0.01, 0.95).
 
+        `ignore` (numeric, default `None`):
+
+            A scalar value that should be ignored when computing histogram
+            points (e.g., a value that indicates bad data). If this valus is
+            not specified, all data are used.
+
     Return value:
 
         A list specifying the values in `data` that correspond to the
         associated CDF values in `cdf_vals`.
     '''
     data = data.ravel()
+    if ignore is not None and ignore in data:
+        data = data[np.where(data != ignore)]
     isort = np.argsort(data)
     N = len(data)
     return[data[isort[int(x * (N - 1))]] for x in cdf_vals]
-    
+
 
 class NaNValueWarning(UserWarning):
     pass

spectral/graphics/graphics.py

@@ -687,29 +687,35 @@ def get_rgb_meta(source, bands=None, **kwargs):
         if stretch.shape not in ((2,), (3, 2)):
             raise ValueError("`stretch` keyword must be numeric or a " \
                              "sequence with shape (2,) or (3, 2).")
+        nondata = kwargs.get('ignore', None)
         if stretch.ndim == 1:
             if monochrome:
-                s = get_histogram_cdf_points(rgb[:, :, 0], stretch)
+                s = get_histogram_cdf_points(rgb[:, :, 0], stretch,
+                                             ignore=nondata)
                 rgb_lims = [s, s, s]
             elif stretch_all:
                 # Stretch each color component independently
-                rgb_lims = [get_histogram_cdf_points(rgb[:, :, i], stretch) \
+                rgb_lims = [get_histogram_cdf_points(rgb[:, :, i], stretch,
+                                                     ignore=nondata) \
                             for i in range(3)]
             else:
                 # Use a common lower/upper limit for each band by taking
                 # the lowest lower limit and greatest upper limit.
-                lims = np.array([get_histogram_cdf_points(rgb[:,:,i], stretch) \
+                lims = np.array([get_histogram_cdf_points(rgb[:,:,i], stretch,
+                                                          ignore=nondata) \
                         for i in range(3)])
                 minmax = np.array([lims[:,0].min(), lims[:,1].max()])
                 rgb_lims = minmax[np.newaxis, :].repeat(3, axis=0)
         else:
             if monochrome:
                 # Not sure why anyone would want separate RGB stretches for
                 # a gray-scale image but we'll let them.
-                rgb_lims = [get_histogram_cdf_points(rgb[:,:,0], stretch[i]) \
+                rgb_lims = [get_histogram_cdf_points(rgb[:,:,0], stretch[i],
+                                                     ignore=nondata) \
                             for i in range(3)]
             elif stretch_all:
-                rgb_lims = [get_histogram_cdf_points(rgb[:,:,i], stretch[i]) \
+                rgb_lims = [get_histogram_cdf_points(rgb[:,:,i], stretch[i],
+                                                     ignore=nondata) \
                             for i in range(3)]
             else:
                 msg = 'Can not use common stretch if different stretch ' \
@@ -730,7 +736,7 @@ def get_rgb_meta(source, bands=None, **kwargs):
 
 # For checking if valid keywords were supplied
 _get_rgb_kwargs = ('stretch', 'stretch_all', 'bounds', 'colors', 'color_scale',
-                   'auto_scale')
+                   'auto_scale', 'ignore')
 
 def running_ipython():
     '''Returns True if ipython is running.'''