@header@
 
 
matplotlib.transforms		index
/usr/local/lib/python2.3/site-packages/matplotlib/transforms.py

This module contains the newfangled transform class which allows the
placement of artists (lines, patches, text) in a variety of coordinate
systems (display, arbitrary data, relative axes, physical sizes)
 
The default Transform() is identity.
 
  t = Transform()
  x == Transform.positions(x)  True
  x == Transform.scale(x)      True
 
A linear Transformation is specified by giving a Bound1D (min, max)
instance for the domain and range.  The transform below maps the
interval [0,1] to [-10,10]
 
  t = Transform( Bound1D(0,1), Bound1D(-10,10) )
 
Since all Transforms know their inverse function, you can compute an
inverse transformation by calling inverse_positions or inverse_scale
 
  t = Transform( Bound1D(0,1), Bound1D(-10,10) )
  val = t.inverse_positions(5)  # maps [-10,10] to [0,1]
 
The difference between 'positions' and 'scale' is that the positions
func is appropriate for locations (eg, x,y) and the scale func is
appropriate for lengths (eg, width, height).
 
The Bound1D methods provide a number of utility functions: the
interval max-min, determining if a point is in the open or closed
interval, constraining the bound to be positive (useful for log
transforms), and so on.  These are useful for storing view, data and
display limits of a given axis.
 
The Bound2D is a straight-forward generalization of Bound1D, and
stores 2 Bound1D instances 'x' and 'y' to represent a 2D Bound (useful
for Axes bounding boxes, clipping etc).  All Artists are responsible
for returning their extent in display coords as a Bound2D instance,
which is useful for determining whether 2 Artists overlap.  Some
utility functions, eg, bound2d_all, return the Bound2D instance that
bounds all the Bound2D instances passed as args.  This helps in text
layout, eg, in positioning the axis labels to not overlap the tick
labels.
 
The Bound1D instances store their max and min values as RWVals
(read/write references).  These are mutable scalars that can be shared
among all the figure components.  When a figure clas resizes and thus
changes the display limits of an Axes, the Axes and all its components
know about the changes because they store a reference to the
displaylim, not the scalar value of the display lim.  Likewise for
DPI.
 
Also, it is possible to do simple arithmetic in RRefs via the derived
BinOp class, which stores both sides of a binary arithmetic operation,
as well as the binary function to return the result of the binop
applied to the dereferenced scalars.  This allows you to place artists
with locations like '3 centimenters below the x axis'
 
