palettetools 0.8.0

Color palette tools for processing imgix-served images.

========
Overview
========


A Python library for extracting and analyzing color palettes from images.
All images must be served through Imgix, more information can be found at http://www.imgix.com.

* Free software: BSD 2-Clause License

Installation
============

::

pip install palettetools

Extracting Color Palettes
=============


PaletteTools allows for two different ways to extract a color palette from an image.
The first of these two functions will return a string in the format of a text/css MIME type:

.. code-block:: python

import palettetools as pt
url = "https://assets.imgix.net/examples/bluehat.jpg"

css_palette = pt.extract_colors_css(url)

# Will return the following:
#
#.image-fg-1 { color:#0d0c10 !important; }
#.image-bg-1 { background-color:#0d0c10 !important; }
#.image-fg-2 { color:#015091 !important; }
#.image-bg-2 { background-color:#015091 !important; }
#.image-fg-3 { color:#0870d3 !important; }
#.image-bg-3 { background-color:#0870d3 !important; }
#.image-fg-4 { color:#239be0 !important; }
#.image-bg-4 { background-color:#239be0 !important; }
#.image-fg-5 { color:#b1dfeb !important; }
#.image-bg-5 { background-color:#b1dfeb !important; }
#.image-fg-6 { color:#f0c9b4 !important; }
#.image-bg-6 { background-color:#f0c9b4 !important; }
#.image-fg-ex-1 { color:#000000 !important; }
#.image-bg-ex-1 { background-color:#000000 !important; }
#.image-fg-ex-2 { color:#ffffff !important; }
#.image-bg-ex-2 { background-color:#ffffff !important; }
#.image-fg-vibrant { color:#0d95e4 !important; }
#.image-bg-vibrant { background-color:#0d95e4 !important; }
#.image-fg-muted-dark { color:#38445c !important; }
#.image-bg-muted-dark { background-color:#38445c !important; }
#.image-fg-muted { color:#966760 !important; }
#.image-bg-muted { background-color:#966760 !important; }
#.image-fg-vibrant-light { color:#72c5f4 !important; }
#.image-bg-vibrant-light { background-color:#72c5f4 !important; }
#.image-fg-muted-light { color:#d8b6aa !important; }
#.image-bg-muted-light { background-color:#d8b6aa !important; }
#.image-fg-vibrant-dark { color:#015091 !important; }
#.image-bg-vibrant-dark { background-color:#015091 !important; }

This can be appended to a pre-existing CSS file through the following script:

.. code-block:: python

>>> import palettetools as pt
>>> url = "https://assets.imgix.net/examples/bluehat.jpg"
>>> css = pt.extract_colors_css(url)
>>> file = open("colors.css", 'w')
>>> file.write(css)
>>> file.close()

Color palettes can also be extracted as a JSON object through the following function.
Also note that the object has 3 keys: **colors** , **average_luminance** , and **dominant_colors**

.. code-block:: python

import palettetools as pt
url = "https://assets.imgix.net/examples/bluehat.jpg"

json_palette = pt.extract_colors_json(url)

print json_palette

# Will return the following:
# {
# "colors": [
# {
# "red": 0.0509804,
# "hex": "#0d0c10",
# "blue": 0.0627451,
# "green": 0.0470588
# },
# {
# "red": 0.00392157,
# "hex": "#015091",
# "blue": 0.568627,
# "green": 0.313725
# },
# {
# "red": 0.0313725,
# "hex": "#0870d3",
# "blue": 0.827451,
# "green": 0.439216
# },
# {
# "red": 0.137255,
# "hex": "#239be0",
# "blue": 0.878431,
# "green": 0.607843
# },
# {
# "red": 0.694118,
# "hex": "#b1dfeb",
# "blue": 0.921569,
# "green": 0.87451
# },
# {
# "red": 0.941176,
# "hex": "#f0c9b4",
# "blue": 0.705882,
# "green": 0.788235
# }
# ],
# "average_luminance": 0.708396,
# "dominant_colors": {
# "vibrant": {
# "red": 0.0509804,
# "hex": "#0d95e4",
# "blue": 0.894118,
# "green": 0.584314
# },
# "muted_light": {
# "red": 0.847059,
# "hex": "#d8b6aa",
# "blue": 0.666667,
# "green": 0.713725
# },
# "muted": {
# "red": 0.588235,
# "hex": "#966760",
# "blue": 0.376471,
# "green": 0.403922
# },
# "vibrant_dark": {
# "red": 0.00392157,
# "hex": "#015091",
# "blue": 0.568627,
# "green": 0.313725
# },
# "vibrant_light": {
# "red": 0.447059,
# "hex": "#72c5f4",
# "blue": 0.956863,
# "green": 0.772549
# },
# "muted_dark": {
# "red": 0.219608,
# "hex": "#38445c",
# "blue": 0.360784,
# "green": 0.266667
# }
# }
# }


Overlaid Text Color
=============

PaletteTools can also give a suggested color for overlaid text on a specific image.
The function will either return the hexadecimal value for **white** or **black** depending on which is more visible for the passed in image:

.. code-block:: python

import palettetools as pt
url = "https://assets.imgix.net/examples/bluehat.jpg"

color_suggested = pt.overlay_text_color(url)

print color_suggested

# Will return:
#
# 000

Testing
===========

To run the all tests run::

tox


Changelog
=========

0.2.0 - 0.8.0 (2018-11-08)
------------------

* Debugging needed to fix broken build

0.1.0 (2018-11-08)
------------------

* First release on PyPI.