io: Document colour mixer.

scikits/image/io/_plugins/_colormixer.pyx

@@ -1,4 +1,14 @@
-# ColorMixer function implementations
+# -*- python -*-
+
+"""Colour Mixer
+
+NumPy does not do overflow checking when adding or multiplying
+integers, so currently the only way to clip results efficiently
+(without making copies of the data) is with an extension such as this
+one.
+
+"""
+
 import numpy as np
 cimport numpy as np
 
@@ -7,12 +17,26 @@ import cython
 @cython.boundscheck(False)
 def add(np.ndarray[np.uint8_t, ndim=3] img,
         np.ndarray[np.uint8_t, ndim=3] stateimg,
-        int channel, int ammount):
+        int channel, int amount):
+    """Add a given amount to a colour channel of `stateimg`, and
+    store the result in `img`.  Overflow is clipped.
 
+    Parameters
+    ----------
+    img : (M, N, 3) ndarray of uint8
+        Output image.
+    stateimg : (M, N, 3) ndarray of uint8
+        Input image.
+    channel : int
+        Channel (0 for "red", 1 for "green", 2 for "blue").
+    amount : int
+        Value to add.
+
+    """
     cdef int height = img.shape[0]
     cdef int width = img.shape[1]
     cdef int k = channel
-    cdef int n = ammount
+    cdef int n = amount
 
     cdef np.int16_t op_result
 
@@ -30,12 +54,26 @@ def add(np.ndarray[np.uint8_t, ndim=3] img,
 @cython.boundscheck(False)
 def multiply(np.ndarray[np.uint8_t, ndim=3] img,
              np.ndarray[np.uint8_t, ndim=3] stateimg,
-             int channel, float ammount):
+             int channel, float amount):
+    """Multiply a colour channel of `stateimg` by a certain amount, and
+    store the result in `img`.  Overflow is clipped.
 
+    Parameters
+    ----------
+    img : (M, N, 3) ndarray of uint8
+        Output image.
+    stateimg : (M, N, 3) ndarray of uint8
+        Input image.
+    channel : int
+        Channel (0 for "red", 1 for "green", 2 for "blue").
+    amount : float
+        Multiplication factor.
+
+    """
     cdef int height = img.shape[0]
     cdef int width = img.shape[1]
     cdef int k = channel
-    cdef float n = ammount
+    cdef float n = amount
 
     cdef float op_result
 
@@ -48,4 +86,4 @@ def multiply(np.ndarray[np.uint8_t, ndim=3] img,
             elif op_result < 0:
                 img[i, j, k] = 0
             else:
-                img[i, j, k] = <np.uint8_t>op_result
+                img[i, j, k] = <np.uint8_t>op_result