manual/color.rst

   1
   2 .. module:: color
   3
   4 *******************
   5 Module :mod:`color`
   6 *******************
   7
   8
   9 Color models
  10 ============
  11
  12 PostScript provides different color models. They are available to PyX by
  13 different color classes, which just pass the colors down to the PostScript
  14 level. This implies, that there are no conversion routines between different
  15 color models available. However, some color model conversion routines are
  16 included in Python's standard library in the module ``colorsym``. Furthermore
  17 also the comparison of colors within a color model is not supported, but might
  18 be added in future versions at least for checking color identity and for
  19 ordering gray colors.
  20
  21 There is a class for each of the supported color models, namely ``gray``,
  22 ``rgb``, ``cmyk``, and ``hsb``. The constructors take variables appropriate for
  23 the color model. Additionally, a list of named colors is given in appendix
  24 :ref:`colorname`.
  25
  26
  27 Example
  28 =======
  29
  30    ::
  31
  32       from pyx import *
  33
  34       c = canvas.canvas()
  35
  36       c.fill(path.rect(0, 0, 7, 3), [color.gray(0.8)])
  37       c.fill(path.rect(1, 1, 1, 1), [color.rgb.red])
  38       c.fill(path.rect(3, 1, 1, 1), [color.rgb.green])
  39       c.fill(path.rect(5, 1, 1, 1), [color.rgb.blue])
  40
  41       c.writeEPSfile("color")
  42
  43
  44 The file ``color.eps`` is created and looks like:
  45
  46 .. _fig_color:
  47 .. figure:: color.*
  48    :align:  center
  49
  50    Color example
  51
  52
  53 Color gradients
  54 ===============
  55
  56 The color module provides a class :class:`gradient` for continous transitions between
  57 colors. A list of named gradients is available in appendix :ref:`gradientname`.
  58
  59 Note that all predefined non-gray gradients are defined in the RGB color space,
  60 except for `gradient.Rainbow`, `gradient.ReverseRainbow`, `gradient.Hue`, and
  61 `gradient.ReverseHue`, which are naturally defined in the HSB color space. Converted
  62 RGB and CMYK versions of these latter gradients are also defined under the names
  63 `rgbgradient.Rainbow` and `cmykgradient.Rainbow`, etc.
  64
  65
  66 .. class:: gradient()
  67
  68    This class defines the methods for the ``gradient``.
  69
  70    .. function:: getcolor(parameter)
  71
  72       Returns the color that corresponds to *parameter* (must be between *min* and
  73       *max*).
  74
  75
  76    .. function:: select(index, n_indices)
  77
  78       When a total number of *n_indices* different colors is needed from the gradient,
  79       this method returns the *index*-th color.
  80
  81 .. class:: functiongradient_cmyk(f_c, f_m, f_y, f_k)
  82 .. class:: functiongradient_gray(f_gray)
  83 .. class:: functiongradient_hsb(f_g, f_s, f_b)
  84 .. class:: functiongradient_rgb(f_r, f_g, f_b)
  85
  86    This class provides an arbitray transition between colors of the same color
  87    model.
  88
  89    The functions *f_c*, etc. map the values [0, 1] to the respective components
  90    of the color model.
  91
  92 .. function:: lineargradient_cmyk(mincolor, maxcolor)
  93 .. function:: lineargradient_gray(mincolor, maxcolor)
  94 .. function:: lineargradient_hsb(mincolor, maxcolor)
  95 .. function:: lineargradient_rgb(mincolor, maxcolor)
  96
  97    These factory functors for the corresponding *functiongradient_* classes
  98    provide a linear transition between two given instances of the same color
  99    class. The linear interpolation is performed on the color components of the
 100    specific color model.
 101
 102    *mincolor* and *maxcolor* must be colors of the corresponding color class.
 103
 104 .. class:: class rgbgradient(gradient)
 105
 106    This class takes an arbitrary gradient and converts it into one in the RGB color model.
 107    This is useful for instance in bitmap output, where only certain color models
 108    are supported in Postscript/PDF.
 109
 110 .. class:: class cmykgradient(gradient)
 111
 112    This class takes an arbitrary gradient and converts it into one in the CMYK color mode.
 113    This is useful for instance in bitmap output, where only certain color models
 114    are supported in Postscript/PDF.
 115
 116
 117
 118 Transparency
 119 ============
 120
 121
 122 .. class:: transparency(value)
 123
 124    Instances of this class will make drawing operations (stroking, filling) to
 125    become partially transparent. *value* defines the transparency factor in the
 126    range ``0`` (opaque) to ``1`` (transparent).
 127
 128    Transparency is available in PDF output only since it is not supported by
 129    PostScript. However, for certain ghostscript devices (for example the pdf
 130    backend as used by ps2pdf) proprietary PostScript extension allows for
 131    transparency in PostScript code too. PyX creates such PostScript proprietary
 132    code, but issues a warning when doing so.
 133