Skip to content

Commit 28cebd4

Browse files
jklymakjklymak
authored
Merge pull request matplotlib#22702 from tacaswell/doc_tweak_transform_tutorial
Doc tweak transform tutorial
2 parents a436253 + 05b5049 commit 28cebd4

File tree

1 file changed

+95
-74
lines changed

1 file changed

+95
-74
lines changed

‎tutorials/advanced/transforms_tutorial.py‎

Lines changed: 95 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -3,80 +3,100 @@
33
Transformations Tutorial
44
========================
55
6-
Like any graphics packages, Matplotlib is built on top of a
7-
transformation framework to easily move between coordinate systems,
8-
the userland *data* coordinate system, the *axes* coordinate system,
9-
the *figure* coordinate system, and the *display* coordinate system.
10-
In 95% of your plotting, you won't need to think about this, as it
11-
happens under the hood, but as you push the limits of custom figure
12-
generation, it helps to have an understanding of these objects so you
13-
can reuse the existing transformations Matplotlib makes available to
14-
you, or create your own (see :mod:`matplotlib.transforms`). The table
15-
below summarizes the some useful coordinate systems, the transformation
16-
object you should use to work in that coordinate system, and the
17-
description of that system. In the ``Transformation Object`` column,
18-
``ax`` is a :class:`~matplotlib.axes.Axes` instance, and ``fig`` is a
19-
:class:`~matplotlib.figure.Figure` instance.
20-
21-
+----------------+-----------------------------+-----------------------------------+
22-
|Coordinates |Transformation object |Description |
23-
+================+=============================+===================================+
24-
|"data" |``ax.transData`` |The coordinate system for the data,|
25-
| | |controlled by xlim and ylim. |
26-
+----------------+-----------------------------+-----------------------------------+
27-
|"axes" |``ax.transAxes`` |The coordinate system of the |
28-
| | |`~matplotlib.axes.Axes`; (0, 0) |
29-
| | |is bottom left of the axes, and |
30-
| | |(1, 1) is top right of the axes. |
31-
+----------------+-----------------------------+-----------------------------------+
32-
|"subfigure" |``subfigure.transSubfigure`` |The coordinate system of the |
33-
| | |`.SubFigure`; (0, 0) is bottom left|
34-
| | |of the subfigure, and (1, 1) is top|
35-
| | |right of the subfigure. If a |
36-
| | |figure has no subfigures, this is |
37-
| | |the same as ``transFigure``. |
38-
+----------------+-----------------------------+-----------------------------------+
39-
|"figure" |``fig.transFigure`` |The coordinate system of the |
40-
| | |`.Figure`; (0, 0) is bottom left |
41-
| | |of the figure, and (1, 1) is top |
42-
| | |right of the figure. |
43-
+----------------+-----------------------------+-----------------------------------+
44-
|"figure-inches" |``fig.dpi_scale_trans`` |The coordinate system of the |
45-
| | |`.Figure` in inches; (0, 0) is |
46-
| | |bottom left of the figure, and |
47-
| | |(width, height) is the top right |
48-
| | |of the figure in inches. |
49-
+----------------+-----------------------------+-----------------------------------+
50-
|"display" |``None``, or |The pixel coordinate system of the |
51-
| |``IdentityTransform()`` |display window; (0, 0) is bottom |
52-
| | |left of the window, and (width, |
53-
| | |height) is top right of the |
54-
| | |display window in pixels. |
55-
+----------------+-----------------------------+-----------------------------------+
56-
|"xaxis", |``ax.get_xaxis_transform()``,|Blended coordinate systems; use |
57-
|"yaxis" |``ax.get_yaxis_transform()`` |data coordinates on one of the axis|
58-
| | |and axes coordinates on the other. |
59-
+----------------+-----------------------------+-----------------------------------+
60-
61-
All of the transformation objects in the table above take inputs in
62-
their coordinate system, and transform the input to the *display*
63-
coordinate system. That is why the *display* coordinate system has
64-
``None`` for the ``Transformation Object`` column -- it already is in
65-
*display* coordinates. The transformations also know how to invert
66-
themselves, to go from *display* back to the native coordinate system.
67-
This is particularly useful when processing events from the user
68-
interface, which typically occur in display space, and you want to
69-
know where the mouse click or key-press occurred in your *data*
70-
coordinate system.
71-
72-
Note that specifying objects in *display* coordinates will change their
73-
location if the ``dpi`` of the figure changes. This can cause confusion when
74-
printing or changing screen resolution, because the object can change location
75-
and size. Therefore it is most common
76-
for artists placed in an Axes or figure to have their transform set to
77-
something *other* than the `~.transforms.IdentityTransform()`; the default when
78-
an artist is placed on an Axes using `~.axes.Axes.add_artist` is for the
79-
transform to be ``ax.transData``.
6+
Like any graphics packages, Matplotlib is built on top of a transformation
7+
framework to easily move between coordinate systems, the userland *data*
8+
coordinate system, the *axes* coordinate system, the *figure* coordinate
9+
system, and the *display* coordinate system. In 95% of your plotting, you
10+
won't need to think about this, as it happens under the hood, but as you push
11+
the limits of custom figure generation, it helps to have an understanding of
12+
these objects so you can reuse the existing transformations Matplotlib makes
13+
available to you, or create your own (see :mod:`matplotlib.transforms`). The
14+
table below summarizes some useful coordinate systems, a description of each
15+
system, and the transformation object for going from each coordinate system to
16+
the *display* coordinates. In the "Transformation Object" column, ``ax`` is a
17+
:class:`~matplotlib.axes.Axes` instance, ``fig`` is a
18+
:class:`~matplotlib.figure.Figure` instance, and ``subfigure`` is a
19+
:class:`~matplotlib.figure.SubFigure` instance.
20+
21+
22+
+----------------+-----------------------------------+---------------------------------------------------+
23+
|Coordinate |Description |Transformation object |
24+
|system | |from system to display |
25+
+================+===================================+===================================================+
26+
|"data" |The coordinate system of the data |``ax.transData`` |
27+
| |in the Axes. | |
28+
+----------------+-----------------------------------+---------------------------------------------------+
29+
|"axes" |The coordinate system of the |``ax.transAxes`` |
30+
| |`~matplotlib.axes.Axes`; (0, 0) | |
31+
| |is bottom left of the axes, and | |
32+
| |(1, 1) is top right of the axes. | |
33+
+----------------+-----------------------------------+---------------------------------------------------+
34+
|"subfigure" |The coordinate system of the |``subfigure.transSubfigure`` |
35+
| |`.SubFigure`; (0, 0) is bottom left| |
36+
| |of the subfigure, and (1, 1) is top| |
37+
| |right of the subfigure. If a | |
38+
| |figure has no subfigures, this is | |
39+
| |the same as ``transFigure``. | |
40+
+----------------+-----------------------------------+---------------------------------------------------+
41+
|"figure" |The coordinate system of the |``fig.transFigure`` |
42+
| |`.Figure`; (0, 0) is bottom left | |
43+
| |of the figure, and (1, 1) is top | |
44+
| |right of the figure. | |
45+
+----------------+-----------------------------------+---------------------------------------------------+
46+
|"figure-inches" |The coordinate system of the |``fig.dpi_scale_trans`` |
47+
| |`.Figure` in inches; (0, 0) is | |
48+
| |bottom left of the figure, and | |
49+
| |(width, height) is the top right | |
50+
| |of the figure in inches. | |
51+
+----------------+-----------------------------------+---------------------------------------------------+
52+
|"xaxis", |Blended coordinate systems, using |``ax.get_xaxis_transform()``, |
53+
|"yaxis" |data coordinates on one direction |``ax.get_yaxis_transform()`` |
54+
| |and axes coordinates on the other. | |
55+
+----------------+-----------------------------------+---------------------------------------------------+
56+
|"display" |The native coordinate system of the|`None`, or |
57+
| |output ; (0, 0) is the bottom left |:class:`~matplotlib.transforms.IdentityTransform()`|
58+
| |of the window, and (width, height) | |
59+
| |is top right of the output in | |
60+
| |"display units". | |
61+
| | | |
62+
| |The exact interpertation of the | |
63+
| |units depends on the back end. For | |
64+
| |example it is pixels for Agg and | |
65+
| |points for svg/pdf. | |
66+
+----------------+-----------------------------------+---------------------------------------------------+
67+
68+
69+
70+
71+
72+
The `~matplotlib.transforms.Transform` objects are naive to the source and
73+
destination coordinate systems, however the objects referred to in the table
74+
above are constructed to take inputs in their coordinate system, and transform
75+
the input to the *display* coordinate system. That is why the *display*
76+
coordinate system has `None` for the "Transformation Object" column -- it
77+
already is in *display* coordinates. The naming and destination conventions
78+
are an aid to keeping track of the available "standard" coordinate systems and
79+
transforms.
80+
81+
The transformations also know how to invert themselves (via
82+
`.Transform.inverted`) to generate a transform from output coordinate system
83+
back to the input coordinate system. For example, ``ax.transData`` converts
84+
values in data coordinates to display coordinates and
85+
``ax.transData.inversed()`` is a :class:`matplotlib.transforms.Transform` that
86+
goes from display coordinates to data coordinates. This is particularly useful
87+
when processing events from the user interface, which typically occur in
88+
display space, and you want to know where the mouse click or key-press occurred
89+
in your *data* coordinate system.
90+
91+
Note that specifying the position of Artists in *display* coordinates may
92+
change their relative location if the ``dpi`` or size of the figure changes.
93+
This can cause confusion when printing or changing screen resolution, because
94+
the object can change location and size. Therefore it is most common for
95+
artists placed in an Axes or figure to have their transform set to something
96+
*other* than the `~.transforms.IdentityTransform()`; the default when an artist
97+
is added to an Axes using `~.axes.Axes.add_artist` is for the transform to be
98+
``ax.transData`` so that you can work and think in *data* coordinates and let
99+
Matplotlib take care of the transformation to *display*.
80100
81101
.. _data-coords:
82102
@@ -89,6 +109,7 @@
89109
:meth:`~matplotlib.axes.Axes.set_ylim` methods. For example, in the figure
90110
below, the data limits stretch from 0 to 10 on the x-axis, and -1 to 1 on the
91111
y-axis.
112+
92113
"""
93114

94115
import numpy as np

0 commit comments

Comments
 (0)