Extract colors from an image. Colors are grouped based on visual similarities using the CIE76 formula.
The major bump in version should have been done a long time ago but with no ability to correct the past we are taking the opportunity to do so now.
The aim if for a version scheme that is more commonly used for Python packages. The three numbers represent in order:
Support has been added for Python 3.9 now that the official version has been release.
At the same time Python 3.5 has reached its end-of-life and so it will no longer be supported.
In conjunction with the Python release cycle Pillow has also added support for 3.9 and dropped support of 3.5. To align the supported versions the minimum required Pillow version will be 8.0.0.
The code that dealt with color conversion has been separated into its own packaged called convcolors. The intention is to make a clearer distinction what the goal of extcolors is, the extraction of colors from images, and what it needs to perform that action.
In the long run the intention is also to extend convcolors from being only a library to also support command line operation (similar to what extcolors does today) for quick conversion between color spaces.
The command line interface now has the option to export a GIMP color palette file, extension .gpl. Even though the format was created by and for GIMP it's format that is open and supported by other applications.
Example of the new option:
$ extcolors gameboy.png --gpl gameboy-palette
With the addition of the new GPL output option the old output options have been reworked.
Most notably an image palette will not longer be generated by default. Instead to generated the image palette the --image flag needs to be provided.
The following two command will generate the same result as the default options before the rework. With the first command using the short hand version of the flag:
$ extcolors gameboy.png -i
$ extcolors gameboy.png --image
After the change a name can be supplied after the flag:
$ extcolors gameboy.png -i "GameBoy Image Palette"
$ extcolors gameboy.png --image gameboy-image-palette
The standard text output will be provided no matter if both, either, or none of the other output options are used. Along with that change there is now a flag that will silence the standard output.
$ extcolors gameboy.png --silence --image
Before:
$ extcolors gameboy.png --output all
After:
$ extcolors gameboy.png --image
Before:
$ extcolors gameboy.png --output image
After:
$ extcolors gameboy.png --silence --image
Before:
$ extcolors gameboy.png --output text
After:
$ extcolors gameboy.png
Previously pixel that were fully transparent would be counted towards black which would skew the result. Now fully transparent pixels will be ignored and not counted towards the total.
When calling extcolors from the command line the reported version wouldn't match the installed version.
The function extract has been renamed extract_from_path with the addition of a new function extract_from_image.
>>> import extcolors
>>> colors, pixel_count = extcolors.extract_from_path("gameboy.png")
The addition of extract_from_image was contributed by ashirviskas. The function can be used if an image has already been loaded using Pillow.
>>> import extcolors
>>> import PIL
>>> img = PIL.Image.open("gameboy.png")
>>> colors, pixel_count = extcolors.extract_from_image(img)
The implementation has changed to report the RGB colors produced by Pillow directly and perform color space conversion in only one direction. The change should eliminate any instability in the reported colors.
The modification done to increase the stability of the reported colors was an opportunity to change the data structures used. The new data structures allowed for some additional modifications that improve the performance of extracting colors from some medium complex images.
As an example: an image with 223715 unique colors showed a dramatic speed increase, the color extraction went from taking almost 19 minutes to just above 4 seconds.
Support for Python 3.4 was dropped as the version reached end-of-life on March the 18th 2019. PEP 429 - Python 3.4 Release Schedule.
Support for Python 2.7 was dropped as the version reached end-of-life on January the 1st 2020. With the final release being published on April the 20th 2020. PEP 373 - Python 2.7 Release Schedule.
The required version of Pillow has been defined to 7.0.0 or above. With that the packages will require the same Python versions, making them compatible.
A reported issue highlighted that there were slight errors in the conversion from RGB to CIE XYZ and back again. The stability was increased using higher precision for the conversion. However there are still slight rounding errors.
The conversion between color spaced can be bypassed using a tolerance level of zero. The option can be used to produced absolute color distribution that has complete stability.
$ extcolors --tolerance=0 gameboy.png
$ extcolors -t=0 gameboy.png
Follow the same Python requirements defined by Pillow (a required dependency).