colour
index
/home/bjn/src/py-colour/colour.py

colour
Bart Nagel <bart@tremby.net>
https://github.com/tremby/py-colour
licensed under the Gnu GPL version 3
 
Originally ported from Colour.php, a colour manipulation class for PHP by the 
same author, but now quite different.
 
Provides a Colour class and various supporting functions, plus the list of CSS3 
named colours.
 
Colours are internally stored as float RGB values. RGB values are the 
intensities of the red, green and blue channels.
 
RGB
---
 
Conceptually RGB colour space can be thought of as a cube along whose three axes 
the intensities of red, green and blue increase, respectively. The best way to 
think of the RGB colour cube is balancing on its point, so the black corner as 
at the bottom and the white corner is at the top. Shades of grey are then in a 
column up the middle. Colours get more intense as we move upwards through the 
cube.
 
The RGB color cube is not so useful for thinking about and transforming colours. 
For that we can more intuitively use other models.
 
HSV
---
 
The HSV model is best thought of as the RGB colour cube on its point but 
deformed so that the middle six corners (red, yellow, green, cyan, blue, 
magenta) are all in the same horizontal plane as the top corner (white). This 
makes a hexagonal cone. Just like the RGB cube, black is still at the point at 
the bottom, and shades of grey are still in a column in the centre. It's easiest 
to think of it then as stretched out sideways into a cylinder, where the whole 
bottom face is black and the top face has bright colours around the edge, all 
fading to white at a point in its centre.
 
All the primary and secondary colours, then, are on the circumference of the top 
face of the cylinder. The angle from the red primary, in the direction of 
yellow, is called the hue (the H in HSV) and is measured in degrees.
 
As we move inwards from the circumference of the cylinder towards the central 
vertical axis, colour is lost. The distance outwards from grey to the colour is 
called the saturation (the S in HSV) -- 0 at grey and 1 at the edge of the 
cylinder.
 
Moving upwards from the bottom face gives lighter colours, but since we could be 
at the top and not be at white (white is only in the centre of the top), the 
vertical axis can't very well be called "lightness". So the distance upwards is 
called the value (the V in HSV).
 
HSL
---
 
The HSL model is similar to HSV but instead of moving the primaries and 
secondaries up to the same horizontal plane as white, the primaries are moved up 
a little and the secondaries down a little so that they are all in a horizontal 
plane half way up the model. This results in a double hexagonal cone. Stretch 
this out into a cylinder again and we have the HSL model. The bottom face is 
still all black and now the top face is all white.
 
Hue is the same as in HSV, but obviously the primaries and secondaries are now 
in a plane halfway up the model rather than at the top.
 
Saturation is similar to in the HSV model -- it is still the distance from the 
central vertical axis to the colour -- but most colours will have different 
saturation values in the HSV and HSL models. The difference is particularly 
large for very light colours, since that is where the two models are most 
different.
 
The distance up the vertical axis running from black to white is then called 
lightness (the L in HSL), and now it is a fitting name since we will always end 
up with white if we increase it enough.
 
YIQ
---
 
The YIQ model is mostly used in broadcasting, particularly in the NTSC standard.
 
Its lightness metric is called luma and has the abbreviation Y. This is useful 
to have in broadcasting since it is all the information a black and white TV set 
needs. It is called luma rather than lightness since it measures the perceived 
lightness of the colour rather than an intensity based on the actual amounts of 
light. This is important since the eye perceives the same amount of light of 
different colours as different lightnesses -- for instance, we see #0f0 (the 
green primary) as being much brighter than #00f (the blue primary), though both 
have the same lightness according to the metrics of RGB (average intensity), HSV 
(value) and HSL (lightness). In the YIQ model, the green has a much higher luma 
than the blue.
 
Luma is calculated by weighting the red, green and blue channels by finely tuned 
coefficients and then summing.
 
Colour information, then (called chrominance), is in the other two channels, I 
and Q. (I and Q stand for "in-phase" and "quadrature", which have something to 
do with how they are modulated for broadcast transmission.) These are simply two 
axes of colour space. With luma at 0.5 the IQ plane would look like a plane 
halfway up the HSL cylinder (grey in the centre, colours towards the edges) but 
rotated somewhat and with all points appearing to be at the same lightness. (In 
the HSL plane some parts would look lighter than others, such as yellow looking 
brighter than blue).

 
Modules
       
colorsys
hashlib
re

 
Classes
       
