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.
  97 \end{classdesc}
  98