update the documentation

doc/datasets/index.rst

@@ -47,6 +47,31 @@ These datasets are useful to quickly illustrate the behavior of the
 various algorithms implemented in the scikit. They are however often too
 small to be representative of real world machine learning tasks.
 
+Sample images
+=============
+
+The scikit also embed a couple of sample JPEG images published under Creative
+Commons license by their authors. Those image can be useful to test algorithms
+and pipeline on 2D data.
+
+.. autosummary::
+
+   load_sample_images
+   load_sample_image
+
+.. note::
+
+  The default coding of images is based on the ``uint8`` dtype to
+  spare memory.  Often machine learning algorithms work best if the
+  input is converted to a floating point representation first.  Also,
+  if you plan to use ``pylab.imshow`` don't forget to scale to the range
+  0 - 1 as done in the following example.
+
+.. topic:: Examples:
+
+    * :ref:`example_cluster_plot_vq_china.py`
+
+
 Sample generators
 =================
 

examples/cluster/vq_china.py → examples/cluster/plot_vq_china.py

@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
 """
-=========================================
-Vector Quantization of Lena using k-means
-=========================================
+============================================
+Vector Quantization of a photo using k-means
+============================================
 
-Performs a Vector Quantization of an image, reducing the number of colors
-required to show the image.
+Performs a pixel-wise Vector Quantization of an image, reducing the number of
+colors required to show the image while preserving the overall appearance.
 """
 print __doc__
 import numpy as np
@@ -52,13 +52,15 @@ def recreate_image(codebook, labels, w, h):
     return image
 
 # Display all results, alongside original image
-pl.figure()
-ax = pl.axes([0, 0, 1, 1], frameon=False)
-ax.set_axis_off()
+pl.figure(1)
+pl.clf()
+ax = pl.axes([0, 0, 1, 1])
+pl.axis('off')
 pl.imshow(china)
 
-pl.figure()
-ax = pl.axes([0, 0, 1, 1], frameon=False)
-ax.set_axis_off()
+pl.figure(2)
+pl.clf()
+ax = pl.axes([0, 0, 1, 1])
+pl.axis('off')
 pl.imshow(recreate_image(kmeans.cluster_centers_, labels, w, h))
 pl.show()