manual/color.tex

   1 \chapter{Module color}
   2 \label{color}
   3 \section{Color models}
   4 PostScript provides different color models. They are available to
   5 \PyX{} by different color classes, which just pass the colors down to
   6 the PostScript level. This implies, that there are no conversion
   7 routines between different color models available. However, some color
   8 model conversion routines are included in Python's standard library in
   9 the module \texttt{colorsym}. Furthermore also the comparison of
  10 colors within a color model is not supported, but might be added in
  11 future versions at least for checking color identity and for ordering
  12 gray colors.
  13
  14 There is a class for each of the supported color models, namely
  15 \verb|gray|, \verb|rgb|, \verb|cmyk|, and \verb|hsb|. The constructors
  16 take variables appropriate for the color model. Additionally, a list of
  17 named colors is given in appendix~\ref{colorname}.
  18
  19 \section{Example}
  20 \begin{quote}
  21 \begin{verbatim}
  22 from pyx import *
  23
  24 c = canvas.canvas()
  25
  26 c.fill(path.rect(0, 0, 7, 3), [color.gray(0.8)])
  27 c.fill(path.rect(1, 1, 1, 1), [color.rgb.red])
  28 c.fill(path.rect(3, 1, 1, 1), [color.rgb.green])
  29 c.fill(path.rect(5, 1, 1, 1), [color.rgb.blue])
  30
  31 c.writeEPSfile("color")
  32 \end{verbatim}
  33 \end{quote}
  34
  35 The file \verb|color.eps| is created and looks like:
  36 \begin{quote}
  37 \includegraphics{color}
  38 \end{quote}
  39
  40 \section{Color gradients}
  41
  42 The color module provides a class \verb|gradient| for continous transitions between
  43 colors. A list of named gradients is available in appendix~\ref{gradientname}.
  44
  45 \begin{classdesc}{gradient}{min=0, max=1}
  46   This class provides the methods for the \verb|gradient|. Different
  47   initializations can be found in \verb|lineargradient| and
  48   \verb|functiongradient|.
  49
  50   \var{min} and \var{max} provide the valid range of the arguments for
  51   \verb|getcolor|.
  52
  53   \begin{funcdesc}{getcolor}{parameter}
  54     Returns the color that corresponds to \var{parameter} (must be between
  55     \var{min} and \var{max}).
  56   \end{funcdesc}
  57
  58   \begin{funcdesc}{select}{index, n\_indices}
  59     When a total number of \var{n\_indices} different colors is needed from the
  60     gradient, this method returns the \var{index}-th color.
  61   \end{funcdesc}
  62
  63 \end{classdesc}
  64
  65
  66 \begin{classdesc}{lineargradient}{startcolor, endcolor, min=0, max=1}
  67   This class provides a linear transition between two given colors. The linear
  68   interpolation is performed on the color components of the specific color
  69   model.
  70
  71   \var{startcolor} and \var{endcolor} must be colors of the same color model.
  72 \end{classdesc}
  73
  74 \begin{classdesc}{functiongradient}{functions, type, min=0, max=1}
  75   This class provides an arbitray transition between colors of the same
  76   color model.
  77
  78   \var{type} is a string indicating the color model (one of \code{"cmyk"},
  79   \code{"rgb"}, \code{"hsb"}, \code{"grey"})
  80
  81   \var{functions} is a dictionary that maps the color components onto given
  82   functions. E.g. for \code{type="rgb"} this dictionary must have the keys
  83   \code{"r"}, \code{"g"}, and \code{"b"}.
  84
  85 \end{classdesc}
  86
  87 \section{Transparency}
  88
  89 \begin{classdesc}{transparency}{value}
  90   Instances of this class will make drawing operations (stroking,
  91   filling) to become partially transparent. \var{value} defines the
  92   transparency factor in the range \code{0} (opaque) to \code{1}
  93   (transparent).
  94
  95   Transparency is available in PDF output only since it is not
  96   supported by PostScript. However, for certain ghostscript devices
  97   (for example the pdf backend as used by ps2pdf) proprietary
  98   PostScript extension allows for transparency in PostScript code too.
  99   \PyX{} creates such PostScript proprietary code, but issues a
 100   warning when doing so.
 101 \end{classdesc}
 102