Skip to content

Commit

Permalink
[docs] Auto publish docs on main (#38)
Browse files Browse the repository at this point in the history 
* Publish docs on main

* update link
  • Loading branch information
@qTipTip
qTipTip authored Jul 7, 2024
1 parent c6d890a commit 70d0325
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 91 deletions.
43 changes: 43 additions & 0 deletions .github/workflows/publish-docs-on-master.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: ci
on:
push:
branches:
- master
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configure Git Credentials
run: |
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- uses: actions/setup-python@v5
with:
python-version: 3.x
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- uses: actions/cache@v4
with:
key: mkdocs-material-${{ env.cache_id }}
path: .cache
restore-keys: |
mkdocs-material-
- name: Install poetry
uses: abatilo/actions-poetry@v2
with:
poetry-version: ${{ matrix.poetry-version }}
- name: Setup a local virtual environment (if no poetry.toml file)
run: |
poetry config virtualenvs.create true --local
poetry config virtualenvs.in-project true --local
- uses: actions/cache@v3
name: Define a cache for the virtual environment based on the dependencies lock file
with:
path: ./.venv
key: venv-${{ hashFiles('poetry.lock') }}
- name: Install the project dependencies
run: poetry install
- run: poetry run mkdocs gh-deploy --force
184 changes: 93 additions & 91 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,94 +1,120 @@
# Pylette

Welcome to Pylette, the easy-to-use Python library for extracting color palettes from images!

[![PyPI version](https://badge.fury.io/py/Pylette.svg)](https://badge.fury.io/py/Pylette)
[![Downloads](http://pepy.tech/badge/pylette)](http://pepy.tech/project/pylette)
[![Built with Material for MkDocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
![Dependabot](https://img.shields.io/badge/dependabot-enabled-025E8C?logo=dependabot&logoColor=white)

A color palette extractor written in Python using KMeans clustering.

---

**Documentation**: [https://qtiptip.github.io/Pylette/](https://qtiptip.github.io/Pylette/)
**Documentation**: [qtiptip.github.io/Pylette](https://qtiptip.github.io/Pylette/)

**Source Code**: [https://github.com/qTipTip/Pylette](https://github.com/qTipTip/Pylette)
**Source code:** [qTipTip/Pylette](https://github.com/qTipTip/Pylette)

---

## Motivation
## What is Pylette?

Working with computer graphics and visualizations, one often needs a way of specifying a set of colors
with a certain visual appeal. Such a set of colors is often called a *color palette*. The aim of this
library is to easily extract a set of colors from a supplied image, with support for the various color modes (RGB, RGBa, HSV, etc).
Dabbling in generative art, the need often arises for being able to pick colors at random from a palette.
Pylette supports this, both picking colors uniformly, but also using the color frequency from the original image as probabilities.
Pylette is a powerful yet user-friendly library designed to help you extract color palettes from images. Whether you're
working on computer graphics, visualizations, or generative art, Pylette makes it easy to create visually appealing
color sets.

Key features:

* Extract color palettes from images
* Support for various color modes (RGB, RGBa, HSV, etc.)
* Random color selection from palettes
* Command-line interface for quick palette extraction

#### Other color palette related Python-libraries:
1. [Color Thief](https://github.com/fengsp/color-thief-py): Extraction of color palettes using the median cut algorithm.
2. [Palettable](https://pypi.org/project/palettable/): Generation of matplotlib compatible color schemes
3. [Colorgram](https://github.com/obskyr/colorgram.py): Extraction of colors from images (similar to the intended use of this library),
however, I was unable to install this.
## Getting Started

## Installation
### Installation

Pylette is available in the python package index (PyPi), and can be installed using `pip`:
You can easily install Pylette using pip:

```shell
pip install Pylette
```

## Basic usage
Or if you prefer using Poetry:

A `Palette` object is created by calling the `extract_colors` function, either using a path to an image, or an image url:
```shell
poetry add Pylette
```

```python
from Pylette import extract_colors
### Quick Start Guide

palette = extract_colors(image='image.jpg', palette_size=10, resize=True)
palette = extract_colors(image_url='https://path.to.image', palette_size=10, resize=True, mode='MC',
sort_mode='luminance')
```
Here's how to extract a color palette from an image and work with it in Python:

This yields a palette of ten colors, and the `resize` flag tells Pylette to resize the image to a more manageable size (256 x 256) before
beginning color extraction. This significantly speeds up the extraction, but reduces the faithfulness of the color palette.
One can choose between color quantization using K-Means (default) or Median-Cut algorithms, by setting in the `mode`-parameter. One can also specify to alternatively sort the color palette by the luminance (percieved brightness).

The palette object supports indexing and iteration, and the colors are sorted from highest to lowest frequency by default.
E.g, the following snippet will fetch the most common, and least common
color in the picture if the palette was sorted by frequency, or the darkest to lightest color if sorted by luminance:
```python
most_common_color = palette[0]
least_common_color = palette[-1]
three_most_common_colors = palette[:3]
```
As seen, slicing is also supported.
!!! example "Extracting a Color Palette"

The Palette object contains a list of Color objects, which contains a representation of the color in various color modes, with RGB being the default. Accessing the color attributes is easy:
```python
from Pylette import extract_colors

```python
color = palette[0]
palette = extract_colors(image='image.jpg', palette_size=10)
# Access colors by index
most_common_color = palette[0]
least_common_color = palette[-1]

print(color.rgb)
print(color.hls)
print(color.hsv)
```
# Get color information
print(most_common_color.rgb)
print(most_common_color.hls)
print(most_common_color.hsv)

To display the extracted color palette, simply call the `display`-method, which optionally takes a flag for saving the palette to an image file.
The palette can be dumped to a CSV-file as well, where each row represents the RGB values and the corresponding color frequency (optional).
```python
palette.display(save_to_file=False)
palette.to_csv(filename='color_palette.csv', frequency=True)
```
# Display the palette, and save the image to file
palette.display(save_to_file=True)

In order to pick colors from the palette at random, Pylette offers the `random_color`-method, which supports both drawing
uniformly, and from the original color distribution, given by the frequencies of the extracted colors:
# Save palette's color values to CSV
palette.to_csv(filename='color_palette.csv', frequency=True)

```python
random_color = palette.random_color(N=1, mode='uniform')
random_colors = palette.random_color(N=100, mode='frequency')
```
# Pick random colors
random_color = palette.random_color(N=1, mode='uniform')
random_colors = palette.random_color(N=100, mode='frequency')
```

This will give you a palette of 10 colors, sorted by frequency.
The image is automatically resized to 256x256 pixels for faster processing.
See the [reference documentation](https://qtiptip.github.io/Pylette/reference/) for a complete list of available methods and attributes.

## Command Line Tool

Pylette also comes with a handy command-line tool. Here's a quick overview of its usage:

!!! example "Command Line Usage"

=== "Extracting a Color Palette using the CLI"

```bash
pylette --filename image.jpg --mode KM --n 5 --sort_by luminance --colorspace rgb --display-colors True
```

=== "Options"

```bash
╰─❯ pylette --help
usage: pylette [-h] (--filename FILENAME | --image-url IMAGE_URL) [--mode {KM,MC}] [--n N] [--sort_by {luminance,frequency}] [--stdout STDOUT] [--colorspace {rgb,hsv,hls}] [--out_filename OUT_FILENAME]
[--display-colors DISPLAY_COLORS]

options:
-h, --help show this help message and exit
--filename FILENAME path to image file (default: None)
--image-url IMAGE_URL
url to the image file (default: None)
--mode {KM,MC} extraction_mode (KMeans/MedianCut (default: KM)
--n N the number of colors to extract (default: 5)
--sort_by {luminance,frequency}
sort by luminance or frequency (default: luminance)
--stdout STDOUT whether to display the extracted color values in the stdout (default: True)
--colorspace {rgb,hsv,hls}
color space to represent colors in (default: RGB)
--out_filename OUT_FILENAME
where to save the csv file (default: None)
--display-colors DISPLAY_COLORS
Open a window displaying the extracted palette (default: False)

```

## Example Palettes

Expand All @@ -100,42 +126,18 @@ Original Image | Extracted Palette
<img src="https://images.unsplash.com/photo-1534547774987-e59593542e1e?ixlib=rb-0.3.5&ixid=eyJhcHBfaWQiOjEyMDd9&s=e8e5af1676517ac1ef8067f97a206415&auto=format&fit=crop&w=1234&q=80" width=200 height=200> | ![](docs/example_imgs/alex_perez_palette_kmeans.jpg) ![](docs/example_imgs/alex_perez_palette_mediancut.jpg)
<img src="https://images.unsplash.com/photo-1534537841395-2e594ba9ed4a?ixlib=rb-0.3.5&ixid=eyJhcHBfaWQiOjEyMDd9&s=34ad54d1ba5d88b42abf43219c905c78&auto=format&fit=crop&w=1234&q=80" width=200 height=200> | ![](docs/example_imgs/josh_hild_palette_kmeans.jpg) ![](docs/example_imgs/josh_hild_palette_mediancut.jpg)

## Command Line Tool

The new version of Pylette also comes bundled with a command line tool, which can be used to extract color palettes from the command line.

```shell script
usage: pylette [-h] (--filename FILENAME | --image-url IMAGE_URL) [--mode {KM,MC}] [--n N] [--sort_by {luminance,frequency}] [--stdout STDOUT] [--colorspace {rgb,hsv,hls}] [--out_filename OUT_FILENAME]
[--display-colors DISPLAY_COLORS]

options:
-h, --help show this help message and exit
--filename FILENAME path to image file (default: None)
--image-url IMAGE_URL
url to the image file (default: None)
--mode {KM,MC} extraction_mode (KMeans/MedianCut (default: KM)
--n N the number of colors to extract (default: 5)
--sort_by {luminance,frequency}
sort by luminance or frequency (default: luminance)
--stdout STDOUT whether to display the extracted color values in the stdout (default: True)
--colorspace {rgb,hsv,hls}
color space to represent colors in (default: RGB)
--out_filename OUT_FILENAME
where to save the csv file (default: None)
--display-colors DISPLAY_COLORS
Open a window displaying the extracted palette (default: False)
```
## How Pylette Works

## Under the hood
Pylette uses various color quantization algorithms to extract the most representative colors from your images.
Currently, it supports:

Currently, Pylette can use KMeans or Median-cut for the color quantization. There are plans for implementing other color quantization schemes, like:
1. K-Means clustering
2. Median-Cut algorithm

1. Octree
2. Modified minmax
## We'd Love Your Feedback And Contributions!

The article [*Improving the Performance of K-Means for Color Quantization*](https://arxiv.org/pdf/1101.0395.pdf) gives a
nice overview of available methods.
Pylette is an ongoing project, and we're always looking to improve it.
If you have any suggestions, questions, or just want to share how you're using Pylette, please don't hesitate to reach
out, or make a pull request on our GitHub repository.

## Feedback
Any feedback and suggestions is much appreciated.
This is very much a work in progress.
Happy color extracting!

0 comments on commit 70d0325

Please sign in to comment.