diff --git a/.github/workflows/publish-docs-on-master.yaml b/.github/workflows/publish-docs-on-master.yaml
new file mode 100644
index 0000000..e240804
--- /dev/null
+++ b/.github/workflows/publish-docs-on-master.yaml
@@ -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
diff --git a/README.md b/README.md
index bbe1c0d..5df4586 100644
--- a/README.md
+++ b/README.md
@@ -1,94 +1,120 @@
# Pylette
+Welcome to Pylette, the easy-to-use Python library for extracting color palettes from images!
+
[](https://badge.fury.io/py/Pylette)
[](http://pepy.tech/project/pylette)
[](https://squidfunk.github.io/mkdocs-material/)
-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
@@ -100,42 +126,18 @@ Original Image | Extracted Palette
|  
|  
-## 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!