vikpe/chromato

Color utilities for Python.

🍅 chromato

Fresh color utilities for Python

• Color spaces: CMYK, HEX, RGB, HSL, HSV
• Color class: Convenience class for color manipulation
• Operations: shade, tone, tint, grayscale, invert, complement, add, subtract, multiply
• Conversion: Convert any color space to any color space
• Parsing
• Validation
• (zero dependecies!)

Install

pip install chromato

Example usage

Color class

from chromato.spaces import Color

red = Color(255, 0, 0)

red.cmyk  # CMYK(c=0, m=100, y=100, k=0)
red.hex   # HEX(ff0000)
red.rgb   # RGB(r=255, g=0, b=0)
red.hsl   # HSL(h=0, s=1, l=0.5)
red.hsv   # HSV(h=0, s=1, v=1)

Operations

from chromato import operations
from chromato.spaces import RGB

red = RGB(255, 0, 0)
blue = RGB(0, 0, 255)

operations.add(red, blue)        # RGB(r=255, g=0, b=255)
operations.blend(red, blue).rgb  # RGB(r=128, g=0, b=128)
operations.invert(red).rgb       # RGB(r=0, g=255, b=255)
operations.tint(red, 0.1).rgb    # RGB(r=255, g=26, b=26)

Conversion

from chromato import convert

convert.rgb_to_hex(255, 0, 0)  # HEX(ff0000)
convert.hex_to_rgb("ff0000")   # RGB(r=255, g=0, b=0)
convert.hex_to_cmyk("f0f")     # CMYK(c=0, m=100, y=0, k=0)

API

Color spaces

Name	Properties	Range
CMYK	c, m, y, k	0-100, 0-100, 0-100, 0-100
HEX	(is a string)	000000-ffffff
HSL	h, s, l	0-1, 0-1, 0-1
HSV	h, s, v	0-1, 0-1, 0-1
RGB	r, g, b	0-255, 0-255, 0-255

from chromato.spaces import CMYK, HEX, HSL, HSV, RGB

red_cmyk = CMYK(0, 100, 100, 0)
red_hex  = HEX("ff0000")
red_hsl  = HSL(0, 1, 0.5)
red_hsv  = HSV(0, 1, 1)
red_rgb  = RGB(255, 0, 0)

Color class

Properties

from chromato.spaces import Color

red = Color(255, 0, 0)

red.cmyk  # CMYK(c=0, m=100, y=100, k=0)
red.hex   # HEX(ff0000)
red.hsl   # HSL(h=0, s=1, l=0.5)
red.hsv   # HSV(h=0, s=1, v=1)
red.rgb   # RGB(r=255, g=0, b=0)

Construct

# examples below are equal
Color(255, 0, 0)
Color((255, 0, 0))
Color([255, 0, 0])
Color({"r": 255, "g": 0, "b": 0})
Color("ff0000")
Color("ff0")
Color(Color(255, 0, 0))
Color(RGB(255, 0, 0))
Color(HEX("ff0"))
Color(HSV(0, 1, 1))
Color(HSL(0, 1, 0.5))
Color(CMYK(0, 100, 100, 0))

Operations

Each operation take one or several color values and returns a Color instance.

Operation	Description
add(color1, color2)	Add colors
blend(color1, color2, factor)	Blend/mix colors
complement(color)	Complementary color
hsv_mod(color, hue_shift, saturation_shift, value_shift)	HSV modification
invert(color)	Invert color
multiply(color1, color2)	Multiply colors
shade(color, factor)	Increase darkness (blend with black)
subtract(color1, color2)	Subtract colors
tint(color, factor)	Increase lightness (blend with white)
tone(color, factor)	Reduce colorfullness (blend with gray)

• Arguments: color<any>, factor <float> [0-1]
• Returns: instance of Color

Example

from chromato.spaces import RGB
from chromato.operations import blend, invert

white = RGB(255, 255, 255)
black = RGB(0, 0, 0)

blend(white, black).rgb       # RGB(r=128, g=128, b=128)
blend(white, black, 0.2).rgb  # RGB(r=204, g=204, b=204)
blend(white, black, 0.8).rgb  # RGB(r=51, g=51, b=51)

invert(black).rgb             # RGB(r=255, g=255, b=255)
invert((255, 0, 0)).cmyk      # CMYK(c=0, m=100, y=100, k=0)
invert("ff0000").hex          # HEX(00ffff)

Conversion

Convert any color space to any color space.

🔀	RGB	HEX	CMYK	HSL	HSV
RGB		hex_to_rgb	cmyk_to_rgb	hsl_to_rgb	hsv_to_rgb
HEX	rgb_to_hex		cmyk_to_hex	hsl_to_hex	hsv_to_hex
CMYK	rgb_to_cmyk	hex_to_cmyk		hsl_to_cmyk	hsv_to_cmyk
HSL	rgb_to_hsl	hex_to_hsl	cmyk_to_hsl		hsv_to_hsl
HSV	rgb_to_hsv	hex_to_hsv	cmyk_to_hsv	hsl_to_hsv

Example

from chromato import convert

convert.rgb_to_cmyk(255, 0, 0)  # CMYK(c=0, m=100, y=100, k=0)
convert.rgb_to_hex(255, 0, 0)   # HEX(ff0000)
convert.rgb_to_hex(255, 0, 0)   # HEX(ff0000)
convert.rgb_to_hsl(255, 0, 0)   # HSL(h=0, s=1, l=0.5)
convert.rgb_to_hsv(255, 0, 0)   # HSV(h=0, s=1, v=1)

Parsing

Each parse function takes any kind of value and tries to parse it.

Function	Returns	Description
parse_cmyk(value)	tuple(c,m,y,k)	Parse value as CMYK
parse_hex(value)	str(hex)	Parse value as HEX
parse_hsl(value)	tuple(h,l,s)	Parse value as HSL
parse_hsv(value)	tuple(h,s,v)	Parse value as HSV
parse_rgb(value)	tuple(r,g,b)	Parse value as RGB

Example

from chromato import parse
from chromato.spaces import Color, HEX, RGB

parse.parse_hex("f")                 # "ffffff"
parse.parse_hex("f60")               # "ff6600"
parse.parse_hex("ff6600")            # "ff6600"
parse.parse_hex(" #ff6600 ")         # "ff6600"
parse.parse_hex(333)                 # "333333"
parse.parse_hex(HEX("ff6600"))       # "ff6600"
parse.parse_hex(RGB(255, 102, 0))    # "ff6600"
parse.parse_hex(Color(255, 102, 0))  # "ff6600"

Validation

Each validation function validates type and range. Returns True/False.

from chromato import validation

validation.is_cmyk(c, m, y, k)
validation.is_hex(hex)
validation.is_hsl(h, s, l)
validation.is_hsv(h, s, v)
validation.is_rgb(r, g, b)

Development

Setup

1. Install poetry
2. poetry install

Tests

Run tests on changes in source code or tests.

poetry run ptw --clear --runner "poetry run pytest --cov -vv" 

Code formatting (black)

poetry run black .