Make it easier to plot text etc. with an offset: transforms.offset_copy().

efiring · efiring · commit 6858631507b4 · 2006-07-31T07:51:33.000Z
svn path=/trunk/matplotlib/; revision=2638
diff --git a/examples/transoffset.py b/examples/transoffset.py
@@ -0,0 +1,61 @@
+#!/usr/bin/env python
+
+'''
+This illustrates the use of transforms.offset_copy to
+make a transform that positions a drawing element such as
+a text string at a specified offset in screen coordinates
+(dots or inches) relative to a location given in any
+coordinates.
+
+Every Artist--the mpl class from which classes such as
+Text and Line are derived--has a transform that can be
+set when the Artist is created, such as by the corresponding
+pylab command.  By default this is usually the Axes.transData
+transform, going from data units to screen dots.  We can
+use the offset_copy function to make a modified copy of
+this transform, where the modification consists of an
+offset.
+'''
+
+import pylab as P
+from matplotlib.transforms import offset_copy
+
+X = P.arange(7)
+Y = P.rand(7)
+
+ax = P.subplot(1,1,1)
+
+# If we want the same offset for each text instance,
+# we only need to make one transform.  To get the
+# transform argument to offset_copy, we need to make the axes
+# first; the subplot command above is one way to do this.
+transOffset = offset_copy(ax.transData, fig=P.gcf(),
+                            x = 0.05, y=0.10, units='inches')
+
+for x, y in zip(X, Y):
+    P.plot((x,),(y,), 'ro')
+    P.text(x, y, '%0.2f, %0.2f' % (x,y), transform=transOffset)
+
+P.figure()
+
+
+# offset_copy works for polar plots also, but one can't simply
+# make an axes with subplot and then use the polar command to plot
+# in it.  (This is a bug.)  One way to get around this while
+# sticking with the pylab interface is to grab the transform
+# after the first polar() command.
+first = True
+for x, y in zip(X, Y):
+    L = P.polar((x,),(y,), 'ro')
+    if first:
+        transOffset = offset_copy(P.gca().transData, fig=P.gcf(),
+                                y = 6, units='dots')
+        first = False
+    P.text(x, y, '%0.2f, %0.2f' % (x,y),
+                transform=transOffset,
+                horizontalalignment='center',
+                verticalalignment='bottom')
+
+
+P.show()
+
diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py
@@ -121,7 +121,9 @@
   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
+  numerix_xy(xy)        - xy is a numerix array of shape (N,2)
+  inverse_numerix_xy(xy)- inverse of the above
+  seq_xy_tups(seq)      - seq is a sequence of xy tuples or a (N,2) array
   inverse_xy_tup(xy)    - apply the inverse transformation to tuple xy
 
   set_offset(xy, trans) - xy is an x,y tuple and trans is a
@@ -141,6 +143,7 @@
   set_funcx() - set the Func instance on x
   set_funcy() - set the Func instance on y
 
+
 Affine transformations
 ----------------------
 
@@ -423,9 +426,11 @@ def inverse_transform_bbox(trans, bbox):
     return Bbox(Point(Value(xmin), Value(ymin)),
                 Point(Value(xmax), Value(ymax)))
 
+## begin possibly deleted block; all transforms have deepcopy
+## and shallowcopy methods, we may not need any of the following
 
-def copy_bbox_transform(trans):
-    'return a deep copy of the bbox transform'
+def copy_separable_transform(trans):
+    'return a deep copy of the separable transform'
 
     inbox = trans.get_bbox1()
     xmin, xmax  =  inbox.intervalx().get_bounds()
@@ -436,7 +441,7 @@ def copy_bbox_transform(trans):
     outbox = trans.get_bbox2()
     xmin, xmax  =  outbox.intervalx().get_bounds()
     ymin, ymax  =  outbox.intervaly().get_bounds()
-    
+
     newOutbox  = Bbox( Point(Value(xmin),  Value(ymin)),
                        Point(Value(xmax),  Value(ymax))  )
 
@@ -449,10 +454,12 @@ def copy_bbox_transform(trans):
     newtrans.get_funcy().set_type(typey)
     return newtrans
 
+copy_bbox_transform = copy_separable_transform
+
 
