A lightweight Python library that makes working with color easy
Project description
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:
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.
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:
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:
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:
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:
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:
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:
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:
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:
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:
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%:
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:
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:
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:
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)
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:
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)
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:
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:
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 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:
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 object.
Applying triadic harmony rule to the color
To apply the triadic rule to the current color, use Color.harmony_triadic() method.
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 object.
Applying tetradic harmony rule to the color
To apply the tetradic rule to the current color, use Color.harmony_tetradic() method.
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 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:
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 object.
Comparing the colors
To compare Color objects, use a simple == statement.
For example, the code below wil print The colors are the same:
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:
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,analogousbase_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
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
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
