Skip to content

Document get_{x,y}axis_transform more prominently. #9375

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 11, 2017
Merged

Document get_{x,y}axis_transform more prominently. #9375

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 28 additions & 23 deletions tutorials/advanced/transforms_tutorial.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,37 +3,42 @@
Transformations Tutorial
========================

Transforming visuals in Matplotlib.

Like any graphics packages, matplotlib is built on top of a
Like any graphics packages, Matplotlib is built on top of a
transformation framework to easily move between coordinate systems,
the userland `data` coordinate system, the `axes` coordinate system,
the `figure` coordinate system, and the `display` coordinate system.
In 95% of your plotting, you won't need to think about this, as it
happens under the hood, but as you push the limits of custom figure
generation, it helps to have an understanding of these objects so you
can reuse the existing transformations matplotlib makes available to
can reuse the existing transformations Matplotlib makes available to
you, or create your own (see :mod:`matplotlib.transforms`). The table
below summarizes the existing coordinate systems, the transformation
below summarizes the some useful coordinate systems, the transformation
object you should use to work in that coordinate system, and the
description of that system. In the `Transformation Object` column,
``ax`` is a :class:`~matplotlib.axes.Axes` instance, and ``fig`` is a
:class:`~matplotlib.figure.Figure` instance.

========== ===================== ====================================================================================
Coordinate Transformation Object Description
========== ===================== ====================================================================================
`data` ``ax.transData`` The userland data coordinate system, controlled by the xlim and ylim
`axes` ``ax.transAxes`` The coordinate system of the :class:`~matplotlib.axes.Axes`; (0, 0) is
bottom left of the axes, and (1, 1) is top right of the axes.
`figure` ``fig.transFigure`` The coordinate system of the :class:`~matplotlib.figure.Figure`; (0, 0)
is bottom left of the figure, and (1, 1) is top right of the figure.
`display` `None` This is the pixel coordinate system of the display; (0, 0) is the bottom
left of the display, and (width, height) is the top right of the display in pixels.
Alternatively, the identity transform
(:class:`matplotlib.transforms.IdentityTransform()`) may be used instead of None.
========== ===================== ====================================================================================

=========== ============================= =====================================
Coordinates Transformation object Description
=========== ============================= =====================================
"data" ``ax.transData```` The coordinate system for the data,
controlled by xlim and ylim.
"axes" ``ax.transAxes`` The coordinate system of the
`~.Axes`; (0, 0) is bottom left of
the axes, and (1, 1) is top right of
the axes.
"figure" ``fig.transFigure`` The coordinate system of the
`~.Figure`; (0, 0) is bottom left of
the figure, and (1, 1) is top right
of the figure.
"display" ``None``, or The pixel coordinate system of the
``IdentityTransform()`` display; (0, 0) is bottom left of the
display, and (width, height) is top
right of the display in pixels.
"xaxis", ``ax.get_xaxis_transform()``, Blended coordinate systems; use data
"yaxis" ``ax.get_yaxis_transform()`` coordinates on one of the axis and
axes coordinates on the other.
=========== ============================= =====================================

All of the transformation objects in the table above take inputs in
their coordinate system, and transform the input to the `display`
Expand All @@ -52,7 +57,7 @@
================

Let's start with the most commonly used coordinate, the `data`
coordinate system. Whenever you add data to the axes, matplotlib
coordinate system. Whenever you add data to the axes, Matplotlib
updates the datalimits, most commonly updated with the
:meth:`~matplotlib.axes.Axes.set_xlim` and
:meth:`~matplotlib.axes.Axes.set_ylim` methods. For example, in the
Expand Down Expand Up @@ -431,7 +436,7 @@
# The final piece is the ``self.transScale`` attribute, which is
# responsible for the optional non-linear scaling of the data, e.g., for
# logarithmic axes. When an Axes is initially setup, this is just set to
# the identity transform, since the basic matplotlib axes has linear
# the identity transform, since the basic Matplotlib axes has linear
# scale, but when you call a logarithmic scaling function like
# :meth:`~matplotlib.axes.Axes.semilogx` or explicitly set the scale to
# logarithmic with :meth:`~matplotlib.axes.Axes.set_xscale`, then the
Expand All @@ -455,7 +460,7 @@
# data, to a separable Cartesian coordinate system. There are several
# projection examples in the ``matplotlib.projections`` package, and the
# best way to learn more is to open the source for those packages and
# see how to make your own, since matplotlib supports extensible axes
# see how to make your own, since Matplotlib supports extensible axes
# and projections. Michael Droettboom has provided a nice tutorial
# example of creating a hammer projection axes; see
# example of creating a Hammer projection axes; see
# :ref:`sphx_glr_gallery_api_custom_projection_example.py`.