Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nickythelion/ciris
A lightweight native Python library that makes working with color easier
https://github.com/nickythelion/ciris
color color-processing python python-3 python-3-10 python-3-11 python-3-8 python-3-9 python3
Last synced: 19 days ago
JSON representation
A lightweight native Python library that makes working with color easier
- Host: GitHub
- URL: https://github.com/nickythelion/ciris
- Owner: nickythelion
- License: mit
- Created: 2022-10-05T17:49:22.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2022-11-12T07:25:57.000Z (about 2 years ago)
- Last Synced: 2024-11-17T01:20:17.688Z (about 1 month ago)
- Topics: color, color-processing, python, python-3, python-3-10, python-3-11, python-3-8, python-3-9, python3
- Language: Python
- Homepage:
- Size: 48.8 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Ciris
Ciris is a lightweight library that specializes on working with color.
The package does not rely on any third-party dependencies.
The name of a library is the first letter of the word "color" and the name of the Greek goddess of color, Iris, if you were interested :)
# Color class
Ciris provides a handy Color class that provides functionality for working with color.
This class stores the color in HSV color space and allows the end user the greater
flexibility while modifying the color.
## Creating a Color class using HSV values
Since the Color class uses HSV, the default constructor is set up to accept HSV values directly:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color(hue, saturation, value)
```
You can also use the built-in function `Color.from_hsv()` to construct the Color object.
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
```
In this case, both methods are equivalent. The latter was added for the sake of consistency with the other constructors.
## Creating a Color object using RGB values
The Color object provides a `Color.from_rgb()` function which can be used to create Color object from RGB band values, like this:
```python
from ciris import Color
r, g, b = 100, 0, 255
c = Color.from_rgb(r, g, b)
```
## Creating a Color object using CMYK values
In case you need to create a Color object from CMYK values, you can use the `Color.from_cmyk()` method:
```python
from ciris import Color
c, m, y, k = 15, 0, 45, 2
c = Color.from_cmyk(c, m, y, k)
```
Note that CMYK values should be integers in range [0..100], not floats. For example, a CMYK color defined as (45%, 11%, 0%, 56%) should be passed as `c=45, m=11, y=0, k=56`
## Creating a Color object using a hex-string
If you have a hex-string you can use the built-in `Color.from_hex()` method to create a Color object:
```python
from ciris import Color
my_hex_str = "#00FF56"
c = Color.from_hex(my_hex_str)
```
Note that `Color.from_hex()` method only accepts a 7-symbol hex-string (a pound sign, 2 symbols for red, 2 symbols for green, 2 symbols for blue). Other variations, such as ARGB, are not yet supported.
## Representing the color as HSV
Since the HSV space is the space that the Color object uses to store data, no conversion is necessary.
To represent the color as HSV values, simply call the `Color.as_hsv()` method:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
hsv_tuple = c.as_hsv()
```
This method returns a tuple with the signature `(hue_value, saturation_value, value_value)`
## Representing the color as RGB
To convert the current color to RGB, simply call the `Color.as_rgb()` method:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
rgb_tuple = c.as_rgb()
```
This method returns a tuple with the signature `(r_value, g_value, b_value)`.
## Representing the color as CMYK
To convert the current color to CMYK, call the `Color.as_cmyk()` method:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
cmyk_tuple = c.as_cmyk()
```
This method returns a tuple with the signature `(c_value, m_value, y_value, k_value)`. Note that these values are integers in range [0..100].
## Altering the hue of the color
To alter the color's hue, use the `Color.hue_shift()` method. The method takes a required positional argument `amount: int`, which specifies the amount in degrees on a color wheel that the hue will be shifted by.
For example, this code will shift the color's hue by 30 degrees clockwise:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.hue_shift(30)
print(c.as_hsv()) # (290, 90, 90)
```
You can also pass a negative integer into the method to shift the hue counterclockwise. For example, the code below shifts the color's hue by 60 degrees counterclockwise:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.hue_shift(-60)
print(c.as_hsv()) # (200, 90, 90)
```
Since the hue is always in range [0..360], the method will account for this. An example:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.hue_shift(120) # The shift has caused the hue to become out of acceptable range
# The hue is a representation of a color wheel, which cannot be more than 360deg, so the method has corrected the hue
print(c.as_hsv()) # (20, 90, 90)
```
The same logic works for negative shifts.
## Altering the saturation of the color
To alter the color's saturation, use the `Color.adjust_saturation()` method. It takes a required positional argument `amount: int`, that indicated the amount that the saturation needs to be adjusted by.
For example, this code below raises the color's saturation by 5%:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.adjust_saturation(5)
print(c.as_hsv()) # (260, 95, 90)
```
You can also pass a negative integer to lower the saturation level:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.adjust_saturation(-10)
print(c.as_hsv()) # (260, 80, 90)
```
Since the saturation level should always be in range [0..100], the method will cap any excessive adjustment:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.adjust_saturation(60000)
# The saturation has only been raised by 10 due to it being capped
print(c.as_hsv()) # (260, 100, 90)
```
## Altering the color's value
To adjust color's value, use the `Color.lighten()` and `Color.darken()` methods to lighten and darken the color respectively:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.lighten(10)
print(c.as_hsv()) # (200, 90, 100)
```
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.darken(60)
print(c.as_hsv()) # (260, 90, 30)
```
These methods do accept negative integers. In that case their functionality is reversed.
Since the value should always be in range [0..100], the method will cap any excessive adjustment:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.lighten(10000)
print(c.as_hsv()) # (200, 90, 100)
```
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.darken(600000)
print(c.as_hsv()) # (260, 90, 0)
```
## Inverting the color
To invert the color, use the `Color.invert()` method:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
c.invert()
print(c.as_hsv()) # (80, 90, 90)
```
## Applying complementary harmony rule to the color
To apply the complementary rule to the current color, use `Color.harmony_complementary()` method:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
rule = c.harmony_complementary()
```
This method returns a [HarmonyRule](#harmonyrule-class) object.
## Applying split complementary harmony rule to the color
To apply the split complementary rule to the current color, use `Color.harmony_split_complementary()` method. You can also pass an optional argument `phi: int` that indicates the offset in degrees that will be used. By default it is 150deg:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
rule = c.harmony_split_complementary(phi=40) # The offset used is 40deg
```
This method returns a [HarmonyRule](#harmonyrule-class) object.
## Applying triadic harmony rule to the color
To apply the triadic rule to the current color, use `Color.harmony_triadic()` method.
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
rule = c.harmony_triadic()
```
This method returns a [HarmonyRule](#harmonyrule-class) object.
## Applying tetradic harmony rule to the color
To apply the tetradic rule to the current color, use `Color.harmony_tetradic()` method.
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
rule = c.harmony_tetradic()
```
This method returns a [HarmonyRule](#harmonyrule-class) object.
## Applying analogous harmony rule to the color
To apply the split complementary rule to the current color, use `Color.harmony_analogous()` method. You can also pass an optional argument `phi: int` that indicates the offset in degrees that will be used. By default it is 30deg:
```python
from ciris import Color
hue, saturation, value = 260, 90, 90
c = Color.from_hsv(hue, saturation, value)
rule = c.harmony_split_complementary(phi=40) # The offset used is 40deg
```
This method returns a [HarmonyRule](#harmonyrule-class) object.
## Comparing the colors
To compare Color objects, use a simple `==` statement.
For example, the code below wil print `The colors are the same`:
```python
from ciris import Color
if Color(255, 100, 100) == Color.from_hsv(255, 100, 100):
print("The colors are the same")
```
## Looking up colors in a list
The Color objects are hashable, meaning that you can easily check if the color
is already stored an a list of colors using a simple `in` statement:
```python
from ciris import Color
b_and_w = [Color.from_hex("#FFFFFF"), Color.from_hex("#000000")]
print(Color.from_rgb(0, 0, 0) in b_and_w) # True
print(Color.from_rgb(62, 81, 22) in b_and_w) # False
```
# HarmonyRule class
This class is a dataclass that is used by ciris to describe any harmony rule that has been applied to the color.
It has 3 attributes:
* `rule_type: str` - This attribute stores the type of rule that was applied. Available types are: `complementary`, `split_complementary`, `triadic`, `tetradic`, `analogous`
* `base_color: Color` - This attribute stores the base color (the color that the rule was applied to)
* `secondary_colors: List[Color]` - This attribute stores a list of colors that were derived from the base one according to the harmony rule
All these attributes have their appropriate getters.
# Method chaining
The ciris' Color class supports method chaining, allowing you to write simple, concise and practical one-liners, such as:
### Color conversion
```python
from ciris import Color
c = Color.from_hsv(260, 90, 90).as_hex()
v = Color.from_rgb(145, 90, 10).as_cmyk()
# ...
g = Color.from_hex("#ff0097").as_hsv()
```
### Color processing
```python
from ciris import Color
new_color = Color.from_rgb(old.r, old.g, old.b).invert().lighten(15).hue_shift(10).as_cmyk()
```
# Color Harmony Sources
Here you can find the source material that was used to create color harmony rules
* https://en.wikipedia.org/wiki/Harmony_(color)
* https://blog.thepapermillstore.com/color-theory-color-harmonies/
* https://blog.matthewgove.com/2021/07/02/color-theory-a-simple-exercise-in-mathematics-and-graphic-design/