Metadata-Version: 2.4
Name: principal-colors
Version: 0.2.0
Summary: A dead-simple tool to extract a strong, distinct palette from any image.
Author: Niall Miller
License-Expression: MIT
Project-URL: Homepage, https://github.com/nialljmiller/principal_colors
Project-URL: Issues, https://github.com/nialljmiller/principal_colors/issues
Project-URL: Source, https://github.com/nialljmiller/principal_colors
Project-URL: Documentation, https://github.com/nialljmiller/principal_colors/blob/main/docs/API.md
Keywords: color,palette,image,oklab,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: Pillow>=10.0
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Dynamic: license-file

# principal_colors

`principal_colors` is a dead-simple tool to extract a strong, distinct palette from any image.

It is designed around one obvious path for normal users:

```bash
principal-colors path/to/image.jpg
```

That prints the palette to stdout and also writes a single JSON file next to the image, such as:

```text
image.palette.json
```

Under the hood, it uses OKLab distances and can optionally account for common color-vision deficiencies, but those are secondary features rather than the headline.

## Why this rewrite

This package has been rewritten around a simpler public UX:

- standard CLI flags instead of `key=value`
- a positional image path
- no import-time side effects
- a clean Python API for both simple and detailed use
- a small dependency footprint: just NumPy and Pillow
- feature-rich advanced exports without cluttering the default experience

## Installation

From PyPI:

```bash
pip install principal-colors
```

From a local checkout:

```bash
pip install .
```

For development:

```bash
python -m pip install -e '.[dev]'
```

## Command line usage

The basic path is:

```bash
principal-colors image.jpg
```

That will:

- print the palette as hex colors to stdout
- save `image.palette.json`

### Basic examples

```bash
principal-colors image.jpg
principal-colors image.jpg --colors 10
principal-colors image.jpg --stdout-only
principal-colors image.jpg --output my_palette.json
```

### Advanced examples

```bash
principal-colors image.jpg --cb-mode all
principal-colors image.jpg --save-formats json,svg,png --output-prefix out/palette
principal-colors image.jpg --print-format rgb
principal-colors image.jpg --details
```

### No arguments

If you run:

```bash
principal-colors
```

it shows an overview, a manual, and an ASCII logo.

## Python API

The simple API returns hex colors by default:

```python
from principal_colors import extract_palette

colors = extract_palette("image.jpg")
print(colors)
```

You can ask for other return types:

```python
from principal_colors import extract_palette

rgb_colors = extract_palette("image.jpg", return_format="rgb")
result = extract_palette("image.jpg", return_format="result")
```

Or use the detailed API directly:

```python
from principal_colors import extract_palette_result

result = extract_palette_result("image.jpg", num_colors=10)
print(result.hex_colors)
print(result.rgb_colors)
print(result.oklab_colors)
result.save()  # writes image.palette.json
result.save_many(["json", "svg", "png"], output_prefix="out/palette")
```

## Public low-level helpers

The lower-level functions are intentionally public, so advanced users can do things like:

```python
from principal_colors import rgb_to_oklab, oklab_to_rgb, simulate_cb
```

## Output formats

The package can write:

- JSON
- TXT
- CSV
- SVG
- PNG swatches
- CSS variables
- Tailwind JSON
- Matplotlib style files
- GIMP palette files

The default automatic save format is JSON because it is a reasonable, machine-readable single-file default.

## API docs

A small API reference lives in [`docs/API.md`](docs/API.md).

## Development

Run checks with:

```bash
ruff check .
pytest
python -m build
python -m twine check dist/*
```

## License

MIT.
