Working with transformations

matplotlib.transforms

matplotlib includes a framework for arbitrary geometric transformations that is used determine the final position of all elements drawn on the canvas.

Transforms are composed into trees of TransformNode objects whose actual value depends on their children. When the contents of children change, their parents are automatically invalidated. The next time an invalidated transform is accessed, it is recomputed to reflect those changes. This invalidation/caching approach prevents unnecessary recomputations of transforms, and contributes to better interactive performance.

For example, here is a graph of the transform tree used to plot data to the graph:

../_images/transforms.png

The framework can be used for both affine and non-affine transformations. However, for speed, we want use the backend renderers to perform affine transformations whenever possible. Therefore, it is possible to perform just the affine or non-affine part of a transformation on a set of data. The affine is always assumed to occur after the non-affine. For any transform:

full transform == non-affine part + affine part

The backends are not expected to handle non-affine transformations themselves.

class matplotlib.transforms.TransformNode

Bases: object

TransformNode is the base class for anything that participates in the transform tree and needs to invalidate its parents or be invalidated. This includes classes that are not really transforms, such as bounding boxes, since some transforms depend on bounding boxes to compute their values.

Creates a new TransformNode.

frozen()
Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used.
invalidate()
Invalidate this transform node and all of its ancestors. Should be called any time the transform changes.
set_children(*children)
Set the children of the transform, to let the invalidation system know which transforms can invalidate this transform. Should be called from the constructor of any transforms that depend on other transforms.
class matplotlib.transforms.BboxBase

Bases: matplotlib.transforms.TransformNode

This is the base class of all bounding boxes, and provides read-only access to its data. A mutable bounding box is provided by the Bbox class.

The canonical representation is as two points, with no restrictions on their ordering. Convenience properties are provided to get the left, bottom, right and top edges and width and height, but these are not stored explicity.

Creates a new TransformNode.

anchored(c, container=None)

Return a copy of the Bbox, shifted to position c within a container.

c: may be either:

  • a sequence (cx, cy) where cx, cy range from 0 to 1, where 0 is left or bottom and 1 is right or top
  • a string: - C for centered - S for bottom-center - SE for bottom-left - E for left - etc.

Optional argument container is the box within which the Bbox is positioned; it defaults to the initial Bbox.

bounds
(property) Returns (x0, y0, width, height).
contains(x, y)
Returns True if (x, y) is a coordinate inside the bounding box or on its edge.
containsx(x)
Returns True if x is between or equal to x0 and x1.
containsy(y)
Returns True if y is between or equal to y0 and y1.
corners()
Return an array of points which are the four corners of this rectangle. For example, if this Bbox is defined by the points (a, b) and (c, d), corners() returns (a, b), (a, d), (c, b) and (c, d).
count_contains(vertices)

Count the number of vertices contained in the Bbox.

vertices is a Nx2 numpy array.

count_overlaps(bboxes)

Count the number of bounding boxes that overlap this one.

bboxes is a sequence of BboxBase objects