Here are some concepts and how to apply them via the transform
architecture
 
  * Map view limits to display limits via a linear tranformation
 
    # viewlim and displaylim are Bound1D instances
    tx = Transform( axes.xaxis.viewlim, axes.xaxis.displaylim )
    ty = Transform( axes.yaxis.viewlim, axes.yaxis.displaylim )
    l = Line2D(dpi, bbox, xdata, ydata, transx=tx, transy=ty)
 
  * Map relative axes coords ( 0,0 is lower left and 1,1 is upper
    right ) to display coords.  This example puts text in the middle
    of the axes (0.5, 0.5)
    
    tx = Transform( Bound1D(0,1), axes.xaxis.displaylim )
    ty = Transform( Bound1D(0,1), axes.yaxis.displaylim )
    text = AxisText(dpi, bbox, 0.5, 0.5, transx=tx, transy=ty)
    
 * Map x view limits to display limits via a log transformation and y
   view limits via linear transform.  The funcs pair is the
   transform/inverse pair
 
    funcs = logwarn, pow10
    tx = Transform( axes.xaxis.viewlim, axes.xaxis.displaylim, funcs )
    ty = Transform( axes.yaxis.viewlim, axes.yaxis.displaylim )
    l = Line2D(dpi, bbox, xdata, ydata, transx=tx, transy=ty)
 
 * You can also do transformation from one physical scale (inches, cm,
   points, ...) to another.  You need to specify an offset in output
   coords.
 
      offset = 100  # dots
      cm = Centimeter( self.dpi)
      dots =  Dots( self.dpi)
      t =  TransformSize(cm, dots, offset)
 
   If you don't know the offset in output coords, you can supply an
   optional transform to transform the offset to output coords.  Eg,
   if you want to offset by x in data coords, and the output is
   display coords, you can do
 
      offset = 0.2  # x data coords
      cm = Centimeter( self.dpi)
      dots =  Dots( self.dpi)
      t =  TransformSize(cm, dots, offset, axes.xaxis.transData)
   
 * Combining the above, we can specify that a text instance is at an x
   location in data coords and a y location in points relative to an
   axis.  Eg. the transformation below indicates that the x value of
   an xticklabel position is in data coordinates and the y value is 3
   points below the x axis, top justified
 
        # the top of the x ticklabel text is the bottom of the y axis
        # minus 3 points.  Note the code below uses the overloading of
        # __sub__ and __mul__ to return a BinOp.  Changes in the
        # position of bbox.y or dpi, eg, on a resize event, are
        # automagically reflected in the tick label position.
        # dpi*3/72 converts 3 points to dots.
        
        top = self.bbox.y.get_refmin() - self.dpi*RRef(3/72.0)
        text =  backends.AxisText(dpi, bbox, x=xdata, y=top,  
            verticalalignment='top',
            horizontalalignment='center',
            transx = self.axes.xaxis.transData,
            # transy is default, identity transform)
 
The unittest code for the transforms module is unit/transforms_unit.py

 
Modules
       
sys

 
Classes
       
Bound1D
Bound2D
RRef
BinOp
RWRef
Size
Centimeter
Dots
Inches
Millimeter
Points
Transform
TransformSize

 
class BinOp(RRef)
    A read only ref that handles binary ops of refs
 
  Methods defined here:
__init__(self, ref1, ref2, func=<function binadd>)
get(self)
Methods inherited from RRef:
__add__(self, other)
__mul__(self, other)
__rmul__(self, other)
__sub__(self, other)

 
class Bound1D
    Store and update information about a 1D bound
 
  Methods defined here:
__init__(self, minval=None, maxval=None, isPos=False)
__repr__(self)
bounds(self)
Return the min, max of the bounds
defined(self)
return true if both endpoints defined
get_refmax(self)
get_refmin(self)
in_interval(self, val)
Return true if val is in [min,max]
in_open_interval(self, val)
Return true if val is in (min,max)
interval(self)
return max - min if defined, else None
is_positive(self, b)
If true, bound will only return positive endpoints.
max(self)
return the max of the bounds
min(self)
return the min of the bounds
overlap(self, bound)
Return true if bound overlaps with self.
 
Return False if either bound undefined
scale(self, s)
scale the min and max by ratio s and return a reference to self
set_bounds(self, vmin, vmax)
set the min and max to vmin, vmax
set_max(self, vmax)
set the max to vmax
set_min(self, vmin)
shift(self, val)
Shift min and max by val and return a reference to self
update(self, x)
Update the min and max with values in x.  Eg, only update min
if min(x)<min().  Return a reference to self

 
class Bound2D
    Store and update 2D bounding box information
 
Publicly accessible attributes
 
 x the x Bound1D instance
 y the y Bound2D instance
 
  Methods defined here:
__init__(self, left, bottom, width, height)
__repr__(self)
copy(self)
Return a deep copy of self
defined(self)
get_bounds(self)
overlap(self, bound)
Return true if bound overlaps with self.
 
Return False if either bound undefined
set_bounds(self, left, bottom, width, height)
Reset the bounds

 
class Centimeter(Size)
     Methods defined here:
to_inches(self)
units(self)
Methods inherited from Size:
__init__(self, dpi, val=1)
__repr__(self)
get(self)
set_val(self, val)
to_dots(self)

 
class Dots(Size)
     Methods defined here:
to_dots(self)
to_inches(self)
units(self)
Methods inherited from Size:
__init__(self, dpi, val=1)
__repr__(self)
get(self)
set_val(self, val)

 
class Inches(Size)
     Methods defined here:
to_inches(self)
units(self)
Methods inherited from Size:
__init__(self, dpi, val=1)
__repr__(self)
get(self)
set_val(self, val)
to_dots(self)

 
class Millimeter(Size)
     Methods defined here:
to_inches(self)
units(self)
Methods inherited from Size:
__init__(self, dpi, val=1)
__repr__(self)
get(self)
set_val(self, val)
to_dots(self)

 
class Points(Size)
     Methods defined here:
to_inches(self)
units(self)
Methods inherited from Size:
__init__(self, dpi, val=1)
__repr__(self)
get(self)
set_val(self, val)
to_dots(self)

 
class RRef
    A read only ref
 
  Methods defined here:
__add__(self, other)
__init__(self, val)
__mul__(self, other)
__rmul__(self, other)
__sub__(self, other)
get(self)

 
class RWRef(RRef)
    A readable and writable ref
 
  Methods defined here:
set(self, val)
Methods inherited from RRef:
__add__(self, other)
__init__(self, val)
__mul__(self, other)
__rmul__(self, other)
__sub__(self, other)
get(self)

 
class Size
     Methods defined here:
__init__(self, dpi, val=1)
__repr__(self)
get(self)
set_val(self, val)
to_dots(self)
to_inches(self)
units(self)

 
class Transform
    Abstract base class for transforming data
 
Publicly accessible attributes are
  func            : the transform func
  ifunc           : the inverse tranform func
 
A tranform from in->out is defined by
 
scale = (maxout-maxin)/( func(maxin)-func(minin) )
out =  scale * ( func(in)-func(minin) ) + minout
 
funcs are paired with inverses, allowing Transforms to return
their inverse
 
  Methods defined here:
__init__(self, boundin=Bound1D: 0 1, boundout=Bound1D: 0 1, funcs=(<function identity>, <function identity>))
The default transform is identity.
 
To do a linear transform, replace the bounds with the
coodinate bounds of the input and output spaces
 
To do a log transform, use funcs=(log10, pow10)
__repr__(self)
inverse_positions(self, x)
Return the inverse transform of x
inverse_scale(self, x)
Return the inverse transform of scale x
position_scale(self, pos, scale, isScalarOrArray=False)
Transform scalar position and scale
 
Doing both together reduces duplication of function calls, eg,
for a x position and width if both use same transform
 
set isScalarOrArray to True if you know x is a scalar or array
for performace
positions(self, x, isScalarOrArray=False)
Transform the positions in x.
 
set isScalarOrArray to True if you know x is a scalar or array
for performace
scale(self, s, isScalarOrArray=False)
Transform the scale in s
 
set isScalarOrArray to True if you know x is a scalar or array
for performace
set_funcs(self, funcs)
Set the func, ifunc to funcs

 
class TransformSize
     Methods defined here:
__init__(self, sin, sout, offset, transOffset=Transform: Bound1D: 0 1 to Bound1D: 0 1)
transform size in Size instance sin to Size instance sout,
offsetting by Bound1D instance RRef instance offset.
transOffset is used to transform the offset if not None
inverse_positions(self, x)
inverse_scale(self, x)
positions(self, x)
scale(self, x)

 
Functions
       
binadd(x, y)
binsub(x, y)
bintimes(x, y)
bound1d_all(bounds)
Return a Bound1D instance that bounds all the Bound1D instances in
sequence bounds.
 
If the min or max val for any of the bounds is None, the
respective value for the returned bbox will also be None
bound2d_all(bounds)
Return a Bound2D instance that bounds all the Bound2D instances in
sequence bounds.
 
If the min or max val for any of the bounds is None, the
respective value for the returned bbox will also be None
identity(x)
The identity function
inverse_transform_bound1d(bound, trans)
Inverse transform a Bound1D instance using trans.inverse()
inverse_transform_bound2d(bbox, transx, transy)
Inverse transform a Bound2D instance using transforms transx, transy
iterable_to_array(x)
logwarn(x)
Return log10 for positive x
pow10(x)
the inverse of log10; 10**x
transform_bound1d(bound, trans)
Transform a Bound1D instance using transforms trans
transform_bound2d(bbox, transx, transy)
Transform a Bound2D instance using transforms transx, transy

 
Data
        division = _Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
log10 = <UFunc: 'log10'>
@footer@