seenaburns / chroma

Python color handling made simple.

Chroma

Chroma is a Python module for handling colors with ease.

Manipulating colors can quickly escalate into a tedious and complicated task, particularly when you become concerned with color systems beyond RGB. Chroma is here to provide a simple API to do the heavy lifting, so that you can stay focused on the important parts of your projects.

Before you ask, Chroma is BSD licensed, available on Github and PyPI.

Features

• Hex (#rrggbb, #rrggbbaa)
• RGB
• HLS
• HSV
• CMY, CMYK
• Alpha
• Color Blending: additive and subtractive mixing

Roadmap

• Coordinates (sRGB, YIQ, CIE, LAB and more)
• Color harmonies: complementary, analogous, triad
• Color difference
• Color detection in images

Quickstart

Getting started with the power of Chroma is meant to be straightforward

import chroma

# Create a color object
color = chroma.Color('#00FF00')

# Handling different color systems
color.cmy = (0.3, 0.7, 0.8)
color.rgb    # (0.7, 0.3, 0.2)
color.hls    # (0.0333, 0.45, 0.5556)

# Alpha
color.alpha = 0.5
color.hsv    # (0.03333, 0.7143, 0.7, 0.5)

# Color blending
color + chroma.Color("#FF00FF")
# #FF4DFF

And there you have it. The documentation describes Chroma's functionality and usage in detail.

Installation

Installation is as easy as

pip install chroma

Or if you're an easy_install-er

easy_install chroma

Chroma does not yet support Python 3, but, if you're interested, contribute!

Contribute

Chroma is under active development and could use your support. Even bug reports, feature suggestions and feedback can help push Chroma forward in the right direction.

Chroma is hosted on Github and there are a number of ideas of where to start in the issues section.

chroma's Issues

Magic Methods (comparison, string)

Some relevant magic methods can be implemented in chroma.Color:

• ne: inequality (!=)
• eq: equality (=)
• str, repr, unicode, format: various to strings

Other posibilites:

• hex: convert to hex
• int: could make sense (?)

Contribute Documenation

The biggest improvement to documentation would be detailing how anyone can contribute easily, bug reports, feature requests, link to the issue tracker, the github page, etc.

Continuous integration

Hello,

it will be nice to enable Continuous Integration.
Travis-CI could help.

Kind regards

Value Error on bad input

Raise a value error on bad input in init (format or hex input) instead of a generic exception.

Hue in degrees not percentages

Hue (of HLS and HSV) coordinates is considered to be in degrees (of 360 rather than of 256) while lightness, saturation, value and RGB all in percentages.

Proper HLS return would be (210°, 47%, 29%) for example.

Saturation modification API

Because HSV saturation and HLS saturation are different, the direct modification properties has an unintuitive API:

c.hls_saturation
c.hsv_saturation

While this isn't a big issue, it makes Chroma's API less intuitive and harder to use.

Blending does not take alpha-channel into account

and color the blending produces unintuitive results in general even if we choose to ignore alpha

https://en.wikipedia.org/wiki/Alpha_compositing#Alpha_blending
https://github.com/fyngyrz/colorblending/blob/master/colorblending.cpp

Python 3 support

Hello,

Chroma doesn't seems to support Python 3.

In [1]: import chroma
  File "//anaconda/lib/python3.4/site-packages/chroma/core.py", line 273
    except Exception, e:

Kind regards

Color mixing

Feature enhancement: add color mixing (additive, subtractive). Update magic methods as well.

Rounding

Rounding needs to be addressed. As of now there is no rounding implemented, as I thought this would be the best approach, but it seems bugs are starting to pop up.

c.hex = '#335577'
# RGB Out: (0.2, 0.3333333333333333, 0.4666666666666667)
# CMYK Out: (0.5714285714285715, 0.28571428571428586, 0.0, 0.5333333333333333)

c.cmyk = (0.5714285714285715, 0.28571428571428586, 0.0, 0.5333333333333333)
# RGB Out: (0.19999999999999996, 0.33333333333333326, 0.4666666666666667)
# HEX Out: '#325477'

This is because in the _float_to_hex function, the int conversion truncates and does not round.

0.19999999999999996 * 255 = 50.999999999999986 -> 50
versus
0.2 * 255 = 51.0 -> 51

This might be the solution to this particular issue, but I'm suspicious it might be a symptom of a larger problem

Documentation

Chroma is outgoing documentation in README.rst, and could use separate, more extensive documentation on Read the Docs or something.

Color functions

Chroma could potentially benefit from basic color functions like Grayscale(), Darken(%), Lighten(%), and any other similar functions.

Refractor Tests

More tests + separate functions for each case.

Anytime a bug / corner case found, make a test to cover it.

More hex formats

Mainly: #RGB
Maybe: #RRRGGGBBB and #RRRRGGGGBBBB

Seems like Hex3 and Hex4 are only used in GTK themes, but it's easy to support the output format. Taking in them as inputs would require downscaling since the internal representation doesn't represent colorspace with that specificity.

Alpha Bug

Because of the way alpha is handled, anything that tries to unpack self.rgb has an error.

Color Harmonies

Potential feature enhancement, provide color harmonies: complementary, analogous, triad

Refactor properties

A lot of duplicate code exists in chroma.Color object's getters / setters. An internal function that accepts a color format function could simplify codebase and make adding additional formats trivial. Also alpha support would be simplified.

Usage would look like:

self.rgb = self._format(self, color_tuple, colorsys.hls_to_rgb)

New Color Coordinates

Unfortunately, it doesn't seem like any other coordinate systems can take advantage of colorsys, but the more coordinate systems Chroma supports, the better.

Possibilities:

• sRGB
• YIQ
• YUV
• CIE
• CMY(K)
• RYB
• Others (?)

Color detection in images

Basic idea is to implement something along the lines of Charles Leifer's "Using python and k-means to find the dominant colors in images."

I've run into some bugs using the exact code in this article, and issues with K-Means returning muddy results (as expected, but possibly not desired). The functionality is there, but perhaps it could be enhanced, also taking from colorific.

Note: PIL will probably be required, but it the color detection can be left in it's own file and not force imported to leave PIL as an optional library for the rest of Chroma.

Color difference

Implement color difference - http://en.wikipedia.org/wiki/Color_difference

Explanation of implementation choice would be helpful.