expanded(sw, sh)
Return a new Bbox which is this Bbox expanded around its center by the given factors sw and sh.
extents
(property) Returns (x0, y0, x1, y1).
frozen()
TransformNode is the base class for anything that participates in the transform tree and needs to invalidate its parents or be invalidated. This includes classes that are not really transforms, such as bounding boxes, since some transforms depend on bounding boxes to compute their values.
fully_contains(x, y)
Returns True if (x, y) is a coordinate inside the bounding box, but not on its edge.
fully_containsx(x)
Returns True if x is between but not equal to x0 and x1.
fully_containsy(y)
Returns True if y is between but not equal to y0 and y1.
fully_overlaps(other)
Returns True if this bounding box overlaps with the given bounding box other, but not on its edge alone.
height
(property) The height of the bounding box. It may be negative if y1 < y0.
intervalx
(property) intervalx is the pair of x coordinates that define the bounding box. It is not guaranteed to be sorted from left to right.
intervaly
(property) intervaly is the pair of y coordinates that define the bounding box. It is not guaranteed to be sorted from bottom to top.
inverse_transformed(transform)
Return a new Bbox object, statically transformed by the inverse of the given transform.
is_unit()
Returns True if the Bbox is the unit bounding box from (0, 0) to (1, 1).
max
(property) max is the top-right corner of the bounding box.
min
(property) min is the bottom-left corner of the bounding box.
overlaps(other)
Returns True if this bounding box overlaps with the given bounding box other.
p0
(property) p0 is the first pair of (x, y) coordinates that define the bounding box. It is not guaranteed to be the bottom-left corner. For that, use min.
p1
(property) p1 is the second pair of (x, y) coordinates that define the bounding box. It is not guaranteed to be the top-right corner. For that, use max.
padded(p)
Return a new Bbox that is padded on all four sides by the given value.
rotated(radians)
Return a new bounding box that bounds a rotated version of this bounding box by the given radians. The new bounding box is still aligned with the axes, of course.
shrunk(mx, my)
Return a copy of the Bbox, shurnk by the factor mx in the x direction and the factor my in the y direction. The lower left corner of the box remains unchanged. Normally mx and my will be less than 1, but this is not enforced.
shrunk_to_aspect(box_aspect, container=None, fig_aspect=1.0)
Return a copy of the Bbox, shrunk so that it is as large as it can be while having the desired aspect ratio, box_aspect. If the box coordinates are relative—that is, fractions of a larger box such as a figure—then the physical aspect ratio of that figure is specified with fig_aspect, so that box_aspect can also be given as a ratio of the absolute dimensions, not the relative dimensions.
size
(property) The width and height of the bounding box. May be negative, in the same way as width and height.
splitx(*args)

e.g., bbox.splitx(f1, f2, ...)

Returns a list of new Bbox objects formed by splitting the original one with vertical lines at fractional positions f1, f2, ...

splity(*args)

e.g., bbox.splitx(f1, f2, ...)

Returns a list of new Bbox objects formed by splitting the original one with horizontal lines at fractional positions f1, f2, ...

transformed(transform)
Return a new Bbox object, statically transformed by the given transform.
translated(tx, ty)
Return a copy of the Bbox, statically translated by tx and ty.
union
Return a Bbox that contains all of the given bboxes.
width
(property) The width of the bounding box. It may be negative if x1 < x0.
x0
(property) x0 is the first of the pair of x coordinates that define the bounding box. x0 is not guaranteed to be less than x1. If you require that, use xmin.
x1
(property) x1 is the second of the pair of x coordinates that define the bounding box. x1 is not guaranteed to be greater than x0. If you require that, use xmax.
xmax
(property) xmax is the right edge of the bounding box.
xmin
(property) xmin is the left edge of the bounding box.
y0
(property) y0 is the first of the pair of y coordinates that define the bounding box. y0 is not guaranteed to be less than y1. If you require that, use ymin.
y1
(property) y1 is the second of the pair of y coordinates that define the bounding box. y1 is not guaranteed to be greater than y0. If you require that, use ymax.
ymax
(property) ymax is the top edge of the bounding box.
ymin
(property) ymin is the bottom edge of the bounding box.
class matplotlib.transforms.Bbox(points)

Bases: matplotlib.transforms.BboxBase

A mutable bounding box.

points: a 2x2 numpy array of the form [[x0, y0], [x1, y1]]

If you need to create a Bbox object from another form of data, consider the static methods unit, from_bounds and from_extents.

from_bounds

(staticmethod) Create a new Bbox from x0, y0, width and height.

width and height may be negative.

from_extents

(staticmethod) Create a new Bbox from left, bottom, right and top.

The y-axis increases upwards.

get_points()
Get the points of the bounding box directly as a numpy array of the form: [[x0, y0], [x1, y1]].
ignore(value)

