Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/vikpe/chromato

Color utilities for Python.
https://github.com/vikpe/chromato

cmyk colors hex hls hsv python rgb

Last synced: about 2 months ago
JSON representation

Color utilities for Python.

Host: GitHub
URL: https://github.com/vikpe/chromato
Owner: vikpe
License: mit
Created: 2021-10-03T13:38:58.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2022-07-18T19:07:52.000Z (over 2 years ago)
Last Synced: 2024-04-15T01:43:47.581Z (9 months ago)
Topics: cmyk, colors, hex, hls, hsv, python, rgb
Language: Python
Homepage:
Size: 113 KB
Stars: 2
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        


    🍅 chromato

    

        Fresh color utilities for Python

    


[![test](https://github.com/vikpe/chromato/actions/workflows/test.yml/badge.svg)](https://github.com/vikpe/chromato/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/vikpe/chromato/branch/main/graph/badge.svg)](https://codecov.io/gh/vikpe/chromato)






* [**Color spaces**](#color-spaces): CMYK, HEX, RGB, HSL, HSV

* [**Color class**](#color-class): Convenience class for color manipulation

* [**Operations**](#operations): shade, tone, tint, grayscale, invert, complement, add, subtract, multiply

* [**Conversion**](#conversion): Convert any color space to any color space

* [Parsing](#parsing)

* [Validation](#validation)

* (zero dependecies!)




# Install

```shell

pip install chromato

```




# Example usage

**Color class**

```python

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**

```python

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**

```python

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`

```python

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**

```python

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**

```python

# 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`, `factor  [0-1]`

* **Returns**: instance of `Color`

**Example**

```python

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**

```python

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**

```python

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

```python

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](https://github.com/python-poetry/poetry)

2. `poetry install`

**Tests**

Run tests on changes in source code or tests.

```shell

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

```

**Code formatting (black)**

```shell

poetry run black . 

```