Latest revision as of 19:35, 29 August 2009
This page provides a short introduction to using the colour package on hackage.
 1 The Colour data type
data type and its basic operations are found in the
module. The type variable
is used to specify the numeric type used for the internal representation of the data. Typically one will use:
You may wish to make a type synonym for this type in your program if you will use it everywhere.
You can always use
to change to a different internal representation type.
 2 Creating colours
A collections of colours given by name can be found in the
module. There is also a
to convert a string with one of these names into a colour. Be aware that the colour
will conflict with the Prelude function unless you hide the Prelude function or import the module qualified.
Another way to make a colour is by specifying an RGB triple. These functions can be found in the
library. For example, if you have three
will create the colour with those sRGB colour coordinates.
If you have three
s (or whatever you are using for your internal representation) named
will produce the colour with those colour coordinates. These
should be in the range [0,1] otherwise the resulting colour would be out of gamut (a colour gamut
is a collection of representable colours on a device, such as your monitor).
can create colour from string specifications of the form
 3 Manipulating Colours
The colour operations are found in the
The most common operation on colours is
. For example,
will create a new colour that is 25% red, and 75% green. The weight parameter (the first parameter) should be between 0 and 1, otherwise an out-of-gamut colour could result.
If you need to blend more than two colours, you can use multiple applications of
, or you can use
. For example,
affineCombo [(0.25,red),(0.5,green)] violet
will create a new colour that is 25% red, 50% green, and 25% violet. Again the weights should all be non-negative and the sum of the weights should be no more than 1, otherwise an out-of-gamut colour could result.
Colour intensity can be changed by using
. For example,
will produce a turquoise that is only 40% of the intensity of normal turquoise.
The weight parameter (the first parameter) should be between 0 and 1, otherwise an out-of-gamut colour could result. However if you know that the intensity is low enough, you may safely "darken" by values greater than 1 (which will actually lighten the colour).
Lastly, colours are instance of a Monoid
so colours can be "added" by using
is a quick way to get black). However, like spotlights, adding colours makes more intense colours. Adding colours could take you out of gamut by making colours too intense. Unless you specifically know you want to be adding colours (for example, when writing a ray-tracer), you probably want to be using
 4 Getting colour coordinates out
To retrieve the sRGB
coordinates of a colour, use the functions found in the
module. To get coordinates as
s (or whatever your internal representation is) use
. For example
will produce a value of type
 4.1 RGB triples
is special type of (strict) triple used to store colour coordinates. The functions
can be used to access the three fields. The constructor
will create such a triple. For example,
You might find the functions
curryRGB :: (RGB a -> b) -> a -> a -> a -> b
uncurryRGB :: (a -> a -> a -> b) -> RGB a -> b
useful when working with functions that operate on RGB triples. These functions can be found in
 4.2 Back to colour coordinates
. The coordinates output by
will all be between 0 and 1 unless the colour is out of gamut.
If you want to retrieve the colour coordinates as
will produce an
. Out-of-gamut channels will be clamped to the range 0 to 255.
Lastly, the functions
will produce colour strings of the form
 5 Transparent Colour
Colours that are semi transparent are represented by the
type found in
. Again the
type parameter represents the data type used for the internal representation and would typically be
. You can use
to change the internal representation type of a semi-transparent colour.
s are created from
. For example.
creates an opaque goldenrod. Semi transparent colours can be made using
moccasin `withOpacity` 0.7
creates a colour that is 70% opaque and hence 30% transparent.
is 100% transparent and
transparent == anyColour `withOpacity` 0
Like regular colours, semi-transparent colours can be blended using
. The function
will darken a semi-transparent colour without affecting its opacity.
To make an existing semi-transparent colour more transparent use
. For example,
will return a semi-transparent colour that is 60% of the opacity of
One should avoid dissolving with weights (the first parameter) greater than 1, as you may create invalid "super-opaque" colours. If you know the opacity is less than
then you can safely use weights no more than
. Negative weights will also produce invalid "super-transparent" colours.
anyColour `withOpacity` opacity == disolve opacity (opaque anyColour)
Lastly, the key operation on transparent colours is compositing. Given two semitransparent colours
will produce the semi-transparent colour resulting from acTop being composited over top of
. The bottom layer,
can be a non-transparent colour (of type
). In this case the result will also be a non-transparent colour. However, the top layer must be of semi-transparent type (although it could, of course, be opaque).
Compositing is such important operation on semi-transparent colours, that it is the Monoid
. The function
 5.1 Getting semi-transparent coordinates
The opacity of a semi-transparent colour can be retrieved by the
The pure colour of a semi-transparent colour
can be retrieved by first compositing the colour over black, then darkening by the reciprocal of the alpha channel.
pureColour :: AlphaColour a -> Colour a
pureColour ac | a > 0 = darken (recip a) (ac `over` black)
| otherwise = error "transparent has no pure colour"
a = alphaChannel ac
Note however, that transparent has no pure colour, and this case needs to be handled specially.
This operation is not natively provided because it is an operation that should be avoided. It is only really useful for interfacing with libraries that require pure colour components. Ideally it would be these libraries that implement conversion to and from
. However, you may find it necessary to implement the conversion functions yourself, in which case you can use the above "trick" to write the conversion function.