# base

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

颜色解析和操作。

[Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)
类是 `luxonis-ml` 共享的单一颜色基元——可视化层重新导出它，其他子模块（例如增强填充值）也通过它解析颜色，因此没有模块重新实现颜色处理。

颜色被标准化为 8 位整数的 `(r, g, b, a)`
元组。[Color.parse](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)
接受用户实际拥有的形状——十六进制字符串、CSS 颜色名称、单个灰度整数、RGB/RGBA 元组或另一个
[Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)——并公开调色板和样式派生所依赖的
HSL 空间操作。

## 类

### Color

具有 HSL 空间帮助器的不可变 RGBA 颜色。

> **示例**
> ```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'
```

#### 方法

##### darken

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

在 HSL 空间中将颜色向黑色移动。

参数

 * `amount` (`float`): 要移除的当前亮度分数，范围为 `[0, 1]`。

返回

 * `Color`: 较暗的 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)，alpha 值保持不变。

##### from_hls

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

从色相/亮度/饱和度构建颜色。

参数

 * `hue` (`float`): 色相，范围为 `[0, 1]`。
 * `lightness` (`float`): 亮度，范围为 `[0, 1]`。
 * `saturation` (`float`): 饱和度，范围为 `[0, 1]`。
 * `a` (`int`): Alpha 通道，0-255。

返回

 * `Color`: 对应的 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)。

##### lighten

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

在 HSL 空间中将颜色向白色移动。

参数

 * `amount` (`float`): 要添加的剩余亮度分数，范围为 `[0, 1]`。

返回

 * `Color`: 较亮的 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)，alpha 值保持不变。

##### parse

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

将类似颜色的值强制转换为 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)。

参数

 * `value` (`object`): 十六进制字符串（`"#rgb"`、`"#rrggbb"`、`"#rrggbbaa"`，带或不带前导 `#`）、CSS 颜色名称（`"red"`）、单个灰度整数（`128` → 灰色）、`(r, g, b)` 或 `(r, g, b, a)` 元组，或现有的 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)。

返回

 * `Color`: 对应的 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)。

引发

 * `ValueError`: 如果该值无法解释为颜色。

##### readable_text_color

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

返回接近黑色或白色，以在此颜色上更易读的为准。

返回

 * `不透明颜色`: 在浅色上是柔和的接近黑色，在深色上是白色，因此此颜色芯片上的标签文本保持清晰可辨。

##### saturate

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

增加（或，如果为负数，则减少）饱和度。

参数

 * `amount` (`float`): 要添加的剩余饱和度分数，范围为 `[-1, 1]`。

返回

 * `Color`: 饱和度调整后的 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)，alpha 值保持不变。

##### shift_hue

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

围绕色轮旋转色相。

参数

 * `turns` (`float`): 旋转量，以圈为单位（`1.0` 是一整圈）。

返回

 * `Color`: 色相旋转后的 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)，alpha 值保持不变。

##### with_alpha

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

返回带有新 alpha 值的副本。

参数

 * `a` (`float`): Alpha 值，可以是整数 (0-255) 或浮点数 `[0, 1]`。

返回

 * `Color`: 具有请求 alpha 值的新 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)。

#### 属性

##### a

Alpha 通道，0-255（255 为不透明）。

##### b

蓝色通道，0-255。

##### g

绿色通道，0-255。

##### hls

颜色表示为 `(hue, lightness, saturation)` 元组，范围为 `[0, 1]`。

##### is_light

此颜色是否足够亮，需要在其上方使用深色文本。

以 WCAG 相对亮度的方式加权通道，但保持伽马编码而不是先线性化——这是感知亮度的一个近似值，也是亮/暗决策所需的全部。

##### r

红色通道，0-255。

##### rgb

颜色表示为 `(r, g, b)` 元组。

##### rgba

颜色表示为 `(r, g, b, a)` 元组。

## 属性

### ColorLike

十六进制字符串或颜色名称、灰度整数、RGB/RGBA 元组或 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)。

### RGB

一个 8 位整数的 `(r, g, b)` 元组 (0-255)。

### RGBA

一个 8 位整数的 `(r, g, b, a)` 元组 (0-255)。