Set whether the existing bounds of the box should be ignored by subsequent calls to update_from_data() or update_from_data_xy().

value:

set(other)
Set this bounding box from the “frozen” bounds of another Bbox.
set_points(points)
Set the points of the bounding box directly from a numpy array of the form: [[x0, y0], [x1, y1]]. No error checking is performed, as this method is mainly for internal use.
unit
(staticmethod) Create a new unit Bbox from (0, 0) to (1, 1).
update_from_data(x, y, ignore=None)

Update the bounds of the Bbox based on the passed in data.

x: a numpy array of x-values

y: a numpy array of y-values

ignore:
  • when True, ignore the existing bounds of the Bbox.
  • when False, include the existing bounds of the Bbox.
  • when None, use the last value passed to ignore().
update_from_data_xy(xy, ignore=None)

Update the bounds of the Bbox based on the passed in data.

xy: a numpy array of 2D points

ignore:
  • when True, ignore the existing bounds of the Bbox.
  • when False, include the existing bounds of the Bbox.
  • when None, use the last value passed to ignore().
class matplotlib.transforms.TransformedBbox(bbox, transform)

Bases: matplotlib.transforms.BboxBase

A Bbox that is automatically transformed by a given transform. When either the child bounding box or transform changes, the bounds of this bbox will update accordingly.

bbox: a child bbox

transform: a 2D transform

get_points()
Get the points of the bounding box directly as a numpy array of the form: [[x0, y0], [x1, y1]].
class matplotlib.transforms.Transform

Bases: matplotlib.transforms.TransformNode

The base class of all TransformNodes that actually perform a transformation.

All non-affine transformations should be subclasses of this class. New affine transformations should be subclasses of Affine2D.

Subclasses of this class should override the following members (at minimum):

  • input_dims
  • output_dims
  • transform()
  • is_separable
  • has_inverse
  • inverted() (if has_inverse() can return True)

If the transform needs to do something non-standard with mathplotlib.path.Path objects, such as adding curves where there were once line segments, it should override:

Creates a new TransformNode.

get_affine()
Get the affine part of this transform.
inverted()

Return the corresponding inverse transformation.

The return value of this method should be treated as temporary. An update to ‘self’ does not cause a corresponding update to its inverted copy.

x === self.inverted().transform(self.transform(x))

transform(values)

Performs the transformation on the given array of values.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_affine(values)

Performs only the affine part of this transformation on the given array of values.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally a no-op. In affine transformations, this is equivalent to transform(values).

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_non_affine(values)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_path(path)

Returns a transformed copy of path.

path: a Path instance.

In some cases, this transform may insert curves into the path that began as line segments.

transform_path_affine(path)

Returns a copy of path, transformed only by the affine part of this transform.

path: a Path instance

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

transform_path_non_affine(path)

Returns a copy of path, transformed only by the non-affine part of this transform.

path: a Path instance

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

transform_point(point)

A convenience function that returns the transformed copy of a single point.

The point is given as a sequence of length input_dims. The transformed point is returned as a sequence of length output_dims.

class matplotlib.transforms.TransformWrapper(child)

Bases: matplotlib.transforms.Transform

A helper class that holds a single child transform and acts equivalently to it.

This is useful if a node of the transform tree must be replaced at run time with a transform of a different type. This class allows that replacement to correctly trigger invalidation.

Note that TransformWrapper instances must have the same input and output dimensions during their entire lifetime, so the child transform may only be replaced with another child transform of the same dimensions.

child: A Transform instance. This child may later be replaced with set().

frozen()
Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used.
set(child)

Replace the current child of this transform with another one.

The new child must have the same number of input and output dimensions as the current child.

class matplotlib.transforms.AffineBase

Bases: matplotlib.transforms.Transform

The base class of all affine transformations of any number of dimensions.

get_affine()
Get the affine part of this transform.
get_matrix()
Get the underlying transformation matrix as a numpy array.
transform_non_affine(points)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_path_affine(path)

