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 .. % DUMMY
  52 .. _fig_label:
  53 .. figure:: bitmap.*
  54    :align:  center
  55
  56
  57 .. centered:: An introductory bitmap example.
  58
  59
  60 Bitmap module
  61 =============
  62
  63 .. module:: bitmap
  64    :synopsis: Bitmap support
  65
  66
  67
  68 .. class:: image(width, height, mode, data, compressed=None)
  69
  70    This class is a container for image data. *width* and *height* are the size of
  71    the image in pixel. *mode* is one of ``"L"``, ``" RGB"`` or ``"CMYK"`` for
  72    grayscale, rgb, or cmyk colours, respectively. *data* is the bitmap data as a
  73    string, where each single character represents a colour value with ordinal range
  74    ``0`` to ``255``. Each pixel is described by the appropriate number of colour
  75    components according to *mode*. The pixels are listed row by row one after the
  76    other starting at the upper left corner of the image.
  77
  78    *compressed* might be set to ``" Flate"`` or ``"DCT"`` to provide already
  79    compressed data. Note that those data will be passed to PostScript without
  80    further checks, *i.e.* this option is for experts only.
  81
  82
  83 .. class:: jpegimage(file)
  84
  85    This class is specialized to read data from a JPEG/JFIF-file. *file* is either
  86    an open file handle (it only has to provide a :meth:`read` method; the file
  87    should be opened in binary mode) or a string. In the latter case
  88    :class:`jpegimage` will try to open a file named like *file* for reading.
  89
  90    The contents of the file is checked for some JPEG/JFIF format markers in order
  91    to identify the size and dpi resolution of the image for further usage. These
  92    checks will typically fail for invalid data. The data are not uncompressed, but
  93    directly inserted into the output stream (for invalid data the result will be
  94    invalid PostScript). Thus there is no quality loss by recompressing the data as
  95    it would occur when recompressing the uncompressed stream with the lossy jpeg
  96    compression method.
  97
  98
  99 .. 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)
 100
 101    *xpos* and *ypos* are the position of the lower left corner of the image. This
 102    position might be modified by some additional transformations when inserting the
 103    bitmap into a canvas. *image* is an instance of :class:`image` or
 104    :class:`jpegimage` but it can also be an image instance from the "Python Image
 105    Library".
 106
 107    *width*, *height*, and *ratio* adjust the size of the image. At least *width* or
 108    *height* needs to be given, when no dpi information is available from *image*.
 109
 110    *storedata* is a flag indicating, that the (still compressed) image data should
 111    be put into the printers memory instead of writing it as a stream into the
 112    PostScript file. While this feature consumes memory of the PostScript
 113    interpreter, it allows for multiple usage of the image without including the
 114    image data several times in the PostScript file.
 115
 116    *maxstrlen* defines a maximal string length when *storedata* is enabled. Since
 117    the data must be kept in the PostScript interpreters memory, it is stored in
 118    strings. While most interpreters do not allow for an arbitrary string length (a
 119    common limit is 65535 characters), a limit for the string length is set. When
 120    more data need to be stored, a list of strings will be used. Note that lists are
 121    also subject to some implementation limits. Since a typical value is 65535
 122    entries, in combination a huge amount of memory can be used.
 123
 124    Valid values for *compressmode* currently are ``"Flate"`` (zlib compression),
 125    ``"DCT"`` (jpeg compression), or ``None`` (disabling the compression). The zlib
 126    compression makes use of the zlib module as it is part of the standard Python
 127    distribution. The jpeg compression is available for those *image* instances
 128    only, which support the creation of a jpeg-compressed stream, *e.g.* images from
 129    the "Python Image Library" with jpeg support installed. The compression must be
 130    disabled when the image data is already compressed.
 131
 132    *flatecompresslevel* is a parameter of the zlib compression. *dctquality*,
 133    *dctoptimize*, and *dctprogression* are parameters of the jpeg compression.
 134    Note, that the progression feature of the jpeg compression should be turned off
 135    in order to produce valid PostScript. Also the optimization feature is known to
 136    produce errors on certain printers.
 137