colour.js
Colour manipulation class
This is an old class I originally wrote for PHP years ago and then ported to
Javascript. I have also written from scratch a similar class in
Python, which I intend to use as a base
and port back to Javascript as version colour.js version 2. Until then, main
documentation is in the source code.
Node
Get the module with npm
:
npm install --save colour.js
Import it (Coffeescript syntax):
Colour = require 'colour.js'
Browser
You can install the script via bower
or download it manually.
bower install --save colour.js
Include the script on your page. In the browser it is attached to the window
object.
Reference
Making new colours
-
A new colour is black by default:
black = new Colour()
-
Array of red, green and blue intensities (float 0~1):
pink = new Colour [1, 0.7, 0.7]
-
Another colour object to make a copy:
black = new Colour()
anotherBlack = new Colour black
-
Greyscale lightness (float 0~1 where 0 is black, 1 is white):
lightGrey = new Colour 0.8
-
Hex colour string; all of the following are valid:
red = new Colour '#f00'
green = new Colour '0f0'
blue = new Colour '0000ff'
cyan = new Colour '#00ffff'
-
CSS3 colour name (case insensitive):
greenyellow = new Colour 'greenyellow'
goldenrod = new Colour 'GOLDENrod'
That's all the constructor supports but you can also make a new colour and then
call one of the replacement routines:
reddish = new Colour().hsv 0, 0.8, 0.5
Getting and setting the current colour
There are various functions which either get or set (replace) the colour. These
return the component, array of components or string if called with no arguments
or replace the colour if arguments are given. In the case of those with multiple
components for example rgb
, the values can be given as separate arguments or
as an array of the components. When setting a colour, the object being operated
on is returned.
rgb
: get or set red, green and blue components as floats 0~1rgb255
: as rgb
but with components as ints 0~255rgb100
: as rgb
but with components as ints 0~100r
, red
, g
, green
, b
, blue
: get or set the component as a float 0~1hsv
: get or set hue (float 0360), saturation (float 01) and value (float
0~1) componentshsv100
: as hsv
but with saturation and value components on an int 0~100
scalehex
: get or set the colour's hex string. When setting can be w ith or
without a leading hash and can be in 3 or 6 digit form. When getting, false
can be passed to suppress the leading hash.
Setting the current colour
These only set and don't have a version which gets.
gr
, grey
, gray
: set red, green and blue components all to the given
intensity (float 0~1), defaulting to 0.5
Get components, make variations of the current colour or change the current colour
These return a new colour by default, or modify and return the current colour if
the last argument is set to false
. With no arguments they return a component
or other metric.
h
, hue
: get or alter the hue (float 0~360)s
, saturation
: get or alter the saturation (float 0~1)v
, value
: get or alter the value (float 0~1)shade
, sh
: get or set the shade. Shade is calculated by summing the red,
green and blue components and dividing by 3.
Make variations of the current colour or change the current colour
These return a new colour by default, or modify and return the current colour if
the last argument is set to false
.
desaturate
: shortcut to saturation
with 0
as the first argumentshiftshade
, shsh
: brighten or darken the colour by moving in a straight
line towards black (negative values) or white (positive values), by the given
proportion, where -1
will result in black, 0
will result in no change to
the colour, 1
will result in whiteshifthue
, shh
: rotate the hue by the given angle (float 0~360)shiftsaturation
, shs
: saturate or desaturate the colour by the given
proportion, where -1
will completely desaturate the colour 0
will cause no
change and 1
will completely saturate itshiftvalue
, shv
: lighten or darken the colour by shifting its HSV value by
the given proportion, where -1
will result in black, 0
will cause no
change and 1
will result in a bright colourhalfsat
, hs
: takes either hue (float 0360) and value (float 01) or just
value (float 0~1) (using the current colour's hue). Produces a washed out
shade of the given lightness.mix
: mix the current colour with the given colour (Colour object or any
single argument the constructor can take) by the given amount (default 0.5)xarashade
, xs
: convenience method to shift saturation and value with
arguments which match those in the Xara colour picker's shade editor. The
first argument affects saturation (-100
gives full saturation, 0
gives no
change, 100
desaturates) and the second affects value (-100
gives black,
0
gives no change, 100
gives a bright colour).
Miscellaneous output
swatch
: return an HTML fragment depicting a colour swatch. Arguments are
[bool showhex = true, [string cssclass = ""]]
.rgburl
: return a query string in the form r=0&g=0.3&b=1
, with red, green
and blue components as floats 0~1
Conversion functions
hsvtorgb
: takes hue (float 0360), saturation (float 01), value (float 01)
or an array of the save components, returns array of red, green and blue
components as floats 01rgbtohsv
: takes red, green and blue components (float 01) or an array of
the same, returns array of hue (float 0360), saturation (float 01) and value
(float 01)hextorgb
: takes a colour string in 3 or 6 digit hex notation with or without
a leading hash and returns an array of red, green and blue components as
floats 0~1rgbtohex
: takes red, green and blue components (float 0~1) or an array of
the same, plus optionally a boolean for whether to include a leading hash
(default true
) returns the colour as a hex string