Returns a copy of path, transformed only by the affine part of this transform.

path: a Path instance

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

transform_path_non_affine(path)

Returns a copy of path, transformed only by the non-affine part of this transform.

path: a Path instance

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

class matplotlib.transforms.Affine2DBase

Bases: matplotlib.transforms.AffineBase

The base class of all 2D affine transformations.

2D affine transformations are performed using a 3x3 numpy array:

a c e
b d f
0 0 1

This class provides the read-only interface. For a mutable 2D affine transformation, use Affine2D.

Subclasses of this class will generally only need to override a constructor and ‘get_matrix’ that generates a custom 3x3 matrix.

frozen()
Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used.
inverted()

Return the corresponding inverse transformation.

The return value of this method should be treated as temporary. An update to ‘self’ does not cause a corresponding update to its inverted copy.

x === self.inverted().transform(self.transform(x))

matrix_from_values

(staticmethod) Create a new transformation matrix as a 3x3 numpy array of the form:

a c e
b d f
0 0 1
to_values()
Return the values of the matrix as a sequence (a,b,c,d,e,f)
transform(points)

Performs only the affine part of this transformation on the given array of values.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally a no-op. In affine transformations, this is equivalent to transform(values).

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_affine(points)

Performs only the affine part of this transformation on the given array of values.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally a no-op. In affine transformations, this is equivalent to transform(values).

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_point(point)

A convenience function that returns the transformed copy of a single point.

The point is given as a sequence of length input_dims. The transformed point is returned as a sequence of length output_dims.

class matplotlib.transforms.Affine2D(matrix=None)

Bases: matplotlib.transforms.Affine2DBase

A mutable 2D affine transformation.

Initialize an Affine transform from a 3x3 numpy float array:

a c e
b d f
0 0 1

If matrix is None, initialize with the identity transform.

clear()
Reset the underlying matrix to the identity transform.
from_values

(staticmethod) Create a new Affine2D instance from the given values:

a c e
b d f
0 0 1
get_matrix()

Get the underlying transformation matrix as a 3x3 numpy array:

a c e
b d f
0 0 1
identity

(staticmethod) Return a new Affine2D object that is the identity transform.

Unless this transform will be mutated later on, consider using the faster IdentityTransform class instead.

rotate(theta)

Add a rotation (in radians) to this transform in place.

Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg, :meth:`translate() and scale().

rotate_around(x, y, theta)

Add a rotation (in radians) around the point (x, y) in place.

Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg, :meth:`translate() and scale().

rotate_deg(degrees)

Add a rotation (in degrees) to this transform in place.

Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg, :meth:`translate() and scale().

rotate_deg_around(x, y, degrees)

Add a rotation (in degrees) around the point (x, y) in place.

Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg, :meth:`translate() and scale().

scale(sx, sy=None)

Adds a scale in place.

If sy is None, the same scale is applied in both the x- and y-directions.

Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg, :meth:`translate() and scale().

set(other)
Set this transformation from the frozen copy of another Affine2DBase object.
set_matrix(mtx)

Set the underlying transformation matrix from a 3x3 numpy array:

a c e
b d f
0 0 1
translate(tx, ty)

Adds a translation in place.

Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg, :meth:`translate() and scale().

class matplotlib.transforms.IdentityTransform

Bases: matplotlib.transforms.Affine2DBase

A special class that does on thing, the identity transform, in a fast way.

frozen()
Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used.
get_affine()

Return the corresponding inverse transformation.

The return value of this method should be treated as temporary. An update to ‘self’ does not cause a corresponding update to its inverted copy.

x === self.inverted().transform(self.transform(x))

get_matrix()
Get the underlying transformation matrix as a numpy array.
inverted()

Return the corresponding inverse transformation.

The return value of this method should be treated as temporary. An update to ‘self’ does not cause a corresponding update to its inverted copy.

