@@ -508,30 +508,34 @@ def get_image_magnification(self):
508508 """
509509return 1.0
510510
511- def draw_image (self ,gc ,x ,y ,im ,trans = None ):
511+ def draw_image (self ,gc ,x ,y ,im ,transform = None ):
512512"""
513- Drawthe image instance into the current axes;
513+ Drawan RGBA image.
514514
515515 *gc*
516- aGraphicsContext containing clipping information
516+ a:class:`GraphicsContextBase` instance with clipping information.
517517
518518 *x*
519- is the distance in pixels from the left hand side of the canvas.
519+ the distance in physical units (i.e., dots or pixels) from the left
520+ hand side of the canvas.
520521
521522 *y*
522- the distance from the origin. That is, if origin is
523- upper, y is the distance from top. If origin is lower, y
524- is the distance from bottom
523+ the distance in physical units (i.e., dots or pixels) from the
524+ bottom side of the canvas.
525525
526526 *im*
527527 An NxMx4 array of RGBA pixels (of dtype uint8).
528528
529- *trans*
530- If the concrete backend is written such that
531- `option_scale_image` returns `True`, an affine
532- transformation may also be passed to `draw_image`. The
533- backend should apply the transformation to the image
534- before applying the translation of `x` and `y`.
529+ *transform*
530+ If and only if the concrete backend is written such that
531+ :meth:`option_scale_image` returns ``True``, an affine
532+ transformation *may* be passed to :meth:`draw_image`. It takes the
533+ form of a :class:`~matplotlib.transforms.Affine2DBase` instance.
534+ The translation vector of the transformation is given in physical
535+ units (i.e., dots or pixels). Note that the transformation does not
536+ override `x` and `y`, and has to be applied *before* translating
537+ the result by `x` and `y` (this can be accomplished by adding `x`
538+ and `y` to the translation vector defined by `transform`).
535539 """
536540raise NotImplementedError
537541
@@ -544,8 +548,8 @@ def option_image_nocomposite(self):
544548
545549def option_scale_image (self ):
546550"""
547- override this method for renderers that support arbitrary
548- scaling of image (mostof the vectorbackend ).
551+ override this method for renderers that support arbitrary affine
552+ transformations in :meth:`draw_image` (most vectorbackends ).
549553 """
550554return False
551555