colour-2.3.6: A model for human colour/color perception

Safe Haskell | Safe-Inferred
Language | Haskell98

Data.Colour

Contents

- Interfacing with Other Libraries' Colour Spaces
- Colour type
- Colour operations
- Orphan instances

Description

Datatypes for representing the human perception of colour. Includes common operations for blending and compositing colours. The most common way of creating colours is either by name (see Data.Colour.Names) or by giving an sRGB triple (see Data.Colour.SRGB).

Methods of specifying Colours can be found in

- Data.Colour.SRGB
- Data.Colour.SRGB.Linear
- Data.Colour.CIE

Colours can be specified in a generic `RGBSpace` by using

- Data.Colour.RGBSpace

Synopsis

- data Colour a
- colourConvert :: (Fractional b, Real a) => Colour a -> Colour b
- black :: Num a => Colour a
- data AlphaColour a
- opaque :: Num a => Colour a -> AlphaColour a
- withOpacity :: Num a => Colour a -> a -> AlphaColour a
- transparent :: Num a => AlphaColour a
- alphaColourConvert :: (Fractional b, Real a) => AlphaColour a -> AlphaColour b
- alphaChannel :: AlphaColour a -> a
- class AffineSpace f where
  - affineCombo :: Num a => [(a, f a)] -> f a -> f a
- blend :: (Num a, AffineSpace f) => a -> f a -> f a -> f a
- class ColourOps f where
  - over :: Num a => AlphaColour a -> f a -> f a
  - darken :: Num a => a -> f a -> f a
- dissolve :: Num a => a -> AlphaColour a -> AlphaColour a
- atop :: Fractional a => AlphaColour a -> AlphaColour a -> AlphaColour a

# Interfacing with Other Libraries' Colour Spaces

Executive summary: Always use Data.Colour.SRGB when interfacing with other libraries. Use `toSRGB24` / `sRGB24` when interfacing with libraries wanting `Word8` per channel. Use `toSRGB` / `sRGB` when interfacing with libraries wanting `Double` or `Float` per channel.

