manual/bitmap.tex

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