Module color

The color module provides classes representing colors in four device color spaces (gray, rgb, cmyk, and hsb), continuous color gradients (gradient), and opacity attributes (transparency). Because all color and transparency instances act as both style.strokestyle and style.fillstyle attributes, they can be passed directly to canvas.canvas.stroke(), canvas.canvas.fill(), canvas.canvas.draw(), canvas.canvas.text(), or canvas.canvas.set().

Color Models and Named Colors

PyX provides four color classes corresponding to standard PostScript/PDF color models. All color component values are floating-point numbers in the range [0.0, 1.0]:

class color.gray(g)

Grayscale color with intensity g from 0.0 (black) to 1.0 (white). grey is provided as an alias for gray.

gray()

rgb()

cmyk()

hsb()

Converts the color to a gray, rgb, cmyk, or hsb instance.

class color.rgb(r=0.0, g=0.0, b=0.0)

RGB color with red (r), green (g), and blue (b) components in [0.0, 1.0]. Provides conversion methods gray(), rgb(), cmyk(), and hsb(), as well as rgbhex() (returning a "#RRGGBB" hex string).

class color.cmyk(c=0.0, m=0.0, y=0.0, k=0.0)

CMYK color with cyan (c), magenta (m), yellow (y), and black/key (k) ink components in [0.0, 1.0]. Provides conversion methods gray(), rgb(), cmyk(), and hsb().

class color.hsb(h=0.0, s=0.0, b=0.0)

HSB (hue, saturation, brightness) color with h, s, and b in [0.0, 1.0]. Provides conversion methods gray(), rgb(), cmyk(), and hsb().

In addition to constructing colors numerically, PyX predefines a rich palette of named colors as attributes on gray, rgb, and cmyk (such as color.gray.black, color.rgb.red, color.cmyk.CornflowerBlue). All predefined named colors are illustrated in appendix Appendix: Named colors.

Color Conversion Configuration

When converting between RGB, CMYK, and Grayscale via c.rgb(), c.cmyk(), or c.gray(), PyX uses configurable transfer functions that can be adjusted via color.set():

Example

from pyx import *

c = canvas.canvas()

c.fill(path.rect(0, 0, 7, 3), [color.gray(0.8)])
c.fill(path.rect(1, 1, 1, 1), [color.rgb.red])
c.fill(path.rect(3, 1, 1, 1), [color.rgb.green])
c.fill(path.rect(5, 1, 1, 1), [color.rgb.blue])

c.writeEPSfile("color")

The resulting figure is shown in figure Filling rectangles with grayscale and predefined RGB colors..

Filling rectangles with grayscale and predefined RGB colors.

Color Gradients

The gradient hierarchy represents continuous transitions across a color space parameterized by a floating-point value in \([0, 1]\). Gradients serve two roles in PyX:

1. Continuous color scales (used by deco.colorgradient, graph.style.rect, graph.style.surface, and graph.style.density) via gradient.getcolor().

2. Changeable attributes (attr.changeattr) that automatically step through N evenly spaced colors across a multi-dataset plot or graph.style.bar chart via gradient.select().

All predefined gradients are listed and illustrated in appendix Appendix: Named gradients. Note that all predefined non-gray gradients are defined in the RGB color space except for gradient.Rainbow, gradient.ReverseRainbow, gradient.Hue, and gradient.ReverseHue, which are defined in HSB space; pre-converted RGB and CMYK versions of those four are provided as rgbgradient.Rainbow, cmykgradient.Rainbow, etc.

class color.gradient

Base class for all color gradients.

getcolor(parameter)

Returns the color instance corresponding to parameter in [0.0, 1.0].

select(index, n_indices)

Implements the attr.changeattr interface: returns the index-th color out of n_indices evenly spaced samples along the gradient (evaluating getcolor(index / (n_indices - 1)) when n_indices > 1, or getcolor(0) when n_indices == 1).

class color.functiongradient_gray(f_gray)

class color.functiongradient_rgb(f_r, f_g, f_b)

class color.functiongradient_cmyk(f_c, f_m, f_y, f_k)

class color.functiongradient_hsb(f_h, f_s, f_b)

Constructs a custom gradient in the respective color space where each component callable f_*(x) maps a parameter \(x \in [0, 1]\) to a component value in \([0, 1]\).

color.lineargradient_gray(mincolor, maxcolor)

color.lineargradient_rgb(mincolor, maxcolor)

color.lineargradient_cmyk(mincolor, maxcolor)

color.lineargradient_hsb(mincolor, maxcolor)

Factory functions that return a functiongradient_* instance interpolating linearly between mincolor (at 0.0) and maxcolor (at 1.0) in the respective color space.

class color.rgbgradient(gradient)

class color.cmykgradient(gradient)

Wraps an existing gradient (such as an HSB gradient) and converts all returned colors to rgb or cmyk. This is particularly useful for graph.style.surface and graph.style.density plots in PostScript and PDF, which require shading meshes and bitmaps to use Gray, RGB, or CMYK color spaces rather than HSB.

Transparency

class color.transparency(value)

Makes stroking and filling operations partially transparent, where value is in the range 0.0 (completely opaque) to 1.0 (completely transparent).

Note

Transparency is natively supported in PDF and SVG output. Standard PostScript does not support alpha transparency; when writing PostScript or EPS, PyX emits a Ghostscript-specific transparency extension (supported by ps2pdf) and logs a warning.