# palette

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

来自可插拔的、基于索引的生成器的不同类颜色。

[Palette](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)
为每个新类分配一个来自颜色生成器的下一个颜色：一个可调用 `int -> Color`，它将序列位置映射到颜色。默认生成器
[GoldenRatioColors](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)
将每个色相与上一个色相偏移黄金角度（约 137.5°），因此没有两个类落在近乎相同的色相上——这是固定调色板（或哈希到其中一个）在类计数接近调色板大小时无法避免的故障模式。类标签故意保留这种独特的色相方案；Luxonis 品牌颜色保留用于界面（请参阅
[luxonis_ml.utils.color.brand](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/brand.md)），尽管
[SequenceColors](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)
允许调用者在需要时将调色板锚定到品牌
[BRAND_COLORS](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)。

交换整个配色方案是一个单一的参数——`Palette(generator=...)`——因此策略只存在于一个地方，调用者只接触
[Palette.color_for](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)。

由于间距保证仅适用于顺序索引，因此颜色按首次出现的顺序分配并记忆：在一个进程中，一个类在每个图像中都保持其颜色（模块级别的
[DEFAULT_PALETTE](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)
是共享的）。缺点是类的颜色取决于类首次出现的顺序，而不是仅仅取决于其名称——在一次运行中以及在以相同顺序请求类的多次运行中是稳定的，但在任意重新排序中则不是。使用
[Palette.pin](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)
或通过以固定顺序预注册类来显式固定颜色，当名称必须永远映射到一个精确的颜色时。

## 类

### GoldenRatioColors

通过黄金比例色相间距将序列索引映射到不同的颜色。

这是默认的
[ColorGenerator](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)。所有影响外观的旋钮都位于此处，因此重新设计整个调色板意味着构造其中一个（或任何其他
`int -> Color` 可调用对象）并将其传递给
[Palette](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)。

> **示例**
> ```pycon
>>> gen = GoldenRatioColors()
>>> gen(0) == gen(0)
True
>>> gen(0) == gen(1)
False
```

#### 属性

##### hue0

索引 0 的色相，范围为 `[0, 1]` 圈（默认为蓝色）。

##### lightness

每个颜色的基本亮度，范围为 `[0, 1]`。

##### lightness_jitter

与 `lightness` 的峰值亮度偏差，通过第二个低差异序列应用，使亮度微妙变化（即使在类计数很高时色相变得拥挤，也能使颜色保持分离）。

##### saturation

每个颜色的固定饱和度，范围为 `[0, 1]`。

### Palette

根据颜色生成器，按首次使用的顺序为类分配颜色。

> **示例**
> 一个类保持其颜色；不同的类获得不同的颜色：

```pycon
>>> p = Palette()
>>> p.color_for("car") == p.color_for("car")
True
>>> p.color_for("car") == p.color_for("bus")
False
>>> len(p)
2
```

只要类以相同的顺序请求（“car”在两者中都是索引 0），两个新的调色板就会一致...

```pycon
>>> Palette().color_for("car") == Palette().color_for("car")
True
```

...但颜色遵循首次出现的顺序，而不是名称，所以重新排序会改变它：

```pycon
>>> Palette(["a", "b"]).color_for("b") == Palette(
...     ["b", "a"]
... ).color_for("b")
False
```

#### 方法

##### init

```python
def __init__(classes: Iterable[str] | None = None, *, generator: ColorGenerator | None = None, colors: Mapping[str, ColorLike] |
None = None):
```

创建一个调色板，可选地固定类顺序和精确颜色。

参数

 * `classes` (`Iterable[str] | None`): 要预先注册的类名，按固定其颜色的顺序。任何未列出的类将在首次使用时分配。
 * `generator` (`ColorGenerator | None`): `int -> Color` 策略；默认为 [GoldenRatioColors](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)。
 * `colors` (`Mapping[str, ColorLike] | None`): 显式 `{class_name: color}` 固定。固定的类总是获得精确的颜色，并且从不消耗生成器槽，因此固定不会改变其他类的序列颜色。

##### at

```python
def at(index: int) -> Color:
```

返回序列位置 `index` 的颜色（不注册它）。

参数

 * `index` (`int`): 生成器序列中的零基位置。

返回

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

##### color_for

```python
def color_for(key: str) -> Color:
```

返回分配给 `key` 的颜色，如果未见过则分配一个新颜色。

第一次看到一个键时，它会获取序列中的下一个颜色；之后每次调用该键都会返回相同的颜色。两个线程竞争注册不同的键会获得不同的颜色：只有分配被锁定，因此已着色键的常见情况保持无锁。

参数

 * `key` (`str`): 要着色的标签（或任何字符串标识）。

返回

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

##### pin

```python
def pin(key: str, color: ColorLike) -> Palette:
```

将 `key` 精确地固定到 `color` 并返回 `self` 以进行链式调用。

固定的类总是从 [color_for](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md) 获取此颜色，覆盖任何生成的颜色，并且从不消耗生成器槽。

参数

 * `key` (`str`): 要固定的类名（或字符串标识）。
 * `color` (`ColorLike`): `key` 的精确颜色（任何 [ColorLike](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)）。

返回

 * `Palette`: 此调色板，允许流畅的链式调用。

##### with_colors

```python
def with_colors(colors: Mapping[str, ColorLike]) -> Palette:
```

返回此调色板的副本，并带有额外的类颜色固定。

该副本共享生成器并继承已分配的颜色和固定；`colors` 会合并到顶部。原始对象不会被修改，因此共享调色板可以根据每次渲染进行专门化，而不会产生副作用。

参数

 * `colors` (`Mapping[str, ColorLike]`): 要添加的额外 `{class_name: color}` 固定。

返回

 * `Palette`: 一个新的 [Palette](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)，带有合并的固定。

### SequenceColors

首先分发固定颜色列表，然后回退到生成器。

包装一个 `anchors` 列表（例如 Luxonis [BRAND_COLORS](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)），以便首先看到的类按顺序获得这些精确的颜色。一旦锚点用完，索引 `n` 将继续通过 `overflow`（默认情况下是一个 [GoldenRatioColors](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md) 生成器，使用从第一个后锚点类重新开始的索引进行查询），因此任意数量的类仍然会收到不同的颜色。

> **示例**
> ```pycon
>>> from luxonis_ml.utils.color import Color
>>> gen = SequenceColors((Color(255, 0, 0), Color(0, 255, 0)))
>>> gen(0)
Color(r=255, g=0, b=0, a=255)
>>> gen(1)
Color(r=0, g=255, b=0, a=255)
>>> gen(2) == gen(2)  # overflow is deterministic
True
```

#### 属性

##### anchors

为索引 `0 .. len(anchors) - 1` 分发的颜色。

##### overflow

锚点用尽后使用的生成器。

## 属性

### BRAND_COLORS

Luxonis 品牌颜色序列，用于
[SequenceColors](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)。

### ColorGenerator

一个可调用对象，将零基序列索引映射到
[Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)。

### DEFAULT_PALETTE

进程范围内的默认
[Palette](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)，共享以便一个类保持其颜色。

使用独特的色相
[GoldenRatioColors](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)
生成器：标签颜色选择为保持距离，而不是与品牌匹配（品牌保留用于界面）。
