10000 DOC: adjust the prose in the transform tutorial · meeseeksmachine/matplotlib@6aa18c4 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6aa18c4

Browse files
tacaswelltacaswell
committed
DOC: adjust the prose in the transform tutorial
Try to make it more clear that the transforms are naive-to-coordinates functions and the naming conventions / always go to display convention is to aid understanding but not inherent to the code.
1 parent c2a63f4 commit 6aa18c4

File tree

1 file changed

+33
-31
lines changed

1 file changed

+33
-31
lines changed

‎tutorials/advanced/transforms_tutorial.py

Lines changed: 33 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,17 @@
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,
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 the some useful coordinate systems, the description of
15+
that system, and the transformation object for going from that coordinate
16+
system to the *display* coordinates. In the ``Transformation Object`` column,
1817
``ax`` is a :class:`~matplotlib.axes.Axes` instance, and ``fig`` is a
1918
:class:`~matplotlib.figure.Figure` instance.
2019
@@ -68,27 +67,30 @@
6867
6968
7069
70+
The `~matplotlib.transforms.Transform` objects are naive to the source and
71+
destination coordinate systems, however the objects refereed to in the table
72+
above are constructed to take inputs in their coordinate system, and transform
73+
the input to the *display* coordinate system. That is why the *display*
74+
coordinate system has ``None`` for the ``Transformation Object`` column -- it
75+
already is in *display* coordinates. The naming and destination conventions
76+
are an aid to keeping track of the available "standard" coordinate systems and
77+
transforms.
7178
79+
The transformations also know how to invert themselves, to go from *display*
80+
back to the native coordinate system. This is particularly useful when
81+
processing events from the user interface, which typically occur in display
82+
space, and you want to know where the mouse click or key-press occurred in your
83+
*data* coordinate system.
7284
73-
All of the transformation objects in the table above take inputs in
74-
their coordinate system, and transform the input to the *display*
75-
coordinate system. That is why the *display* coordinate system has
76-
``None`` for the ``Transformation Object`` column -- it already is in
77-
*display* coordinates. The transformations also know how to invert
78-
themselves, to go from *display* back to the native coordinate system.
79-
This is particularly useful when processing events from the user
80-
interface, which typically occur in display space, and you want to
81-
know where the mouse click or key-press occurred in your *data*
82-
coordinate system.
83-
84-
Note that specifying objects in *display* coordinates will change their
85-
location if the ``dpi`` of the figure changes. This can cause confusion when
86-
printing or changing screen resolution, because the object can change location
87-
and size. Therefore it is most common
88-
for artists placed in an Axes or figure to have their transform set to
89-
something *other* than the `~.transforms.IdentityTransform()`; the default when
90-
an artist is placed on an Axes using `~.axes.Axes.add_artist` is for the
91-
transform to be ``ax.transData``.
85+
Note that specifying the position of Artists in *display* coordinates may
86+
change their relative location if the ``dpi`` or size of the figure changes.
87+
This can cause confusion when printing or changing screen resolution, because
88+
the object can change location and size. Therefore it is most common for
89+
artists placed in an Axes or figure to have their transform set to something
90+
*other* than the `~.transforms.IdentityTransform()`; the default when an artist
91+
is added to an Axes using `~.axes.Axes.add_artist` is for the transform to be
92+
``ax.transData`` so that you can work and think in *data* coordinates and let
93+
Matplotlib take care of the transformation to *display*.
9294
9395
.. _data-coords:
9496

0 commit comments

Comments
 (0)
0