File: index.rst

package info (click to toggle)
grapefruit 0.1~a3%2Bdfsg-6
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 436 kB
  • sloc: python: 1,883; makefile: 74
file content (457 lines) | stat: -rwxr-xr-x 11,902 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
.. _grapefruit-index:

Welcome! This is the documentation for GrapeFruit |release|, 
last updated |today|.

See the :ref:`genindex` for a list of the topics.


.. module:: grapefruit
.. moduleauthor:: Xavier Basty <xbasty@gmail.com>

==========================
The Color class
==========================

.. class:: Color

The grapefruit module contains only the :class:`Color` class, which exposes all
the functionalities. It can be used to store a color value and manipulate it,
or convert it to another color system.

If you are only interested in converting you colors from one system to another,
you can store them using regular tuples instead of :class:`Color` instances.
You can then use the class static methods to perform the conversions.

:class:`Color` stores both the RGB and HSL representation of the color.
This makes possible to keep the hue intact when the color is a pure white
due to its lightness.
However, certain operations work only with the RGB values, and might then
lose the hue.

All the operations assume that you provide values in the specified ranges,
no checks are made whatsoever. If you provide a value outside of the
specified ranges, you'll get some strange results...

The class instances are immutable, all the methods return a new instance
of the :class:`Color` class, and all the properties are read-only.

.. note::

   Some operations may provide results a bit outside the specified ranges,
   the results are not capped.
   This is due to certain color systems having a wider gamut than others.


Class content
---------------

- :ref:`class-constants`

  - :const:`Color.WHITE_REFERENCE`
  - :const:`Color.NAMED_COLOR`

- :ref:`conversion-functions`

  - :meth:`Color.RgbToHsl`
  - :meth:`Color.HslToRgb`
  - :meth:`Color.RgbToHsv`
  - :meth:`Color.HsvToRgb`
  - :meth:`Color.RgbToYiq`
  - :meth:`Color.YiqToRgb`
  - :meth:`Color.RgbToYuv`
  - :meth:`Color.YuvToRgb`
  - :meth:`Color.RgbToXyz`
  - :meth:`Color.XyzToRgb`
  - :meth:`Color.XyzToLab`
  - :meth:`Color.LabToXyz`
  - :meth:`Color.CmykToCmy`
  - :meth:`Color.CmyToCmyk`
  - :meth:`Color.RgbToCmy`
  - :meth:`Color.CmyToRgb`
  - :meth:`Color.RgbToHtml`
  - :meth:`Color.HtmlToRgb`
  - :meth:`Color.RgbToPil`
  - :meth:`Color.PilToRgb`
  - :meth:`Color.RgbToWebSafe`
  - :meth:`Color.RgbToGreyscale`
  - :meth:`Color.RgbToRyb`
  - :meth:`Color.RybToRgb`

- :ref:`instantiation-functions`

  - :meth:`Color.NewFromRgb`
  - :meth:`Color.NewFromHsl`
  - :meth:`Color.NewFromHsv`
  - :meth:`Color.NewFromYiq`
  - :meth:`Color.NewFromYuv`
  - :meth:`Color.NewFromXyz`
  - :meth:`Color.NewFromLab`
  - :meth:`Color.NewFromCmy`
  - :meth:`Color.NewFromCmyk`
  - :meth:`Color.NewFromHtml`
  - :meth:`Color.NewFromPil`

- :ref:`properties`

  - :attr:`Color.alpha`
  - :attr:`Color.whiteRef`
  - :attr:`Color.rgb`
  - :attr:`Color.hue`
  - :attr:`Color.hsl`
  - :attr:`Color.hsv`
  - :attr:`Color.yiq`
  - :attr:`Color.yuv`
  - :attr:`Color.xyz`
  - :attr:`Color.lab`
  - :attr:`Color.cmy`
  - :attr:`Color.cmyk`
  - :attr:`Color.html`
  - :attr:`Color.pil`
  - :attr:`Color.webSafe`
  - :attr:`Color.greyscale`

- :ref:`manipulation-methods`

  - :meth:`Color.ColorWithAlpha`
  - :meth:`Color.ColorWithWhiteRef`
  - :meth:`Color.ColorWithHue`
  - :meth:`Color.ColorWithSaturation`
  - :meth:`Color.ColorWithLightness`
  - :meth:`Color.DarkerColor`
  - :meth:`Color.LighterColor`
  - :meth:`Color.Saturate`
  - :meth:`Color.Desaturate`
  - :meth:`Color.WebSafeDither`

