https://github.com/t-dynamos/materialyoucolor-python
Material You color generation algorithms in python.
https://github.com/t-dynamos/materialyoucolor-python
color color-palette color-scheme dynamic-color dynamic-theme dynamic-wallpaper kivy kivymd material-you palette python
Last synced: 23 days ago
JSON representation
Material You color generation algorithms in python.
- Host: GitHub
- URL: https://github.com/t-dynamos/materialyoucolor-python
- Owner: T-Dynamos
- License: mit
- Created: 2023-04-16T13:28:20.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-08-18T03:20:51.000Z (over 1 year ago)
- Last Synced: 2024-12-09T13:49:44.721Z (over 1 year ago)
- Topics: color, color-palette, color-scheme, dynamic-color, dynamic-theme, dynamic-wallpaper, kivy, kivymd, material-you, palette, python
- Language: Python
- Homepage:
- Size: 227 KB
- Stars: 40
- Watchers: 4
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [Material You color algorithms](https://m3.material.io/styles/color/overview) for python!
It is built in reference with offical [typescript implementation](https://github.com/material-foundation/material-color-utilities/tree/main/typescript) except it's color quantization part, which is based on [c++ implementation](https://github.com/material-foundation/material-color-utilities/tree/main/cpp) thanks to [pybind](https://github.com/pybind).
## Features
1. Up to date with `material-foundation/material-color-utilities`.
2. Uses official c++ sources for quantization backend, which makes color generation fast!
## Minimal running example:
Run file `tests/test_all.py` as:
```console
usage: test_all.py [-h] [--tonal-spot] [--expressive] [--fidelity] [--fruit-salad] [--monochrome] [--neutral] [--rainbow] [--vibrant]
[--content] [--all] [--image IMAGE] [--quality QUALITY] [--method {pillow,cpp}]
Material You Color Scheme Test
options:
-h, --help show this help message and exit
--tonal-spot Print the tonal-spot dynamic scheme
--expressive Print the expressive dynamic scheme
--fidelity Print the fidelity dynamic scheme
--fruit-salad Print the fruit-salad dynamic scheme
--monochrome Print the monochrome dynamic scheme
--neutral Print the neutral dynamic scheme
--rainbow Print the rainbow dynamic scheme
--vibrant Print the vibrant dynamic scheme
--content Print the content dynamic scheme
--all Print all dynamic schemes (default)
--image IMAGE Path to an image file for color extraction
--quality QUALITY Quality for image quantization (default: 5)
--method {pillow,cpp}
Method for color quantization (default: cpp)
```
Click to view result
[Image Used, size was 8MB](https://unsplash.com/photos/zFMbpChjZGg/)
It is recommended to use the `cpp` backend, as the `pillow` backend is extremely memory-inefficient for large images.
Newer Pillow APIs such as `Image.get_flattened_data()` eagerly materialize the entire image into a full list,
so quality-based subsampling is applied only after full expansion and does not reduce memory usage.
While `Image.getdata()` allows sampling during iteration, it is deprecated.
The `cpp` backend avoids these issues by operating directly on compact pixel buffers.
## Usage
### Install
You can easily install it from pip by executing:
```console
pip3 install materialyoucolor --upgrade
```
Prebuilt binaries are avaliable for `linux`, `windows` and `macos`. If prebuilt binaries aren't available, then you should manually build and install.
### Build and install
```console
# Install
pip3 install https://github.com/T-Dynamos/materialyoucolor-python/archive/master.zip
```
### OS Specific
#### Arch Linux (OUTDATED)
```console
yay -S python-materialyoucolor
```
Thanks :heart: to [@midn8hustlr](https://github.com/midn8hustlr) for this [AUR package](https://aur.archlinux.org/cgit/aur.git/?h=python-materialyoucolor-git).
#### Android (using kivy's [`buildozer`](https://github.com/kivy/buildozer))
Ensure these lines in `buildozer.spec`:
```python
requirements = materialyoucolor==3.0.0
p4a.branch = develop
```
#### IOS (using kivy's [`kivy-ios`](https://github.com/kivy/kivy-ios))
Install latest version of kivy-ios and use as:
```console
toolchain build materialyoucolor
```
## Usage examples
Click to show
- Generate non dynamic colors
```python
from materialyoucolor.scheme import Scheme
from materialyoucolor.scheme.scheme_android import SchemeAndroid
# Color is a an int, which is made as:
# 0xff + hex_code (without #)
# Eg: 0xff + #4181EE = 0xff4181EE
# To convert hex to this form, do `int("0xff" + "", 16)`
color = 0xff4181EE
print(Scheme.light(color).props)
print(Scheme.dark(color).props)
# Props is a dict, key is color name and value is rgba format list
# {'primary': [0, 90, 195, 255], 'onPrimary': ....
# Same way for android
print(SchemeAndroid.light(color).props)
print(SchemeAndroid.dark(color).props)
```
- Generate dynamic colors
```python
# Color in hue, chroma, tone form
from materialyoucolor.hct import Hct
from materialyoucolor.dynamiccolor.color_spec import COLOR_NAMES
from materialyoucolor.dynamiccolor.material_dynamic_colors import MaterialDynamicColors
# There are 9 different variants of scheme.
from materialyoucolor.scheme.scheme_tonal_spot import SchemeTonalSpot
# Others you can import: SchemeExpressive, SchemeFruitSalad, SchemeMonochrome, SchemeRainbow, SchemeVibrant, SchemeNeutral, SchemeFidelity and SchemeContent
# SchemeTonalSpot is android default
scheme = SchemeTonalSpot( # choose any scheme here
Hct.from_int(0xff4181EE), # source color in hct form
True, # dark mode
0.0, # contrast
spec_version="2025"
)
mdc = MaterialDynamicColors(spec="2025")
for color in COLOR_NAMES:
_color = getattr(mdc, color)
print(color, _color.get_rgba(scheme), _color.get_hex(scheme))
# background [13, 14, 18, 255] #0D0E12FF
# onBackground [227, 229, 240, 255] #E3E5F0FF
# surface [13, 14, 18, 255] #0D0E12FF
# surfaceDim [13, 14, 18, 255] #0D0E12FF
# surfaceBright [41, 44, 52, 255] #292C34FF
# surfaceContainerLowest [0, 0, 0, 255] #000000FF
# surfaceContainerLow [17, 19, 24, 255] #111318FF
# surfaceContainer [23, 25, 31, 255] #17191FFF
# surfaceContainerHigh [29, 31, 38, 255] #1D1F26FF
# surfaceContainerHighest [35, 38, 45, 255] #23262DFF
# onSurface [227, 229, 240, 255] #E3E5F0FF
# surfaceVariant [35, 38, 45, 255] #23262DFF
# onSurfaceVariant [196, 198, 208, 255] #C4C6D0FF
# outline [142, 144, 154, 255] #8E909AFF
...
```
- Generate and score colors from image
```python
from materialyoucolor.quantize import QuantizeCelebi, ImageQuantizeCelebi
from materialyoucolor.score.score import Score
# Pixel subsampling factor (quality = 1 processes all pixels)
quality = 1
# Run Celebi color quantization on an image.
# Returns a dict: {ARGB_color_int: population}
result = ImageQuantizeCelebi(
"example.jpg",
quality,
128, # maximum number of colors
)
print(result)
# Rank and select the best theme colors.
# Returns a list of ARGB color integers.
selected_colors = Score.score(result)
print(selected_colors)
# {4278911493: 276721,
# 4280550664: 164247,
# 4280683034: 144830,
# ...
```
## Gallery
These are some libraries which use this library for color generattion.
* [`dots-hyprland`](https://github.com/end-4/dots-hyprland)
* [`kde-material-you-colors`](https://github.com/luisbocanegra/kde-material-you-colors)
* [`EarthFM CLONE`]
> This is my private project where the theme colors change based on the album art.
## FAQ
1. How it is different from `avanisubbiah/material-color-utilities`?
This library is up to date, fast, and uses a hybrid system for image generation.