Metadata-Version: 2.4
Name: colorium
Version: 1.0.0
Summary: A comprehensive color manipulation library for Python
Author-email: Abolfazl Hosseini <tryuzr@gmail.com>
License: MIT License
Project-URL: Source Code, https://github.com/inject3r/colorium
Project-URL: Bug Tracker, https://github.com/inject3r/colorium/issues
Project-URL: Documentation, https://inject3r.github.io/colorium
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"

# Colorium

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-100%25-brightgreen)](https://github.com/inject3r/colorium)

A comprehensive, pure Python color manipulation library with support for 10+ color spaces, filters, and color distance calculations.

## Features

- **10+ Color Spaces**: RGB, HSL, HWB, CMYK, NCOL, OKLCH, LAB, LCH, Display P3
- **Color Filters**: Sepia, Grayscale, Invert, Contrast, Brightness, Saturation, Hue Rotation, Posterize, Temperature, Vignette
- **Filter Presets**: Clarendon, Gingham, Moon, Lark, Toaster, Valencia, Amaro (Instagram-style)
- **Color Distance**: CIE76, CIE94, CIEDE2000 (industry standard)
- **Color Similarity**: Perceptual similarity scoring (0.0 to 1.0)
- **Named Colors**: All 147 CSS named colors with case-insensitive lookup
- **Color Constants**: RED, BLUE, GREEN, WHITE, BLACK, and 100+ more
- **Multiple Formats**: Hex, RGB, HSL, HWB, CMYK, NCOL, OKLCH, LAB, LCH, P3
- **Zero Dependencies**: Pure Python, no external libraries required

## Installation

```bash
# Install from PyPI (when published)
pip install colorium

# Install in development mode
git clone https://github.com/inject3r/colorium.git
cd colorium
pip install -e ".[dev]"
```

## Quick Start

```python
from colorium import Color, from_string, RED, BLUE, WHITE, BLACK

# Create colors from various formats
red = Color(255, 0, 0)
blue = from_string("blue")
hex_color = from_string("#FF0000")
named = from_string("crimson")

# Use color constants
bg = WHITE
text = BLACK
primary = RED
secondary = BLUE

# Convert between color spaces
print(red.to_hsl_string())        # hsl(0, 100%, 50%)
print(red.to_hwb_string())        # hwb(0, 0%, 0%)
print(red.to_hex_string())        # #FF0000
print(red.to_cmyk_string())       # cmyk(0%, 100%, 100%, 0%)

# Get color values
hsl = red.to_hsl()                # {'h': 0, 's': 1.0, 'l': 0.5}
rgb = red.to_rgb()                # {'r': 255, 'g': 0, 'b': 0}

# Manipulate colors
red.lighter(0.3)                  # Make brighter
red.darker(0.2)                   # Make darker
red.saturate(0.5)                 # Increase saturation
red.desaturate(0.3)               # Decrease saturation

# Check if color is dark
if red.is_dark():
    print("Dark color!")

# Get color name
print(red.to_name())              # "Red"

# Blend colors
purple = RED.blend(BLUE, 0.5)    # Equal blend
pink = RED.blend(WHITE, 0.7)     # 70% white blend
```

## Color Filters

```python
from colorium import (
    Color,
    SepiaFilter,
    GrayscaleFilter,
    ContrastFilter,
    BrightnessFilter,
    FilterPresets
)

color = Color(200, 150, 100)

# Single filter
sepia = SepiaFilter(0.7)
result = sepia(color)

# Chain filters
from colorium import CompositeFilter
vintage = CompositeFilter([
    SepiaFilter(0.5),
    ContrastFilter(1.1),
    BrightnessFilter(0.9)
])
vintage_result = vintage(color)

# Use presets
clarendon = FilterPresets.clarendon()
clarendon_result = clarendon(color)

moon = FilterPresets.moon()      # Black and white
moon_result = moon(color)
```

## Color Distance and Similarity

```python
from colorium import Color

color1 = Color(100, 150, 200)
color2 = Color(120, 130, 180)

# Calculate color difference (Delta E)
distance = color1.delta_e(color2, "cie2000")
print(f"Delta E: {distance:.2f}")

# Get similarity score (0.0 to 1.0)
similarity = color1.similarity(color2)
print(f"Similarity: {similarity:.2f}")

# Check if colors are similar
if color1.is_similar_to(color2, threshold=0.8):
    print("Colors are very similar!")

# Different methods available
cie76 = color1.delta_e(color2, "cie76")
cie94 = color1.delta_e(color2, "cie94")
cie2000 = color1.delta_e(color2, "cie2000")
```

## Modern Color Spaces (CSS Color Level 4)

```python
from colorium import Color

# OKLCH - Perceptually uniform
color = Color.from_oklch(0.5, 0.2, 180)
print(color.to_oklch_string())   # oklch(50.0% 0.200 180.0)

# CIE L*a*b*
color = Color.from_lab(50, 20, -30)
print(color.to_lab_string())     # lab(50.0% 20.0 -30.0)

# CIE LCH
color = Color.from_lch(50, 30, 180)
print(color.to_lch_string())     # lch(50.0% 30.0 180.0)

# Display P3 Wide Gamut
color = Color.from_p3(0.8, 0.3, 0.5)
print(color.to_p3_string())      # color(display-p3 0.800 0.300 0.500)
```

## Color Constants

```python
from colorium import (
    RED, BLUE, GREEN, WHITE, BLACK,
    SUCCESS, ERROR, WARNING, INFO,
    FACEBOOK_BLUE, TWITTER_BLUE, YOUTUBE_RED,
    ORANGE, PURPLE, PINK, BROWN,
    LIGHT_BLUE, DARK_BLUE, NAVY, ROYAL_BLUE,
    LIGHT_GREEN, DARK_GREEN, FOREST_GREEN,
    TRANSPARENT
)

# Use constants directly
status = SUCCESS if valid else ERROR
bg = WHITE
text = BLACK

# Blend constants
purple = RED.blend(BLUE, 0.5)

# Use as defaults
def create_button(text: str, color: Color = PRIMARY):
    return {"text": text, "color": color}
```

## API Reference

### Color Class

| Method                                 | Description                                |
| -------------------------------------- | ------------------------------------------ |
| `Color(red, green, blue, opacity=1.0)` | Create from RGB                            |
| `to_rgb_string()`                      | RGB string: `rgb(255, 0, 0)`               |
| `to_rgba_string()`                     | RGBA string: `rgba(255, 0, 0, 0.5)`        |
| `to_hsl_string()`                      | HSL string: `hsl(0, 100%, 50%)`            |
| `to_hwb_string()`                      | HWB string: `hwb(0, 0%, 0%)`               |
| `to_cmyk_string()`                     | CMYK string: `cmyk(0%, 100%, 100%, 0%)`    |
| `to_hex_string()`                      | Hex string: `#FF0000`                      |
| `to_oklch_string()`                    | OKLCH string: `oklch(50% 0.2 180)`         |
| `to_lab_string()`                      | LAB string: `lab(50% 20 -30)`              |
| `to_lch_string()`                      | LCH string: `lch(50% 30 180)`              |
| `to_p3_string()`                       | P3 string: `color(display-p3 0.8 0.3 0.5)` |
| `to_name()`                            | CSS color name: `"Red"`                    |
| `to_rgb()`                             | RGB dict: `{'r': 255, 'g': 0, 'b': 0}`     |
| `to_hsl()`                             | HSL dict: `{'h': 0, 's': 1.0, 'l': 0.5}`   |
| `delta_e(other, method)`               | Color difference (CIE76, CIE94, CIEDE2000) |
| `similarity(other, method)`            | Similarity score (0.0 to 1.0)              |
| `is_similar_to(other, threshold)`      | Check similarity                           |
| `blend(other, ratio)`                  | Blend two colors                           |
| `is_dark(threshold=128)`               | Check if dark                              |
| `saturate(amount)`                     | Increase saturation                        |
| `desaturate(amount)`                   | Decrease saturation                        |
| `lighter(amount)`                      | Increase lightness                         |
| `darker(amount)`                       | Decrease lightness                         |
| `clone()`                              | Create a copy                              |

### Factory Functions

| Function                             | Description            |
| ------------------------------------ | ---------------------- |
| `from_string(color_str)`             | Parse any color string |
| `from_hex(hex_str)`                  | Create from hex        |
| `from_rgb(r, g, b, opacity=1.0)`     | Create from RGB        |
| `from_hsl(h, s, l, opacity=1.0)`     | Create from HSL        |
| `from_hwb(h, w, b, opacity=1.0)`     | Create from HWB        |
| `from_cmyk(c, m, y, k, opacity=1.0)` | Create from CMYK       |
| `from_oklch(l, c, h, opacity=1.0)`   | Create from OKLCH      |
| `from_lab(l, a, b, opacity=1.0)`     | Create from LAB        |
| `from_lch(l, c, h, opacity=1.0)`     | Create from LCH        |
| `from_p3(r, g, b, opacity=1.0)`      | Create from P3         |

### Filters

| Filter                                | Description           |
| ------------------------------------- | --------------------- |
| `SepiaFilter(intensity=1.0)`          | Warm sepia tone       |
| `GrayscaleFilter(method="luminance")` | Black and white       |
| `InvertFilter()`                      | Negative effect       |
| `ContrastFilter(amount=1.2)`          | Contrast adjustment   |
| `BrightnessFilter(amount=1.2)`        | Brightness adjustment |
| `SaturationFilter(amount=0.5)`        | Saturation adjustment |
| `HueRotateFilter(degrees=90)`         | Hue rotation          |
| `PosterizeFilter(levels=4)`           | Color quantization    |
| `TemperatureFilter(kelvin=5500)`      | Warm/cool shift       |
| `VignetteFilter(intensity=0.5)`       | Edge darkening        |

### Filter Presets

| Preset                      | Description                                |
| --------------------------- | ------------------------------------------ |
| `FilterPresets.clarendon()` | Increased contrast, brightness, saturation |
| `FilterPresets.gingham()`   | Warm, soft vintage                         |
| `FilterPresets.moon()`      | High-contrast black and white              |
| `FilterPresets.lark()`      | Cool, vibrant modern                       |
| `FilterPresets.toaster()`   | Warm, retro vintage                        |
| `FilterPresets.valencia()`  | Warm, soft vintage                         |
| `FilterPresets.amaro()`     | Rich, warm, slightly dark                  |

## Development

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=colorium

# Run specific test file
pytest tests/test_color.py

# Run specific test
pytest tests/test_color.py::TestColor::test_initialization
```

### Code Style

The project uses:

- **Black** for code formatting
- **Flake8** for linting
- **Mypy** for type checking

```bash
# Format code
black src/ tests/

# Run linter
flake8 src/ tests/

# Type check
mypy src/
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Author

**Abolfazl Hosseini**

- Email: tryuzr@gmail.com
- GitHub: [@inject3r](https://github.com/inject3r)

## Links

- [Source Code](https://github.com/inject3r/colorium)
- [Bug Tracker](https://github.com/inject3r/colorium/issues)
- [Documentation](https://inject3r.github.io/colorium)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Acknowledgments

- CSS Color Module Level 4 specification
- CIE color science standards
- Natural Color System (NCS) for NCOL notation
- Instagram filter effects for inspiration