x === self.inverted().transform(self.transform(x))

transform(points)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_affine(points)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_non_affine(points)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_path(path)

Returns a copy of path, transformed only by the non-affine part of this transform.

path: a Path instance

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

transform_path_affine(path)

Returns a copy of path, transformed only by the non-affine part of this transform.

path: a Path instance

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

transform_path_non_affine(path)

Returns a copy of path, transformed only by the non-affine part of this transform.

path: a Path instance

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

class matplotlib.transforms.BlendedGenericTransform(x_transform, y_transform)

Bases: matplotlib.transforms.Transform

A “blended” transform uses one transform for the x-direction, and another transform for the y-direction.

This “generic” version can handle any given child transform in the x- and y-directions.

Create a new “blended” transform using x_transform to transform the x-axis and y_transform to transform the y_axis.

You will generally not call this constructor directly but use the blended_transform_factory() function instead, which can determine automatically which kind of blended transform to create.

frozen()
Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used.
get_affine()
Get the affine part of this transform.
inverted()

Return the corresponding inverse transformation.

The return value of this method should be treated as temporary. An update to ‘self’ does not cause a corresponding update to its inverted copy.

x === self.inverted().transform(self.transform(x))

transform(points)

Performs the transformation on the given array of values.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_affine(points)

Performs only the affine part of this transformation on the given array of values.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally a no-op. In affine transformations, this is equivalent to transform(values).

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_non_affine(points)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

class matplotlib.transforms.BlendedAffine2D(x_transform, y_transform)

Bases: matplotlib.transforms.Affine2DBase

A “blended” transform uses one transform for the x-direction, and another transform for the y-direction.

This version is an optimization for the case where both child transforms are of type Affine2DBase.

Create a new “blended” transform using x_transform to transform the x-axis and y_transform to transform the y_axis.

Both x_transform and y_transform must be 2D affine transforms.

You will generally not call this constructor directly but use the blended_transform_factory() function instead, which can determine automatically which kind of blended transform to create.

get_matrix()
Get the underlying transformation matrix as a numpy array.
matplotlib.transforms.blended_transform_factory(x_transform, y_transform)

Create a new “blended” transform using x_transform to transform the x-axis and y_transform to transform the y_axis.

A faster version of the blended transform is returned for the case where both child transforms are affine.

class matplotlib.transforms.CompositeGenericTransform(a, b)

Bases: matplotlib.transforms.Transform

A composite transform formed by applying transform a then transform b.

This “generic” version can handle any two arbitrary transformations.

Create a new composite transform that is the result of applying transform a then transform b.

You will generally not call this constructor directly but use the composite_transform_factory() function instead, which can automatically choose the best kind of composite transform instance to create.

frozen()
Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used.
get_affine()
Get the affine part of this transform.
inverted()

Return the corresponding inverse transformation.

The return value of this method should be treated as temporary. An update to ‘self’ does not cause a corresponding update to its inverted copy.

x === self.inverted().transform(self.transform(x))

transform(points)

Performs the transformation on the given array of values.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_affine(points)

Performs only the affine part of this transformation on the given array of values.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally a no-op. In affine transformations, this is equivalent to transform(values).

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_non_affine(points)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

transform_path(path)

Returns a transformed copy of path.

path: a Path instance.

In some cases, this transform may insert curves into the path that began as line segments.

transform_path_affine(path)

Returns a copy of path, transformed only by the affine part of this transform.

path: a Path instance

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

transform_path_non_affine(path)

Returns a copy of path, transformed only by the non-affine part of this transform.

path: a Path instance

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

class matplotlib.transforms.CompositeAffine2D(a, b)

Bases: matplotlib.transforms.Affine2DBase

A composite transform formed by applying transform a then transform b.

This version is an optimization that handles the case where both a and b are 2D affines.

Create a new composite transform that is the result of applying transform a then transform b.

Both a and b must be instances of Affine2DBase.

