Module generativepy.color
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
rvalue of 0.0 means that colour contains no red. - An
rvalue of 1.0 means that colour contains the full intensity red. - An
rvalue of 0.25 means that colour contains a 25% of full intensity red. - Similar for
bandg, allowing any colour can be created using ther,g,bvalues.
For the alpha value, a:
- An
avalue of 0.0 means that colour is fully transparent (ie it can't be seen at all). - An
avalue of 1.0 means that colour is fully opaque. It will completely hide anything behind it. - An
avalue 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.
The color module also contains:
- The
make_colormap()function that can be used to create a color map. - Several reusable colour schemes.
Functions
def make_colormap(length, colors, bands=None)-
A colormap is a list of varying colors. It can be used to map a set of integers onto a list of colours.
A colormap can be used to assign colour gradients, gradients with step changes, or discrete colours depending on how it is set up.
Args
length- int - Total size of returned list.
colors- list[Colors] - Colours for creating the map. The list must be at least 2 long.
bands- list[number] - Relative size of each band. bands[i] gives the size of the band between color[i] and color[i+1]. len(bands) must be exactly 1 less than len(colors). If bands is None, equal bands will be used.
Returns
A list of
Colorobjects.
Classes
class ArtisticColorScheme-
An example colour scheme suitable for a white background,
Expand source code
class ArtisticColorScheme: """ An example colour scheme suitable for a white background, """ def __init__(self): self._RED = Color(0.941, 0.234, 0.125) self._BLUE = Color(0.250, 0.336, 0.629) self._GREEN = Color(0.250, 0.629, 0.336) self._YELLOW = Color(0.840, 0.598, 0.133) self._MAGENTA = Color(0.840, 0.133, 0.598) self._ORANGE = Color("orangered") self._CYAN = Color(0.250, 0.629 , 0.629) self._STEEL = Color(0.770, 0.793, 0.887) self._CREAM = Color(0.934, 0.883, 0.727) self._LIME = Color(0.727, 0.934, 0.727) self._BLACK = Color(0.2) self._GREY = Color(0.4) self._WHITE = Color(1) @property def RED(self): return self._RED @property def BLUE(self): return self._BLUE @property def GREEN(self): return self._GREEN @property def YELLOW(self): return self._YELLOW @property def MAGENTA(self): return self._MAGENTA @property def ORANGE(self): return self._ORANGE @property def CYAN(self): return self._CYAN @property def STEEL(self): return self._STEEL @property def CREAM(self): return self._CREAM @property def LIME(self): return self._LIME @property def BLACK(self): return self._BLACK @property def GREY(self): return self._GREY @property def WHITE(self): return self._WHITEInstance variables
prop BLACK-
Expand source code
@property def BLACK(self): return self._BLACK prop BLUE-
Expand source code
@property def BLUE(self): return self._BLUE prop CREAM-
Expand source code
@property def CREAM(self): return self._CREAM prop CYAN-
Expand source code
@property def CYAN(self): return self._CYAN prop GREEN-
Expand source code
@property def GREEN(self): return self._GREEN prop GREY-
Expand source code
@property def GREY(self): return self._GREY prop LIME-
Expand source code
@property def LIME(self): return self._LIME prop MAGENTA-
Expand source code
@property def MAGENTA(self): return self._MAGENTA prop ORANGE-
Expand source code
@property def ORANGE(self): return self._ORANGE prop RED-
Expand source code
@property def RED(self): return self._RED prop STEEL-
Expand source code
@property def STEEL(self): return self._STEEL prop WHITE-
Expand source code
@property def WHITE(self): return self._WHITE prop YELLOW-
Expand source code
@property def YELLOW(self): return self._YELLOW
class Color (*args)-
Colorholds anrgbacolour object.All numerical input values are clamped in the range 0.0 to 1.0 (values less than 0.0 are replaced with 0.0, values greater than 1.0 are replaced with 1.0).
A color object always contains four values,
r,g,banda. Each value can have a value between 0.0 and 1.0. Out of range values are automatically clamped.RGB values represent he three colours, where 0 is no colour, 1 is full intensity colour.
A is the alpha channel, where 0 is fully transparent and 1 is fully opaque.
Options for initialisation parameters are:
Color(k)a grey color, valuek.Color(k, a)a transparent grey color, valuek, alphaa.Color(r, g, b)an RGB color.Color(r, g, b, a)a transparent RGB color, alphaa.Color(name)a CSS named color, wherenameis the colour name (case insensitive).Color(name, a)a transparent CSS named color, alphaa.
Color objects are immutable.
There are also various static methods and properties for creating other colours.
Args
args- various - See usage.
Returns
A
Colorobject.Expand source code
class Color(): """ `Color` holds an `rgba` colour object. All numerical input values are clamped in the range 0.0 to 1.0 (values less than 0.0 are replaced with 0.0, values greater than 1.0 are replaced with 1.0). """ def __init__(self, *args): """ A color object always contains four values, `r`, `g`, `b` and `a`. Each value can have a value between 0.0 and 1.0. Out of range values are automatically clamped. RGB values represent he three colours, where 0 is no colour, 1 is full intensity colour. A is the alpha channel, where 0 is fully transparent and 1 is fully opaque. Options for initialisation parameters are: * `Color(k)` a grey color, value `k`. * `Color(k, a)` a transparent grey color, value `k`, alpha `a`. * `Color(r, g, b)` an RGB color. * `Color(r, g, b, a)` a transparent RGB color, alpha `a`. * `Color(name)` a CSS named color, where `name` is the colour name (case insensitive). * `Color(name, a)` a transparent CSS named color, alpha `a`. Color objects are immutable. There are also various static methods and properties for creating other colours. Args: args: various - See usage. Returns: A `Color` object. """ if len(args) == 1: if args[0] in cssColors: self.color = tuple([x/255 for x in cssColors[args[0]]]) + (1,) else: g = Color.clamp(args[0]) self.color = (g,)*3 + (1,) elif len(args) == 2: if args[0] in cssColors: self.color = tuple([x/255 for x in cssColors[args[0]]]) + (args[1],) else: g = Color.clamp(args[0]) a = Color.clamp(args[1]) self.color = (g,) * 3 + (a,) elif len(args) == 3: self.color = tuple([Color.clamp(x) for x in args]) + (1,) elif len(args) == 4: self.color = tuple([Color.clamp(x) for x in args]) else: raise ValueError("Color takes 1, 2, 3 or 4 arguments") @staticmethod def of_hsl(h, s, l): """ Static method to create an HSL colour. HSL colours are defined by 3 values: * The hue value controls the position of the colour on 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. Args: h: number - Hue of colour. s: number - Saturation of colour. v: number - Value (lightness) of colour. Returns: A `Color` object. """ h = Color.clamp(h) s = Color.clamp(s) l = Color.clamp(l) r, g, b = colorsys.hls_to_rgb(h, l, s) return Color(r, g, b) @staticmethod def of_hsla(h, s, l, a): """ Static method to create a transparent HSL colour. Similar to `of_hsl` but provides alpha channel. Args: h: number - Hue of colour. s: number - Saturation of colour. v: number - Value (lightness) of colour. a: number - Alpha (transparency) of colour. Returns: A `Color` object. """ h = Color.clamp(h) s = Color.clamp(s) l = Color.clamp(l) a = Color.clamp(a) r, g, b = colorsys.hls_to_rgb(h, l, s) return Color(r, g, b, a) @property def rgb(self): """ Read-only property returns RGB values as a tuple of floats. Each value is in range 0.0 to 1.0. """ return tuple(self.color[:3]) @property def rgba(self): """ Read-only property returns RGBA values as a tuple of floats. Each value is in range 0.0 to 1.0. """ return tuple(self.color) @property def r(self): """ Read-only property returns the red value of the colour as a float in range 0.0 to 1.0. """ return self.color[0] def with_r(self, newval): """ Read-only property returns a new `Color` object with its red value set to `newval` """ newval = Color.clamp(newval) return Color(newval, self.color[1], self.color[2], self.color[3]) def with_r_factor(self, factor): """ Read-only property returns a new `Color` object with its red value multiplied by `factor` """ return Color(self.color[0]*factor, self.color[1], self.color[2], self.color[3]) @property def g(self): """ Read-only property returns green value of the colour as a float in range 0.0 to 1.0. """ return self.color[1] def with_g(self, newval): """ Read-only property returns a new `Color` object with its green value set to `newval` """ newval = Color.clamp(newval) return Color(self.color[0], newval, self.color[2], self.color[3]) def with_g_factor(self, factor): """ Read-only property returns a new `Color` object with its green value multiplied by `factor` """ return Color(self.color[0], self.color[1]*factor, self.color[2], self.color[3]) @property def b(self): """ Read-only property returns blue value of the colour as a float in range 0.0 to 1.0. """ return self.color[2] def with_b(self, newval): """ Read-only property returns a new `Color` object with its blue value set to `newval` """ newval = Color.clamp(newval) return Color(self.color[0], self.color[1], newval, self.color[3]) def with_b_factor(self, factor): """ Read-only property returns a new `Color` object with its blue value multiplied by `factor` """ return Color(self.color[0], self.color[1], self.color[2]*factor, self.color[3]) @property def a(self): """ Read-only property returns the alpha value of the colour as a float in range 0.0 to 1.0. """ return self.color[3] def with_a(self, newval): """ Read-only property returns a new `Color` object with its alpha value set to `newval` """ newval = Color.clamp(newval) return Color(self.color[0], self.color[1], self.color[2], newval) def with_a_factor(self, factor): """ Read-only property returns a new `Color` object with its alpha value multiplied by `factor` """ return Color(self.color[0], self.color[1], self.color[2], self.color[3]*factor) @property def h(self): """ Read-only property returns the h value of the colour as a float in range 0.0 to 1.0. """ h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) return h def with_h(self, newval): """ Read-only property returns a new `Color` object with its h value set to `newval` """ newval = Color.clamp(newval) h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) r, g, b = colorsys.hls_to_rgb(newval, l, s) return Color(r, g, b, self.color[3]) def with_h_factor(self, factor): """ Read-only property returns a new `Color` object with its h value multiplied by `factor` """ h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) r, g, b = colorsys.hls_to_rgb(Color.clamp(h*factor), l, s) return Color(r, g, b, self.color[3]) @property def s(self): """ Read-only property returns the s value of the colour as a float in range 0.0 to 1.0. """ h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) return s def with_s(self, newval): """ Read-only property returns a new `Color` object with its s value set to `newval` """ newval = Color.clamp(newval) h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) r, g, b = colorsys.hls_to_rgb(h, l, newval) return Color(r, g, b, self.color[3]) def with_s_factor(self, factor): """ Read-only property returns a new `Color` object with its s value multiplied by `factor` """ h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) r, g, b = colorsys.hls_to_rgb(h, l, Color.clamp(s*factor)) return Color(r, g, b, self.color[3]) @property def l(self): """ Read-only property returns the l value of the colour as a float in range 0.0 to 1.0. """ h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) return l def with_l(self, newval): """ Read-only property returns a new `Color` object with its l value set to `newval` """ newval = Color.clamp(newval) h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) r, g, b = colorsys.hls_to_rgb(h, newval, s) return Color(r, g, b, self.color[3]) def with_l_factor(self, factor): """ Read-only property returns a new `Color` object with its l value multiplied by `factor` """ h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) r, g, b = colorsys.hls_to_rgb(h, Color.clamp(l*factor), s) return Color(r, g, b, self.color[3]) @property def dark3(self): """ Read-only property returns a new `Color` object that is a much darker version of the current colout. """ return self.with_l_factor(0.3) @property def dark2(self): """ Read-only property returns a new `Color` object that is a darker version of the current colout. """ return self.with_l_factor(0.5) @property def dark1(self): """ Read-only property returns a new `Color` object that is a slightly darker version of the current colout. """ return self.with_l_factor(0.75) @property def light3(self): """ Read-only property returns a new `Color` object that is a much lighter version of the current colout. """ return self.with_l_factor(2.5) @property def light2(self): """ Read-only property returns a new `Color` object that is a lighter version of the current colout. """ return self.with_l_factor(1.9) @property def light1(self): """ Read-only property returns a new `Color` object that is a slightly lighter version of the current colout. """ return self.with_l_factor(1.4) def lerp(self, other, factor): """ Creates a new `Color` object that is part way between the current colour and the `other` colour. `factor` controls the mixture, eg: * 0: Current colour * 0.2: 80% current + 20% other * 0.7: 30% current + 70% other * 1: Other colour Args: other: `Color` - the other colour to mix with the current colour. factor: number - the amount of the other colour to mix (see above). Returns: The new `Color`. """ """ """ factor = Color.clamp(factor) col1 = self.rgba col2 = other.rgba col = [x*(1-factor) + y*factor for x, y in zip(col1, col2)] return Color(*col) def as_rgbstr(self): """ Converts current colour into a string format. Returns: String of form rgb(255, 128, 0) """ return 'rgb({}, {}, {})'.format(int(self.color[0] * 255), int(self.color[1] * 255), int(self.color[2] * 255)) def as_rgb_bytes(self): """ Converts current colour into a tuple. Returns: Tuple of form (255, 128, 0) """ return (int(self.color[0] * 255), int(self.color[1] * 255), int(self.color[2] * 255)) def as_rgba_bytes(self): """ Converts current colour into a tuple including alpha. Returns: Tuple of form (255, 128, 0, 64) """ return (int(self.color[0] * 255), int(self.color[1] * 255), int(self.color[2] * 255), int(self.color[3] * 255)) @staticmethod def clamp(v): try: v = min(1, max(0, v)) #Clamp v between 0 and 1 except Exception as e: raise ValueError('Numerical value required') from e return v def __str__(self): return 'rgba' + str(self.color) def __getitem__(self, i): if i < 4: return self.color[i] else: raise IndexError()Static methods
def clamp(v)def of_hsl(h, s, l)-
Static method to create an HSL colour.
HSL colours are defined by 3 values:
- The hue value controls the position of the colour on 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
rgbacolour. Theh,sandlvalues are converted torgb, with theavalue to 1.Args
h- number - Hue of colour.
s- number - Saturation of colour.
v- number - Value (lightness) of colour.
Returns
A
Colorobject. def of_hsla(h, s, l, a)-
Static method to create a transparent HSL colour.
Similar to
of_hslbut provides alpha channel.Args
h- number - Hue of colour.
s- number - Saturation of colour.
v- number - Value (lightness) of colour.
a- number - Alpha (transparency) of colour.
Returns
A
Colorobject.
Instance variables
prop a-
Read-only property returns the alpha value of the colour as a float in range 0.0 to 1.0.
Expand source code
@property def a(self): """ Read-only property returns the alpha value of the colour as a float in range 0.0 to 1.0. """ return self.color[3] prop b-
Read-only property returns blue value of the colour as a float in range 0.0 to 1.0.
Expand source code
@property def b(self): """ Read-only property returns blue value of the colour as a float in range 0.0 to 1.0. """ return self.color[2] prop dark1-
Read-only property returns a new
Colorobject that is a slightly darker version of the current colout.Expand source code
@property def dark1(self): """ Read-only property returns a new `Color` object that is a slightly darker version of the current colout. """ return self.with_l_factor(0.75) prop dark2-
Read-only property returns a new
Colorobject that is a darker version of the current colout.Expand source code
@property def dark2(self): """ Read-only property returns a new `Color` object that is a darker version of the current colout. """ return self.with_l_factor(0.5) prop dark3-
Read-only property returns a new
Colorobject that is a much darker version of the current colout.Expand source code
@property def dark3(self): """ Read-only property returns a new `Color` object that is a much darker version of the current colout. """ return self.with_l_factor(0.3) prop g-
Read-only property returns green value of the colour as a float in range 0.0 to 1.0.
Expand source code
@property def g(self): """ Read-only property returns green value of the colour as a float in range 0.0 to 1.0. """ return self.color[1] prop h-
Read-only property returns the h value of the colour as a float in range 0.0 to 1.0.
Expand source code
@property def h(self): """ Read-only property returns the h value of the colour as a float in range 0.0 to 1.0. """ h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) return h prop l-
Read-only property returns the l value of the colour as a float in range 0.0 to 1.0.
Expand source code
@property def l(self): """ Read-only property returns the l value of the colour as a float in range 0.0 to 1.0. """ h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) return l prop light1-
Read-only property returns a new
Colorobject that is a slightly lighter version of the current colout.Expand source code
@property def light1(self): """ Read-only property returns a new `Color` object that is a slightly lighter version of the current colout. """ return self.with_l_factor(1.4) prop light2-
Read-only property returns a new
Colorobject that is a lighter version of the current colout.Expand source code
@property def light2(self): """ Read-only property returns a new `Color` object that is a lighter version of the current colout. """ return self.with_l_factor(1.9) prop light3-
Read-only property returns a new
Colorobject that is a much lighter version of the current colout.Expand source code
@property def light3(self): """ Read-only property returns a new `Color` object that is a much lighter version of the current colout. """ return self.with_l_factor(2.5) prop r-
Read-only property returns the red value of the colour as a float in range 0.0 to 1.0.
Expand source code
@property def r(self): """ Read-only property returns the red value of the colour as a float in range 0.0 to 1.0. """ return self.color[0] prop rgb-
Read-only property returns RGB values as a tuple of floats. Each value is in range 0.0 to 1.0.
Expand source code
@property def rgb(self): """ Read-only property returns RGB values as a tuple of floats. Each value is in range 0.0 to 1.0. """ return tuple(self.color[:3]) prop rgba-
Read-only property returns RGBA values as a tuple of floats. Each value is in range 0.0 to 1.0.
Expand source code
@property def rgba(self): """ Read-only property returns RGBA values as a tuple of floats. Each value is in range 0.0 to 1.0. """ return tuple(self.color) prop s-
Read-only property returns the s value of the colour as a float in range 0.0 to 1.0.
Expand source code
@property def s(self): """ Read-only property returns the s value of the colour as a float in range 0.0 to 1.0. """ h, l, s = colorsys.rgb_to_hls(self.color[0], self.color[1], self.color[2]) return s
Methods
def as_rgb_bytes(self)-
Converts current colour into a tuple.
Returns
Tuple of form (255, 128, 0)
def as_rgba_bytes(self)-
Converts current colour into a tuple including alpha.
Returns
Tuple of form (255, 128, 0, 64)
def as_rgbstr(self)-
Converts current colour into a string format.
Returns
String of form rgb(255, 128, 0)
def lerp(self, other, factor)-
Creates a new
Colorobject that is part way between the current colour and theothercolour.factorcontrols the mixture, eg:- 0: Current colour
- 0.2: 80% current + 20% other
- 0.7: 30% current + 70% other
- 1: Other colour
Args
otherColor- the other colour to mix with the current colour.factor- number - the amount of the other colour to mix (see above).
Returns
The new
Color. def with_a(self, newval)-
Read-only property returns a new
Colorobject with its alpha value set tonewval def with_a_factor(self, factor)-
Read-only property returns a new
Colorobject with its alpha value multiplied byfactor def with_b(self, newval)-
Read-only property returns a new
Colorobject with its blue value set tonewval def with_b_factor(self, factor)-
Read-only property returns a new
Colorobject with its blue value multiplied byfactor def with_g(self, newval)-
Read-only property returns a new
Colorobject with its green value set tonewval def with_g_factor(self, factor)-
Read-only property returns a new
Colorobject with its green value multiplied byfactor def with_h(self, newval)-
Read-only property returns a new
Colorobject with its h value set tonewval def with_h_factor(self, factor)-
Read-only property returns a new
Colorobject with its h value multiplied byfactor def with_l(self, newval)-
Read-only property returns a new
Colorobject with its l value set tonewval def with_l_factor(self, factor)-
Read-only property returns a new
Colorobject with its l value multiplied byfactor def with_r(self, newval)-
Read-only property returns a new
Colorobject with its red value set tonewval def with_r_factor(self, factor)-
Read-only property returns a new
Colorobject with its red value multiplied byfactor def with_s(self, newval)-
Read-only property returns a new
Colorobject with its s value set tonewval def with_s_factor(self, factor)-
Read-only property returns a new
Colorobject with its s value multiplied byfactor
class DarkColorScheme-
An example colour scheme suitable for a dark grey background, such as the
BACKGROUNDcolour below.Expand source code
class DarkColorScheme: """ An example colour scheme suitable for a dark grey background, such as the `BACKGROUND` colour below. """ def __init__(self): self._BACKGROUND = Color(0.2) self._RED = Color("firebrick") self._GREEN = Color("mediumseagreen") self._BLUE = Color("steelblue") self._WHITE = Color(0.8) self._GREY = Color(0.5) self._BLACK = Color(0) self._YELLOW = Color("darkkhaki") self._CYAN = Color("darkturquoise") self._MAGENTA = Color("orchid") self._ORANGE = Color("orangered") @property def BACKGROUND(self): return self._BACKGROUND @property def RED(self): return self._RED @property def GREEN(self): return self._GREEN @property def BLUE(self): return self._BLUE @property def WHITE(self): return self._WHITE @property def GREY(self): return self._GREY @property def BLACK(self): return self._BLACK @property def YELLOW(self): return self._YELLOW @property def CYAN(self): return self._CYAN @property def MAGENTA(self): return self._MAGENTA @property def ORANGE(self): return self._ORANGEInstance variables
prop BACKGROUND-
Expand source code
@property def BACKGROUND(self): return self._BACKGROUND prop BLACK-
Expand source code
@property def BLACK(self): return self._BLACK prop BLUE-
Expand source code
@property def BLUE(self): return self._BLUE prop CYAN-
Expand source code
@property def CYAN(self): return self._CYAN prop GREEN-
Expand source code
@property def GREEN(self): return self._GREEN prop GREY-
Expand source code
@property def GREY(self): return self._GREY prop MAGENTA-
Expand source code
@property def MAGENTA(self): return self._MAGENTA prop ORANGE-
Expand source code
@property def ORANGE(self): return self._ORANGE prop RED-
Expand source code
@property def RED(self): return self._RED prop WHITE-
Expand source code
@property def WHITE(self): return self._WHITE prop YELLOW-
Expand source code
@property def YELLOW(self): return self._YELLOW