[cairo] Colour Objects In Qahirah

[Lawrence D'Oliveiro]

Qahirah <https://github.com/ldo/qahirah> is a high-level language
binding for Cairo. By “high-level” I mean it is not restricted to the
facilities available to someone directly calling Cairo from C; instead,
it tries to provide conveniences that a Python programmer would find
useful.

For example, Cairo specifies colours strictly as (r, g, b) or (r, g, b,
a) components. But Python provides a module called “colorsys”
<https://docs.python.org/3/library/colorsys.html>, that also allows
colours to be specified in HSL, HLS and YIQ spaces. So it makes sense
to take advantage of this.

Thus, the Qahirah “Colour” object allows instances to be constructed
out of components specified in any of these spaces, and components in
any of these spaces to be extracted from instances. Of course, the
underlying representation is always RGBA, and this is what is passed to
Cairo and retrieved from Cairo.

It is also useful to perform various transformations on colours, like
mixing two colours, darkening/brightening a colour, determining a
complementary colour and so on. Thus, I provide “combine” and “mix”
methods, as well as “replace” methods for selectively replacing
components in your choice of colour space.

For example, start with some arbitrary colour:

    >>> c = Colour.from_hsva((.3, 1, .5))
    >>> c
    Colour(0.10000000000000009, 0.5, 0.0, 1)

The default representation shows the RGBA components, but we can show
the HSVA components:

    >>> c.to_hsva()
    hsva(h=0.3, s=1.0, v=0.5, a=1)

Let us create a darker version of the same colour, working in HLS space:

    >>> c.replace_hlsa(l = c.to_hlsa().l / 2)
    Colour(0.04999999999999999, 0.25, 0.0, 1)
    >>> c.replace_hlsa(l = c.to_hlsa().l / 2).to_hsva()
    hsva(h=0.3, s=1.0, v=0.25, a=1)

Or a lighter version, again in HLS space:

    >>> c.replace_hlsa(l = 1 - (1 - c.to_hlsa().l) / 2)
    Colour(0.39999999999999997, 1.0, 0.25, 1)
    >>> c.replace_hlsa(l = 1 - (1 - c.to_hlsa().l) / 2).to_hsva()
    hsva(h=0.30000000000000004, s=0.75, v=1.0, a=1)

See how the saturation is reduced in HLS, to move the colour closer to
white.

Or how about working out the complementary colour, with the same
saturation and value, but 180° around the colour wheel:

    >>> c.replace_hsva(h = c.to_hsva().h + 0.5)
    Colour(0.40000000000000036, 0.0, 0.5, 1)
    >>> c.replace_hsva(h = c.to_hsva().h + 0.5).to_hsva()
    hsva(h=0.8000000000000002, s=1.0, v=0.5, a=1)