pyx/canvas.py

   1 #!/usr/bin/env python
   2 # -*- coding: ISO-8859-1 -*-
   3 #
   4 #
   5 # Copyright (C) 2002-2006 Jörg Lehmann <joergl@users.sourceforge.net>
   6 # Copyright (C) 2002-2006 André Wobst <wobsta@users.sourceforge.net>
   7 #
   8 # This file is part of PyX (http://pyx.sourceforge.net/).
   9 #
  10 # PyX is free software; you can redistribute it and/or modify
  11 # it under the terms of the GNU General Public License as published by
  12 # the Free Software Foundation; either version 2 of the License, or
  13 # (at your option) any later version.
  14 #
  15 # PyX is distributed in the hope that it will be useful,
  16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 # GNU General Public License for more details.
  19 #
  20 # You should have received a copy of the GNU General Public License
  21 # along with PyX; if not, write to the Free Software
  22 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
  23
  24 """The canvas module provides a PostScript canvas class and related classes
  25
  26 A canvas holds a collection of all elements and corresponding attributes to be
  27 displayed. """
  28
  29 #
  30 # canvas item
  31 #
  32
  33 class canvasitem:
  34
  35     """Base class for everything which can be inserted into a canvas"""
  36
  37     def bbox(self):
  38         """return bounding box of canvasitem"""
  39         pass
  40
  41     def processPS(self, file, writer, context, registry, bbox):
  42         """process canvasitem by writing the corresponding PS code to file and
  43         by updating context, registry as well as bbox
  44
  45         - the PS code corresponding to the canvasitem has to be written in the
  46           stream file, which provides a write(string) method
  47         - writer is the PSwriter used for the output
  48         - context is an instance of pswriter.context which is used for keeping
  49           track of the graphics state (current linewidth, colorspace and font))
  50         - registry is used for tracking resources needed by the canvasitem
  51         - bbox has to be updated to include the bounding box of the canvasitem
  52         """
  53         raise NotImplementedError()
  54
  55     def processPDF(self, file, writer, context, registry, bbox):
  56         """process canvasitem by writing the corresponding PDF code to file and
  57         by updating context, registry as well as bbox
  58
  59         - the PDF code corresponding to the canvasitem has to be written in the
  60           stream file, which provides a write(string) method
  61         - writer is the PDFwriter used for the output, which contains properties
  62           like whether streamcompression is used
  63         - context is an instance of pdfwriter.context which is used for keeping
  64           track of the graphics state, in particular for the emulation of PS
  65           behaviour regarding fill and stroke styles, for keeping track of the
  66           currently selected font as well as of text regions.
  67         - registry is used for tracking resources needed by the canvasitem
  68         - bbox has to be updated to include the bounding box of the canvasitem
  69         """
  70         raise NotImplementedError()
  71
  72
  73 import attr, deco, deformer, document, style, trafo, type1font
  74 import bbox as bboxmodule
  75
  76
  77 #
  78 # clipping class
  79 #
  80
  81 class clip(canvasitem):
  82
  83     """class for use in canvas constructor which clips to a path"""
  84
  85     def __init__(self, path):
  86         """construct a clip instance for a given path"""
  87         self.path = path
  88
  89     def bbox(self):
  90         # as a canvasitem a clipping path has NO influence on the bbox...
  91         return bboxmodule.empty()
  92
  93     def clipbbox(self):
  94         # ... but for clipping, we nevertheless need the bbox
  95         return self.path.bbox()
  96
  97     def processPS(self, file, writer, context, registry, bbox):
  98         file.write("newpath\n")
  99         self.path.outputPS(file, writer)
 100         file.write("clip\n")
 101
 102     def processPDF(self, file, writer, context, registry, bbox):
 103         self.path.outputPDF(file, writer)
 104         file.write("W n\n")
 105
 106
 107 #
 108 # general canvas class
 109 #
 110
 111 class _canvas(canvasitem):
 112
 113     """a canvas holds a collection of canvasitems"""
 114
 115     def __init__(self, attrs=[], texrunner=None):
 116
 117         """construct a canvas
 118
 119         The canvas can be modfied by supplying args, which have
 120         to be instances of one of the following classes:
 121          - trafo.trafo (leading to a global transformation of the canvas)
 122          - canvas.clip (clips the canvas)
 123          - style.strokestyle, style.fillstyle (sets some global attributes of the canvas)
 124
 125         Note that, while the first two properties are fixed for the
 126         whole canvas, the last one can be changed via canvas.set().
 127
 128         The texrunner instance used for the text method can be specified
 129         using the texrunner argument. It defaults to text.defaulttexrunner
 130
 131         """
 132
 133         self.items     = []
 134         self.trafo     = trafo.trafo()
 135         self.clipbbox  = None
 136         if texrunner is not None:
 137             self.texrunner = texrunner
 138         else:
 139             # prevent cyclic imports
 140             import text
 141             self.texrunner = text.defaulttexrunner
 142
 143         attr.checkattrs(attrs, [trafo.trafo_pt, clip, style.strokestyle, style.fillstyle])
 144         # We have to reverse the trafos such that the PostScript concat operators
 145         # are in the right order. Correspondingly, we below multiply the current self.trafo
 146         # from the right.
 147         # Note that while for the stroke and fill styles the order doesn't matter at all,
 148         # this is not true for the clip operation.
 149         attrs.reverse()
 150         for aattr in attrs:
 151             if isinstance(aattr, trafo.trafo_pt):
 152                 self.trafo = self.trafo * aattr
 153             elif isinstance(aattr, clip):
 154                 if self.clipbbox is None:
 155                     self.clipbbox = aattr.clipbbox().transformed(self.trafo)
 156                 else:
 157                     self.clippbox *= aattr.clipbbox().transformed(self.trafo)
 158             self.items.append(aattr)
 159
 160     def __len__(self):
 161         return len(self.items)
 162
 163     def __getitem__(self, i):
 164         return self.items[i]
 165
 166     def bbox(self):
 167         """returns bounding box of canvas
 168
 169         Note that this bounding box doesn't take into account the linewidths, so
 170         is less accurate than the one used when writing the output to a file.
 171         """
 172         obbox = bboxmodule.empty()
 173         for cmd in self.items:
 174             obbox += cmd.bbox()
 175
 176         # transform according to our global transformation and
 177         # intersect with clipping bounding box (which has already been
 178         # transformed in canvas.__init__())
 179         obbox.transform(self.trafo)
 180         if self.clipbbox is not None:
 181             obbox *= self.clipbbox
 182         return obbox
 183
 184     def processPS(self, file, writer, context, registry, bbox):
 185         context = context()
 186         if self.items:
 187             file.write("gsave\n")
 188             nbbox = bboxmodule.empty()
 189             for item in self.items:
 190                 item.processPS(file, writer, context, registry, nbbox)
 191             # update bounding bbox
 192             nbbox.transform(self.trafo)
 193             if self.clipbbox is not None:
 194                 nbbox *= self.clipbbox
 195             bbox += nbbox
 196             file.write("grestore\n")
 197
 198     def processPDF(self, file, writer, context, registry, bbox):
 199         context = context()
 200         if self.items:
 201             file.write("q\n") # gsave
 202             nbbox = bboxmodule.empty()
 203             for item in self.items:
 204                 if isinstance(item, type1font.text_pt):
 205                     if not context.textregion:
 206                         file.write("BT\n")
 207                         context.textregion = 1
 208                 else:
 209                     if context.textregion:
 210                         file.write("ET\n")
 211                         context.textregion = 0
 212                         context.font = None
 213                 item.processPDF(file, writer, context, registry, nbbox)
 214             if context.textregion:
 215                 file.write("ET\n")
 216                 context.textregion = 0
 217                 context.font = None
 218             # update bounding bbox
 219             nbbox.transform(self.trafo)
 220             if self.clipbbox is not None:
 221                 nbbox *= self.clipbbox
 222             bbox += nbbox
 223             file.write("Q\n") # grestore
 224
 225     def insert(self, item, attrs=None):
 226         """insert item in the canvas.
 227
 228         If attrs are passed, a canvas containing the item is inserted applying attrs.
 229
 230         returns the item
 231
 232         """
 233
 234         if not isinstance(item, canvasitem):
 235             raise RuntimeError("only instances of base.canvasitem can be inserted into a canvas")
 236
 237         if attrs:
 238             sc = _canvas(attrs)
 239             sc.insert(item)
 240             self.items.append(sc)
 241         else:
 242             self.items.append(item)
 243         return item
 244
 245     def draw(self, path, attrs):
 246         """draw path on canvas using the style given by args
 247
 248         The argument attrs consists of PathStyles, which modify
 249         the appearance of the path, PathDecos, which add some new
 250         visual elements to the path, or trafos, which are applied
 251         before drawing the path.
 252
 253         """
 254
 255         attrs = attr.mergeattrs(attrs)
 256         attr.checkattrs(attrs, [deco.deco, deformer.deformer, style.fillstyle, style.strokestyle])
 257
 258         for adeformer in attr.getattrs(attrs, [deformer.deformer]):
 259             path = adeformer.deform(path)
 260
 261         styles = attr.getattrs(attrs, [style.fillstyle, style.strokestyle])
 262         dp = deco.decoratedpath(path, styles=styles)
 263
 264         # add path decorations and modify path accordingly
 265         for adeco in attr.getattrs(attrs, [deco.deco]):
 266             adeco.decorate(dp, self.texrunner)
 267
 268         self.insert(dp)
 269
 270     def stroke(self, path, attrs=[]):
 271         """stroke path on canvas using the style given by args
 272
 273         The argument attrs consists of PathStyles, which modify
 274         the appearance of the path, PathDecos, which add some new
 275         visual elements to the path, or trafos, which are applied
 276         before drawing the path.
 277
 278         """
 279
 280         self.draw(path, [deco.stroked]+list(attrs))
 281
 282     def fill(self, path, attrs=[]):
 283         """fill path on canvas using the style given by args
 284
 285         The argument attrs consists of PathStyles, which modify
 286         the appearance of the path, PathDecos, which add some new
 287         visual elements to the path, or trafos, which are applied
 288         before drawing the path.
 289
 290         """
 291
 292         self.draw(path, [deco.filled]+list(attrs))
 293
 294     def settexrunner(self, texrunner):
 295         """sets the texrunner to be used to within the text and text_pt methods"""
 296
 297         self.texrunner = texrunner
 298
 299     def text(self, x, y, atext, *args, **kwargs):
 300         """insert a text into the canvas
 301
 302         inserts a textbox created by self.texrunner.text into the canvas
 303
 304         returns the inserted textbox"""
 305
 306         return self.insert(self.texrunner.text(x, y, atext, *args, **kwargs))
 307
 308
 309     def text_pt(self, x, y, atext, *args):
 310         """insert a text into the canvas
 311
 312         inserts a textbox created by self.texrunner.text_pt into the canvas
 313
 314         returns the inserted textbox"""
 315
 316         return self.insert(self.texrunner.text_pt(x, y, atext, *args))
 317
 318 #
 319 # user canvas class which adds a few convenience methods for single page output
 320 #
 321
 322 def _wrappedindocument(method):
 323     def wrappedindocument(self, filename, *args, **kwargs):
 324         d = document.document([document.page(self, *args, **kwargs)])
 325         self.__name__ = method.__name__
 326         self.__doc__ = method.__doc__
 327         return method(d, filename)
 328     return wrappedindocument
 329
 330 class canvas(_canvas):
 331
 332     """a canvas holds a collection of canvasitems"""
 333
 334     writeEPSfile = _wrappedindocument(document.document.writeEPSfile)
 335     writePSfile = _wrappedindocument(document.document.writePSfile)
 336     writePDFfile = _wrappedindocument(document.document.writePDFfile)
 337     writetofile = _wrappedindocument(document.document.writetofile)