builtins.object
Colour

 
class Colour(builtins.object)
    Colours can be made from CSS3 named colours, hex strings, RGB values, HSV 
values, HSL values, YIQ values, lightness (for shades of grey), arbitrary 
bits of data (through hashing their string representations) or copied from 
other Colour objects.
 
They can be manipulated in various ways -- setting or shifting luma, hue, 
value, saturation and so on, or mixing with other colours.
 
Colours can be output as hex strings, 3-tuples of RGB, HSV, HSL or YIQ 
values and HTML colour swatches.
 
Very basic examples:
        # Import the library
        from colour import Colour
 
        # Print a hex representation of a CSS3 named colour
        print(Colour("red"))
 
        # To produce modified versions of a base colour (in this case shifted in 
        # lightness towards black or white) we can make a start Colour object
        green = Colour("#006310")
 
        # ...then make modified copies by putting the start colour through the 
        # constructor and then calling one of its colour modification methods
        darkgreen = Colour(green).shiftluma(-0.5)
        lightgreen = Colour(green).shiftluma(0.5)
 
        # If we hadn't used the constructor to make copies the original Colour 
        # object would have been modified.
 
        # Instead of shifting by a proprtion we can produce shades of a colour 
        # on an absolute scale
        verydarkgreen = Colour(green).luma(0.1)
        verylightgreen = Colour(green).luma(0.9)
 
        # Produce a rainbow by repeatedly shifting the hue of a Colour object
        c = Colour(hsv=(0, 0.8, 0.6))
        for x in range(12):
                print(c.shifthue(30))
 
        # A similar rainbow with uniform brightness (with copies of the Colour 
        # object rather than by modifying the original)
        c = Colour(hsv=(0, 0.8, 0.6))
        for x in range(12):
                print(Colour(c).shifthue(x * 30, perceptual=True))
 
        # An almost-grey version of our green from earlier
        almostgrey = Colour(green).saturation_hsv(0.2)
 
        # Another almost-grey version, but this time with a perceptually similar 
        # level of lightness
        almostgrey2 = Colour(green).saturation_hsv(0.2, perceptual=True)
 
        # Make a set of colours to colour-code some usernames
        usernames = ["tremby", "yappy", "mon", "bill"]
        for username in usernames:
                print("<li style="color: %s">%s</li>" \
                                % (Colour(hash=username), username))
 
        # The same list of usernames but only allowing reds and oranges
        for username in usernames:
                print("<li style="color: %s">%s</li>" \
                                % (Colour().hash(username, minh=0, maxh=30), username))
 
To test the class and see lots more examples you can use the test.py script 
(distributed with this module) which outputs HTML, then view the result in 
your browser:
        python test.py >/tmp/colour.html
        x-www-browser /tmp/colour.html
 
  Methods defined here:
__init__(self, arg=None, grey=None, rgb=None, rgb100=None, rgb255=None, hsv=None, hsv100=None, hsv255=None, hsl=None, hsl100=None, hsl255=None, yiq=None, hex=None, css3=None, hash=None, colour=None)
Constructor
 
This can be called without any arguments, in which case the colour is 
set to black.
 
If the first argument is used its type and value are used to choose the 
action to take. It can be
        a float or integer in the range 0~1
                act as if the grey argument was used
        a 3-tuple
                act as if the rgb argument was used
        a valid hex RGB string
                act as if the hex argument was used
        a string corresponding with a CSS3 named colour
                act as if the css3 argument was used
        a Colour object
                act as if the colour argument was used
 
Otherwise exactly one of the other arguments must be used.
        grey=i
                Set the colour to a grey of this intensity (in the range 0~1).
        rgb=(r, g, b), rgb100=(r, g, b), rgb255=(r, g, b)
                Set colour to these RGB values (in the range 0~1, 0~100 or 0~255 
                depending on the argument used).
        hsv=(h, s, v), hsv100=(h, s, v), hsv255=(h, s, v)
        hsl=(h, s, l), hsl100=(h, s, l), hsl255=(h, s, l)
                Set the colour to these HSV or HSL values (h in degrees, s and v 
                in the range 0~1, 0~100 or 0~255 depending on the argument 
                used).
        yiq=(y, i, q)
                Set the colour to these YIQ values (y in the range 0~1, i and q 
                in the range -1~1).
        hex=string
                Set colour to this hex representation of an RGB colour. See the 
                hex() method for what is accepted.
        css3=string
                Set colour to the CSS3 named colour of this name.
        hash=something
                Convert whatever was passed to a string, hash it and make a 
                colour from the result.
        colour=colour_object
                Set colour to match the given Colour object
