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