ImageColor Module
#################

:doc: https://pillow.readthedocs.io/en/latest/reference/ImageColor.html,
      http://effbot.org/imagingbook/imagecolor.htm

Normally, you don't have to use this module explicitly. For example, these are identical:

.. list-table::

    * - ::

            from PIL import Image
            img = Image.new("RGB", (32, 32), "lightgrey")

      - ::

            from PIL import Image, ImageColor
            img = Image.new("RGB", (32, 32), ImageColor.getrgb("lightgrey"))

    * - ::

            from PIL import Image
            img = Image.new("RGB", (32, 32), "#add8e6")

      - ::

            from PIL import Image, ImageColor
            img = Image.new("RGB", (32, 32), ImageColor.getrgb("#add8e6"))

    * - ::

            from PIL import Image, ImageColor
            img = Image.new("RGB", (32, 32), "rgb(173, 216, 230)")

      - ::

            from PIL import Image, ImageColor
            img = Image.new("RGB", (32, 32), ImageColor.getrgb("rgb(173, 216, 230)"))

Of course if you have a rgb tuple itself (or an integer for grayscale), you can use it and it doesn't spend any extra cost:

::

    from PIL import Image
    img = Image.new("RGB", (32, 32), (173, 216, 230))

::

    from PIL import Image
    img = Image.new("L", (32, 32), 255)

but you can not always so, for example when the color value comes from external or
you have any reason to use HSL(, etc). Wherever the color value is needed, you can
use the string formats supported by ImageColor module:

* Hexadecimal color specifiers, given as :code:`#rgb` or :code:`#rrggbb`. ::

    from PIL import Image, ImageDraw
    img = Image.new("RGB", (32, 32))
    dctx = ImageDraw.Draw(img)
    dctx.rectangle((8, 8, 16, 16), fill="#ddddff")

* RGB functions, given as :code:`rgb(red, green, blue)` where the color values
  are integers in the range 0 to 255. ::

    from PIL import Image, ImageDraw
    img = Image.new("RGB", (32, 32))
    dctx = ImageDraw.Draw(img)
    dctx.ellipse((8, 8, 16, 16), fill="rgb(255, 128, 255)")

  Alternatively, the color values can be given as three percentages (0% to 100%). ::

    from PIL import Image, ImageDraw
    img = Image.new("RGB", (32, 32))
    dctx = ImageDraw.Draw(img)
    dctx.ellipse((8, 8, 16, 16), outline="rgb(10%, 100%, 50%)")

* Hue-Saturation-Lightness (HSL) functions, given as :code:`hsl(hue, saturation%, lightness%)`
  where hue is the color given as an angle between 0 and 360 (red=0, green=120, blue=240),
  saturation is a value between 0% and 100% (gray=0%, full color=100%), and lightness is
  a value between 0% and 100% (black=0%, normal=50%, white=100%). ::

    from PIL import Image, ImageDraw
    img = Image.new("RGB", (32, 32))
    dctx = ImageDraw.Draw(img)
    dctx.ellipse((8, 8, 16, 16), fill="hsl(0, 100%, 50%)")  # pure red

* Common HTML color names. ::

    from PIL import Image
    img = Image.new("RGB", (32, 32), "skyblue")

ImageColor module has no support for `YIQ <https://en.wikipedia.org/wiki/YIQ>`_ and `HSV <https://en.wikipedia.org/wiki/HSV_color_space>`_,
but note that you can use `colorsys <https://docs.python.org/3/library/colorsys.html>`_ module of standard library: ::

    import colorsys
    from PIL import Image
    clr = tuple(map(lambda c: int(c * 255), colorsys.yiq_to_rgb(0.65, 0.3, 0.1)))
    img = Image.new("RGB", (32, 32), clr)

getrgb, getcolor, colormap
**************************

.. code-block:: pycon

    >>> from PIL import ImageColor
    >>> 
    >>> ImageColor.getrgb("orange")
    (255, 165, 0)
    >>> ImageColor.getcolor("orange", "RGB")
    (255, 165, 0)
    >>> ImageColor.getcolor("orange", "RGBA")
    (255, 165, 0, 255)
    >>> ImageColor.getcolor("orange", "L")
    173
    >>> len(ImageColor.colormap)
    148
    >>> list(sorted(ImageColor.colormap.items()))[:2]
    [('aliceblue', '#f0f8ff'), ('antiquewhite', '#faebd7')]

.. list-table::
  :widths: 20 10

  * - .. literalinclude:: _static/exams/ImageColor_01.py
    - |
      | `result <_static/exams/result/ImageColor_01.html>`_