[Scipy-svn] r6882 - trunk/scipy/misc

scipy-svn@scip... scipy-svn@scip...
Sun Nov 14 03:57:54 CST 2010


Author: rgommers
Date: 2010-11-14 03:57:53 -0600 (Sun, 14 Nov 2010)
New Revision: 6882

Modified:
   trunk/scipy/misc/__init__.py
   trunk/scipy/misc/common.py
   trunk/scipy/misc/pilutil.py
Log:
DOC: merge wiki edits for misc module.

Modified: trunk/scipy/misc/__init__.py
===================================================================
--- trunk/scipy/misc/__init__.py	2010-11-14 09:57:33 UTC (rev 6881)
+++ trunk/scipy/misc/__init__.py	2010-11-14 09:57:53 UTC (rev 6882)
@@ -1,4 +1,51 @@
+"""
+Various utilities that don't have another home.
 
+Note that the Python Imaging Library (PIL) is not a dependency
+of SciPy and therefore the `pilutil` module is not available on
+systems that don't have PIL installed.
+
+Modules
+-------
+.. autosummary::
+   :toctree: generated/
+
+   common     - Common functions requiring SciPy Base and Level 1 SciPy
+   doccer     - Docstring fragment insertion utilities
+   helpmod    -
+   pexec      -
+   pilutil    - Image utilities using the Python Imaging Library (PIL)
+   ppimport   - Postpone module import to future
+   setup      -
+   setupscons -
+
+Functions
+---------
+.. autosummary::
+   :toctree: generated/
+
+   bytescale - Byte scales an array (image)
+   central_diff_weights - Weights for an n-point central m-th derivative
+   comb - Combinations of N things taken k at a time, "N choose k"
+   derivative -\tFind the n-th derivative of a function at a point
+   factorial  - The factorial function, n! = special.gamma(n+1)
+   factorial2 - Double factorial, (n!)!
+   factorialk - (...((n!)!)!...)! where there are k '!'
+   fromimage - Return a copy of a PIL image as a numpy array
+   imfilter - Simple filtering of an image
+   imread - Read an image file from a filename
+   imresize - Resize an image
+   imrotate - Rotate an image counter-clockwise
+   imsave - Save an array to an image file
+   imshow - Simple showing of an image through an external viewer
+   info - Get help information for a function, class, or module
+   lena - Get classic image processing example image Lena
+   pade - Pade approximation to function as the ratio of two polynomials
+   radon -
+   toimage - Takes a numpy array and returns a PIL image
+
+"""
+
 from info import __doc__
 
 __all__ = ['who', 'source', 'info']

Modified: trunk/scipy/misc/common.py
===================================================================
--- trunk/scipy/misc/common.py	2010-11-14 09:57:33 UTC (rev 6881)
+++ trunk/scipy/misc/common.py	2010-11-14 09:57:53 UTC (rev 6882)
@@ -13,14 +13,38 @@
 # to numpy perhaps?
 
 def factorial(n,exact=0):
-    """n! = special.gamma(n+1)
+    """
+    The factorial function, n! = special.gamma(n+1).
 
-    If exact==0, then floating point precision is used, otherwise
+    If exact is 0, then floating point precision is used, otherwise
     exact long integer is computed.
 
-    Notes:
-      - Array argument accepted only for exact=0 case.
-      - If n<0, the return value is 0.
+    - Array argument accepted only for exact=0 case.
+    - If n<0, the return value is 0.
+
+    Parameters
+    ----------
+    n : int or array_like of ints
+        Calculate ``n!``.  Arrays are only supported with `exact` set
+        to False.  If ``n < 0``, the return value is 0.
+    exact : bool, optional
+        The result can be approximated rapidly using the gamma-formula
+        above.  If `exact` is set to True, calculate the
+        answer exactly using integer arithmetic. Default is False.
+
+    Returns
+    -------
+    nf : float or int
+        Factorial of `n`, as an integer or a float depending on `exact`.
+
+    Examples
+    --------
+    >>> arr = np.array([3,4,5])
+    >>> sc.factorial(arr, exact=False)
+    array([   6.,   24.,  120.])
+    >>> sc.factorial(5, exact=True)
+    120L
+
     """
     if exact:
         if n < 0:
@@ -39,9 +63,10 @@
 
 
 def factorial2(n, exact=False):
-    """Double factorial.
+    """
+    Double factorial.
 
-    This is the factorial with every second value is skipped, i.e.,
+    This is the factorial with every second value skipped, i.e.,
     ``7!! = 7 * 5 * 3 * 1``.  It can be approximated numerically as::
 
       n!! = special.gamma(n/2+1)*2**((m+1)/2)/sqrt(pi)  n odd
@@ -49,7 +74,7 @@
 
     Parameters
     ----------
-    n : int, array-like
+    n : int or array_like
         Calculate ``n!!``.  Arrays are only supported with `exact` set
         to False.  If ``n < 0``, the return value is 0.
     exact : bool, optional
@@ -63,10 +88,12 @@
         Double factorial of `n`, as an int or a float depending on
         `exact`.
 
-    References
-    ----------
-    .. [1] Wikipedia, "Double Factorial",
-           http://en.wikipedia.org/wiki/Factorial#Double_factorial
+    Examples
+    --------
+    >>> factorial2(7, exact=False)
+    array(105.00000000000001)
+    >>> factorial2(7, exact=True)
+    105L
 
     """
     if exact:
@@ -100,7 +127,7 @@
 
     Parameters
     ----------
-    n : int, array-like
+    n : int, array_like
         Calculate multifactorial. Arrays are only supported with exact
         set to False. If n < 0, the return value is 0.
     exact : bool, optional
