ENH: Built-in as_grey pipeline

doc/source/opening_files.rst

@@ -1,8 +1,8 @@
 Opening Files
 =============
 
-QuickStart
-----------
+Quick Start
+-----------
 
 Where possible, pims detects the type of file(s) automatically. Here are some
 examples.
@@ -14,6 +14,18 @@ examples.
    images = pims.open('my_directory/*.tif')  # many TIFs with sequential names
    images = pims.open('tiff_stack.tif')  # one TIF file containing many frames
 
+If your images are in a color format, but you need to convert them to greyscale
+for processing, you can use ``pims.as_grey``:
+
+.. code-block:: python
+
+   import pims
+   images = pims.as_grey(pims.open('my_directory/*.png'))
+
+``as_grey`` operates on any PIMS reader object, and it only converts images as
+they are loaded. PIMS makes it easy to create your own custom functions like
+this, called :doc:`pipelines`.
+
 Using Specific Readers
 ----------------------
 

doc/source/pipelines.rst

@@ -34,8 +34,10 @@ underlying video data is only accessed one element at a time.
 Conversion to greyscale
 -----------------------
 
-Say we want to convert an RGB video to greyscale. We define a function as
-follows and decorate it with ``@pipeline`` to turn it into a pipeline:
+Say we want to convert an RGB video to greyscale. A pipeline to do this is
+already provided as ``pims.as_grey``, but it is also easy to make our own.
+We define a function as follows and decorate it with ``@pipeline`` to turn
+it into a pipeline:
 
 .. code-block:: python
 

pims/api.py

@@ -20,6 +20,7 @@
 from .norpix_reader import NorpixSeq  # noqa
 from pims.tiff_stack import TiffStack_tifffile  # noqa
 from .spe_stack import SpeStack
+from pims.process import as_grey
 
 
 def not_available(requirement):

pims/process.py

@@ -0,0 +1,25 @@
+from __future__ import (absolute_import, division, print_function,
+                        unicode_literals)
+
+import six
+
+import numpy as np
+
+from slicerator import pipeline
+
+@pipeline
+def as_grey(frame):
+    """Convert a 2D image or PIMS reader to greyscale.
+
+    This weights the color channels according to their typical
+    response to white light.
+
+    It does nothing if the input is already greyscale.
+    """
+    if len(frame.shape) == 2:
+        return frame
+    else:
+        red = frame[:, :, 0]
+        green = frame[:, :, 1]
+        blue = frame[:, :, 2]
+        return 0.2125 * red + 0.7154 * green + 0.0721 * blue

pims/tests/test_common.py

@@ -265,6 +265,7 @@ def _color_channel(img, channel):
     else:
         return img
 
+
 class _image_series(_image_single):
     def test_iterator(self):
         self.check_skip()
@@ -332,6 +333,13 @@ def test_composed_pipelines(self):
         expected = _rescale(_color_channel(self.v[0], 0))
         assert_image_equal(composed[0], expected)
 
+    def test_as_grey(self):
+        gr = pims.as_grey(self.v)
+        assert len(gr[0].shape) == 2
+        # Calling a second time does nothing
+        gr2 = pims.as_grey(gr)
+        assert_image_equal(gr[0], gr2[0])
+
     def test_getting_single_frame(self):
         self.check_skip()
         assert_image_equal(self.v[0], self.frame0)