hbutils.color.model

Overview:

Color model, include rgb, hsv, hls color system.

More color system will be supported soon.

Color

class hbutils.color.model.Color(c: str | Tuple[float, float, float] | Color, alpha: float | None = None)[source]

Overview:

Color utility object.

Examples::

>>> from hbutils.color import Color
>>>
>>> c = Color('red')  # from name
>>> c
<Color red>
>>> str(c)  # hex format
'#ff0000'
>>> (c.rgb.red, c.rgb.green, c.rgb.blue)            # rgb format
(1.0, 0.0, 0.0)
>>> (c.hls.hue, c.hls.lightness, c.hls.saturation)  # hls format
(0.0, 0.5, 1.0)
>>> (c.hsv.hue, c.hsv.value, c.hsv.saturation)      # hsv format
(0.0, 1.0, 1.0)

>>> c1 = Color('#56a3f0')  # from hex
>>> c1
<Color #56a3f0>
>>> str(c1)  # hex format
'#56a3f0'
>>> (c1.rgb.red, c1.rgb.green, c1.rgb.blue)            # rgb format
(0.33725490196078434, 0.6392156862745098, 0.9411764705882353)
>>> (c1.hls.hue, c1.hls.lightness, c1.hls.saturation)  # hls format
(0.5833333333333334, 0.6392156862745098, 0.8369565217391304)
>>> (c1.hsv.hue, c1.hsv.value, c1.hsv.saturation)      # hsv format
(0.5833333333333334, 0.9411764705882353, 0.6416666666666666)

>>> c2 = Color('#56a3f077')  # from hex
>>> c2
<Color #56a3f0, alpha: 0.467>
>>> c2.alpha  # alpha value
0.4666666666666667
>>> str(c2)   # hex format
'#56a3f077'

__eq__(other) → bool[source]

Get equality between colors.

Parameters:: other – Another object to compare with.
Returns:: True if equal, False otherwise.
Return type:: bool

__getstate__() → Tuple[float, float, float, float | None][source]

Dump color as pickle object.

Returns:: Dumped data object containing (r, g, b, alpha).
Return type:: Tuple[float, float, float, Optional[float]]

__hash__() → int[source]

Get hash value of current object.

Returns:: Hash value of current color.
Return type:: int

__init__(c: str | Tuple[float, float, float] | Color, alpha: float | None = None)[source]

Constructor of Color.

Parameters:

c (Union[str, Tuple[float, float, float], Color]) – Color value, can be hex string value, tuple rgb value, or another Color object.
alpha (Optional[float]) – Alpha value of color, default is None which means no alpha value.

Raises:

TypeError – If c is not a valid color type.
ValueError – If c is an invalid string color format.

__repr__() → str[source]

Get the string representation of the Color object.

Returns:: String representation.
Return type:: str

__setstate__(v: Tuple[float, float, float, float | None])[source]

Load color from pickle object.

Parameters:: v (Tuple[float, float, float, Optional[float]]) – Dumped data object containing (r, g, b, alpha).

__str__() → str[source]

Hex format of this Color object.

Returns:: Hexadecimal color string.
Return type:: str

property alpha: float | None