__str__(self)
Return a string representation of the object
 
The hex() method is called, returning a hex RGB string with a leading 
hash.
css3(self, name=None)
Get or set the colour as a CSS3 named colour
 
Called with no name argument, attempt to find a CSS3 named colour equal 
to this colour and return its name if found.
 
Called with a string, the colour is set to the CSS3 named colour 
corresponding to the given string.
grey(self, i=None, min=0.0, max=1.0)
Set the colour to a shade of grey with the given intensity, or return 
the current intensity if this colour is a shade of grey, in a particular 
range
 
Called with no i argument, return the intensity of this colour as long 
as the colour is a shade of gray, otherwise return False.
 
Called with a number, the colour is set to a shade of grey with the 
given intensity.
hash(self, tohash, minh=None, maxh=None, mins=0.2, maxs=1.0, miny=0.3, maxy=0.7)
Make a colour to be associated with the given input
 
The tohash argument is converted to a string and then put through the 
MD5 algorithm. The resulting hash is then used to seed a hue, saturation 
and luma.
 
Pass minh and maxh values to constrain the hues (for instance -20 
degrees to 140 degrees, which is not the same as 140 degrees to 340 
degrees). Default is all hues.
Pass mins and maxs values to constrain the saturation values. By default 
only colours close to grey are disallowed.
Pass miny and maxy to constrain the luma. By default anything difficult 
to see against black or white is disallowed.
hex(self, hex=None, hash=True, allowshort=False, forceshort=False)
Get or set the colour as a hex RGB string, with or without a leading 
hash
 
Called with no hex argument, return a hex representation of the object's 
colour.
The hash argument controls whether or not a leading hash will be 
present.
The allowshort argument controls whether or not a short (3-digit) 
version is used if it can losslessly be.
The forceshort argument forces a short (3-digit) hex representation by 
snapping to the closest available colour.
 
Called with the hex argument, attempt to parse the string as a hex RGB 
colour and set the colour to the result. Three or six digit strings are 
accepted.
hsl(self, hsl=None, perceptual=False, hmin=0.0, hmax=360.0, slmin=0.0, slmax=1.0)
Get or set the colour as a 3-tuple of HSL values in a particular range
 
Called with no hsl argument, return the object's colour.
If both min and max are integer types rather than floats, values are 
rounded to the nearest integer.
 
Called with a 3-tuple, the colour is set to the given colour.
Any missing channels (that is, where None is given rather than a number) 
are not changed.
Hues out of the range are accepted since hue is circular.
If the perceptual argument is True attempt to preserve the colour's luma 
in order to retain the colour's perceived brightness.
hsl100(self, *args, **kwargs)
Same as hsl() with hmin=0, hmax=360, slmin=0, slmax=100
hsl255(self, *args, **kwargs)
Same as hsl() with hmin=0, hmax=360, slmin=0, slmax=255
hsv(self, hsv=None, perceptual=False, hmin=0.0, hmax=360.0, svmin=0.0, svmax=1.0)
Get or set the colour as a 3-tuple of HSV values in a particular range
 
Called with no hsv argument, return the object's colour.
If both min and max are integer types rather than floats, values are 
rounded to the nearest integer.
 
Called with a 3-tuple, the colour is set to the given colour.
Any missing channels (that is, where None is given rather than a number) 
are not changed.
Hues out of the range are accepted since hue is circular.
If the perceptual argument is True attempt to preserve the colour's luma 
in order to retain the colour's perceived brightness.
hsv100(self, *args, **kwargs)
Same as hsv() with hmin=0, hmax=360, svmin=0, svmax=100
hsv255(self, *args, **kwargs)
Same as hsv() with hmin=0, hmax=360, svmin=0, svmax=255
hue(self, h=None, perceptual=False)
Get or set the hue in degrees
 
Called with no h argument, return the colour's hue in degrees.
 
Called with a number in degrees, set the colour's hue.
If the perceptual argument is True attempt to preserve the colour's luma 
in order to retain the colour's perceived brightness.
intensity(self, i=None)
Get or set the colour's intensity as a float in the range 0~1
 
The intensity of a colour is the average of its red, green and blue 
components. So the scale of intensity for this colour ranges from black 
with intensity 0, in a straight line in the RGB cube to this colour, 
then in another straight line in the RGB cube towards white.
 