-def copy_bbox_transform_shallow(trans):
+def copy_separable_transform_shallow(trans):
     """
-    return a shallow copy of the bbox transform -- the Values are
+    return a shallow copy of the separable transform -- the Values are
     retained by reference but the transform is copied.  This allows
     you to copy a transform, set a new offset to it, but not lose the
     value reference semantics
@@ -470,6 +477,37 @@ def copy_bbox_transform_shallow(trans):
     newtrans.get_funcy().set_type(typey)
     return newtrans
 
+copy_bbox_transform_shallow = copy_separable_transform_shallow
+
+def copy_transform_shallow(trans):
+    return trans.shallowcopy()
+
+## end possibly deleted block
+
+def offset_copy(trans, fig=None, x=0, y=0, units='inches'):
+    '''
+    Return a shallow copy of a transform with an added offset.
+      args:
+        trans is any transform
+      kwargs:
+        fig is the current figure; it can be None if units are 'dots'
+        x, y give the offset in units of 'inches' or 'dots'
+        units is 'inches' or 'dots'
+    '''
+    newtrans = trans.shallowcopy()
+    if units == 'dots':
+        newtrans.set_offset((x,y), identity_transform())
+        return newtrans
+    if not units == 'inches':
+        raise ValueError('units must be dots or inches')
+    if fig is None:
+        raise ValueError('For units of inches a fig kwarg is needed')
+    tx = Value(x) * fig.dpi
+    ty = Value(y) * fig.dpi
+    newtrans.set_offset((0,0), translation_transform(tx, ty))
+    return newtrans
+
+
 def get_vec6_scales(v):
     'v is an affine vec6 a,b,c,d,tx,ty; return sx, sy'
     a,b,c,d = v[:4]
diff --git a/src/_transforms.cpp b/src/_transforms.cpp
@@ -1615,7 +1615,16 @@ Py::Object
 SeparableTransformation::deepcopy(const Py::Tuple &args) {
   _VERBOSE("SeparableTransformation::deepcopy");
   args.verify_length(0);
-  return Py::asObject( new SeparableTransformation( static_cast<Bbox*>((_b1->_deepcopy()).ptr()),static_cast<Bbox*>((_b2->_deepcopy()).ptr()), _funcx,_funcy ));
+  return Py::asObject( new SeparableTransformation(
+        static_cast<Bbox*>((_b1->_deepcopy()).ptr()),
+        static_cast<Bbox*>((_b2->_deepcopy()).ptr()), _funcx,_funcy ));
+}
+
+Py::Object
+SeparableTransformation::shallowcopy(const Py::Tuple &args) {
+  _VERBOSE("SeparableTransformation::shallowcopy");
+  args.verify_length(0);
+  return Py::asObject( new SeparableTransformation(_b1, _b2, _funcx,_funcy ));
 }
 
 NonseparableTransformation::NonseparableTransformation(Bbox *b1, Bbox *b2, FuncXY *funcxy) :
@@ -1799,6 +1808,14 @@ NonseparableTransformation::deepcopy(const Py::Tuple &args) {
   return Py::asObject( new NonseparableTransformation( static_cast<Bbox*>((_b1->_deepcopy()).ptr()),static_cast<Bbox*>((_b2->_deepcopy()).ptr()), _funcxy ));
 }
 
+Py::Object
+NonseparableTransformation::shallowcopy(const Py::Tuple &args) {
+  _VERBOSE("NonseparableTransformation::shallowcopy");
+  args.verify_length(0);
+  return Py::asObject( new NonseparableTransformation(_b1,_b2, _funcxy ));
+}
+
+
 Affine::Affine(LazyValue *a, LazyValue *b,  LazyValue *c,
 	       LazyValue *d, LazyValue *tx, LazyValue *ty) :
   _a(a), _b(b), _c(c), _d(d), _tx(tx), _ty(ty) {
@@ -1939,6 +1956,14 @@ Affine::deepcopy(const Py::Tuple &args) {
                                    new Value(_dval),new Value(_txval),new Value(_tyval) ));
 }
 
+Py::Object
+Affine::shallowcopy(const Py::Tuple &args) {
+  _VERBOSE("Affine::shallowcopy");
+  args.verify_length(0);
+
+  return Py::asObject( new Affine( _a, _b, _c, _d, _tx, _ty ));
+}
+
 
 
 /* ------------ module methods ------------- */
@@ -2270,6 +2295,7 @@ Transformation::init_type()
   add_varargs_method("as_vec6", &Transformation::as_vec6, "as_vec6(): return the affine as length 6 list of Values\n");
   add_varargs_method("as_vec6_val", &Transformation::as_vec6_val, "as_vec6_val(): return the affine as length 6 list of float\n");
   add_varargs_method("deepcopy", &Transformation::deepcopy, "deepcopy()\n");
+  add_varargs_method("shallowcopy", &Transformation::shallowcopy, "shallowcopy()\n");
 
 }
 
diff --git a/src/_transforms.h b/src/_transforms.h
@@ -609,6 +609,7 @@ class Transformation: public Py::PythonExtension<Transformation> {
   Py::Object nonlinear_only_numerix(const Py::Tuple &args, const Py::Dict &kwargs);
   Py::Object inverse_xy_tup(const Py::Tuple &args);
   virtual Py::Object deepcopy(const Py::Tuple &args) =0;
+  virtual Py::Object shallowcopy(const Py::Tuple &args) =0;
 
   //freeze the lazy values and don't relax until thawed
   Py::Object freeze(const Py::Tuple &args) {
@@ -712,6 +713,7 @@ class SeparableTransformation: public BBoxTransformation {
   void arrayOperator(const int length, const double x[], const double y[], double newx[], double newy[]);
 
   Py::Object deepcopy(const Py::Tuple &args) ;
+  Py::Object shallowcopy(const Py::Tuple &args) ;
 
 protected:
   Func *_funcx, *_funcy;
@@ -732,6 +734,7 @@ class NonseparableTransformation: public BBoxTransformation {
   std::pair<double, double> & inverse_api(const double &x, const double &y);
   void arrayOperator(const int length, const double x[], const double y[], double newx[], double newy[]);
   Py::Object deepcopy(const Py::Tuple &args) ;
+  Py::Object shallowcopy(const Py::Tuple &args) ;
 
   void nonlinear_only_api(double *x, double *y);
 
@@ -760,6 +763,7 @@ class Affine: public Transformation {
   std::pair<double, double> & inverse_api(const double &x, const double &y);
   void eval_scalars(void);
   Py::Object deepcopy(const Py::Tuple &args);
+  Py::Object shallowcopy(const Py::Tuple &args);
 
   void affine_params_api(double* a, double* b, double* c, double*d, double* tx, double* ty);
 private:
