| matplotlib.transforms | index /usr/local/lib/python2.3/site-packages/matplotlib/transforms.py |
The transforms module is broken into two parts, a collection of
classes written in the extension module _transforms to handle
efficient transformation of data, and some helper functions in
transforms to make it easy to instantiate and use those objects.
Hence the core of this module lives in _transforms.
The transforms class is built around the idea of a LazyValue. A
LazyValue is a base class that defines a method get that returns the
value. The concrete derived class Value wraps a float, and simply
returns the value of that float. The concrete derived class BinOp
allows binary operations on LazyValues, so you can add them, multiply
them, etc. When you do something like
inches = Value(8)
dpi = Value(72)
width = inches * dpi
width is a BinOp instance (that tells you the width of the figure in
pixels. Later, if the figure size in changed, ie we call
inches.set(10)
The width variable is automatically updated because it stores a
pointer to the inches variable, not the value. Since a BinOp is also
a lazy value, you can define binary operations on BinOps as well, such
as
middle = Value(0.5) * width
The bounding box class Bbox is also heavily used, and is defined by a
lower left point ll and an upper right point ur. The points ll and ur
are given by Point(x, y) instances, where x and y are LazyValues. So
you can represent a point such as
ll = Point( Value(0), Value(0) ) # the origin
ur = Point( width, height ) # the upper right of the figure
where width and height are defined as above, using the product of the
figure width in inches and the dpi. This is, in face, how the Figure
bbox is defined
bbox = Bbox(ll, ur)
A bbox basically defines an x,y coordinate system, with ll giving the
lower left of the coordinate system and ur giving the upper right.
The bbox methods are
ll() - return the lower left Point
ur() - return the upper right Point
overlaps(bbox) - return True if self overlaps bbox
overlapsx(bbox) - return True if self overlaps bbox in the x interval
overlapsy(bbox) - return True if self overlaps bbox in the y interval
intervalx() - return the x Interval instance
intervaly() - return the y interval instance
get_bounds() - get the left, bottom, width, height bounding tuple
update(xys, ignore) - update the boox to bound all the xy tuples in
xys; if ignore is true ignore the current contents of bbox and
just bound the tuples. If ignore is false, bound self + tuples
width() - return the width of the bbox
height() - return the height of the bbox
xmax() - return the x coord of upper right
ymax() - return the y coord of upper right
xmin() - return the x coord of lower left
ymin() - return the y coord of lower left
scale(sx,sy) - scale the bbox by sx, sy
deepcopy() - return a deep copy of self (pointers are lost)
The basic transformation maps one bbox to another, with an optional
nonlinear transformation of one of coordinates (eg log scaling).
The base class for transformations is Transformation, and the concrete
derived classes are SeparableTransformation and Affine. Earlier
versions of matplotlib handled transformation of x and y separately
(ie we assumed all transformations were separable) but this makes it
difficult to do rotations or polar transformations, for example. All
artists contain their own transformation, defaulting to the identity
transform.
The signature of a separable transformation instance is
trans = SeparableTransformation(bbox1, bbox2, funcx, funcy)
where funcx and funcy operatate on x and y. The typical linear
coordinate transformation maps one bounding box to another, with funcx
and funcy both identity. Eg,
transData = Transformation(viewLim, displayLim, Func(IDENTITY), Func(IDENTITY))
maps the axes view limits to display limits. If the xaxis scaling is
changed to log, one simply calls
transData.get_funcx.set_type(LOG10)
For more general transformations including rotation, the Affine class
is provided, which is constructed with 6 LazyValue instances:
a, b, c, d, tx, ty. These give the values of the matrix transformation
[xo = |a c| [xi + [tx
yo] |b d| yi] ty]
From a user persepective, the most important Tranformation methods are
All transformations
-------------------
freeze() - eval and freeze the lazy objects
thaw() - release the laszy objects
xy_tup(xy) - transform the tuple (x,y)
seq_x_y(x, y) - transform the python sequences x and y
numerix_x_y(x, y) - x and y are numerix 1D arrays
seq_xy_tups(seq) - seq is a sequence of xy tuples
inverse_xy_tup(xy) - apply the incerse transformation to tuple xy
set_offset(xy, trans) - xy is an x,y tuple and trans is a
Transformation instance. This will apply a post transformational
offset of all future transformations by xt,yt = trans.xy_tup(xy[0], xy[1])
Separable transformations
-------------------------
get_bbox1() - return the input bbox
get_bbox2() - return the output bbox
set_bbox1() - set the input bbox
set_bbox2() - set the output bbox
get_funcx() - return the Func instance on x
get_funcy() - return the Func instance on y
set_funcx() - set the Func instance on x
set_funcy() - set the Func instance on y
Affine transformations
----------------------
as_vec6() - return the affine as length 6 list of Values
In general, you shouldn't need to construct your own transformations,
but should use the helper functions defined in this module.
zero - return Value(0)
one - return Value(1)
origin - return Point(zero(), zero())
unit_bbox - return the 0,0 to 1,1 bounding box
identity_affine - An affine idenitity transformation
identity_transform - An indentity separable transformation
translation_transform - a pure translational affine
scale_transform - a pure scale affine
scale_sep_transform - a pure scale separable transformation
scale_translation_transform - a scale and translate affine
bound_vertices - return the bbox that bounds all the xy tuples
bbox_all - return the bbox that bounds all the bboxes
lbwh_to_bbox - build a bbox from tuple
left, bottom, width, height tuple
multiply_affines - return the affine that is the matrix product of
the two affines
get_bbox_transform - return a SeparableTransformation instance that
transforms one bbox to another
blend_xy_sep_transform - mix the x and y components of two separable
transformations into a new transformation. This allows you to
specify x and y in different coordinate systems
transform_bbox - apply a transformation to a bbox and return the
transformed bbox
inverse_transform_bbox - apply the inverse transformation of a bbox
and return the inverse transformed bbox
The units/transform_unit.py code has many examples.
| Functions | ||
| ||
| Data | ||
| IDENTITY = 0 LOG10 = 1 | ||