From d89e577c8708b028c969293e25a1e1588af19a54 Mon Sep 17 00:00:00 2001
From: Stefan van der Walt <stefan@sun.ac.za>
Date: Wed, 4 Nov 2009 07:46:52 +0200
Subject: [PATCH] io: Document colour mixer.

---
 scikits/image/io/_plugins/_colormixer.pyx | 50 ++++++++++++++++++++---
 1 file changed, 44 insertions(+), 6 deletions(-)

diff --git a/scikits/image/io/_plugins/_colormixer.pyx b/scikits/image/io/_plugins/_colormixer.pyx
index 35d7bd6b..aefe96bc 100644
--- a/scikits/image/io/_plugins/_colormixer.pyx
+++ b/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
\ No newline at end of file
+                img[i, j, k] = <np.uint8_t>op_result