diff --git a/PIL/ImageColor.py b/PIL/ImageColor.py index 86f221adc..c14257151 100644 --- a/PIL/ImageColor.py +++ b/PIL/ImageColor.py @@ -30,6 +30,15 @@ import re # as an RGB value. def getrgb(color): + """ + Convert a color string to an RGB tuple. If the string cannot be parsed, + this function raises a :py:exc:`ValueError` exception. + + .. versionadded:: 1.1.4 + + :param color: A color string + :return: ``(red, green, blue)`` + """ try: rgb = colormap[color] except KeyError: @@ -97,6 +106,16 @@ def getrgb(color): raise ValueError("unknown color specifier: %r" % color) def getcolor(color, mode): + """ + Same as :py:func:`~PIL.ImageColor.getrgb`, but converts the RGB value to a + greyscale value if the mode is not color or a palette image. If the string + cannot be parsed, this function raises a :py:exc:`ValueError` exception. + + .. versionadded:: 1.1.4 + + :param color: A color string + :return: ``(red, green, blue)`` + """ # same as getrgb, but converts the result to the given mode color = getrgb(color) if mode == "RGB": diff --git a/docs/PIL.rst b/docs/PIL.rst index c191d42a3..517439caa 100644 --- a/docs/PIL.rst +++ b/docs/PIL.rst @@ -65,14 +65,6 @@ PIL Package :undoc-members: :show-inheritance: -:mod:`ImageColor` Module ------------------------- - -.. automodule:: PIL.ImageColor - :members: - :undoc-members: - :show-inheritance: - :mod:`ImageDraw` Module ----------------------- diff --git a/docs/reference/ImageColor.rst b/docs/reference/ImageColor.rst new file mode 100644 index 000000000..2d6dd0355 --- /dev/null +++ b/docs/reference/ImageColor.rst @@ -0,0 +1,41 @@ +.. py:module:: PIL.ImageColor +.. py:currentmodule:: PIL.ImageColor + +:mod:`ImageColor` Module +======================== + +The :py:mod:`ImageColor` module contains color tables and converters from +CSS3-style color specifiers to RGB tuples. This module is used by +:py:meth:`PIL.Image.Image.new` and the :py:mod:`~PIL.ImageDraw` module, among +others. + +Color Names +----------- + +The ImageColor module supports the following string formats: + +* Hexadecimal color specifiers, given as ``#rgb`` or ``#rrggbb``. For example, + ``#ff0000`` specifies pure red. + +* RGB functions, given as ``rgb(red, green, blue)`` where the color values are + integers in the range 0 to 255. Alternatively, the color values can be given + as three percentages (0% to 100%). For example, ``rgb(255,0,0)`` and + ``rgb(100%,0%,0%)`` both specify pure red. + +* Hue-Saturation-Lightness (HSL) functions, given as ``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%). For example, ``hsl(0,100%,50%)`` is pure + red. + +* Common HTML color names. The :py:mod:`~PIL.ImageColor` module provides some + 140 standard color names, based on the colors supported by the X Window + system and most web browsers. color names are case insensitive. For example, + ``red`` and ``Red`` both specify pure red. + +Functions +--------- + +.. autofunction:: getrgb +.. autofunction:: getcolor diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 6b8b45c9f..8604a8787 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -6,4 +6,5 @@ Reference Image ImageChops + ImageColor ../PIL