Document image drawing in Kiva

docs/source/index.rst

@@ -8,6 +8,7 @@ Enable Documentation
   kiva/backends.rst
   kiva/fonts.rst
   kiva/compiled_path.rst
+  kiva/images.rst
   kiva/state.rst
   kiva/quickref.rst
 

docs/source/kiva/images.rst

@@ -0,0 +1,57 @@
+Kiva Image Rendering
+====================
+
+Drawing images in kiva is accomplished via
+:py:meth:`GraphicsContext.draw_image`. A unique feature of drawing images
+(relative to path drawing) is that you can apply an arbitrary translation and
+scaling to the image without involving the current transformation matrix.
+
+The signature for :py:meth:`draw_image` is straightforward:
+
+.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.draw_image
+   :noindex:
+
+The ``image`` object that is passed to :py:meth:`draw_image` can be a numpy
+array, a `PIL <https://pillow.readthedocs.io/en/stable/>`_ ``Image`` instance,
+or another ``GraphicsContext`` instance of the same backend. If ``image`` is a
+numpy array, it is typically converted to a more convenient format via
+`PIL.Image.fromarray <https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.fromarray>`_.
+Therefore, one must be careful about the expected pixel format of the image. If
+your image is rendering with incorrect colors, this might be the problem.
+Passing the other allowed versions of ``image`` should give a more consistent
+result.
+
+If ``image`` contains an alpha channel and transparent or translucent pixels,
+this transparency should also be honored by the destination graphics context.
+However, not all backends may support this.
+
+Regarding the ``rect`` argument to :py:meth:`draw_image`, if it is not
+specified then the bounding rectangle of the graphics context will be used. As
+mentioned before, ``rect`` can be used to apply an arbitrary translation and
+scaling to an image. The translation is the x,y position of the rectangle and
+the scaling is the ratio of the image's width and height to those of the
+rectangle. In every case, ``rect`` will be transformed by the current
+transformation matrix.
+
+Special considerations
+----------------------
+If you only want to draw a subset of an image, you should pass only that subset
+to :py:meth:`draw_image`. The Kiva API does not support defining a "source"
+rectangle when drawing images, only a "destination".
+
+If drawing images with some scaling applied, one might wish to have control
+over the interpolation used when drawing the image. This can be accomplished
+with the :py:meth:`set_image_interpolation` method.
+
+.. note::
+  :py:meth:`set_image_interpolation` is currently only implemented by the
+  ``kiva.agg`` backend. Other backends may have the method, but it is
+  effectively a no-op.
+
+Saving images
+-------------
+One can also save the contents of a graphics context to an image. This is done
+via the :py:meth:`save` method:
+
+.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.save
+   :noindex: