# base

Python API: `luxonis_ml.utils.color.base`

Color parsing and manipulation.

The
[Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)
class is the single color primitive shared across `luxonis-ml` — the visualization layer re-exports it, and other submodules (e.g.
augmentation fill values) parse colors through it too, so no module reimplements color handling.

Colors are normalized to an `(r, g, b, a)` tuple of 8-bit integers.
[Color.parse](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)
accepts the shapes users actually have on hand — hex strings, CSS color names, a single grayscale integer, RGB/RGBA tuples, or
another
[Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)
— and exposes the HSL-space operations the palette and style derivation rely on.

## Classes

### Color

An immutable RGBA color with HSL-space helpers.

> **Examples**
> ```pycon
>>> Color.parse("#4c8dff")
Color(r=76, g=141, b=255, a=255)
>>> Color.parse("#abc")
Color(r=170, g=187, b=204, a=255)
>>> Color.parse("white")
Color(r=255, g=255, b=255, a=255)
>>> Color.parse(128)
Color(r=128, g=128, b=128, a=255)
>>> Color.parse(300)  # out-of-range channels are clamped
Color(r=255, g=255, b=255, a=255)
>>> Color.parse((255, 0, 0))
Color(r=255, g=0, b=0, a=255)
>>> Color.parse("white").rgb
(255, 255, 255)
>>> Color(255, 0, 0).with_alpha(0.5)
Color(r=255, g=0, b=0, a=128)
>>> Color(1, 2, 3, 4).rgba
(1, 2, 3, 4)
>>> Color(255, 255, 255).readable_text_color()
Color(r=17, g=17, b=17, a=255)
>>> Color(0, 0, 0).readable_text_color()
Color(r=255, g=255, b=255, a=255)
>>> c = Color(120, 120, 120)
>>> c.lighten(0.5).hls[1] > c.hls[1]
True
>>> c.darken(0.5).hls[1] < c.hls[1]
True
>>> Color.parse("#12")
Traceback (most recent call last):
    ...
ValueError: invalid hex color '#12'
```

#### Methods

##### darken

```python
def darken(amount: float) -> Color:
```

Move the color toward black in HSL space.

Parameters

 * `amount` (`float`): Fraction of the current lightness to remove, in `[0, 1]`.

Returns

 * `Color`: A darker [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md), alpha preserved.

##### from_hls

```python
def from_hls(hue: float, lightness: float, saturation: float, a: int = 255) -> Color:
```

Build a color from hue/lightness/saturation.

Parameters

 * `hue` (`float`): Hue in `[0, 1]`.
 * `lightness` (`float`): Lightness in `[0, 1]`.
 * `saturation` (`float`): Saturation in `[0, 1]`.
 * `a` (`int`): Alpha channel, 0-255.

Returns

 * `Color`: The corresponding [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md).

##### lighten

```python
def lighten(amount: float) -> Color:
```

Move the color toward white in HSL space.

Parameters

 * `amount` (`float`): Fraction of the remaining lightness to add, in `[0, 1]`.

Returns

 * `Color`: A lighter [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md), alpha preserved.

##### parse

```python
def parse(value: object) -> Color:
```

Coerce a color-like value into a [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md).

Parameters

 * `value` (`object`): A hex string (`"#rgb"`, `"#rrggbb"`, `"#rrggbbaa"`, with or without the leading `#`), a CSS color name (`"red"`), a single grayscale integer (`128` → gray), an `(r, g, b)` or `(r, g, b, a)` tuple, or an existing [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md).

Returns

 * `Color`: The corresponding [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md).

Raises

 * `ValueError`: If the value cannot be interpreted as a color.

##### readable_text_color

```python
def readable_text_color(self) -> Color:
```

Return near-black or white, whichever is more readable on this color.

Returns

 * `Opaque Color`: a soft near-black on light colors, white on dark ones, so label text on a chip of this color stays legible.

##### saturate

```python
def saturate(amount: float) -> Color:
```

Increase (or, with a negative amount, decrease) saturation.

Parameters

 * `amount` (`float`): Fraction of the remaining saturation to add, in `[-1, 1]`.

Returns

 * `Color`: A [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md) with adjusted saturation, alpha preserved.

##### shift_hue

```python
def shift_hue(turns: float) -> Color:
```

Rotate the hue around the color wheel.

Parameters

 * `turns` (`float`): Amount to rotate, in turns (`1.0` is a full circle).

Returns

 * `Color`: A hue-rotated [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md), alpha preserved.

##### with_alpha

```python
def with_alpha(a: float) -> Color:
```

Return a copy with a new alpha.

Parameters

 * `a` (`float`): Alpha as an int (0-255) or a float in `[0, 1]`.

Returns

 * `Color`: A new [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md) with the requested alpha.

#### Attributes

##### a

Alpha channel, 0-255 (255 is opaque).

##### b

Blue channel, 0-255.

##### g

Green channel, 0-255.

##### hls

The color as a `(hue, lightness, saturation)` tuple in `[0, 1]`.

##### is_light

Whether this color is bright enough to need dark text on top.

Weights the channels the way WCAG relative luminance does, but leaves them gamma-encoded rather than linearizing first — an approximation of perceived brightness, which is all a light/dark decision needs.

##### r

Red channel, 0-255.

##### rgb

The color as an `(r, g, b)` tuple.

##### rgba

The color as an `(r, g, b, a)` tuple.

## Attributes

### ColorLike

a hex string or color name, a grayscale int, an RGB/RGBA tuple, or a [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md).

### RGB

An `(r, g, b)` tuple of 8-bit integers (0-255).

### RGBA

An `(r, g, b, a)` tuple of 8-bit integers (0-255).