You will generally not call this constructor directly but use the composite_transform_factory() function instead, which can automatically choose the best kind of composite transform instance to create.

get_matrix()
Get the underlying transformation matrix as a numpy array.
matplotlib.transforms.composite_transform_factory(a, b)

Create a new composite transform that is the result of applying transform a then transform b.

Shortcut versions of the blended transform are provided for the case where both child transforms are affine, or one or the other is the identity transform.

Composite transforms may also be created using the ‘+’ operator, e.g.:

c = a + b
class matplotlib.transforms.BboxTransform(boxin, boxout)

Bases: matplotlib.transforms.Affine2DBase

BboxTransform linearly transforms points from one Bbox to another Bbox.

Create a new BboxTransform that linearly transforms points from boxin to boxout.

get_matrix()
Get the underlying transformation matrix as a numpy array.
class matplotlib.transforms.BboxTransformTo(boxout)

Bases: matplotlib.transforms.Affine2DBase

BboxTransformTo is a transformation that linearly transforms points from the unit bounding box to a given Bbox.

Create a new BboxTransformTo that linearly transforms points from the unit bounding box to boxout.

get_matrix()
Get the underlying transformation matrix as a numpy array.
class matplotlib.transforms.BboxTransformFrom(boxin)

Bases: matplotlib.transforms.Affine2DBase

BboxTransform linearly transforms points from a given Bbox to the unit bounding box.

get_matrix()
Get the underlying transformation matrix as a numpy array.
class matplotlib.transforms.ScaledTranslation(xt, yt, scale_trans)

Bases: matplotlib.transforms.Affine2DBase

A transformation that translates by xt and yt, after xt and yt have been transformaed by the given transform scale_trans.

get_matrix()
Get the underlying transformation matrix as a numpy array.
class matplotlib.transforms.TransformedPath(path, transform)

Bases: matplotlib.transforms.TransformNode

A TransformedPath caches a non-affine transformed copy of the path. This cached copy is automatically updated when the non-affine part of the transform changes.

Create a new TransformedPath from the given path and transform.

get_fully_transformed_path()
Return a fully-transformed copy of the child path.
get_transformed_path_and_affine()
Return a copy of the child path, with the non-affine part of the transform already applied, along with the affine part of the path necessary to complete the transformation.
get_transformed_points_and_affine()
Return a copy of the child path, with the non-affine part of the transform already applied, along with the affine part of the path necessary to complete the transformation. Unlike get_transformed_path_and_affine, no interpolation will be performed.
matplotlib.transforms.nonsingular(vmin, vmax, expander=0.001, tiny=1.0000000000000001e-15, increasing=True)

Ensure the endpoints of a range are not too close together.

“too close” means the interval is smaller than ‘tiny’ times the maximum absolute value.

If they are too close, each will be moved by the ‘expander’. If ‘increasing’ is True and vmin > vmax, they will be swapped, regardless of whether they are too close.

matplotlib.path

Contains a class for managing paths (polylines).

class matplotlib.path.Path(vertices, codes=None)

Bases: object

Path represents a series of possibly disconnected, possibly closed, line and curve segments.

The underlying storage is made up of two parallel numpy arrays:
  • vertices: an Nx2 float array of vertices
  • codes: an N-length uint8 array of vertex types

These two arrays always have the same length in the first dimension. For example, to represent a cubic curve, you must provide three vertices as well as three codes CURVE3.

The code types are:

  • STOP : 1 vertex (ignored)

    A marker for the end of the entire path (currently not required and ignored)

  • MOVETO : 1 vertex

    Pick up the pen and move to the given vertex.

  • LINETO : 1 vertex

    Draw a line from the current position to the given vertex.

  • CURVE3 : 1 control point, 1 endpoint

    Draw a quadratic Bezier curve from the current position, with the given control point, to the given end point.

  • CURVE4 : 2 control points, 1 endpoint

    Draw a cubic Bezier curve from the current position, with the given control points, to the given end point.

  • CLOSEPOLY : 1 vertex (ignored)

    Draw a line segment to the start point of the current polyline.