@@ -117,6 +144,13 @@
     NotImplementedError
         Raises when exact is False
 
+    Examples
+    --------
+    >>> sc.factorialk(5, 1, exact=True)
+    120L
+    >>> sc.factorialk(5, 3, exact=True)
+    10L
+
     """
     if exact:
         if n < 1-k:
@@ -133,14 +167,15 @@
 
 def comb(N,k,exact=0):
     """
-    Combinations of N things taken k at a time.
+    The number of combinations of N things taken k at a time.
+    This is often expressed as "N choose k".
 
     Parameters
     ----------
     N : int, array
-        Nunmber of things.
+        Number of things.
     k : int, array
-        Numner of elements taken.
+        Number of elements taken.
     exact : int, optional
         If exact is 0, then floating point precision is used, otherwise
         exact long integer is computed.
@@ -155,6 +190,15 @@
     - Array arguments accepted only for exact=0 case.
     - If k > N, N < 0, or k < 0, then a 0 is returned.
 
+    Examples
+    --------
+    >>> k = np.array([3, 4])
+    >>> n = np.array([10, 10])
+    >>> sc.comb(n, k, exact=False)
+    array([ 120.,  210.])
+    >>> sc.comb(10, 3, exact=True)
+    120L
+
     """
     if exact:
         if (k > N) or (N < 0) or (k < 0):
@@ -224,6 +268,14 @@
     -----
     Decreasing the step size too small can result in round-off error.
 
+    Examples
+    --------
+    >>> def x2(x):
+    ...     return x*x
+    ...
+    >>> derivative(x2, 2)
+    4.0
+
     """
     assert (order >= n+1), "Number of points must be at least the derivative order + 1."
     assert (order % 2 == 1), "Odd number of points only."
@@ -282,6 +334,36 @@
     return poly1d(p[::-1]), poly1d(q[::-1])
 
 def lena():
+    """
+    Get classic image processing example image, Lena, at 8-bit grayscale
+    bit-depth, 512 x 512 size.
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    lena : ndarray
+        Lena image
+
+    Examples
+    --------
+    >>> import scipy.misc
+    >>> lena = scipy.misc.lena()
+    >>> lena.shape
+    (512, 512)
+    >>> lena.max()
+    245
+    >>> lena.dtype
+    dtype('int32')
+
+    >>> import matplotlib.pyplot as plt
+    >>> plt.gray()
+    >>> plt.imshow(lena)
+    >>> plt.show()
+
+    """
     import cPickle, os
     fname = os.path.join(os.path.dirname(__file__),'lena.dat')
     f = open(fname,'rb')

Modified: trunk/scipy/misc/pilutil.py
===================================================================
--- trunk/scipy/misc/pilutil.py	2010-11-14 09:57:33 UTC (rev 6881)
+++ trunk/scipy/misc/pilutil.py	2010-11-14 09:57:53 UTC (rev 6882)
@@ -1,3 +1,10 @@
+"""
+A collection of image utilities using the Python Imaging Library (PIL).
+
+Note that PIL is not a dependency of SciPy and this module is not
+available on systems that don't have PIL installed.
+
+"""
 # Functions which need the PIL
 
 import numpy
@@ -16,20 +23,44 @@
 # Returns a byte-scaled image
 def bytescale(data, cmin=None, cmax=None, high=255, low=0):
     """
+    Byte scales an array (image).
+
     Parameters
     ----------
-    im : PIL image
-         Input image.
-    flatten : bool
-              If true, convert the output to grey-scale
+    data : ndarray
+        PIL image data array.
+    cmin :  Scalar
+        Bias scaling of small values, Default is data.min().
+    cmax : scalar
+        Bias scaling of large values, Default is data.max().
+    high : scalar
+        Scale max value to `high`.
+    low : scalar
+        Scale min value to `low`.
 
     Returns
     -------
     img_array : ndarray
-                The different colour bands/channels are stored in the
-                third dimension, such that a grey-image is MxN, an
-                RGB-image MxNx3 and an RGBA-image MxNx4.
+        Bytescaled array.
 
+    Examples
+    --------
+    >>> img = array([[ 91.06794177,   3.39058326,  84.4221549 ],
+                     [ 73.88003259,  80.91433048,   4.88878881],
+                     [ 51.53875334,  34.45808177,  27.5873488 ]])
+    >>> bytescale(img)
+    array([[255,   0, 236],
+           [205, 225,   4],
+           [140,  90,  70]], dtype=uint8)
+    >>> bytescale(img, high=200, low=100)
+    array([[200, 100, 192],
+           [180, 188, 102],
+           [155, 135, 128]], dtype=uint8)
+    >>> bytescale(img, cmin=0, cmax=255)
+    array([[91,  3, 84],
+           [74, 81,  5],
+           [52, 34, 28]], dtype=uint8)
+
     """
     if data.dtype == uint8:
         return data
@@ -255,8 +286,29 @@
     return fromimage(im)
 
 def imshow(arr):
-    """Simple showing of an image through an external viewer.
     """
+    Simple showing of an image through an external viewer.
+
+    Uses the image viewer specified by the environment variable
+    SCIPY_PIL_IMAGE_VIEWER, or if that is not defined then `see`,
+    to view a temporary file generated from array data.
+
+    Parameters
+    ----------
+    arr : ndarray
+        Array of image data to show.
+
+    Returns
+    -------
+    None
+
+    Examples
+    --------
+    >>> a = np.tile(np.arange(255), (255,1))
+    >>> from scipy import misc
+    >>> misc.pilutil.imshow(a)
+
+    """
     im = toimage(arr)
     fnum,fname = tempfile.mkstemp('.png')
     try:



More information about the Scipy-svn mailing list