Called with no i argument, return the colour's intensity.
 
Called with a number, set the colour's intensity to the given value.
lightness(self, l=None)
Get or set the lightness in HSL space in the range 0~1
 
Called with no v argument, return the colour's lightness in HSL space.
 
Called with a number in the range 0~1, set the colour's lightness in HSV 
space. The hue and saturation are not changed.
luma(self, y=None)
Get or set the luma of the colour in the range 0~1
 
Called with no y argument, return the colour's luma.
 
Called with a number in the range 0~1, set the colour's luma as close to 
the given value as possible while keeping its colour intact.
mix(self, colour, proportion)
Mix this colour with another
 
The colour argument is usually another Colour object. If it is not, it 
is passed to the constructor to attempt to produce a new colour.
The proportion argument is a float in the range 0~1 controlling how far 
towards the given colour to move, so 0 is no change and 1 is a complete 
change.
rgb(self, rgb=None, min=0.0, max=1.0)
Get or set the colour as a 3-tuple of RGB values in a particular range
 
Called with no rgb argument, return the object's colour.
If both min and max are integer types rather than floats, values are 
rounded to the nearest integer.
 
Called with a 3-tuple, the colour is set to the given colour.
Any missing channels (that is, where None is given rather than a number) 
are not changed.
rgb100(self, *args, **kwargs)
Same as rgb() with min set to 0 and max to 100
rgb255(self, *args, **kwargs)
Same as rgb() with min set to 0 and max to 255
saturation_hsl(self, s=None, perceptual=False)
Get or set the saturation in HSL space in the range 0~1
 
Called with no s argument, return the colour's saturation in HSL space.
 
Called with a number in the range 0~1, set the colour's saturation in 
HSL space. The hue and value are not changed.
If the perceptual argument is True attempt to preserve the colour's luma 
in order to retain the colour's perceived brightness.
saturation_hsv(self, s=None, perceptual=False)
Get or set the saturation in HSV space in the range 0~1
 
Called with no s argument, return the colour's saturation in HSV space.
 
Called with a number in the range 0~1, set the colour's saturation in 
HSV space. The hue and value are not changed.
If the perceptual argument is True attempt to preserve the colour's luma 
in order to retain the colour's perceived brightness.
shifthue(self, angle, perceptual=False)
Shift the hue of this colour relatively by a given number of degrees
 
Return a new colour like this one but with its hue shifted by the given 
number of degrees.
If the perceptual argument is True attempt to preserve the colour's luma 
in order to retain the colour's perceived brightness.
shiftintensity(self, scale)
Shift the intensity of this colour relatively towards black or white
 
See intensity() for what exactly "intensity" means.
 
Called with a float argument in the range -1~1, shift the colour towards 
black (-1 <= scale < 0) or white (0 < scale <= 1) linearly in the RGB 
cube.
shiftlightness(self, scale)
Shift the lightness of this colour relatively
 
Called with a float argument in the range -1~1, return a new colour like 
this one but shifted by the given proportion along the lightness axis of 
HSL space.
Passing 1 would result in white, passing 0 would cause no change and 
passing -1 would result in black.
shiftluma(self, scale)
Shift the luma of this colour relatively
 
Called with a float argument in the range -1~1, return a new colour like 
this one but brightened or darkened by the given proportion in luma.
Passing 1 would result in the brightest possible colour for this colour, 
passing 0 would cause no change and passing -1 would result in the 
darkest.
shiftsaturation_hsl(self, scale, perceptual=False)
Shift the saturation of this colour relatively in HSL space
 
Called with a float argument in the range -1~1, return a new colour like 
this one but shifted by the given proportion along the saturation axis 
of HSL space.
Passing 1 would saturate the colour completely, passing -1 would 
desatuarate the colour completely.
If the perceptual argument is True attempt to preserve the colour's luma 
in order to retain the colour's perceived brightness.
shiftsaturation_hsv(self, scale, perceptual=False)
Shift the saturation of this colour relatively in HSV space
 
Called with a float argument in the range -1~1, return a new colour like 
this one but shifted by the given proportion along the saturation axis 
of HSV space.
Passing 1 would saturate the colour completely, passing -1 would 
desatuarate the colour completely.
If the perceptual argument is True attempt to preserve the colour's luma 
in order to retain the colour's perceived brightness.
shiftvalue(self, scale)
Shift the value of this colour relatively
 
