DOC: Rewrite parts of imshow origin/extent handling

timhoffm · timhoffm · commit f1b481b322ca · 2018-04-27T02:55:29.000+02:00
diff --git a/tutorials/intermediate/imshow_extent.py b/tutorials/intermediate/imshow_extent.py
@@ -14,6 +14,9 @@
 **data coordinates**, the *origin* kwarg controls how the image fills
 that bounding box, and the orientation in the final rendered image is
 also affected by the axes limits.
+
+.. hint:: For the moment, you may want to skip the code details below and
+   directly continue with the discussion of the results.
 """
 import numpy as np
 import matplotlib.pyplot as plt
@@ -80,7 +83,7 @@ def set_extent_None_text(ax):
             ha='center', va='center', color='w')
 
 
-def generate_imshow_demo_grid(extents, auto_limits):
+def generate_imshow_demo_grid(extents, xlim=None, ylim=None):
     N = len(extents)
     fig = plt.figure(tight_layout=True)
     fig.set_size_inches(6, N * (11.25) / 5)
@@ -98,12 +101,12 @@ def generate_imshow_demo_grid(extents, auto_limits):
             im = ax.imshow(d, origin=origin, extent=extent)
             left, right, bottom, top = im.get_extent()
 
-            if auto_limits or top > bottom:
+            if xlim is None or top > bottom:
                 upper_string, lower_string = 'top', 'bottom'
             else:
                 upper_string, lower_string = 'bottom', 'top'
 
-            if auto_limits or left < right:
+            if ylim is None or left < right:
                 port_string, starboard_string = 'left', 'right'
                 inverted_xindex = False
             else:
@@ -135,9 +138,10 @@ def generate_imshow_demo_grid(extents, auto_limits):
                 ax.text(tx, ty, index, color='white', ha=halign, va='center',
                         bbox={'boxstyle': 'square', 'facecolor': facecolor})
 
-            if not auto_limits:
-                ax.set_xlim(-1, 7)
-                ax.set_ylim(-1, 6)
+            if xlim:
+                ax.set_xlim(*xlim)
+            if ylim:
+                ax.set_ylim(*ylim)
 
     for ax, extent in zip(columns['label'], extents):
         text_kwargs = {'ha': 'right',
@@ -158,71 +162,92 @@ def generate_imshow_demo_grid(extents, auto_limits):
     return columns
 
 
-extents = (None,
-           (-0.5, 6.5, -0.5, 5.5),
-           (-0.5, 6.5, 5.5, -0.5),
-           (6.5, -0.5, -0.5, 5.5),
-           (6.5, -0.5, 5.5, -0.5))
 
+###############################################################################
+#
+# Default extent
+# --------------
+#
+# First, let's have a look at the default `extent=None`
 
+generate_imshow_demo_grid(extents=[None])
 
 ###############################################################################
 #
+# Generally, for an array of shape (N, M), the first index runs along the
+# vertical, the second index runs along the horizontal.
+# The pixel centers are at integer positions ranging from 0 to `N' = N - 1``
+# vertically and from 0 to ``M' = M - 1`` horizontally.
+# *origin* determines how to the data is filled in the bounding box.
 #
-# First, using *extent* we pick a bounding box in dataspace that the
-# image will fill and then interpolate/resample the underlying data to
-# fill that box.
+# For ``origin='lower'``:
 #
-# - If ``origin='lower'`` than the ``[0, 0]`` entry is closest to the
-#   ``(left, bottom)`` corner of the bounding box and moving closer to
-#   ``(left, top)`` moves along the ``[:, 0]`` axis of the array to
-#   higher indexed rows and moving towards ``(right, bottom)`` moves you
-#   along the ``[0, :]`` axis of the array to higher indexed columns
+#    - [0, 0] is at (left, bottom)
+#    - [N', 0] is at (left, top)
+#    - [0, M'] is at (right, bottom)
+#    - [N', M'] is at (right, top)
 #
-# - If ``origin='upper'`` then the ``[-1, 0]`` entry is closest to the
-#   ``(left, bottom)`` corner of the bounding box and moving towards
-#   ``(left, top)`` moves along the ``[:, 0]`` axis of the array to
-#   lower index rows and moving towards ``(right, bottom)`` moves you
-#   along the ``[-1, :]`` axis of the array to higher indexed columns
-
-generate_imshow_demo_grid(extents[:1], auto_limits=True)
-
-###############################################################################
+# ``origin='upper'`` reverses the vertical axes direction and filling:
+#
+#    - [0, 0] is at (left, top)
+#    - [N', 0] is at (left, bottom)
+#    - [0, M'] is at (right, top)
+#    - [N', M'] is at (right, bottom)
 #
-# If we only specify *origin* we can see why it is so named.  For
-# ``origin='upper'`` the ``[0, 0]`` pixel is on the upper left and for
-# ``origin='lower'`` the ``[0, 0]`` pixel is in the lower left [#]_.
-# The gray arrows are attached to the ``(left, bottom)`` corner of the
-# image.  There are two tricky things going on here: first the default
-# value of *extent* depends on the value of *origin* and second the x
-# and y limits are adjusted to match the extent.  The default *extent*
-# is ``(-0.5, numcols-0.5, numrows-0.5, -0.5)`` when ``origin ==
-# 'upper'`` and ``(-0.5, numcols-0.5, -0.5, numrows-0.5)`` when ``origin
-# == 'lower'`` which puts the pixel centers on integer positions and the
-# ``[0, 0]`` pixel at ``(0, 0)`` in dataspace.
+# In summary, the position of the [0, 0] index as well as the extent are
+# influenced by *origin*:
 #
+# ======  ===============  ==========================================
+# origin  [0, 0] position  extent
+# ======  ===============  ==========================================
+# upper   top left         ``(-0.5, numcols-0.5, numrows-0.5, -0.5)``
+# lower   bottom left      ``(-0.5, numcols-0.5, -0.5, numrows-0.5)``
+# ======  ===============  ==========================================
 #
-# .. [#] The default value of *origin* is set by :rc:`image.origin`
-#    which defaults to ``'upper'`` to match the matrix indexing
-#    conventions in math and computer graphics image indexing
-#    conventions.
+# The default value of *origin* is set by :rc:`image.origin` which defaults
+# to ``'upper'`` to match the matrix indexing conventions in math and
+# computer graphics image indexing conventions.
+#
+#
+# Explicit extent
+# ---------------
+#
+# By setting *extent* we pick a bounding box in dataspace that the image will
+# fill. Then, the underlying data is interpolated/resampled to fill that box.
 #
 # If the axes is set to autoscale, then view limits of the axes are set
 # to match the *extent* which ensures that the coordinate set by
 # ``(left, bottom)`` is at the bottom left of the axes!  However, this
 # may invert the axis so they do not increase in the 'natural' direction.
 #
 
-columns = generate_imshow_demo_grid(extents[1:], auto_limits=True)
+extents = [(-0.5, 6.5, -0.5, 5.5),
+           (-0.5, 6.5, 5.5, -0.5),
+           (6.5, -0.5, -0.5, 5.5),
+           (6.5, -0.5, 5.5, -0.5)]
+
+columns = generate_imshow_demo_grid(extents)
 set_extent_None_text(columns['upper'][1])
 set_extent_None_text(columns['lower'][0])
 
 
 ###############################################################################
 #
-# If we fix the axes limits so ``(0, 0)`` is at the bottom left and
-# increases to up and to the right (from the viewer point of view) then
-# we can see that:
+# Explicit extent and axes limits
+# -------------------------------
+#
+# If we fix the axes limits by explicity setting `set_xlim` / `set_ylim`, we
+# force a certain size and orientation of the axes.
+# This can decouple the 'left-right' and 'top-bottom' sense of the image from
+# the orientation on the screen.
+#
+# In the example below we have chosen the limits slightly larger than the
+# the extent (note the white areas within the Axes.
+#
+# While we keep the extents as in the examples before, (0, 0) is now
+# explicitly put at the bottom left and values
+# increase to up and to the right (from the viewer point of view).
+# We can see that:
 #
 # - The ``(left, bottom)`` anchors the image which then fills the
 #   box going towards the ``(right, top)`` point in data space.
@@ -232,6 +257,5 @@ def generate_imshow_demo_grid(extents, auto_limits):
 # - The 'left-right' and 'top-bottom' sense of the image is uncoupled from
 #   the orientation on the screen.
 
-columns = generate_imshow_demo_grid(extents, auto_limits=False)
-set_extent_None_text(columns['upper'][2])
-set_extent_None_text(columns['lower'][1])
+generate_imshow_demo_grid(extents=[None] + extents,
+                          xlim=(-2, 8), ylim=(-1, 6))
