==========
colorutils
==========
.. image:: https://pypip.in/license/colorutils/badge.svg
:target: https://pypi.python.org/pypi/colorutils/
:alt: License
.. image:: https://pypip.in/version/colorutils/badge.svg
:target: https://pypi.python.org/pypi/colorutils/
:alt: Latest Version
.. image:: https://pypip.in/download/colorutils/badge.svg
:target: https://pypi.python.org/pypi//colorutils/
:alt: Downloads
A library which provides utilities for working with colors in Python. Colors are modeled by the ``Color`` class and can be
represented in ``RGB``, ``HEX``, ``WEB``, and ``YIQ`` formats.
0. Installation
===============
``colorutils`` can be installed from pypi::
pip install colorutils
to update an existing installation from pypi to the latest version::
pip install colorutils --upgrade
1. Current Features
===================
**v0.2.1** (released 05/25/2015)
- Bug fix for pip install on Windows for unfound packages
**v0.2** (released 05/23/2015)
- Add HSV color representation and conversions
- Add YIQ color representation and conversions
- Color objects can be treated as iterables
- Implementation of color runs
- Addition of pre-defined color palettes
- Package restructuring
**v0.1** (released 05/16/2015)
- A versatile abstract color model which allows color addition and subtraction
- Conversions between: ``RGB`` tuples, 6-character ``HEX`` strings, 3-character ``HEX`` strings, and ``WEB`` representations of color.
- Random color generation
2. Reporting Bugs / Requesting Features
=======================================
To report a bug or request a feature for colorutils, please open a new issue_
.. _issue: https://github.com/edaniszewski/colorutils/issues
3. Usage
========
3.1 Instantiating a ``Color``
-----------------------------
The basic way to instantiate a ``Color``::
>>> from colorutils import Color
>>> c = Color((255, 255, 255))
>>> c
<Color (255, 255, 255)>
By default, the Color object expects an ``RGB`` 3-tuple, but there are multiple ways to instantiate a ``Color``. The possibilities for Cyan, for example::
Color((0, 255, 255))
Color(green=255, blue=255)
Color(rgb=(0, 255, 255))
Color(hex='#00FFFF')
Color(hex='00ffff')
Color(hex='#0ff')
Color(hex='0ff')
Color(web='cyan')
Color(web='Cyan')
Color(web='CYAN')
Color(web='#00ffff')
Color(web='#0ff')
Color(yiq=(0.701, -0.596, -0.217))
Color(hsv=(180, 1, 1))
``Color`` objects can also take the color from other ``Color`` objects::
>>> Color(Color((255, 255, 255)))
<Color (255, 255, 255)>
>>> Color(Color(Color(Color((255, 255, 255)))))
<Color (255, 255, 255)>
3.2 Color Conversion
--------------------
The current color models supported by ``colorutils`` are: ``RGB``, ``HEX``, ``WEB``, ``YIQ``, and ``HSV``. Each instantiated ``Color`` object has properties which will automatically perform the required conversions::
>>> c = Color((46, 139, 87))
>>> c.red
46
>>> c.green
139
>>> c.blue
87
>>> c.rgb
(46, 139, 87)
>>> c.hex
'#2e8b57'
>>> c.shorthex
'#2e8b57'
>>> c.web
'SeaGreen'
>>> c.yiq
(0.413, -0.152, -0.143)
>>> c.hsv
(146.452, 0.669, 0.545)
If the color were such that the ``HEX`` representation could be captured as a 3-char hex::
>>> c = Color((0, 0, 0))
>>> c.hex
'#000000'
>>> c.shorthex
'#000'
The web representation will return the hex value if the color is not a well-known named web color::
>>> c = Color((1, 243, 77))
>>> c.hex
'#01f34d'
>>> c.web
'#01f34d'
These same conversions can be done without instantiating a ``Color`` object by using the static methods:
* ``rgb_to_hex()``
* ``rgb_to_web()``
* ``rgb_to_yiq()``
* ``rgb_to_hsv()``
* ``hex_to_rgb()``
* ``hex_to_web()``
* ``hex_to_yiq()``
* ``hex_to_hsv()``
* ``web_to_rbg()``
* ``web_to_hex()``
* ``web_to_yiq()``
* ``web_to_hsv()``
* ``yiq_to_rgb()``
* ``yiq_to_hex()``
* ``yiq_to_web()``
* ``yiq_to_hsv()``
* ``hsv_to_rgb()``
* ``hsv_to_hex()``
* ``hsv_to_web()``
* ``hsv_to_yiq()``
Using these static conversion methods, one can chain conversions (due to the in-param and out-param of all multi-value color representations being a tuple), which you are unable to do using the Python default `colorsys`.::
>>> rgb_to_hex(hex_to_rgb('#808080'))
'#808080'
Of course, be wary of chaining. Since approximation exists in the conversion algorithms, degradation will occur::
>>> yiq_to_web(rgb_to_yiq(hex_to_rgb('808080')))
'#7f807e'
Though, the values will still be close::
>>> hex(int('80', 16) - int('7f', 16)) # Red difference
'0x1'
>>> hex(int('80', 16) - int('80', 16)) # Green difference
'0x0'
>>> hex(int('80', 16) - int('7e', 16)) # Blue difference
'0x2'
3.3 ``Color`` Arithmetic
------------------------
Although the addition and subtraction of color does not always make sense, the ability to do so is supported. There are two additive models currently supported: ``LIGHT`` and ``BLEND``.
3.3.1 Addition
~~~~~~~~~~~~~~
``LIGHT``
the light model is an additive model, where the rgb components are added, but do not exceed the maximum value, 255. This model is the default model which every ``Color`` is initialized with, unless overridden.
An example of ``LIGHT`` addition::
>>> Color((0, 100, 200)) + Color((100, 100, 100))
<Color (100, 200, 255)>
``BLEND``
the blend model is an averaging model, where each rgb component is averaged.
An example of ``BLEND`` addition::
>>> Color((0, 100, 200), arithmetic=ArithmeticModel.BLEND) + Color((100, 100, 100))
<Color (50, 150, 250)>
When assigning models, it is important to note that the arithmetic model for the first object in the operation, e.g. Object1 in 'Object1 + Object2', is the model which will be used when computing the addition.
``Color`` addition can also operate on 3-tuples, which represent an ``RGB`` value::
>>> Color((50, 50, 50)) + (20, 20, 20)
<Color (70, 70, 70)>
3.3.2 Subtraction
~~~~~~~~~~~~~~~~~
There is currently only one subtractive model, the equivalent to the inverse of the ``LIGHT`` additive model. There is no model representing the inverse of ``BLEND``, since the inverse average does not really make sense.::
>>> Color((100, 100, 100)) - Color((0, 75, 200))
<Color (100, 25, 0)>
``Color`` subtraction can also operate on 3-tuples, which represent an ``RGB`` value::
>>> Color((50, 50, 50)) - (20, 20, 20)
<Color (30, 30, 30)>
3.4 Color Equality
------------------
Testing for equality between colors defaults to testing between the equality of the ``RGB`` values::
>>> c1 = Color((10, 20, 30))
>>> c2 = Color((10, 20, 30))
>>> c3 = Color((10, 20, 20))
>>> c1 == c2
True
>>> c1 == c3
False
Different equality functions can be set, using either the predefined equalities in ``colorutils.equality``, or from a custom equality function::
>>> from colorutils.equality import *
>>> c = Color((10, 20, 30), equality_fn=RED_eq)
>>> c2 = Color((10, 40, 60))
>>> c == c2
True
>>> c2 == c
False
Notice that in the above example, when checking for red equality, when the color with the ``RED_eq`` equality comes first in the comparison, it
evaluates to ``True``. If it comes second, it evaluates to ``False``. This is because the equality function of the first ``Color`` instance in
the comparison defines which equality function is used.
The predefined equalities are:
* ``RGB_eq``
* ``RED_eq``
* ``GREEN_eq``
* ``BLUE_eq``
* ``HEX_eq``
* ``WEB_eq``
* ``YIQ_eq``
* ``HSV_eq``
Defining a custom equality would follow the pattern defined by the RGB_eq definition, below::
RGB_eq = lambda c1, c2: c1.rgb == c2.rgb
3.5 Color Palettes
------------------
A collection of pre-defined color palettes exists for convenience. The palettes which are currently implemented include:
* grayscale
* primary
* rgb
* roygbv
* secondary
Individual named colors can be used from the palettes, or all colors can be retrieved::
>>> import colorutils.palettes.primary as primary
>>> primary.red
<Color (255, 0, 0)>
>>> primary.yellow
<Color (255, 255, 0)>
>>> primary.blue
<Color (0, 0, 255)>
>>> primary.all
[<Color (255, 0, 0)>, <Color (255, 255, 0)>, <Color (0, 0, 255)>]
4. ``colorutils`` vs others
===========================
To see how the ``colorutils`` conversion algorithms compare to other algorithms/provided values, see the comparisons_ wiki page.
.. _comparisons: https://github.com/edaniszewski/colorutils/wiki/Comparing-Conversion-Algorithms
Raw data
{
"_id": null,
"home_page": "https://github.com/edaniszewski/colorutils",
"name": "colorutils",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "color,color manipulation,color conversion,color tools",
"author": "Erick Daniszewski",
"author_email": "edaniszewski@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/90/bb/bec37d30ca26b5f3716b42bc81c187bc0ec9e8a87a8a23b5b2d54590db30/colorutils-0.3.0.tar.gz",
"platform": "",
"description": "==========\ncolorutils\n==========\n\n.. image:: https://pypip.in/license/colorutils/badge.svg\n :target: https://pypi.python.org/pypi/colorutils/\n :alt: License\n\n.. image:: https://pypip.in/version/colorutils/badge.svg\n :target: https://pypi.python.org/pypi/colorutils/\n :alt: Latest Version\n\n.. image:: https://pypip.in/download/colorutils/badge.svg\n :target: https://pypi.python.org/pypi//colorutils/\n :alt: Downloads\n\nA library which provides utilities for working with colors in Python. Colors are modeled by the ``Color`` class and can be\nrepresented in ``RGB``, ``HEX``, ``WEB``, and ``YIQ`` formats.\n\n0. Installation\n===============\n\n``colorutils`` can be installed from pypi::\n\n pip install colorutils\n\nto update an existing installation from pypi to the latest version::\n\n pip install colorutils --upgrade\n\n\n1. Current Features\n===================\n\n**v0.2.1** (released 05/25/2015)\n\n- Bug fix for pip install on Windows for unfound packages\n\n**v0.2** (released 05/23/2015)\n\n- Add HSV color representation and conversions\n- Add YIQ color representation and conversions\n- Color objects can be treated as iterables\n- Implementation of color runs\n- Addition of pre-defined color palettes\n- Package restructuring\n\n**v0.1** (released 05/16/2015)\n\n- A versatile abstract color model which allows color addition and subtraction\n- Conversions between: ``RGB`` tuples, 6-character ``HEX`` strings, 3-character ``HEX`` strings, and ``WEB`` representations of color.\n- Random color generation\n\n\n2. Reporting Bugs / Requesting Features\n=======================================\n\nTo report a bug or request a feature for colorutils, please open a new issue_\n\n .. _issue: https://github.com/edaniszewski/colorutils/issues\n\n\n3. Usage\n========\n\n3.1 Instantiating a ``Color``\n-----------------------------\n\nThe basic way to instantiate a ``Color``::\n\n >>> from colorutils import Color\n >>> c = Color((255, 255, 255))\n >>> c\n <Color (255, 255, 255)>\n\nBy default, the Color object expects an ``RGB`` 3-tuple, but there are multiple ways to instantiate a ``Color``. The possibilities for Cyan, for example::\n\n Color((0, 255, 255))\n Color(green=255, blue=255)\n Color(rgb=(0, 255, 255))\n Color(hex='#00FFFF')\n Color(hex='00ffff')\n Color(hex='#0ff')\n Color(hex='0ff')\n Color(web='cyan')\n Color(web='Cyan')\n Color(web='CYAN')\n Color(web='#00ffff')\n Color(web='#0ff')\n Color(yiq=(0.701, -0.596, -0.217))\n Color(hsv=(180, 1, 1))\n\n``Color`` objects can also take the color from other ``Color`` objects::\n\n >>> Color(Color((255, 255, 255)))\n <Color (255, 255, 255)>\n\n >>> Color(Color(Color(Color((255, 255, 255)))))\n <Color (255, 255, 255)>\n\n3.2 Color Conversion\n--------------------\nThe current color models supported by ``colorutils`` are: ``RGB``, ``HEX``, ``WEB``, ``YIQ``, and ``HSV``. Each instantiated ``Color`` object has properties which will automatically perform the required conversions::\n\n >>> c = Color((46, 139, 87))\n\n >>> c.red\n 46\n\n >>> c.green\n 139\n\n >>> c.blue\n 87\n\n >>> c.rgb\n (46, 139, 87)\n\n >>> c.hex\n '#2e8b57'\n\n >>> c.shorthex\n '#2e8b57'\n\n >>> c.web\n 'SeaGreen'\n\n >>> c.yiq\n (0.413, -0.152, -0.143)\n\n >>> c.hsv\n (146.452, 0.669, 0.545)\n\nIf the color were such that the ``HEX`` representation could be captured as a 3-char hex::\n\n >>> c = Color((0, 0, 0))\n\n >>> c.hex\n '#000000'\n\n >>> c.shorthex\n '#000'\n\nThe web representation will return the hex value if the color is not a well-known named web color::\n\n >>> c = Color((1, 243, 77))\n\n >>> c.hex\n '#01f34d'\n\n >>> c.web\n '#01f34d'\n\nThese same conversions can be done without instantiating a ``Color`` object by using the static methods:\n\n* ``rgb_to_hex()``\n* ``rgb_to_web()``\n* ``rgb_to_yiq()``\n* ``rgb_to_hsv()``\n* ``hex_to_rgb()``\n* ``hex_to_web()``\n* ``hex_to_yiq()``\n* ``hex_to_hsv()``\n* ``web_to_rbg()``\n* ``web_to_hex()``\n* ``web_to_yiq()``\n* ``web_to_hsv()``\n* ``yiq_to_rgb()``\n* ``yiq_to_hex()``\n* ``yiq_to_web()``\n* ``yiq_to_hsv()``\n* ``hsv_to_rgb()``\n* ``hsv_to_hex()``\n* ``hsv_to_web()``\n* ``hsv_to_yiq()``\n\nUsing these static conversion methods, one can chain conversions (due to the in-param and out-param of all multi-value color representations being a tuple), which you are unable to do using the Python default `colorsys`.::\n\n >>> rgb_to_hex(hex_to_rgb('#808080'))\n '#808080'\n\nOf course, be wary of chaining. Since approximation exists in the conversion algorithms, degradation will occur::\n\n >>> yiq_to_web(rgb_to_yiq(hex_to_rgb('808080')))\n '#7f807e'\n\nThough, the values will still be close::\n\n >>> hex(int('80', 16) - int('7f', 16)) # Red difference\n '0x1'\n\n >>> hex(int('80', 16) - int('80', 16)) # Green difference\n '0x0'\n\n >>> hex(int('80', 16) - int('7e', 16)) # Blue difference\n '0x2'\n\n3.3 ``Color`` Arithmetic\n------------------------\n\nAlthough the addition and subtraction of color does not always make sense, the ability to do so is supported. There are two additive models currently supported: ``LIGHT`` and ``BLEND``.\n\n3.3.1 Addition\n~~~~~~~~~~~~~~\n\n``LIGHT``\n the light model is an additive model, where the rgb components are added, but do not exceed the maximum value, 255. This model is the default model which every ``Color`` is initialized with, unless overridden.\n\nAn example of ``LIGHT`` addition::\n\n >>> Color((0, 100, 200)) + Color((100, 100, 100))\n <Color (100, 200, 255)>\n\n``BLEND``\n the blend model is an averaging model, where each rgb component is averaged.\n\nAn example of ``BLEND`` addition::\n\n >>> Color((0, 100, 200), arithmetic=ArithmeticModel.BLEND) + Color((100, 100, 100))\n <Color (50, 150, 250)>\n\nWhen assigning models, it is important to note that the arithmetic model for the first object in the operation, e.g. Object1 in 'Object1 + Object2', is the model which will be used when computing the addition.\n\n``Color`` addition can also operate on 3-tuples, which represent an ``RGB`` value::\n\n >>> Color((50, 50, 50)) + (20, 20, 20)\n <Color (70, 70, 70)>\n\n3.3.2 Subtraction\n~~~~~~~~~~~~~~~~~\n\nThere is currently only one subtractive model, the equivalent to the inverse of the ``LIGHT`` additive model. There is no model representing the inverse of ``BLEND``, since the inverse average does not really make sense.::\n\n >>> Color((100, 100, 100)) - Color((0, 75, 200))\n <Color (100, 25, 0)>\n\n\n``Color`` subtraction can also operate on 3-tuples, which represent an ``RGB`` value::\n\n >>> Color((50, 50, 50)) - (20, 20, 20)\n <Color (30, 30, 30)>\n\n\n3.4 Color Equality\n------------------\n\nTesting for equality between colors defaults to testing between the equality of the ``RGB`` values::\n\n >>> c1 = Color((10, 20, 30))\n >>> c2 = Color((10, 20, 30))\n >>> c3 = Color((10, 20, 20))\n\n >>> c1 == c2\n True\n\n >>> c1 == c3\n False\n\nDifferent equality functions can be set, using either the predefined equalities in ``colorutils.equality``, or from a custom equality function::\n\n >>> from colorutils.equality import *\n >>> c = Color((10, 20, 30), equality_fn=RED_eq)\n >>> c2 = Color((10, 40, 60))\n\n >>> c == c2\n True\n\n >>> c2 == c\n False\n\nNotice that in the above example, when checking for red equality, when the color with the ``RED_eq`` equality comes first in the comparison, it\nevaluates to ``True``. If it comes second, it evaluates to ``False``. This is because the equality function of the first ``Color`` instance in\nthe comparison defines which equality function is used.\n\nThe predefined equalities are:\n\n* ``RGB_eq``\n* ``RED_eq``\n* ``GREEN_eq``\n* ``BLUE_eq``\n* ``HEX_eq``\n* ``WEB_eq``\n* ``YIQ_eq``\n* ``HSV_eq``\n\nDefining a custom equality would follow the pattern defined by the RGB_eq definition, below::\n\n RGB_eq = lambda c1, c2: c1.rgb == c2.rgb\n\n\n3.5 Color Palettes\n------------------\n\nA collection of pre-defined color palettes exists for convenience. The palettes which are currently implemented include:\n\n* grayscale\n* primary\n* rgb\n* roygbv\n* secondary\n\nIndividual named colors can be used from the palettes, or all colors can be retrieved::\n\n >>> import colorutils.palettes.primary as primary\n\n >>> primary.red\n <Color (255, 0, 0)>\n\n >>> primary.yellow\n <Color (255, 255, 0)>\n\n >>> primary.blue\n <Color (0, 0, 255)>\n\n >>> primary.all\n [<Color (255, 0, 0)>, <Color (255, 255, 0)>, <Color (0, 0, 255)>]\n\n\n4. ``colorutils`` vs others\n===========================\n\nTo see how the ``colorutils`` conversion algorithms compare to other algorithms/provided values, see the comparisons_ wiki page.\n\n .. _comparisons: https://github.com/edaniszewski/colorutils/wiki/Comparing-Conversion-Algorithms\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A utility for working with colors in Python.",
"version": "0.3.0",
"split_keywords": [
"color",
"color manipulation",
"color conversion",
"color tools"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "81ad7df7203f6bfdeef3a709925da8d3",
"sha256": "767ae0fbde51355bdaa1d09f8de30c3a2c2474a3120778eae9bc8a25ee727f55"
},
"downloads": -1,
"filename": "colorutils-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81ad7df7203f6bfdeef3a709925da8d3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13457,
"upload_time": "2020-11-06T12:11:51",
"upload_time_iso_8601": "2020-11-06T12:11:51.344337Z",
"url": "https://files.pythonhosted.org/packages/b9/52/75ff95b1ecad884703bc3c5cb25670b9cf8f6dfc65fa1cbd2280227b48c8/colorutils-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "6b1b7a2690f2bb536958f0b870976e24",
"sha256": "7d116d4d9119bdb9ab26c05beaaffa10473a21dbfb22e8842bf1cc29513c3cab"
},
"downloads": -1,
"filename": "colorutils-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "6b1b7a2690f2bb536958f0b870976e24",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18882,
"upload_time": "2020-11-06T12:11:52",
"upload_time_iso_8601": "2020-11-06T12:11:52.830512Z",
"url": "https://files.pythonhosted.org/packages/90/bb/bec37d30ca26b5f3716b42bc81c187bc0ec9e8a87a8a23b5b2d54590db30/colorutils-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-11-06 12:11:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "edaniszewski",
"github_project": "colorutils",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "colorutils"
}
JSON
