1Colour
2======
3
4Curv provides operations for constructing colour values,
5displaying colours on the screen, and applying colours to geometric shapes.
6
7For example:
8
9* ``red`` is a colour value.
10* ``show_colour red`` displays the colour red in the graphics window.
11* ``cube >> colour red`` is a red cube.
12
13Colour Spaces
14-------------
15A *colour space* maps a set of coordinates (usually called R, G and B)
16onto a set of absolute, colorimetrically quantified colours.
17Each Curv colour value is constructed using a specific colour space,
18and denotes an absolute colour.
19
20The *gamut* of a colour space is the set of absolute colours it contains.
21The gamut of most popular colour spaces is smaller than the set of colours
22that can be perceived by the human visual system.
23
24The `sRGB colour space`_ has been the industry standard for the
25computer graphics industry for many years. It's the colour space of
26most older monitors. It's the default colour space for images and
27for the world wide web.
28
29.. _`sRGB colour space`: https://en.wikipedia.org/wiki/SRGB
30
31Newer displays support larger colour spaces with wider gamuts than sRGB.
32Newer Apple products support the *DCI-P3* colour space,
33and the *Rec.2020* colour space in the UHDTV standard is even larger.
34
35For now, Curv only supports sRGB. However, support for other colour spaces
36is planned, both to fully support modern display hardware, and to accurately
37describe and display coloured shapes intended for 3D printing, since colour
383D printers have very different gamuts and colour spaces than display hardware.
39
40Colour spaces are represented by Curv values.
41For now, we just have one such value, called ``sRGB``.
42
43Constructors
44------------
45High level operations for constructing colour values.
46
47``sRGB [r,g,b]``
48  Construct a colour value using red, green and blue coordinates in the
49  sRGB colour space. Each colour component is in the range 0 to 1.
50
51``webRGB [r,g,b]``
52  Another way to specify sRGB colours, where the colour components are
53  in the range 0 to 255.
54  A `web colour`_ like PeachPuff (#FFDAB9 or rgb(255,218,185))
55  can be transcribed in Curv like this: ``webRGB[0xFF,0xDA,0xB9]``
56  or ``webRGB[255,218,185]``.
57
58.. _`web colour`: http://encycolorpedia.com/
59
60``sRGB.hue h``
61  A hue is a pure colour with no white or black mixed in.
62  ``sRGB.hue`` is a colour map that can construct any of the hues in the sRGB colour space.
63  ``h`` is a number between 0 and 1:
64
65  ===== ============
66  0     red -- the red primary of the sRGB colour space
67  1/12  orange
68  1/6   yellow
69  1/4   chartreuse
70  1/3   green -- the green primary of the sRGB colour space
71  5/12  spring green
72  1/2   cyan
73  7/12  azure
74  2/3   blue -- the blue primary of the sRGB colour space
75  3/4   violet
76  5/6   magenta
77  11/12 rose
78  1     red
79  ===== ============
80
81``sRGB.grey i``
82  A greyscale colour map containing all of the neutral colours in the sRGB colour space.
83  ``i`` is between 0 and 1, where 0 is black and 1 is white.
84
85``sRGB.HSV [hue,saturation,brightness]``
86  HSV (also known as HSB) is a popular colour model supported by many
87  graphics languages.
88  ``sRGB.HSV`` is a more user-friendly way to specify sRGB colours.
89  The three arguments are:
90
91  ``hue``
92    A number between 0 and 1, specifying a hue (a pure colour). See ``sRGB.hue``.
93
94  ``saturation``
95    Saturation is the distance from a neutral colour (white/grey/black), in the range 0 to 1.
96    Turning down the saturation leaches out the hue and brings the colour
97    closer to neutral.
98
99    * A ``saturation`` of 0 constructs a neutral greyscale colour
100      based on the ``brightness``, ignoring the ``hue``. So ``sRGB.HSV[h,0,b]``
101      is white if b==1, medium grey if b==0.5, and black if b==0.
102    * A ``saturation`` of 1 constructs a "shade" (a mixture of a pure
103      colour and black), where ``hue`` is the pure colour,
104      and ``brightness`` is the distance from black.
105
106  ``brightness``
107    Brightness (aka "value") is the distance from black, from 0 to 1.
108    Turning down the brightness makes the colour dimmer and closer to black.
109
110    * If the ``brightness`` is 0, then the resulting colour is black,
111      ignoring the hue and saturation.
112    * A ``brightness`` of 1 constructs a "tint" (a mixture of a pure colour
113      and white), where ``hue`` is the pure colour,
114      and ``saturation`` is the distance from white.
115
116For convenience, there is a limited set of predefined sRGB colour names:
117
118* ``red``
119* ``yellow``
120* ``green``
121* ``cyan``
122* ``blue``
123* ``magenta``
124* ``white``
125* ``black``
126
127Applying Colours to Shapes
128--------------------------
129``show_colour`` *colour*
130  Display *colour* in the graphics window.
131
132``colour`` *colour* *shape*
133  Apply a colour to a shape.
134
135Internal Representation (Linear RGB)
136------------------------------------
137A colour value is an [R,G,B] triple, where:
138
139* The R, G and B components represent the linear intensity
140  of red, green and blue light in the colour.
141  This is different from sRGB, which uses a non-linear encoding.
142* Each component is a number between 0 and 1 inclusive.
143
144This representation (called linear RGB) is a low-level representation
145that is useful internally, for mixing colours and performing computations
146within the 3D lighting model.
147
148The actual colour space that gives meaning to these coordinates
149is defined by the rendering environment.
150You should use high level operations to construct colour values,
151and not try to create linear R,G,B triples by hand.
152
153Future Work
154-----------
155* Add the LAB and HCL colour spaces.
156  These are perceptually uniform colour spaces, useful for interpolation
157  and generating colour sequences.
158* Add sRGB.HWB colour space. It's the best RGB based colour space for colour picking by artists.
159