manual/bitmap.rst

   1
   2 *******
   3 Bitmaps
   4 *******
   5
   6
   7 Introduction
   8 ============
   9
  10 PyX focuses on the creation of scaleable vector graphics. However, PyX also
  11 allows for the output of bitmap images. Still, the support for creation and
  12 handling of bitmap images is quite limited. On the other hand the interfaces are
  13 built that way, that its trivial to combine PyX with the "Python Image Library",
  14 also known as "PIL".
  15
  16 The creation of a bitmap can be performed out of some unpacked binary data by
  17 first creating image instances::
  18
  19    from pyx import *
  20    image_bw = bitmap.image(2, 2, "L", "\0\377\377\0")
  21    image_rgb = bitmap.image(3, 2, "RGB", "\77\77\77\177\177\177\277\277\277"
  22                                          "\377\0\0\0\377\0\0\0\377")
  23
  24 Now ``image_bw`` is a :math:`2\times2` grayscale image. The bitmap data is
  25 provided by a string, which contains two black (``"\0" == chr(0)``) and two
  26 white (``"\377" == chr(255)``) pixels. Currently the values per (colour) channel
  27 is fixed to 8 bits. The coloured image ``image_rgb`` has :math:`3\times2` pixels
  28 containing a row of 3 different gray values and a row of the three colours red,
  29 green, and blue.
  30
  31 The images can then be wrapped into ``bitmap`` instances by::
  32
  33    bitmap_bw = bitmap.bitmap(0, 1, image_bw, height=0.8)
  34    bitmap_rgb = bitmap.bitmap(0, 0, image_rgb, height=0.8)
  35
  36 When constructing a ``bitmap`` instance you have to specify a certain position
  37 by the first two arguments fixing the bitmaps lower left corner. Some optional
  38 arguments control further properties. Since in this example there is no
  39 information about the dpi-value of the images, we have to specify at least a
  40 ``width`` or a ``height`` of the bitmap.
  41
  42 The bitmaps are now to be inserted into a canvas::
  43
  44    c = canvas.canvas()
  45    c.insert(bitmap_bw)
  46    c.insert(bitmap_rgb)
  47    c.writeEPSfile("bitmap")
  48
  49 Figure :ref:`fig_bitmap` shows the resulting output.
  50
  51 .. _fig_bitmap:
  52 .. figure:: bitmap.*
  53    :align:  center
  54
  55    An introductory bitmap example.
  56
  57
  58 .. module:: bitmap
  59
  60 Bitmap :mod:`module`: Bitmap support
  61 ====================================
  62
  63
  64 .. class:: image(width, height, mode, data, compressed=None)
  65
  66    This class is a container for image data. *width* and *height* are the size of
  67    the image in pixel. *mode* is one of ``"L"``, ``" RGB"`` or ``"CMYK"`` for
  68    grayscale, rgb, or cmyk colours, respectively. *data* is the bitmap data as a
  69    string, where each single character represents a colour value with ordinal range
  70    ``0`` to ``255``. Each pixel is described by the appropriate number of colour
  71    components according to *mode*. The pixels are listed row by row one after the
  72    other starting at the upper left corner of the image.
  73
  74    *compressed* might be set to ``" Flate"`` or ``"DCT"`` to provide already
  75    compressed data. Note that those data will be passed to PostScript without
  76    further checks, *i.e.* this option is for experts only.
  77
  78
  79 .. class:: jpegimage(file)
  80
  81    This class is specialized to read data from a JPEG/JFIF-file. *file* is either
  82    an open file handle (it only has to provide a :meth:`read` method; the file
  83    should be opened in binary mode) or a string. In the latter case
  84    :class:`jpegimage` will try to open a file named like *file* for reading.
  85
  86    The contents of the file is checked for some JPEG/JFIF format markers in order
  87    to identify the size and dpi resolution of the image for further usage. These
  88    checks will typically fail for invalid data. The data are not uncompressed, but
  89    directly inserted into the output stream (for invalid data the result will be
  90    invalid PostScript). Thus there is no quality loss by recompressing the data as
  91    it would occur when recompressing the uncompressed stream with the lossy jpeg
  92    compression method.
  93
  94
  95 .. class:: bitmap(xpos, ypos, image, width=None, height=None, ratio=None, storedata=0, maxstrlen=4093, compressmode="Flate", flatecompresslevel=6, dctquality=75, dctoptimize=1, dctprogression=0)
  96
  97    *xpos* and *ypos* are the position of the lower left corner of the image. This
  98    position might be modified by some additional transformations when inserting the
  99    bitmap into a canvas. *image* is an instance of :class:`image` or
 100    :class:`jpegimage` but it can also be an image instance from the "Python Image
 101    Library".
 102
 103    *width*, *height*, and *ratio* adjust the size of the image. At least *width* or
 104    *height* needs to be given, when no dpi information is available from *image*.
 105
 106    *storedata* is a flag indicating, that the (still compressed) image data should
 107    be put into the printers memory instead of writing it as a stream into the
 108    PostScript file. While this feature consumes memory of the PostScript
 109    interpreter, it allows for multiple usage of the image without including the
 110    image data several times in the PostScript file.
 111
 112    *maxstrlen* defines a maximal string length when *storedata* is enabled. Since
 113    the data must be kept in the PostScript interpreters memory, it is stored in
 114    strings. While most interpreters do not allow for an arbitrary string length (a
 115    common limit is 65535 characters), a limit for the string length is set. When
 116    more data need to be stored, a list of strings will be used. Note that lists are
 117    also subject to some implementation limits. Since a typical value is 65535
 118    entries, in combination a huge amount of memory can be used.
 119
 120    Valid values for *compressmode* currently are ``"Flate"`` (zlib compression),
 121    ``"DCT"`` (jpeg compression), or ``None`` (disabling the compression). The zlib
 122    compression makes use of the zlib module as it is part of the standard Python
 123    distribution. The jpeg compression is available for those *image* instances
 124    only, which support the creation of a jpeg-compressed stream, *e.g.* images from
 125    the "Python Image Library" with jpeg support installed. The compression must be
 126    disabled when the image data is already compressed.
 127
 128    *flatecompresslevel* is a parameter of the zlib compression. *dctquality*,
 129    *dctoptimize*, and *dctprogression* are parameters of the jpeg compression.
 130    Note, that the progression feature of the jpeg compression should be turned off
 131    in order to produce valid PostScript. Also the optimization feature is known to
 132    produce errors on certain printers.
 133