| | |
- 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)
| |