Users of Path objects should not access the vertices and codes arrays directly. Instead, they should use iter_segments() to get the vertex/code pairs. This is important, since many Path objects, as an optimization, do not store a codes at all, but have a default one provided for them by iter_segments().

Create a new path with the given vertices and codes.

vertices is an Nx2 numpy float array, masked array or Python sequence.

codes is an N-length numpy array or Python sequence of type matplotlib.path.Path.code_type.

These two arrays must have the same length in the first dimension.

If codes is None, vertices will be treated as a series of line segments. If vertices contains masked values, the resulting path will be compressed, with MOVETO codes inserted in the correct places to jump over the masked regions.

arc

(staticmethod) Returns an arc on the unit circle from angle theta1 to angle theta2 (in degrees).

If n is provided, it is the number of spline segments to make. If n is not provided, the number of spline segments is determined based on the delta between theta1 and theta2.

Masionobe, L. 2003. Drawing an elliptical arc using polylines, quadratic or cubic Bezier curves.
contains_path(path, transform=None)

Returns True if this path completely contains the given path.

If transform is not None, the path will be transformed before performing the test.

contains_point(point, transform=None)

Returns True if the path contains the given point.

If transform is not None, the path will be transformed before performing the test.

get_extents(transform=None)

Returns the extents (xmin, ymin, xmax, ymax) of the path.

Unlike computing the extents on the vertices alone, this algorithm will take into account the curves and deal with control points appropriately.

interpolated(steps)
Returns a new path resampled to length N x steps. Does not currently handle interpolating curves.
intersects_bbox(bbox)
Returns True if this path intersects a given Bbox.
intersects_path(other)
Returns True if this path intersects another given path.
iter_segments()
Iterates over all of the curve segments in the path. Each iteration returns a 2-tuple (vertices, code), where vertices is a sequence of 1 - 3 coordinate pairs, and code is one of the Path codes.
make_compound_path
(staticmethod) Make a compound path from a list of Path objects. Only polygons (not curves) are supported.
to_polygons(transform=None, width=0, height=0)

Convert this path to a list of polygons. Each polygon is an Nx2 array of vertices. In other words, each polygon has no MOVETO instructions or curves. This is useful for displaying in backends that do not support compound paths or Bezier curves, such as GDK.

If width and height are both non-zero then the lines will be simplified so that vertices outside of (0, 0), (width, height) will be clipped.

transformed(transform)

Return a transformed copy of the path.

See matplotlib.transforms.TransformedPath for a path that will cache the transformed result and automatically update when the transform changes.

unit_circle

(staticmethod) Returns a Path of the unit circle. The circle is approximated using cubic Bezier curves. This uses 8 splines around the circle using the approach presented here:

Lancaster, Don. Approximating a Circle or an Ellipse Using Four Bezier Cubic Splines.
unit_rectangle
(staticmethod) Returns a Path of the unit rectangle from (0, 0) to (1, 1).
unit_regular_asterisk
(staticmethod) Returns a Path for a unit regular asterisk with the given numVertices and radius of 1.0, centered at (0, 0).
unit_regular_polygon
(staticmethod) Returns a Path for a unit regular polygon with the given numVertices and radius of 1.0, centered at (0, 0).
unit_regular_star
(staticmethod) Returns a Path for a unit regular star with the given numVertices and radius of 1.0, centered at (0, 0).
wedge

(staticmethod) Returns a wedge of the unit circle from angle theta1 to angle theta2 (in degrees).

If n is provided, it is the number of spline segments to make. If n is not provided, the number of spline segments is determined based on the delta between theta1 and theta2.

matplotlib.path.get_path_collection_extents(*args)
Given a sequence of Path objects, returns the bounding box that encapsulates all of them.