materialyoucolor 3.0.2

Material You color generation algorithms in pure python!

Material You color algorithms for python!

It is built in reference with offical typescript implementation except it's color quantization part, which is based on c++ implementation thanks to 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:

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

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:

pip3 install materialyoucolor --upgrade

Prebuilt binaries are avaliable for linux, android, windows and macos. If prebuilt binaries aren't available, then you should manually build and install.

Build and install

# Install 
pip3 install https://github.com/T-Dynamos/materialyoucolor-python/archive/master.zip

OS Specific

Arch Linux (OUTDATED)

yay -S python-materialyoucolor

Thanks :heart: to @midn8hustlr for this AUR package.

Android (using kivy's buildozer)

Ensure these lines in buildozer.spec:

requirements = materialyoucolor==3.0.2
p4a.branch = develop

IOS (using kivy's kivy-ios)

Install latest version of kivy-ios and use as:

toolchain build materialyoucolor

Usage examples

Click to show

• Generate non dynamic colors

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" + "<hex code>", 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

# 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

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

• 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.