|
3 | 3 | Transformations Tutorial |
4 | 4 | ======================== |
5 | 5 |
|
6 | | -Transforming visuals in Matplotlib. |
7 | | -
|
8 | | -Like any graphics packages, matplotlib is built on top of a |
| 6 | +Like any graphics packages, Matplotlib is built on top of a |
9 | 7 | transformation framework to easily move between coordinate systems, |
10 | 8 | the userland `data` coordinate system, the `axes` coordinate system, |
11 | 9 | the `figure` coordinate system, and the `display` coordinate system. |
12 | 10 | In 95% of your plotting, you won't need to think about this, as it |
13 | 11 | happens under the hood, but as you push the limits of custom figure |
14 | 12 | generation, it helps to have an understanding of these objects so you |
15 | | -can reuse the existing transformations matplotlib makes available to |
| 13 | +can reuse the existing transformations Matplotlib makes available to |
16 | 14 | you, or create your own (see :mod:`matplotlib.transforms`). The table |
17 | | -below summarizes the existing coordinate systems, the transformation |
| 15 | +below summarizes the some useful coordinate systems, the transformation |
18 | 16 | object you should use to work in that coordinate system, and the |
19 | 17 | description of that system. In the `Transformation Object` column, |
20 | 18 | ``ax`` is a :class:`~matplotlib.axes.Axes` instance, and ``fig`` is a |
21 | 19 | :class:`~matplotlib.figure.Figure` instance. |
22 | 20 |
|
23 | | -========== ===================== ==================================================================================== |
24 | | -Coordinate Transformation Object Description |
25 | | -========== ===================== ==================================================================================== |
26 | | -`data` ``ax.transData`` The userland data coordinate system, controlled by the xlim and ylim |
27 | | -`axes` ``ax.transAxes`` The coordinate system of the :class:`~matplotlib.axes.Axes`; (0, 0) is |
28 | | - bottom left of the axes, and (1, 1) is top right of the axes. |
29 | | -`figure` ``fig.transFigure`` The coordinate system of the :class:`~matplotlib.figure.Figure`; (0, 0) |
30 | | - is bottom left of the figure, and (1, 1) is top right of the figure. |
31 | | -`display` `None` This is the pixel coordinate system of the display; (0, 0) is the bottom |
32 | | - left of the display, and (width, height) is the top right of the display in pixels. |
33 | | - Alternatively, the identity transform |
34 | | - (:class:`matplotlib.transforms.IdentityTransform()`) may be used instead of None. |
35 | | -========== ===================== ==================================================================================== |
36 | | -
|
| 21 | +=========== ============================= ===================================== |
| 22 | +Coordinates Transformation object Description |
| 23 | +=========== ============================= ===================================== |
| 24 | +"data" ``ax.transData```` The coordinate system for the data, |
| 25 | + controlled by xlim and ylim. |
| 26 | +"axes" ``ax.transAxes`` The coordinate system of the |
| 27 | + `~.Axes`; (0, 0) is bottom left of |
| 28 | + the axes, and (1, 1) is top right of |
| 29 | + the axes. |
| 30 | +"figure" ``fig.transFigure`` The coordinate system of the |
| 31 | + `~.Figure`; (0, 0) is bottom left of |
| 32 | + the figure, and (1, 1) is top right |
| 33 | + of the figure. |
| 34 | +"display" ``None``, or The pixel coordinate system of the |
| 35 | + ``IdentityTransform()`` display; (0, 0) is bottom left of the |
| 36 | + display, and (width, height) is top |
| 37 | + right of the display in pixels. |
| 38 | +"xaxis", ``ax.get_xaxis_transform()``, Blended coordinate systems; use data |
| 39 | +"yaxis" ``ax.get_yaxis_transform()`` coordinates on one of the axis and |
| 40 | + axes coordinates on the other. |
| 41 | +=========== ============================= ===================================== |
37 | 42 |
|
38 | 43 | All of the transformation objects in the table above take inputs in |
39 | 44 | their coordinate system, and transform the input to the `display` |
|
52 | 57 | ================ |
53 | 58 |
|
54 | 59 | Let's start with the most commonly used coordinate, the `data` |
55 | | -coordinate system. Whenever you add data to the axes, matplotlib |
| 60 | +coordinate system. Whenever you add data to the axes, Matplotlib |
56 | 61 | updates the datalimits, most commonly updated with the |
57 | 62 | :meth:`~matplotlib.axes.Axes.set_xlim` and |
58 | 63 | :meth:`~matplotlib.axes.Axes.set_ylim` methods. For example, in the |
|
431 | 436 | # The final piece is the ``self.transScale`` attribute, which is |
432 | 437 | # responsible for the optional non-linear scaling of the data, e.g., for |
433 | 438 | # logarithmic axes. When an Axes is initially setup, this is just set to |
434 | | -# the identity transform, since the basic matplotlib axes has linear |
| 439 | +# the identity transform, since the basic Matplotlib axes has linear |
435 | 440 | # scale, but when you call a logarithmic scaling function like |
436 | 441 | # :meth:`~matplotlib.axes.Axes.semilogx` or explicitly set the scale to |
437 | 442 | # logarithmic with :meth:`~matplotlib.axes.Axes.set_xscale`, then the |
|
455 | 460 | # data, to a separable Cartesian coordinate system. There are several |
456 | 461 | # projection examples in the ``matplotlib.projections`` package, and the |
457 | 462 | # best way to learn more is to open the source for those packages and |
458 | | -# see how to make your own, since matplotlib supports extensible axes |
| 463 | +# see how to make your own, since Matplotlib supports extensible axes |
459 | 464 | # and projections. Michael Droettboom has provided a nice tutorial |
460 | | -# example of creating a hammer projection axes; see |
| 465 | +# example of creating a Hammer projection axes; see |
461 | 466 | # :ref:`sphx_glr_gallery_api_custom_projection_example.py`. |
0 commit comments