hbutils.color.utils

Overview:

Useful color utilities based on color model.

This module provides utilities for color manipulation including:

  • Visual distance calculation between colors

  • Random color generation with visual distinctiveness

  • Linear gradient generation between multiple colors

visual_distance

hbutils.color.utils.visual_distance(c1: Color | str, c2: Color | str) → float[source]

Calculate the visual distance between two colors.

This function computes the perceptual distance between two colors using a weighted Euclidean distance in RGB space. The weights are based on the average red component to account for human perception differences.

Parameters:

  • c1 (Union[Color, str]) – First color, can be a Color object or string representation.

  • c2 (Union[Color, str]) – Second color, can be a Color object or string representation.

Returns:

Distance value representing visual difference between colors.

Return type:

float

Examples::
>>> from hbutils.color import visual_distance, Color
>>> visual_distance(
...     '#ff0000',
...     '#00ff00'
... )
2.5495097567963922
>>> visual_distance(
...     '#778800',
...     '#887700'
... )
0.16996731711975946

rnd_colors

hbutils.color.utils.rnd_colors(count, lightness=0.5, saturation=1.0, alpha=None, init_dis=4.0, lr=0.95, ur=1.5, rnd=None) → Iterator[Color][source]

Generate random colors that are visually distinct from each other.

This function generates a specified number of colors with controlled visual distinctiveness. It uses the HLS color space and ensures generated colors maintain a minimum visual distance from previously generated colors.

Parameters:

  • count (int) – Number of colors to generate.

  • lightness (float) – Lightness value in HLS color space (0.0 to 1.0), default is 0.5.

  • saturation (float) – Saturation value in HLS color space (0.0 to 1.0), default is 1.0.

  • alpha (float, optional) – Alpha (transparency) value for colors, default is None.

  • init_dis (float) – Initial minimum distance between colors, default is 4.0.

  • lr (float) – Lower ratio for adjusting minimum distance when generation fails, default is 0.95.

  • ur (float) – Upper ratio for adjusting minimum distance when generation succeeds, default is 1.5.

  • rnd (random.Random, optional) – Random number generator instance, default is random.Random(0).

Returns:

Iterator yielding Color objects.

Return type:

Iterator[Color]

Examples::
>>> from hbutils.color import rnd_colors
>>> for c in rnd_colors(12):
...     print(c)
#ff00ee
#00ff00
#009cff
#ff006c
#c9ff00
#00f3ff
#d100ff
#ffaf00
#00ff6c
#4100ff
#ff5300
#46ff00

>>> for c in rnd_colors(12, 0.8, 0.9):
...     print(c)
#fa9ef4
#9efaa1
#9eb4fa
#faa69e
#c5fa9e
#9ed6fa
#f09efa
#faf89e
#9ef9fa
#c09efa
#fabe9e
#9efaca

linear_gradient

hbutils.color.utils.linear_gradient(colors: Sequence[Color | str] | Sequence[Tuple[float, Color | str]]) → Callable[[float], Color][source]

Create a linear gradient function from a sequence of colors.

This function creates a gradient mapping that interpolates linearly between the provided colors. Colors can be provided either as a simple sequence (evenly distributed) or as position-color tuples for custom positioning.

Parameters:

colors (Union[Sequence[Union[Color, str]], Sequence[Tuple[float, Union[Color, str]]]]) – Sequence of colors or position-color tuples. If simple sequence, colors are evenly distributed from 0 to 1. If tuples, first element is position (float) and second is color.

Returns:

A function that takes a float parameter and returns the interpolated Color.

Return type:

Callable[[float], Color]

Examples::

  • Simple Linear Gradientation

>>> from hbutils.color import linear_gradient
>>>
>>> f = linear_gradient(('red', 'yellow', 'lime'))
>>> f(0)
<Color red>
>>> f(0.25)
<Color #ff8000>
>>> f(1 / 3)
<Color #ffaa00>
>>> f(0.5)
<Color yellow>
>>> f(2 / 3)
<Color #aaff00>
>>> f(0.75)
<Color #80ff00>
>>> f(1)
<Color lime>

  • Complex Linear Gradientation

>>> f = linear_gradient(((-0.2, 'red'), (0.7, '#ffff0044'), (1.1, 'lime')))
>>> f(-0.2)
<Color red, alpha: 1.000>
>>> f(0)
<Color #ff3900, alpha: 0.837>
>>> f(0.25)
<Color #ff8000, alpha: 0.633>
>>> f(1 / 3)
<Color #ff9700, alpha: 0.565>
>>> f(0.5)
<Color #ffc600, alpha: 0.430>
>>> f(2 / 3)
<Color #fff600, alpha: 0.294>
>>> f(0.7)
<Color yellow, alpha: 0.267>
>>> f(0.75)
<Color #dfff00, alpha: 0.358>
>>> f(0.8)
<Color #bfff00, alpha: 0.450>
>>> f(1)
<Color #40ff00, alpha: 0.817>
>>> f(1.1)
<Color lime, alpha: 1.000>