Metadata-Version: 2.4
Name: colorice
Version: 0.2.0
Summary: Perceptually accurate wallpaper-to-rice color scheme generator
Author-email: rattle99 <rattle99@users.noreply.github.com>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/rattle99/colorice
Project-URL: Repository, https://github.com/rattle99/colorice
Project-URL: Issues, https://github.com/rattle99/colorice/issues
Keywords: color-scheme,wallpaper,terminal,theming,pywal,oklab,rice
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: Pillow>=10.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scikit-image>=0.22
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Colorice

[![PyPI](https://img.shields.io/pypi/v/colorice?style=for-the-badge&logo=pypi&logoColor=white&color=bd93f9)](https://pypi.org/project/colorice/)
[![Python](https://img.shields.io/pypi/pyversions/colorice?style=for-the-badge&logo=python&logoColor=white&color=bd93f9)](https://pypi.org/project/colorice/)
[![License](https://img.shields.io/badge/license-GPL--3.0-bd93f9?style=for-the-badge)](LICENSE)

Colorice is a modern alternative to pywal that uses Oklab color space for perceptually accurate color extraction, generates multiple mood variants (vibrant, muted, warm, cool) to preview and select from, enforces WCAG contrast ratios, and applies schemes across your full desktop rice via a pywal-compatible template engine(yes existing pywal templates work) with color manipulation filters.

## Install

Requires Python 3.11+.

```bash
pipx install colorice
```

Or with pip:

```bash
pip install colorice
```

## Quick start

```bash
# Install default templates for common tools
colorice --init

# Generate a scheme and apply to your configured tools
colorice ~/wallpapers/sunset.jpg --apply
```

This will:
1. Extract dominant colors using over-cluster + farthest-first diversity selection
2. Generate 4 palette variants (vibrant, muted, warm, cool)
3. Preview them in your terminal — pick one
4. Write the scheme to `~/.local/share/colorice/colors.json`
5. Render configured templates and reload your apps

## Options

```
colorice <image> [options]

Extraction:
  -c, --colors N            Dominant colors to extract (3-16, default: 8)
  --segment                 Region-aware extraction via Felzenszwalb segmentation

Palette:
  -m, --moods MOOD[,...]    Mood names (default: vibrant,muted,warm,cool)
  --min-contrast RATIO      Min fg/bg contrast ratio (default: 7.0)
  --semantic                Enforce ANSI color name conventions (red=red, etc.)
  --light                   Light theme

Output:
  -o, --output PATH         Output JSON path (default: ~/.local/share/colorice/colors.json)
                            Use -o - for stdout
  --no-preview              Skip preview, output first palette
  -q, --quiet               Suppress all output except errors

Templates:
  -a, --apply               Apply scheme to configured templates
  --config PATH             Path to config.toml
  --dry-run                 Preview template output without writing files
  --no-hooks                Skip post-apply hooks
  --init                    Install default templates and exit

Info:
  --list-moods              List available mood names and exit
  -v, --version             Show version and exit
```

## Examples

```bash
# Generate and interactively select a scheme
colorice ~/wallpapers/sunset.jpg

# Generate, select, and apply to all configured tools
colorice ~/wallpapers/sunset.jpg --apply

# Quiet mode, pipe JSON to stdout
colorice ~/wallpapers/ocean.png -q -o -

# Light theme with specific moods
colorice wallpaper.jpg --light -m vibrant,cool

# Region-aware extraction (better for complex images)
colorice wallpaper.jpg --segment --apply

# Re-apply existing scheme to templates (no image needed)
colorice --apply

# Preview template output without writing
colorice wallpaper.jpg --dry-run --apply
```

## Template system

Colorice includes a pywal-compatible template engine. Templates use `{color0}` through `{color15}`, `{background}`, `{foreground}`, `{cursor}`, and `{wallpaper}` placeholders.

### Setup

```bash
# Install bundled templates for common tools
colorice --init
```

This copies templates to `~/.config/colorice/templates/` for: kitty, alacritty, foot, ghostty, wezterm, hyprland, i3, sway, rofi, dunst, mako, waybar, polybar, swaylock, zellij, neovim, vim, cava, xresources, and shell variables.

### Configuration

Edit `~/.config/colorice/config.toml` to map templates to output paths:

```toml
[[templates]]
name = "kitty"
input = "kitty.conf"
output = "~/.config/kitty/current-theme.conf"
hook = "killall -USR1 kitty"

[[templates]]
name = "hyprland"
input = "hyprland-colors.conf"
output = "~/.config/hypr/colorice-colors.conf"
```

Then add the include directive in your app config (one-time setup):
- Kitty: `include ~/.config/kitty/current-theme.conf`
- Alacritty: `import = ["~/.config/alacritty/colorice-theme.toml"]`
- Hyprland: `source = ~/.config/hypr/colorice-colors.conf`
- i3/Sway: `include ~/.config/i3/colorice-colors.conf`
- See each template file for tool-specific instructions.

### Color manipulation

Templates support Oklab color manipulation filters for deriving colors beyond the base 16:

```
{color4.lighten_20}           Increase lightness by 0.20
{color0.darken_10}            Decrease lightness by 0.10
{color1.saturate_15}          Increase chroma by 0.15
{color5.desaturate_10}        Decrease chroma by 0.10
{color4.lighten_20.strip}     Manipulation + format modifier
```

Manipulations can be chained — they apply left to right:

```
{color4.lighten_20.saturate_10.strip}
{color0.darken_10.desaturate_5}
```

Format modifiers (always last in the chain):
- `.strip` — hex without `#` (`1a2b3c`)
- `.red`, `.green`, `.blue` — integer channel value (0-255)
- `.rgb` — `rgb(26,43,60)`
- `.rgba` — `rgba(26,43,60,1.0)`

## How it works

1. **Extract** — loads the image, resizes for performance, runs KMeans clustering in Oklab color space. Over-clusters to 4x the requested count, then uses farthest-first selection for maximum perceptual diversity. Optionally uses Felzenszwalb segmentation for region-aware extraction.
2. **Cache** — extraction results are cached by image content hash + params in `~/.cache/colorice/`. Same wallpaper with same settings skips re-extraction.
3. **Mood transform** — adjusts chroma, lightness, and hue for the selected mood variant.
4. **Assign roles** — maps colors to 16 ANSI slots. In default (aesthetic) mode, sorts by chroma for wallpaper-matching palettes. In `--semantic` mode, enforces hue-zone mapping (red=slot 1, green=slot 2, etc.).
5. **Enforce contrast** — binary search on Oklab lightness to meet WCAG contrast ratios against the background.
6. **Validate** — warns about any ANSI color pairs that are too similar (pairwise Oklab distance check).
7. **Apply** — renders templates with the scheme and runs post-apply hooks.

## File locations (XDG-compliant)

```
~/.config/colorice/
  config.toml            Template configuration
  templates/             Template files

~/.local/share/colorice/
  colors.json            Generated scheme

~/.cache/colorice/
  <hash>.json            Extraction cache
```

Respects `$XDG_CONFIG_HOME`, `$XDG_DATA_HOME`, and `$XDG_CACHE_HOME`.

## Development

```bash
git clone https://github.com/rattle99/colorice.git
cd colorice
pip install -e ".[dev]"
pytest
```

## License

GPL-3.0