- :ref:`generation-methods`

  - :meth:`Color.Gradient`
  - :meth:`Color.ComplementaryColor`
  - :meth:`Color.TriadicScheme`
  - :meth:`Color.TetradicScheme`
  - :meth:`Color.AnalogousScheme`

- :ref:`blending-methods`

  - :meth:`Color.AlphaBlend`
  - :meth:`Color.Blend`


Example usage
---------------

  To create an instance of the grapefruit.Color from RGB values:
  
    >>> import grapefruit
    >>> r, g, b = 1, 0.5, 0
    >>> col = grapefruit.Color.NewFromRgb(r, g, b)
  
  To get the values of the color in another colorspace:
  
    >>> h, s, v = col.hsv
    >>> l, a, b = col.lab
  
  To get the complementary of a color:
  
    >>> compl = col.ComplementaryColor()
    >>> print compl.hsl
    (210.0, 1.0, 0.5)
  
  To directly convert RGB values to their HSL equivalent:
  
    >>> h, s, l = Color.RgbToHsl(r, g, b)



.. _class-constants:

Class Constants
-----------------

.. data:: Color.WHITE_REFERENCE

The reference white points of the CIE standards illuminants, calculated from
the chromaticity coordinates found at:
http://en.wikipedia.org/wiki/Standard_illuminant

A dictionary mapping the name of the CIE standard illuminants to their reference
white points. The white points are required for the XYZ <-> L*a*b conversions.

The key names are build using the following pattern: ``<observer>_<illuminant>``

The possible values for ``<observer>`` are:

  ======  ===================================
  Value   Observer
  ======  ===================================
  std     CIE 1931 2° Standard Observer
  sup     CIE 1964 10° Supplementary Observer
  ======  ===================================

The possible values for ``<illuminant>`` are the name of the standard illuminants:

  ======  ========  ==================================================
  Value   CCT       Illuminant
  ======  ========  ==================================================
  A       2856 K    Incandescent tungsten
  B       4874 K    Direct sunlight at noon (obsolete)
  C       6774 K    North sky daylight (obsolete)
  D50     5003 K    ICC Profile PCS. Horizon light.
  D55     5503 K    Compromise between incandescent and daylight
  D65     6504 K    Noon daylight (TV & sRGB colorspace)
  D75     7504 K    North sky day light
  E       ~5455 K   Equal energy radiator (not a black body)
  F1      6430 K    Daylight Fluorescent
  F2      4230 K    Cool White Fluorescent
  F3      3450 K    White Fluorescent
  F4      2940 K    Warm White Fluorescent
  F5      6350 K    Daylight Fluorescent
  F6      4150 K    Lite White Fluorescent
  F7      6500 K    Broadband fluorescent, D65 simulator
  F8      5000 K    Broadband fluorescent, D50 simulator
  F9      4150 K    Broadband fluorescent, Cool White Deluxe
  F10     5000 K    Narrowband fluorescent, Philips TL85, Ultralume 50
  F11     4000 K    Narrowband fluorescent, Philips TL84, Ultralume 40
  F12     3000 K    Narrowband fluorescent, Philips TL83, Ultralume 30
  ======  ========  ==================================================

.. data:: Color.NAMED_COLOR

The names and RGB values of the X11 colors supported by popular browsers, with
the gray/grey spelling issues, fixed so that both work (e.g light*grey* and
light*gray*).

Note: For *Gray*, *Green*, *Maroon* and *Purple*, the HTML/CSS values are used
instead of the X11 ones
(see `X11/CSS clashes <http://en.wikipedia.org/wiki/X11_color_names#Color_names_that_clash_between_X11_and_HTML.2FCSS>`_)

Reference: `CSS3 Color module <http://www.w3.org/TR/css3-iccprof#x11-color>`_


.. _conversion-functions:

Conversion functions
--------------------

The conversion functions are static methods of the :class:`Color` class that
let you convert a color stored as the list of its components rather than
as a :class:`Color` instance.

.. automethod:: Color.RgbToHsl

.. automethod:: Color.HslToRgb

.. automethod:: Color.RgbToHsv

.. automethod:: Color.HsvToRgb

