Add imsave() to matplotlib.image, pyplot, and pylab. Patch from Gary Ruben.

astraw · astraw · commit 55e0c6b69e33 · 2009-02-10T04:43:23.000Z
svn path=/trunk/matplotlib/; revision=6899
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,6 @@
+2009-02-08 Added a new imsave function to image.py and exposed it in
+           the pyplot interface - GR
+
 2009-02-04 Some reorgnization of the legend code. anchored_text.py
            added as an example. - JJL
 
diff --git a/doc/_templates/index.html b/doc/_templates/index.html
@@ -564,6 +564,17 @@ <h3>Plotting commands</h3> <br/>
         load image file into array
       </td>
 
+    </tr>
+    <tr>
+      <th align="left">
+        <a href="api/pyplot_api.html#matplotlib.pyplot.imsave">imsave</a>
+
+      </th>
+
+      <td align="left">
+        save array as an image file
+      </td>
+
     </tr>
     <tr>
       <th align="left">
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -19,6 +19,9 @@ list may help describe what changes may be necessary in your code.
 
 Changes for 0.98.x
 ==================
+* Added new :func:`matplotlib.image.imsave` and exposed it to the
+  :mod:`matplotlib.pyplot` interface.
+
 * Remove support for pyExcelerator in exceltools -- use xlwt
   instead 
 
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -747,6 +747,42 @@ def pilread():
     return handler(fname)
 
 
+def imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None, origin=None):
+    """
+    Saves a 2D :class:`numpy.array` as an image with one pixel per element.
+    The output formats available depend on the backend being used.
+
+    Arguments:
+      *fname*:
+        A string containing a path to a filename, or a Python file-like object.
+        If *format* is *None* and *fname* is a string, the output
+        format is deduced from the extension of the filename.
+      *arr*:
+        A 2D array.
+    Keyword arguments:
+      *vmin*/*vmax*: [ None | scalar ]
+        *vmin* and *vmax* set the color scaling for the image by fixing the
+        values that map to the colormap color limits. If either *vmin* or *vmax*
+        is None, that limit is determined from the *arr* min/max value.
+      *cmap*:
+        cmap is a colors.Colormap instance, eg cm.jet.
+        If None, default to the rc image.cmap value.
+      *format*:
+        One of the file extensions supported by the active
+        backend.  Most backends support png, pdf, ps, eps and svg.
+      *origin*
+        [ 'upper' | 'lower' ] Indicates where the [0,0] index of
+        the array is in the upper left or lower left corner of
+        the axes. Defaults to the rc image.origin value.
+    """
+    from matplotlib.backends.backend_agg import FigureCanvasAgg as FigureCanvas
+    from matplotlib.figure import Figure
+
+    fig = Figure(figsize=arr.shape[::-1], dpi=1, frameon=False)
+    canvas = FigureCanvas(fig)
+    fig.figimage(arr, cmap=cmap, vmin=vmin, vmax=vmax, origin=origin)
+    fig.savefig(fname, dpi=1, format=format)
+
 
 def pil_to_array( pilImage ):
     """
diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py
@@ -50,6 +50,7 @@
   ion      - turn interaction mode on
   isinteractive - return True if interaction mode is on
   imread   - load image file into array
+  imsave   - save array as an image file
   imshow   - plot image data
   ishold   - return the hold state of the current axes
   legend   - make an axes legend
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -6,6 +6,7 @@
 from matplotlib.figure import Figure, figaspect
 from matplotlib.backend_bases import FigureCanvasBase
 from matplotlib.image import imread as _imread
+from matplotlib.image import imsave as _imsave
 from matplotlib import rcParams, rcParamsDefault, get_backend
 from matplotlib.rcsetup import interactive_bk as _interactive_bk
 from matplotlib.artist import getp, get, Artist
@@ -1181,6 +1182,7 @@ def plotting():
     legend          add a legend to the axes
     loglog          a log log plot
     imread          load image file into array
+    imsave          save array as an image file
     imshow          plot image data
     matshow         display a matrix in a new figure preserving aspect
     pcolor          make a pseudocolor plot
@@ -1230,7 +1232,7 @@ def plotting():
 def get_plot_commands(): return ( 'axes', 'axis', 'bar', 'boxplot', 'cla', 'clf',
     'close', 'colorbar', 'cohere', 'csd', 'draw', 'errorbar',
     'figlegend', 'figtext', 'figimage', 'figure', 'fill', 'gca',
-    'gcf', 'gci', 'get', 'gray', 'barh', 'jet', 'hist', 'hold', 'imread',
+    'gcf', 'gci', 'get', 'gray', 'barh', 'jet', 'hist', 'hold', 'imread', 'imsave',
     'imshow', 'legend', 'loglog', 'quiver', 'rc', 'pcolor', 'pcolormesh', 'plot', 'psd',
     'savefig', 'scatter', 'set', 'semilogx', 'semilogy', 'show',
     'specgram', 'stem', 'subplot', 'table', 'text', 'title', 'xlabel',
@@ -1370,6 +1372,11 @@ def imread(*args, **kwargs):
 if _imread.__doc__ is not None:
     imread.__doc__ = dedent(_imread.__doc__)
 
+def imsave(*args, **kwargs):
+    return _imsave(*args, **kwargs)
+if _imsave.__doc__ is not None:
+    imsave.__doc__ = dedent(_imsave.__doc__)
+
 def matshow(A, fignum=None, **kw):
     """
     Display an array as a matrix in a new figure window.
