generativepy.color module

generativepy uses Color objects to represent colours.

Colours are stored as 4 values representing the red, green, blue and transparency (rgba). Each value has a range of 0.0 to 1.0, that represents the amount of that colour that is present:

• An r value of 0.0 means that colour contains no red.
• An r value of 1.0 means that colour contains the full intensity red.
• An r value of 0.25 means that colour contains a 25% of full intensity red.
• Similar for b and g, allowing any colour can be created using the r, g, b values.

For the alpha value, a:

• An a value of 0.0 means that colour is fully transparent (ie it can't be seen at all).
• An a value of 1.0 means that colour is fully opaque. It will completely hide anything behind it.
• An a value of 0.25 means that colour is partially transparent. It will partly hide anything behind it, creating a colour that is 75% of the background colour mixed with 25% of the foreground colour.
• The way foreground and background colours mix can be changed using Pycairo compositing operators if you wish.

Color can be used to represent various types of colour, but all are stored internally as rgba values (see the constructor section below for more details).

Color objects are immutable - you cannot change a Color object once it has been created. However there are various factory methods available for creating new colours that are based on an existing colour (for example you can create a new colour that is 20% more red, or 50% less saturated, based on an existing colour).

Color objects behave as immutable sequences (similar to tuples) so you can index, unpack, and loop over a Color.

There are a number of examples of using Color in the /examples/color folder on github.

Constructor

The Color constructor creates an rgba colour object. It accepts between 1 and 4 parameters.

All numerical input values are clamped in the range 0.0 to 1.0 (value sless than 0.0 are replaced with 0.0, values greater than 1.0 are replaced with 1.0).

Monochrome (grey) colour

Color(k)

Creates a grey colour with a value between 0.0 (black) and 1.0 (white).

Internally this is represented as an rgba colour with the r, g and b values equal to k, and the a value to 1.

CSS named colour

Color(name)

Creates a colour based on a CSS name. There are 158 named colours, commonly used in web design but very useful in other areas. The list includes a complete range of colours in different shades that are mainly quite visually pleasing, and can be a good source of colour ideas. There are colour charts available on various websites.

Internally this is represented as an rgba colour with the r, g and b set from a dictionary, the a value to 1.

Transparent monochrome (grey) colour

Color(k, a)

Creates a transparent grey colour.

Internally this is represented as an rgba colour with the r, g and b values equal to k, and the alpha value set to a.

Transparent CSS named colour

(name, a)

Creates a transparent colour based on a CSS name.

Internally this is represented as an rgba colour with the r, g and b set from a dictionary, the alpha value set to 1.

RGB colour

Color(r, g, b)

Creates an rgb colour.

Internally this is represented as an rgba colour based on the r, g and b values, with the a value to 1.

RGBA colour

Color(r, g, b)

Creates a transparent rgba colour.

Internally this is represented as an rgba colour based on the r, g, b and a values.

HSL colour

Color.of_hsl(h, s, l)

Creates an HSL colour.

HSL colours are defined by 3 values:

• The hue value controls the position of the colour the colour wheel.
• The saturation controls how pure the colour is. For a particular hue, reducing the saturation creates a greyed out version of the same colour.
• The lightness controls how light the colour is. Varying the lightness creates a lighter or darker version of the same colour.

HSL is very useful because it allows you to control colours more intuitively.

Internally the colour is still represented as an rgba colour. The h, s and l values are converted to rgb, with the a value to 1.

HSLA colour

Color.of_hsla(h, s, l, a)

Creates an HSLA colour.

Internally the colour is still represented as an rgba colour. The h, s and l values are converted to rgb, with the a added to set the transparency.

Properties

Color objects have the following properties:

Properties are used like this:

color = Color(1, 0, 0)   # rgb colour
print(color.b)           # The blue value of color

All these properties are available no matter how the colour was create. So for example if the colour was created as an rgb colour, you can still get the h property. The h, s, l values are calculated from the rgba colour as needed.

Indexing

A Color object can be indexed similar to a tuple (r, g, b, a). For example:

color = Color(0.1, 0.2, 0.3)   # rgb colour
print(color[1])                # 0.2, the g value

The Color object always behaves as a 4-tuple of RGBA values, no matter how it was created.

Setting a colour channel

You can create a new colour with a different red value like this:

color1 = Color(0.1, 0.2, 0.3)   # rgb colour
color2 = color1.with_r(0.8)     # color2 is rgba(0.8, 0.2, 0.3)

color2 is the same as color1 but with a new red value.

You can use with_g(), with_b(), with_a(), with_h(), with_s(), with_l(), to set the other channels.

For hue, this works by first converting the rgb to HSL values, then updating the hue value, then converting back to rgb. If you alter the hue, you will usually find that the r, g and b values all change. Similar for saturation and lightness.

Multiplying a colour channel

You can create a new colour with the red value multiplied by a factor, like this:

color1 = Color(0.5, 0.2, 0.3)          # rgb colour
color2 = color1.with_r_factor(1.2)     # color2 is rgba(0.6, 0.2, 0.3)

color2 is the same as color1 but with its red value multiplied by 1.2. You can think of it as making the colour 20% more red. The multiplier can also be less than 1, for example a factor of 0.7 would make the colour 30% less red.

You can use with_g_factor(), with_b_factor(), with_a_factor(), with_h_factor(), with_s_factor(), with_l_factor(), to set the other channels.

lerp

The lerp function creates a new colour by linear interpolation between two existing colours.

lerp(other, factor)

Here is an example:

color1 = Color(0.4, 0.8, 0)            # rgb colour1
color2 = Color(0, 0.4, 0.8)            # rgb colour2
color3 = color1.lerp(color2, 0.25)     # color3 is rgba(0.3, 0.7, 0.2, 1.0)

A good way to visualise this is to image a gradient that gradually changes colour from color1 to color2. With a lerp factor of 0.25, it means we have moved a quarter of the way between color1 to color2. Our new colour is 75% color1 mixed with 25% color2.