=================
extract-colors-py
=================
Command-line tool to extract colors from an image.
The result will presented in two formats, text and image.
The text result will provide the usage of each color in the number of pixels and percentage.
While the image will provide a palette for a visual representation.
.. contents:: Table of Contents
.. section-numbering::
------------
Installation
------------
+++++++
Package
+++++++
::
$ pip install extcolors
++++++++
Manually
++++++++
1. Download repository as zip.
2. Unpack zip into folder.
3. Enter folder.
4. Run the following command: ::
$ pip install .
-----
Usage
-----
+++++++++++++++
Input - Console
+++++++++++++++
To use the application provide a path to the image that the application should extract colors from.
In the following example the image is in the folder we are executing the command and the name of the image is ``gameboy.png``:
::
$ extcolors gameboy.png
In this example ``gameboy.png`` refers to the following `image <https://dribbble.com/shots/1056595-Gameboy-Free-PSD>`_
created by `Rebecca Machamer <https://dribbble.com/rebeccamachamer>`_.
.. image:: http://cairns.se/extcolors/gameboy.png
++++++++++++++
Input - Script
++++++++++++++
To use the application provide a path to the image that the colors should be extracted from.
In the following example the image is in the folder we are executing the command and the name of the image is ``gameboy.png``:
.. code:: python
>>> import extcolors
>>> colors, pixel_count = extcolors.extract_from_path("gameboy.png")
>>> print(colors)
[((0, 172, 170), 386062), ((245, 245, 245), 59559), ((82, 90, 92), 17824), ((102, 184, 52), 15080), ((236, 27, 111), 1302), ((255, 180, 0), 137), ((241, 148, 185), 36)]
There is also the option to use an image already loaded through `pillow <https://python-pillow.org/>`_.
.. code:: python
>>> import extcolors
>>> import PIL
>>> img = PIL.Image.open("gameboy.png")
>>> colors, pixel_count = extcolors.extract_from_image(img)
>>> print(colors)
[((0, 172, 170), 386062), ((245, 245, 245), 59559), ((82, 90, 92), 17824), ((102, 184, 52), 15080), ((236, 27, 111), 1302), ((255, 180, 0), 137), ((241, 148, 185), 36)]
+++++++++++++
Output - Text
+++++++++++++
When the application is done it will output information about the
execution. The information contains the extracted colors presented in
the RGB color space along with their occurrence rate.
Output based on ``gameboy.png``: ::
Extracted colors:
(0, 172, 170) : 80.43% (386062)
(245, 245, 245): 12.41% (59559)
(82, 90, 92) : 3.71% (17824)
(102, 184, 52) : 3.14% (15080)
(236, 27, 111) : 0.27% (1302)
(255, 180, 0) : 0.03% (137)
(241, 148, 185): 0.01% (36)
Pixels in output: 480000 of 480000
++++++++++++++
Output - Image
++++++++++++++
Optionally when the application is done it can create an image which
will contain the colors that where extracted sorted based on their
occurrence rate, wrapping from from left to right.
If a name is provided that will be used otherwise the image will use the name of
the original image along with an appended time stamp.
::
$ extcolors gameboy.png --image gameboy-palette
.. image:: http://cairns.se/extcolors/gameboy-result-default.png
+++++++++++++++++++++++++++
Output - GIMP Color Palette
+++++++++++++++++++++++++++
Optionally when the application is done it can create a GIMP color
palette. The colors that where extracted will sorted based in the
palette based on their occurrence rate.
If a name is provided that will be used for both the palette within the
file as well as the filename. If a name isn't provided the palette will
use the name of the original image and the file will use the original
name along with an appended time stamp.
::
$ extcolors gameboy.png --gpl "GameBoy Palette"
------------------
Additional Options
------------------
Generated output from the command-line argument ``extcolors --help``.
::
usage: extcolors [-h] [--version] [-t [N]] [-l [N]] [-s] [-i [NAME]] [-g [NAME]] PATH
Extract colors from a specified image. Colors are grouped based on visual
similarities using the CIE76 formula.
positional arguments:
PATH
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
-t [N], --tolerance [N]
Group colors to limit the output and give a
better visual representation. Based on a
scale from 0 to 100. Where 0 won't group any
color and 100 will group all colors into one.
Tolerance 0 will bypass all conversion.
Defaults to 32.
-l [N], --limit [N] Upper limit to the number of extracted
colors presented in the output.
-s, --silence Silences the default output. Doesn't effect
any other output option.
-i [NAME], --image [NAME]
Output the result to an image palette.
A name for the file can be supplied.
-g [NAME], --gpl [NAME]
Output the result to a GIMP color palette (GPL).
A name for the palette can be supplied.
------------
Known Issues
------------
++++++++++++
Transparency
++++++++++++
The support for images with transparency is limited. Colors that are
fully transparent will be filtered out and will not be counted towards
the colors in the result. Colors that have any level of transparency
other than zero will be kept but the transparency will not be considered
when comparing colors. If a more accurate result is desired the
recommendation would be to apply a background color and perform a
blend in an external application before extracting the colors.
Example - Full Transparency
***************************
The following image is 64 by 64 pixels large. The image consists of a
border that is eight pixels wide and a fully transparent center.
.. image:: http://cairns.se/extcolors/example_fully_transparent.png
Extracting colors from the image results in following where one can
observe how the fully transparent pixels are removed from the
percentage count.
::
Extracted colors:
(34, 32, 52) : 100.00% (1792)
Pixels in output: 1792 of 4096
Example - Partial Transparency
******************************
The following image is 64 by 64 pixels large. The image consists of
a border that is eight pixels wide and a center that has the same color
as the border but with the alpha value set to 50% transparency.
.. image:: http://cairns.se/extcolors/example_partially_transparent.png
Extracting colors from the image results in following where one can
observe how the semi transparent color has been combined with the fully
opaque color as the transparency was disregarded when the two
colors were compared.
::
Extracted colors:
(34, 32, 52) : 100.00% (4096)
Pixels in output: 4096 of 4096
+++++++++++
Performance
+++++++++++
When an image contains a large amount of different colors, which most do, the performance slows to a halt.
If the grouping of colors is not desired/required then a workaround is to set the tolerance levels to zero.
Setting the tolerance to specifically zero will make the application skip any comparisons from being made and
become a simple counter resulting in much greater speeds.
Example, an image (3840x2160) containing about 340k unique colors will take two hours to complete
with a tolerance level of 32 (the default value). However with a tolerance level of zero it will take ten seconds.
Raw data
{
"_id": null,
"home_page": "https://github.com/CairX/extract-colors-py",
"name": "extcolors",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "extract colors image",
"author": "CairX",
"author_email": "lazycairx@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fd/3e/47e48ba0737c1bad19f4134a4b8e00f80701d32de55d3566d64cd20cb013/extcolors-1.0.0.tar.gz",
"platform": "",
"description": "=================\nextract-colors-py\n=================\nCommand-line tool to extract colors from an image.\nThe result will presented in two formats, text and image.\n\nThe text result will provide the usage of each color in the number of pixels and percentage.\nWhile the image will provide a palette for a visual representation.\n\n.. contents:: Table of Contents\n.. section-numbering::\n\n\n------------\nInstallation\n------------\n+++++++\nPackage\n+++++++\n::\n\n $ pip install extcolors\n\n++++++++\nManually\n++++++++\n1. Download repository as zip.\n2. Unpack zip into folder.\n3. Enter folder.\n4. Run the following command: ::\n\n $ pip install .\n\n-----\nUsage\n-----\n+++++++++++++++\nInput - Console\n+++++++++++++++\nTo use the application provide a path to the image that the application should extract colors from.\nIn the following example the image is in the folder we are executing the command and the name of the image is ``gameboy.png``:\n\n::\n\n $ extcolors gameboy.png\n\nIn this example ``gameboy.png`` refers to the following `image <https://dribbble.com/shots/1056595-Gameboy-Free-PSD>`_\ncreated by `Rebecca Machamer <https://dribbble.com/rebeccamachamer>`_.\n\n.. image:: http://cairns.se/extcolors/gameboy.png\n\n++++++++++++++\nInput - Script\n++++++++++++++\nTo use the application provide a path to the image that the colors should be extracted from.\nIn the following example the image is in the folder we are executing the command and the name of the image is ``gameboy.png``:\n\n.. code:: python\n\n >>> import extcolors\n >>> colors, pixel_count = extcolors.extract_from_path(\"gameboy.png\")\n >>> print(colors)\n [((0, 172, 170), 386062), ((245, 245, 245), 59559), ((82, 90, 92), 17824), ((102, 184, 52), 15080), ((236, 27, 111), 1302), ((255, 180, 0), 137), ((241, 148, 185), 36)]\n\nThere is also the option to use an image already loaded through `pillow <https://python-pillow.org/>`_.\n\n.. code:: python\n\n >>> import extcolors\n >>> import PIL\n >>> img = PIL.Image.open(\"gameboy.png\")\n >>> colors, pixel_count = extcolors.extract_from_image(img)\n >>> print(colors)\n [((0, 172, 170), 386062), ((245, 245, 245), 59559), ((82, 90, 92), 17824), ((102, 184, 52), 15080), ((236, 27, 111), 1302), ((255, 180, 0), 137), ((241, 148, 185), 36)]\n\n+++++++++++++\nOutput - Text\n+++++++++++++\nWhen the application is done it will output information about the\nexecution. The information contains the extracted colors presented in\nthe RGB color space along with their occurrence rate.\n\nOutput based on ``gameboy.png``: ::\n\n Extracted colors:\n (0, 172, 170) : 80.43% (386062)\n (245, 245, 245): 12.41% (59559)\n (82, 90, 92) : 3.71% (17824)\n (102, 184, 52) : 3.14% (15080)\n (236, 27, 111) : 0.27% (1302)\n (255, 180, 0) : 0.03% (137)\n (241, 148, 185): 0.01% (36)\n\n Pixels in output: 480000 of 480000\n\n++++++++++++++\nOutput - Image\n++++++++++++++\nOptionally when the application is done it can create an image which\nwill contain the colors that where extracted sorted based on their\noccurrence rate, wrapping from from left to right.\n\nIf a name is provided that will be used otherwise the image will use the name of\nthe original image along with an appended time stamp.\n\n::\n\n $ extcolors gameboy.png --image gameboy-palette\n\n.. image:: http://cairns.se/extcolors/gameboy-result-default.png\n\n+++++++++++++++++++++++++++\nOutput - GIMP Color Palette\n+++++++++++++++++++++++++++\nOptionally when the application is done it can create a GIMP color\npalette. The colors that where extracted will sorted based in the\npalette based on their occurrence rate.\n\nIf a name is provided that will be used for both the palette within the\nfile as well as the filename. If a name isn't provided the palette will\nuse the name of the original image and the file will use the original\nname along with an appended time stamp.\n\n::\n\n $ extcolors gameboy.png --gpl \"GameBoy Palette\"\n\n------------------\nAdditional Options\n------------------\nGenerated output from the command-line argument ``extcolors --help``.\n\n::\n\n usage: extcolors [-h] [--version] [-t [N]] [-l [N]] [-s] [-i [NAME]] [-g [NAME]] PATH\n\n Extract colors from a specified image. Colors are grouped based on visual\n similarities using the CIE76 formula.\n\n positional arguments:\n PATH\n\n optional arguments:\n -h, --help show this help message and exit\n --version show program's version number and exit\n -t [N], --tolerance [N]\n Group colors to limit the output and give a\n better visual representation. Based on a\n scale from 0 to 100. Where 0 won't group any\n color and 100 will group all colors into one.\n Tolerance 0 will bypass all conversion.\n Defaults to 32.\n -l [N], --limit [N] Upper limit to the number of extracted\n colors presented in the output.\n -s, --silence Silences the default output. Doesn't effect\n any other output option.\n -i [NAME], --image [NAME]\n Output the result to an image palette.\n A name for the file can be supplied.\n -g [NAME], --gpl [NAME]\n Output the result to a GIMP color palette (GPL).\n A name for the palette can be supplied.\n\n\n\n------------\nKnown Issues\n------------\n++++++++++++\nTransparency\n++++++++++++\nThe support for images with transparency is limited. Colors that are\nfully transparent will be filtered out and will not be counted towards\nthe colors in the result. Colors that have any level of transparency\nother than zero will be kept but the transparency will not be considered\nwhen comparing colors. If a more accurate result is desired the\nrecommendation would be to apply a background color and perform a\nblend in an external application before extracting the colors.\n\nExample - Full Transparency\n***************************\nThe following image is 64 by 64 pixels large. The image consists of a\nborder that is eight pixels wide and a fully transparent center.\n\n.. image:: http://cairns.se/extcolors/example_fully_transparent.png\n\nExtracting colors from the image results in following where one can\nobserve how the fully transparent pixels are removed from the\npercentage count.\n\n::\n\n Extracted colors:\n (34, 32, 52) : 100.00% (1792)\n\n Pixels in output: 1792 of 4096\n\n\nExample - Partial Transparency\n******************************\nThe following image is 64 by 64 pixels large. The image consists of\na border that is eight pixels wide and a center that has the same color\nas the border but with the alpha value set to 50% transparency.\n\n.. image:: http://cairns.se/extcolors/example_partially_transparent.png\n\nExtracting colors from the image results in following where one can\nobserve how the semi transparent color has been combined with the fully\nopaque color as the transparency was disregarded when the two\ncolors were compared.\n\n::\n\n Extracted colors:\n (34, 32, 52) : 100.00% (4096)\n\n Pixels in output: 4096 of 4096\n\n+++++++++++\nPerformance\n+++++++++++\nWhen an image contains a large amount of different colors, which most do, the performance slows to a halt.\nIf the grouping of colors is not desired/required then a workaround is to set the tolerance levels to zero.\nSetting the tolerance to specifically zero will make the application skip any comparisons from being made and\nbecome a simple counter resulting in much greater speeds.\n\nExample, an image (3840x2160) containing about 340k unique colors will take two hours to complete\nwith a tolerance level of 32 (the default value). However with a tolerance level of zero it will take ten seconds.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Extract colors from an image. Colors are grouped based on visual similarities using the CIE76 formula.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/CairX/extract-colors-py"
},
"split_keywords": [
"extract",
"colors",
"image"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5761b912f519502cd8e2ef590546dcbbd5b853eae33782a367c074bbf63304ef",
"md5": "c13ed21a7f43ba856d6092dc86665475",
"sha256": "92bfcd137c415ca1a3463feaa75f4189a7607f5bdf78dfd6a3e924be09e5ab14"
},
"downloads": -1,
"filename": "extcolors-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c13ed21a7f43ba856d6092dc86665475",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 9840,
"upload_time": "2020-10-19T05:43:10",
"upload_time_iso_8601": "2020-10-19T05:43:10.980101Z",
"url": "https://files.pythonhosted.org/packages/57/61/b912f519502cd8e2ef590546dcbbd5b853eae33782a367c074bbf63304ef/extcolors-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd3e47e48ba0737c1bad19f4134a4b8e00f80701d32de55d3566d64cd20cb013",
"md5": "a09c03543c2ad5c85d9056de35d097c6",
"sha256": "14e81457f98555ba36c07a5dde677d1d555e8f4b75633a4fad42df30a27c4f27"
},
"downloads": -1,
"filename": "extcolors-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a09c03543c2ad5c85d9056de35d097c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8473,
"upload_time": "2020-10-19T05:43:12",
"upload_time_iso_8601": "2020-10-19T05:43:12.477555Z",
"url": "https://files.pythonhosted.org/packages/fd/3e/47e48ba0737c1bad19f4134a4b8e00f80701d32de55d3566d64cd20cb013/extcolors-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-10-19 05:43:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CairX",
"github_project": "extract-colors-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "extcolors"
}
JSON