Called with a float argument in the range -1~1, return a new colour like 
this one but shifted by the given proportion along the value axis of HSV 
space.
Passing 1 would maximise value (but unless the colour is fully saturated 
it will not reach white), passing 0 would cause no change and passing -1 
would result in black.
swatch(self, showhex=True, cssclass=None)
Return an HTML colour swatch string
 
Mainly useful for debugging, this returns an HTML snippet which shows a 
small area of the colour and optionally the hex representation of the 
colour.
The returned element has a CSS class of "swatch" and additionally the 
cssclass argument if given. If the cssclass argument was not given the 
element also carries styles to set its font family and some padding.
value(self, v=None)
Get or set the value in HSV space in the range 0~1
 
Called with no v argument, return the colour's value in HSV space.
 
Called with a number in the range 0~1, set the colour's value in HSV 
space. The hue and saturation are not changed.
yiq(self, yiq=None, ymin=0.0, ymax=1.0, iqmin=-1.0, iqmax=1.0)
Get or set the colour as a 3-tuple of YIQ values in a particular range
 
Called with no yiq argument, return the object's colour.
If both min and max are integer types rather than floats, values are 
rounded to the nearest integer.
 
Called with a 3-tuple, the colour is set to the given colour.
Any missing channels (that is, where None is given rather than a number) 
are not changed.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
Functions
       
hextorgb(hex)
Parse the given colour represented by a hex RGB string to RGB values
 
Argument is a string of any of the following forms:
        #xxx
        #xxxxxx
        xxx
        xxxxxx
Where x is a case-insensitive hexadecimal digit.
Return a 3-tuple of float RGB values in the range 0~1.
hsltorgb(hsl)
Convert the given colour in HSL space to RGB space
 
Argument is a 3-tuple of float HSL values in the range (0~360, 0~1, 0~1), 
though hues out of the range 0~360 are accepted.
Return a 3-tuple of float RGB values in the range 0~1.
hsvtorgb(hsv)
Convert the given colour in HSV space to RGB space
 
Argument is a 3-tuple of float HSV values in the range (0~360, 0~1, 0~1), 
though hues out of the range 0~360 are accepted.
Return a 3-tuple of float RGB values in the range 0~1.
rgbtohex(rgb, hash=True, allowshort=False, forceshort=False)
Encode the given colour in RGB form to its hexadecimal representation
 
Argument is a 3-tuple of float RGB values in the range 0~1.
Return a string of the form #xxxxxx, where x is a lowercase hexadecimal 
digit, two digits per channel.
Pass False as the hash argument to omit the leading hash.
The allowshort argument controls whether or not a short (3-digit) version is 
used if it can losslessly be.
The forceshort argument forces a short (3-digit) hex representation by 
snapping to the closest available colour.
rgbtohsl(rgb)
Convert the given colour in RGB space to HSL space
 
Argument is a 3-tuple of float RGB values in the range 0~1.
Return a 3-tuple of float HSV values in the range (0~360, 0~1, 0~1).
rgbtohsv(rgb)
Convert the given colour in RGB space to HSV space
 
Argument is a 3-tuple of float RGB values in the range 0~1.
Return a 3-tuple of float HSV values in the range (0~360, 0~1, 0~1).
rgbtoyiq(rgb)
Convert the given colour in RGB space to YIQ space
 
Argument is a 3-tuple of float RGB values in the range 0~1.
Return a 3-tuple of float YIQ values in the range (0~1, -1~1, -1~1).
yiqtorgb(yiq)
Convert the given colour in YIQ space to RGB space
 
Argument is a 3-tuple of float YIQ values in the range (0~1, -1~1, -1~1).
Return a 3-tuple of float RGB values in the range 0~1.

 
Data
        AUTHOR = 'Bart Nagel'
AUTHOR_EMAIL = 'bart@tremby.net'
COPYRIGHT_YEAR = '2011~2017'
CSS3 = {'aliceblue': 'f0f8ff', 'antiquewhite': 'faebd7', 'aqua': '00ffff', 'aquamarine': '7fffd4', 'azure': 'f0ffff', 'beige': 'f5f5dc', 'bisque': 'ffe4c4', 'black': '000000', 'blanchedalmond': 'ffebcd', 'blue': '0000ff', ...}
DESCRIPTION = 'Colour manipulation class'
LICENSE = 'GNU GPLv3'
NAME = 'py-colour'
URL = 'https://github.com/tremby/py-colour'
VERSION = '1.1.0'
string_types = (<class 'str'>,)