https://github.com/jolars/qualpal-py
A Python package for automatic generation of qualitative color palettes
https://github.com/jolars/qualpal-py
colors data-visualization palette-generation
Last synced: 9 days ago
JSON representation
A Python package for automatic generation of qualitative color palettes
- Host: GitHub
- URL: https://github.com/jolars/qualpal-py
- Owner: jolars
- License: mit
- Created: 2026-01-06T15:00:15.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-01-29T15:49:45.000Z (2 months ago)
- Last Synced: 2026-01-30T04:29:18.869Z (2 months ago)
- Topics: colors, data-visualization, palette-generation
- Language: Python
- Homepage: https://jolars.github.io/qualpal-py/
- Size: 634 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# Qualpal 
[](https://github.com/jolars/qualpal-py/actions/workflows/test.yml)
[](https://codecov.io/github/jolars/qualpal-py)
[](https://badge.fury.io/py/qualpal)
[](https://doi.org/10.21105/joss.08936)
[](https://qualpal.cc)
Automatically generate qualitative color palettes with distinct, perceptually uniform colors.
## Installation
Qualpal will soon be available on PyPI. In the meantime, you can install it directly from source,
but note that this requires a C++ compiler.
```bash
# Core functionality
pip install git+https://github.com/jolars/qualpal-py
# With visualization support
pip install git+https://github.com/jolars/qualpal-py[viz]
```
## Quick Start
```python
from qualpal import Qualpal
# Generate 6 distinct colors
qp = Qualpal()
palette = qp.generate(6)
# Display colors
print(palette.hex())
# ['#f68ec8', '#233604', '#15045a', '#13cbf6', '#ebf919', '#e84123']
# Export for CSS
css = palette.to_css(prefix="theme")
# ['--theme-1: #f68ec8;', '--theme-2: #233604;', ...]
# Visualize (requires matplotlib)
palette.show(labels=True)
```
## Key Features
- 🎨 **Smart Color Generation** - Automatically selects maximally distinct colors
- 🎯 **Customizable** - Control hue, saturation, lightness ranges
- ♿ **Accessible** - CVD (color vision deficiency) simulation and optimization
- 📊 **Analysis** - Measure perceptual distances between colors
- 📤 **Export** - CSS, JSON, and matplotlib visualization
- 📓 **Jupyter** - Rich HTML display in notebooks
- 🚀 **Fast** - C++ backend with Python interface
## Examples
### Customize Color Space
```python
# Pastel colors
qp = Qualpal(colorspace={"h": (0, 360), "s": (0.3, 0.6), "l": (0.7, 0.9)})
pastels = qp.generate(5)
```
### CVD-Aware Palettes
```python
# Generate palette safe for deuteranomaly
qp = Qualpal(cvd={"deutan": 0.7})
accessible = qp.generate(6)
```
### Color Operations
```python
from qualpal import Color
# Create and convert colors
color = Color("#ff0000")
print(color.rgb()) # (1.0, 0.0, 0.0)
print(color.hsl()) # (0.0, 1.0, 0.5)
print(color.lab()) # (53.24, 80.09, 67.20)
# Measure perceptual distance
red = Color("#ff0000")
orange = Color("#ff6600")
distance = red.distance(orange) # 33.42
```
## Documentation
The full documentation is available at .
## Contributing
Contributions are welcome!
Note that the main functionality comes from the underlying C++ library,
which is developed and maintained at .
So if you want to contribute to the core algorithms, please do so there.
## License
Qualpal is licensed under the [MIT license](LICENSE)
## Citation
If you use Qualpal in your research, please cite the following paper:
> Larsson, J. (2025). Qualpal: Qualitative Color Palettes for Everyone.
> _Journal of Open Source Software_, 10(114), 8936.
> [https://doi.org/10.21105/joss.08936](https://doi.org/10.21105/joss.08936)