obskyr/colorgram.py

A Python module for extracting colors from images. Get a palette of any picture!

colorgram.py

colorgram.py is a Python library that lets you extract colors from images. Compared to other libraries, the colorgram algorithm's results are more intense.

colorgram.py is a port of colorgram.js, a JavaScript library written by GitHub user @darosh. The goal is to have 100% accuracy to the results of the original library (a goal that is met). I decided to port it since I much prefer the results the colorgram algorithm gets over those of alternative libraries - have a look in the next section.

Results

Time-wise, an extraction of a 512x512 image takes about 0.66s (another popular color extraction library, Color Thief, takes about 1.05s).

Installation

You can install colorgram.py with pip, as following:

pip install colorgram.py

How to use

Using colorgram.py is simple. Mainly there's only one function you'll need to use - colorgram.extract.

Example

import colorgram

# Extract 6 colors from an image.
colors = colorgram.extract('sweet_pic.jpg', 6)

# colorgram.extract returns Color objects, which let you access
# RGB, HSL, and what proportion of the image was that color.
first_color = colors[0]
rgb = first_color.rgb # e.g. (255, 151, 210)
hsl = first_color.hsl # e.g. (230, 255, 203)
proportion  = first_color.proportion # e.g. 0.34

# RGB and HSL are named tuples, so values can be accessed as properties.
# These all work just as well:
red = rgb[0]
red = rgb.r
saturation = hsl[1]
saturation = hsl.s

colorgram.extract(image, number_of_colors)

Extract colors from an image. image may be either a path to a file, a file-like object, or a Pillow Image object. The function will return a list of number_of_colors Color objects.

colorgram.Color

A color extracted from an image. Its properties are:

• Color.rgb - The color represented as a namedtuple of RGB from 0 to 255, e.g. (r=255, g=151, b=210).
• Color.hsl - The color represented as a namedtuple of HSL from 0 to 255, e.g. (h=230, s=255, l=203).
• Color.proportion - The proportion of the image that is in the extracted color from 0 to 1, e.g. 0.34.

Sorting by HSL

Something the original library lets you do is sort the colors you get by HSL. In actuality, though, the colors are only sorted by hue (as of colorgram.js 0.1.5), while saturation and lightness are ignored. To get the corresponding result in colorgram.py, simply do:

colors.sort(key=lambda c: c.hsl.h)
# or...
sorted(colors, key=lambda c: c.hsl.h)

Contact

If you find a bug in the colorgram.py, or if there's a feature you would like to be added, please open an issue on GitHub.

If you have a question about the library, or if you'd just like to talk about, well, anything, that's no problem at all. You can reach me in any of these ways:

• Tweet @obskyr
• E-mail me

To get a quick answer, Twitter is your best bet.

Enjoy!

colorgram.py's Issues

colorgram.extract(img_path, n) returns less than 'n' number of colors for certain images

When we run colorgram.extract(img_path, n) for images like THIS for n=6, we get 2-3 colors in return

I understand that these kind of images have lesser color information, but is there any way that colorgram.extract returns exactly n number of colors for all images?

Error: File is not in the directory

I have import "colorgram" module in my program, but it shows the error that file or directory is not found.
As on my observation there is a bug which is casuing this issue. I have one project folder and in that there are some other folders and in that folder, I had import the "colorgram" module but it shows error when file is run. But observation is that it not work properly in nested folders. But when I create a folder on desktop and in that folder I create a file and place my sample image there, but this time it shows no error.

So I think it show error when this module is call in the nested folder. Or may I am the only one facing this issue.

OverflowError: Python int too large to convert to C long

Hi,

I wanted to get a palette from an assortiment of images instead of one image, so I concatenated vertically about 36 images.
The image is available here, so you can test.
When I run the list_colors = colorgram.extract(full_img, number_of_colors=6) on this image, I get the following error:

File "C:\Users\Owner\Dropbox\Online classes\Udemy - Python 100 Days of Code\Python Projects\venv\lib\site-packages\colorgram\colorgram.py", line 42, in extract
samples = sample(image)
File "C:\Users\Owner\Dropbox\Online classes\Udemy - Python 100 Days of Code\Python Projects\venv\lib\site-packages\colorgram\colorgram.py", line 91, in sample
samples[packed] += r
OverflowError: Python int too large to convert to C long

Not sure how to solve this issue...

Reduce memory footprint

Original library dropped the buggy RGB stuff and reduced samples to just:
const cubes: number = Math.pow(sides, 3); packed to 0b00YYhhll

https://github.com/darosh/colorgram-js/blob/4302c3d1e3116ecc70c2557533674322b5d95b82/src/colorgram.ts#L45

.png files giving wrong color output.

When trying to extract colors in a .png with only three colors ((150, 150, 150),(255,255,255),(63, 33, 0)) the one of the colors gets darkened and i get these colors: ((4, 2, 0), (150, 150, 150), (255, 255, 255)).

Extract color coordinates

Hi Colorgramers!

I intend to get the coordinate of each color in my image too, is there any way we can achieve this?

Any help is appreciated

Wrong output for hsl

When we try to convert a color given by the colorgram.extract from RGB to HSL, the conversion is wrong. I tried multiple times and checked from different sources. i found that the conversion is wrong.
x = Rgb(r=53, g=57, b=64)
x.hsl = Hsl(h=154, s=23, l=58)
But the actual value is as per
218, 9.4% , 22.9%
You can check @ https://www.rapidtables.com/convert/color/rgb-to-hsl.html

module 'colorgram' has no attribute 'extract'

upon installing colorgram successfully and calling colorgram.extract using pycharm it pop-up a message:

colors = colorgram.extract('image.jpg',30)

AttributeError: module 'colorgram' has no attribute 'extract'

Do you know what I'm missing?

A way to filter out very light or dark colors

I'm running colorgram on images of board games that I have. Many of them have a black or white box, which means the dominant color in many of the cases is just black. I would like to filter out those colors.

I see that you already calculate luma here: https://github.com/obskyr/colorgram.py/blob/master/colorgram/colorgram.py#L65 -- so what I'm asking for is way to filter out those with high or low luma.

Is this something that is a good fit for this library?

hex property for Color objects

I'd like to have an extra .hex property in the Color object, that contains a string representing the hexadecimal color code.
eg.

>>> print(my_color.hex)
'#0A1FB5'