Conventions Used in Rayon

This chapter describes some conventions that are used throughout Rayon to specify colors, sizes, text and line styles.

Specifying Colors

Colors can be specified in two main ways in Rayon. The first is as a triple or 4-tuple of integers ranging from 0-255. The elements of the tuple represent the proportion of red, green, blue and (if specified) alpha in the color. (An alpha vale of 255 represents full opacity.) For example:

# Add a pure blue background. (c is a chart.)
c.add_plot_background((0, 0, 255, 255))

If no alpha is specified, it is assumed to be 255. The following is equivalent to the above:

c.add_plot_background((0, 0, 255))

Color may also be specified as a string. Rayon follows the format described in and, with two exceptions:

  • Alpha channels are supported in hexadecimal notation as well as in functional notation.
  • The hsl(...) and hsl(...) specification forms are not supported.

For example, here are all the ways to specify that a blue background should be added to a plot in a chart using a string, disregarding case (which is ignored):

# name. All named colors are fully opaque,
# i.e. alpha is 255.
# rgb/rgba
# rrggbb/rrggbbaa
# rgb(...)
c.add_plot_background("rgb(0, 0, 255)")
c.add_plot_background("rgb(0%, 0%, 100%)")
# rgba(...) (Note how alpha is specified)
c.add_plot_background("rgba(0, 0, 255, 1.0)")
c.add_plot_background("rgba(0%, 0%, 100%, 1.0)")

Specifying Size and Distance

Size may be specified in absolute or relative values. If a size specification is a number between 0 and 1, it is presumed to be a proportion of available space (width or height, as appropriate), as in the following example:

# Add a border that is 3% of chart height.
# (c is a chart, b is a border.)
c.add_top_border(b, height=.03)

To specify an absolute size, supply a string containing the number, and a valid unit specifier:

# Add three pixels of padding to
# the top of the chart
c.add_padding('top', '3px')
# Add three points
c.add_padding('top', '3pt')

At this time, there is no practical difference between points and pixels in Rayon, and they may be used interchangeably. In PNG images and GUI canvases, 3px will represent three pixels; in PDF and SVG images, it will represent three points. The same is true of 3pt.

Specifying Line Styles

The configuration of lines in Rayon may be created from string specifications. The format for a line specification is similar to the CSS specification’s shorthand for defining borders, described in width style color, where width is an integer width in device units (points or pixels), style is one of the valid line styles that can be passed to the new_line method of the Toolbox object (i.e., solid, dashed, dotted and dotdash) and color is a valid color specification, as described in Specifying Colors.