---
obj: application
repo: https://github.com/t28hub/auto-palette
---

# auto-palette
🎨 `auto-palette` is a library that automatically extracts prominent color palettes from images, available as Rust library, WebAssembly and CLI tool.

## Overview
`auto-palette` is a Rust project that offers color palette extraction from images. It consists of the following components:

* `auto-palette`: Core library for programmatic usage.
* `auto-palette-cli`: Command-line interface for easy usage.
* `auto-palette-wasm`: WebAssembly version for browser usage.

Perfect for developers, designers and anyone needing efficient color palette extraction.

## Features
* Automatically extracts prominent color palettes from images.
* Provides detailed color swatch information (color, position, population)
* Supports multiple extraction algorithms: `DBSCAN`, `DBSCAN++`, and `KMeans++`.
* Supports numerous color spaces: `RGB`, `HSL`, `LAB`, `LCHuv`, `ANSI256` and more.
* Theme-based swatch selection: `Colorful`, `Vivid`, `Muted`, `Light`, and `Dark`.
* Available as a Rust library, Wasm, and a CLI tool.

## Installation
### Rust Library
To use `auto-palette` in your Rust project, add it to your `Cargo.toml`.

```toml
[dependencies]
auto-palette = "0.8.0"
```

### CLI Tool
To use command-line interface, install the `auto-palette-cli` crate.

```sh
cargo install auto-palette-cli
```

## Usage
### Rust Example
Here is an example of extracting the color palette from an image using the Rust library.

```rust
use auto_palette::{ImageData, Palette};

fn main() {
  // Load the image data from the file
  let image_data = ImageData::load("tests/assets/holly-booth-hLZWGXy5akM-unsplash.jpg").unwrap();

  // Extract the color palette from the image data
  let palette: Palette<f64> = Palette::extract(&image_data).unwrap();
  println!("Extracted {} swatches", palette.len());

  // Find the 5 dominant colors in the palette and print their information
  let swatches = palette.find_swatches(5).unwrap();
  for swatch in swatches {
    println!("Color: {}", swatch.color().to_hex_string());
    println!("Position: {:?}", swatch.position());
    println!("Population: {}", swatch.population());
    println!("Ratio: {}", swatch.ratio());
  }
}
```

### CLI Example
Here is an example of extracting the color palette from an image using the CLI tool.

```sh
# Usage: auto-palette [OPTIONS] [PATH]
$ auto-palette path/to/your_image.jpg -n 6 -c rgb -o table
+---+--------------------+------------+------------+
| # | Color              | Position   | Population |
+---+--------------------+------------+------------+
| 1 | RGB(221, 226, 222) | (104, 96)  |       6778 |
| 2 | RGB(3, 144, 149)   | (114, 201) |       5476 |
| 3 | RGB(23, 37, 36)    | (120, 300) |       4300 |
| 4 | RGB(36, 88, 131)   | (183, 145) |       1348 |
| 5 | RGB(254, 29, 44)   | (183, 190) |        779 |
| 6 | RGB(253, 213, 116) | (25, 158)  |        567 |
+---+--------------------+------------+------------+
```

#### Options

| Option                   | Description                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a, --algorithm <name>` | Algorithm for extracting the color palette. <br><br>**Default:** `dbscan`<br><br>**Possible values:**<br>- `dbscan`: High accuracy but slower speed. Ideal for precision over performance.<br>- `dbscan++`: A balanced algorithm with faster speed and good accuracy.<br>- `kmeans`: Fast speed but potentially less accurate. Ideal for performance over precision. |
| `-t, --theme <name>`     | Theme for selecting the swatches. <br><br>**Possible values:**<br>- `colorful`: Prioritize colorful colors.<br>- `vivid`: Prioritize saturated colors.<br>- `muted`: Prioritize desaturated colors.<br>- `light`: Prioritize light colors.<br>- `dark`: Prioritize dark colors.                                                                                      |
| `-n, --count <number>`   | Number of colors to extract. <br><br>**Default:** `5`                                                                                                                                                                                                                                                                                                                |
| `-c, --color <name>`     | Output color format. <br><br>**Default:** `hex`<br><br>**Possible values:**<br>- `hex`, `rgb`, `cmyk`, `hsl`, `hsv`, `lab`, `luv`, `lchab`, `lchuv`, `oklab`, `oklch`, `xyz`                                                                                                                                                                                         |
| `-o, --output <name>`    | Output format. <br><br>**Default:** `text`<br><br>**Possible values:**<br>- `json`, `text`, `table`                                                                                                                                                                                                                                                                  |
| `--no-resize`            | Disable image resizing before extracting the color palette. May improve accuracy by preserving original image resolution.                                                                                                                                                                                                                                            |
| `--clipboard`            | Get image from system clipboard.                                                                                                                                                                                                                                                                                                                                     |