Metadata-Version: 2.4
Name: pallette
Version: 0.1.0
Summary: A local python library for color palettes using Pygame, NumPy, Pillow, Matplotlib, and Math
Author-email: Alexandre Afonso Santana Dias <whatfish124@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pygame>=2.0.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: matplotlib>=3.4.0

# pallete-picker

A fast and efficient local Python library for extracting unique color palettes from images using Pygame, NumPy, Pillow, Matplotlib, and Math.

`pallete-picker` flattens images and uses optimized NumPy vectorization to calculate color distances instantly, turning hours of pure Python loops into milliseconds of work.

## Features

* **Ultra-Fast Extraction**: Replaces slow nested Python loops with NumPy vector operations.
* **Color Clustering & Filtering**: Ensures all extracted tones are distinct based on customizable Euclidean color distance.
* **Smart Visualization**: Displays a clean, neatly sorted visual grid of your colors, ordered automatically by human perceived brightness.

## Installation

You can install `pallete-picker` directly from PyPI inside your project's virtual environment:

```bash
pip install pallete-picker
```


## Quick Start Example

Here is how to load an image, extract its unique dominant colors, and display the final palette:

```python
from pallete_picker import process, tones, plot

# 1. Load your image file into a NumPy array
img_array = process("your_image.png")

if img_array is not None:
    # 2. Extract unique color tones (using a distance threshold of 5)
    unique_tones = tones(img_array, threshold=5)
    print(f"Found {len(unique_tones)} unique tones!")
    
    # 3. Visualize the grid ordered by color brightness
    plot(unique_tones)
```

```

## Core Functions Explained

### `process(path)`
Loads an image from the specified path, converts it safely to an RGBA format, and returns a processed NumPy multidimensional array. Returns `None` if the file path is invalid.

### `tones_fast(array, threshold=5)`
Analyzes the pixel structure using high-speed vector math (`np.linalg.norm`). It calculates color differences purely on standard RGB space. If a pixel color's mathematical distance is lower than the `threshold` value to an already saved color, it is skipped as a duplicate shade.

### `plot_palette(tones_list)`
Calculates an optimal grid layout to plot all solid color chips in a custom Matplotlib canvas window. It automatically embeds an internal helper function to sort the entire list by human perceived brightness:
$$\text{Brightness} = 0.299 \times R + 0.587 \times G + 0.114 \times B$$