.. automethod:: Color.RgbToYiq

.. automethod:: Color.YiqToRgb

.. automethod:: Color.RgbToYuv

.. automethod:: Color.YuvToRgb

.. automethod:: Color.RgbToXyz

.. automethod:: Color.XyzToRgb

.. automethod:: Color.XyzToLab

.. automethod:: Color.LabToXyz

.. automethod:: Color.CmykToCmy

.. automethod:: Color.CmyToCmyk

.. automethod:: Color.RgbToCmy

.. automethod:: Color.CmyToRgb

.. automethod:: Color.RgbToHtml

.. automethod:: Color.HtmlToRgb

.. automethod:: Color.RgbToPil

.. automethod:: Color.PilToRgb

.. automethod:: Color.RgbToWebSafe

.. automethod:: Color.RgbToGreyscale

.. automethod:: Color.RgbToRyb

.. automethod:: Color.RybToRgb



.. _instantiation-functions:

Instantiation functions
-----------------------

The instantiation functions let you create a new instance of the :class:`Color`
class from the color components using the color system of your choice.

.. automethod:: Color.NewFromRgb

.. automethod:: Color.NewFromHsl

.. automethod:: Color.NewFromHsv

.. automethod:: Color.NewFromYiq

.. automethod:: Color.NewFromYuv

.. automethod:: Color.NewFromXyz

.. automethod:: Color.NewFromLab

.. automethod:: Color.NewFromCmy

.. automethod:: Color.NewFromCmyk

.. automethod:: Color.NewFromHtml

.. automethod:: Color.NewFromPil



.. _properties:

Properties
----------

The properties get the value of the instance in the specified color model.

The properties returning calculated values unless marked otherwise.

.. note::

   All the properties are read-only. You need to make a copy of the instance
   to modify the color value.

.. autoattribute:: Color.alpha

  *This value is not calculated,  the stored value is returned directly.*

.. autoattribute:: Color.whiteRef

  *This value is not calculated,  the stored value is returned directly.*

.. autoattribute:: Color.rgb

  *This value is not calculated,  the stored value is returned directly.*

.. autoattribute:: Color.hue

  *This value is not calculated,  the stored value is returned directly.*

.. autoattribute:: Color.hsl

  *This value is not calculated,  the stored value is returned directly.*

.. autoattribute:: Color.hsv

.. autoattribute:: Color.yiq

.. autoattribute:: Color.yuv

.. autoattribute:: Color.xyz

.. autoattribute:: Color.lab

.. autoattribute:: Color.cmy

.. autoattribute:: Color.cmyk

.. autoattribute:: Color.html

.. autoattribute:: Color.pil

.. autoattribute:: Color.webSafe

.. attribute:: Color.greyscale



.. _manipulation-methods:

Manipulation methods
--------------------

The manipulations methods let you create a new color by changing an existing
color properties.

.. note::

   The methods **do not** modify the current Color instance. They create a
   new instance or a tuple of new instances with the specified modifications.

.. automethod:: Color.ColorWithAlpha

.. automethod:: Color.ColorWithWhiteRef

.. automethod:: Color.ColorWithHue

.. automethod:: Color.ColorWithSaturation

.. automethod:: Color.ColorWithLightness

.. automethod:: Color.DarkerColor

.. automethod:: Color.LighterColor

.. automethod:: Color.Saturate

.. automethod:: Color.Desaturate

.. automethod:: Color.WebSafeDither



.. _generation-methods:

Generation methods
------------------

The generation methods let you create a color scheme by using a color as the
start point.

All the method, apart from Gradient and MonochromeScheme, have a 'mode'
parameter that let you choose which color wheel should be used to generate
the scheme.

The following modes are available:
  :ryb:
    The `RYB <http://en.wikipedia.org/wiki/RYB_color_model>`_ color wheel,
    or *artistic color wheel*. While scientifically incorrect, it generally
    produces better schemes than RGB.
  :rgb:
    The standard RGB color wheel.

.. automethod:: Color.Gradient

.. automethod:: Color.ComplementaryColor

.. automethod:: Color.MonochromeScheme

.. automethod:: Color.TriadicScheme

.. automethod:: Color.TetradicScheme

.. automethod:: Color.AnalogousScheme



.. _blending-methods:

Blending methods
----------------

.. automethod:: Color.AlphaBlend

.. automethod:: Color.Blend