Interfacing with the colour for other libraries, such as cairo (http://www.haskell.org/gtk2hs/archives/category/cairo/) and OpenGL (http://hackage.haskell.org/cgi-bin/hackage-scripts/package/OpenGL), can be a challenge because these libraries often do not use colour spaces in a consistent way. The problem is that these libraries work in a device dependent colour space and give no indication what the colour space is. For most devices this colours space is implicitly the non-linear sRGB space. However, to make matters worse, these libraries also do their compositing and blending in the device colour space. Blending and compositing ought to be done in a linear colour space, but since the device space is typically non-linear sRGB, these libraries typically produce colour blends that are too dark.

(Note that Data.Colour is a device independent colour space, and produces correct blends. e.g. compare `toSRGB (blend 0.5 lime red)` with `RGB 0.5 0.5 0`)

Because these other colour libraries can only blend in device colour spaces, they are fundamentally broken and there is no "right" way to interface with them. For most libraries, the best one can do is assume they are working with an sRGB colour space and doing incorrect blends. In these cases use Data.Colour.SRGB to convert to and from the colour coordinates. This is the best advice for interfacing with cairo.

When using OpenGL, the choice is less clear. Again, OpenGL usually does blending in the device colour space. However, because blending is an important part of proper shading, one may want to consider that OpenGL is working in a linear colour space, and the resulting rasters are improperly displayed. This is born out by the fact that OpenGL extensions that support sRGB do so by converting sRGB input/output to linear colour coordinates for processing by OpenGL.

The best way to use OpenGL, is to use proper sRGB surfaces for textures and rendering. These surfaces will automatically convert to and from OpenGL's linear colour space. In this case, use Data.Colour.SRGB.Linear to interface OpenGL's linear colour space.

If not using proper surfaces with OpenGL, then you have a choice between having OpenGL do improper blending or improper display If you are using OpenGL for 3D shading, I recommend using Data.Colour.SRGB.Linear (thus choosing improper OpenGL display). If you are not using OpenGL for 3D shading, I recommend using Data.Colour.SRGB (thus choosing improper OpenGL blending).

# Colour type

data Colour a Source #

This type represents the human preception of colour. The `a` parameter is a numeric type used internally for the representation.

The `Monoid` instance allows one to add colours, but beware that adding colours can take you out of gamut. Consider using `blend` whenever possible.

#### Instances

Instances details

AffineSpace Colour Source # |
Instance details Defined in Data.Colour.Internal Methods affineCombo :: Num a => [(a, Colour a)] -> Colour a -> Colour a Source #
ColourOps Colour Source # |
Instance details Defined in Data.Colour.Internal Methods over :: Num a => AlphaColour a -> Colour a -> Colour a Source # darken :: Num a => a -> Colour a -> Colour a Source #
Num a => Monoid (Colour a) Source # |
Instance details Defined in Data.Colour.Internal Methods mempty :: Colour a Source # mappend :: Colour a -> Colour a -> Colour a Source # mconcat :: [Colour a] -> Colour a Source #
Num a => Semigroup (Colour a) Source # |
Instance details Defined in Data.Colour.Internal Methods (<>) :: Colour a -> Colour a -> Colour a Source # sconcat :: NonEmpty (Colour a) -> Colour a Source # stimes :: Integral b => b -> Colour a -> Colour a Source #
(Fractional a, Read a) => Read (Colour a) Source # |
Instance details Defined in Data.Colour Methods readsPrec :: Int -> ReadS (Colour a) Source # readList :: ReadS [Colour a] Source # readPrec :: ReadPrec (Colour a) Source # readListPrec :: ReadPrec [Colour a] Source #
(Fractional a, Show a) => Show (Colour a) Source # |
Instance details Defined in Data.Colour Methods showsPrec :: Int -> Colour a -> ShowS Source # show :: Colour a -> String Source # showList :: [Colour a] -> ShowS Source #
Eq a => Eq (Colour a) Source # |
Instance details Defined in Data.Colour.Internal Methods (==) :: Colour a -> Colour a -> Bool Source # (/=) :: Colour a -> Colour a -> Bool Source #

colourConvert :: (Fractional b, Real a) => Colour a -> Colour b Source #

Change the type used to represent the colour coordinates.

black :: Num a => Colour a Source #

data AlphaColour a Source #

This type represents a `Colour` that may be semi-transparent.

The `Monoid` instance allows you to composite colours.

    x `mappend` y == x `over` y

To get the (pre-multiplied) colour channel of an `AlphaColour` `c`, simply composite `c` over black.

    c `over` black

#### Instances

Instances details

AffineSpace AlphaColour Source # |
Instance details Defined in Data.Colour.Internal Methods affineCombo :: Num a => [(a, AlphaColour a)] -> AlphaColour a -> AlphaColour a Source #
ColourOps AlphaColour Source # |
Instance details Defined in Data.Colour.Internal Methods over :: Num a => AlphaColour a -> AlphaColour a -> AlphaColour a Source # darken :: Num a => a -> AlphaColour a -> AlphaColour a Source #
Num a => Monoid (AlphaColour a) Source # |
Instance details Defined in Data.Colour.Internal Methods mempty :: AlphaColour a Source # mappend :: AlphaColour a -> AlphaColour a -> AlphaColour a Source # mconcat :: [AlphaColour a] -> AlphaColour a Source #
Num a => Semigroup (AlphaColour a) Source # | `AlphaColour` forms a monoid with `over` and `transparent`.
Instance details Defined in Data.Colour.Internal Methods (<>) :: AlphaColour a -> AlphaColour a -> AlphaColour a Source # sconcat :: NonEmpty (AlphaColour a) -> AlphaColour a Source # stimes :: Integral b => b -> AlphaColour a -> AlphaColour a Source #
(Fractional a, Read a) => Read (AlphaColour a) Source # |
Instance details Defined in Data.Colour Methods readsPrec :: Int -> ReadS (AlphaColour a) Source # readList :: ReadS [AlphaColour a] Source # readPrec :: ReadPrec (AlphaColour a) Source # readListPrec :: ReadPrec [AlphaColour a] Source #
(Fractional a, Show a, Eq a) => Show (AlphaColour a) Source # |
Instance details Defined in Data.Colour Methods showsPrec :: Int -> AlphaColour a -> ShowS Source # show :: AlphaColour a -> String Source # showList :: [AlphaColour a] -> ShowS Source #
Eq a => Eq (AlphaColour a) Source # |
Instance details Defined in Data.Colour.Internal Methods (==) :: AlphaColour a -> AlphaColour a -> Bool Source # (/=) :: AlphaColour a -> AlphaColour a -> Bool Source #

opaque :: Num a => Colour a -> AlphaColour a Source #

Creates an opaque `AlphaColour` from a `Colour`.

withOpacity :: Num a => Colour a -> a -> AlphaColour a Source #

Creates an `AlphaColour` from a `Colour` with a given opacity.

    c `withOpacity` o == dissolve o (opaque c)

transparent :: Num a => AlphaColour a Source #

This `AlphaColour` is entirely transparent and has no associated colour channel.

alphaColourConvert :: (Fractional b, Real a) => AlphaColour a -> AlphaColour b Source #

Change the type used to represent the colour coordinates.

alphaChannel :: AlphaColour a -> a Source #

Returns the opacity of an `AlphaColour`.

# Colour operations

These operations allow combine and modify existing colours

class AffineSpace f where Source #

Methods

affineCombo :: Num a => [(a, f a)] -> f a -> f a Source #

Compute a affine Combination (weighted-average) of points. The last parameter will get the remaining weight. e.g.

    affineCombo [(0.2,a), (0.3,b)] c == 0.2*a + 0.3*b + 0.5*c

Weights can be negative, or greater than 1.0; however, be aware that non-convex combinations may lead to out of gamut colours.

#### Instances

Instances details

AffineSpace Chromaticity Source # |
Instance details Defined in Data.Colour.CIE Methods affineCombo :: Num a => [(a, Chromaticity a)] -> Chromaticity a -> Chromaticity a Source #
AffineSpace AlphaColour Source # |
Instance details Defined in Data.Colour.Internal Methods affineCombo :: Num a => [(a, AlphaColour a)] -> AlphaColour a -> AlphaColour a Source #
AffineSpace Colour Source # |
Instance details Defined in Data.Colour.Internal Methods affineCombo :: Num a => [(a, Colour a)] -> Colour a -> Colour a Source #

blend :: (Num a, AffineSpace f) => a -> f a -> f a -> f a Source #

Compute the weighted average of two points. e.g.

    blend 0.4 a b = 0.4*a + 0.6*b

The weight can be negative, or greater than 1.0; however, be aware that non-convex combinations may lead to out of gamut colours.

class ColourOps f where Source #

Methods

over :: Num a => AlphaColour a -> f a -> f a Source #

`c1 `over` c2` returns the `Colour` created by compositing the `AlphaColour` `c1` over `c2`, which may be either a `Colour` or `AlphaColour`.

darken :: Num a => a -> f a -> f a Source #

`darken s c` blends a colour with black without changing it's opacity.

For `Colour`, `darken s c = blend s c mempty`

#### Instances

Instances details

ColourOps AlphaColour Source # |
Instance details Defined in Data.Colour.Internal Methods over :: Num a => AlphaColour a -> AlphaColour a -> AlphaColour a Source # darken :: Num a => a -> AlphaColour a -> AlphaColour a Source #
ColourOps Colour Source # |
Instance details Defined in Data.Colour.Internal Methods over :: Num a => AlphaColour a -> Colour a -> Colour a Source # darken :: Num a => a -> Colour a -> Colour a Source #

dissolve :: Num a => a -> AlphaColour a -> AlphaColour a Source #

Returns an `AlphaColour` more transparent by a factor of `o`.

atop :: Fractional a => AlphaColour a -> AlphaColour a -> AlphaColour a Source #

`c1 `atop` c2` returns the `AlphaColour` produced by covering the portion of `c2` visible by `c1`. The resulting alpha channel is always the same as the alpha channel of `c2`.

    c1 `atop` (opaque c2) == c1 `over` (opaque c2)
    AlphaChannel (c1 `atop` c2) == AlphaChannel c2

# Orphan instances

(Fractional a, Read a) => Read (AlphaColour a) Source # |
Instance details Methods readsPrec :: Int -> ReadS (AlphaColour a) Source # readList :: ReadS [AlphaColour a] Source # readPrec :: ReadPrec (AlphaColour a) Source # readListPrec :: ReadPrec [AlphaColour a] Source #
(Fractional a, Read a) => Read (Colour a) Source # |
Instance details Methods readsPrec :: Int -> ReadS (Colour a) Source # readList :: ReadS [Colour a] Source # readPrec :: ReadPrec (Colour a) Source # readListPrec :: ReadPrec [Colour a] Source #
(Fractional a, Show a, Eq a) => Show (AlphaColour a) Source # |
Instance details Methods showsPrec :: Int -> AlphaColour a -> ShowS Source # show :: AlphaColour a -> String Source # showList :: [AlphaColour a] -> ShowS Source #
(Fractional a, Show a) => Show (Colour a) Source # |
Instance details Methods showsPrec :: Int -> Colour a -> ShowS Source # show :: Colour a -> String Source # showList :: [Colour a] -> ShowS Source #