Alpha value, which means the transparent ratio (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available.

Returns:: Alpha value, or None if no alpha is set.
Return type:: Optional[float]

classmethod from_hex(hex_: str) → Color[source]

Load color from hexadecimal rgb string.

Parameters:: hex_ (str) – Hexadecimal string, maybe starts with #.
Returns:: Color object.
Return type:: Color

classmethod from_hls(h: float, l: float, s: float, alpha: float | None = None) → Color[source]

Load color from hls system.

Parameters:

h (float) – Hue value, should be a float value in \(\left[0, 1\right)\).
l (float) – Lightness value, should be a float value in \(\left[0, 1\right]\).
s (float) – Saturation value, should be a float value in \(\left[0, 1\right]\).
alpha (Optional[float]) – Alpha value, should be a float value in \(\left[0, 1\right]\), default is None which means no alpha value is used.

Returns:

Color object.

Return type:

Color

classmethod from_hsv(h: float, s: float, v: float, alpha: float | None = None) → Color[source]

Load color from hsv system.

Parameters:

h (float) – Hue value, should be a float value in \(\left[0, 1\right)\).
s (float) – Saturation value, should be a float value in \(\left[0, 1\right]\).
v (float) – Brightness (value) value, should be a float value in \(\left[0, 1\right]\).
alpha (Optional[float]) – Alpha value, should be a float value in \(\left[0, 1\right]\), default is None which means no alpha value is used.

Returns:

Color object.

Return type:

Color

classmethod from_rgb(r: float, g: float, b: float, alpha: float | None = None) → Color[source]

Load color from rgb system.

Parameters:

r (float) – Red value, should be a float value in \(\left[0, 1\right]\).
g (float) – Green value, should be a float value in \(\left[0, 1\right]\).
b (float) – Blue value, should be a float value in \(\left[0, 1\right]\).
alpha (Optional[float]) – Alpha value, should be a float value in \(\left[0, 1\right]\), default is None which means no alpha value is used.

Returns:

Color object.

Return type:

Color

property hls: HLSColorProxy

Get hls color system based color proxy. See HLSColorProxy.

Returns:: Hls color proxy.
Return type:: HLSColorProxy

property hsv: HSVColorProxy

Get hsv color system based color proxy. See HSVColorProxy.

Returns:: Hsv color proxy.
Return type:: HSVColorProxy

property rgb: RGBColorProxy

Get rgb color system based color proxy. See RGBColorProxy.

Returns:: Rgb color proxy.
Return type:: RGBColorProxy

RGBColorProxy

class hbutils.color.model.RGBColorProxy(this: Color, r: GetSetProxy, g: GetSetProxy, b: GetSetProxy)[source]

Overview:: Color proxy for RGB space.

__init__(this: Color, r: GetSetProxy, g: GetSetProxy, b: GetSetProxy)[source]

Constructor of RGBColorProxy.

Parameters:

this (Color) – Original color object.
r (GetSetProxy) – Get-set proxy for red.
g (GetSetProxy) – Get-set proxy for green.
b (GetSetProxy) – Get-set proxy for blue.

__iter__()[source]

Iterator for this proxy.

Returns:: Iterator yielding red, green, and blue values.
Return type:: Iterator[float]

Examples::

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> r, g, b = c.rgb
>>> print(r, g, b)
0.0 0.5019607843137255 0.0

__repr__()[source]

Representation format.

Returns:: String representation of the RGB color proxy.
Return type:: str

Examples::

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> c.rgb
<RGBColorProxy red: 0.000, green: 0.502, blue: 0.000>

property blue: float

Blue value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Blue component value.
Return type:: float

property green: float

Green value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Green component value.
Return type:: float

property red: float

Red value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Red component value.
Return type:: float

HLSColorProxy

class hbutils.color.model.HLSColorProxy(this: Color, h: GetSetProxy, l: GetSetProxy, s: GetSetProxy)[source]

Overview:: Color proxy for HLS space.

__init__(this: Color, h: GetSetProxy, l: GetSetProxy, s: GetSetProxy)[source]

Constructor of HLSColorProxy.

Parameters:

this (Color) – Original color object.
h (GetSetProxy) – Get-set proxy for hue.
l (GetSetProxy) – Get-set proxy for lightness.
s (GetSetProxy) – Get-set proxy for saturation.

__iter__()[source]

Iterator for this proxy.

Returns:: Iterator yielding hue, lightness, and saturation.
Return type:: Iterator[float]

Examples::

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> h, l, s = c.hls
>>> print(h, l, s)
0.3333333333333333 0.25098039215686274 1.0

__repr__()[source]

Representation format.

Returns:: String representation of the HLS color proxy.
Return type:: str

Examples::

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> c.hls
<HLSColorProxy hue: 0.333, lightness: 0.251, saturation: 1.000>

property hue: float

Hue value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Hue component value.
Return type:: float

property lightness: float

Lightness value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Lightness component value.
Return type:: float

property saturation: float

Saturation value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Saturation component value.
Return type:: float

HSVColorProxy

class hbutils.color.model.HSVColorProxy(this: Color, h: GetSetProxy, s: GetSetProxy, v: GetSetProxy)[source]

Overview:: Color proxy for HSV space.

__init__(this: Color, h: GetSetProxy, s: GetSetProxy, v: GetSetProxy)[source]

Constructor of HSVColorProxy.

Parameters:

this (Color) – Original color object.
h (GetSetProxy) – Get-set proxy for hue.
s (GetSetProxy) – Get-set proxy for saturation.
v (GetSetProxy) – Get-set proxy for value.

__iter__()[source]

Iterator for this proxy.

Returns:: Iterator yielding hue, saturation, and value.
Return type:: Iterator[float]

Examples::

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> h, s, v = c.hsv
>>> print(h, s, v)
0.3333333333333333 1.0 0.5019607843137255

__repr__()[source]

Representation format.

Returns:: String representation of the HSV color proxy.
Return type:: str

Examples::

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> c.hsv
<HSVColorProxy hue: 0.333, saturation: 1.000, value: 0.502>

property brightness: float

Alias for value.

Returns:: Brightness (value) component value.
Return type:: float

property hue: float

Hue value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Hue component value.
Return type:: float

property saturation: float

Saturation value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Saturation component value.
Return type:: float

property value: float

Value value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Value (brightness) component value.
Return type:: float