# gradient

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

用于标量场（如热图）的颜色渐变（色图）。

[Gradient](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)
通过在有序颜色停止点之间进行线性插值，将 `[0, 1]` 中的标量映射到
[Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)。它是热图的颜色模型，与
[Palette](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)
类分开，因为热图着色的是连续的量级，而不是一组离散的类别。

一些现成的渐变已按名称注册在
[GRADIENTS](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)
中（如 `"viridis"`/`"turbo"` 等感知均匀的渐变，以及 `"jet"` 和 `"hot"` 等经典渐变）。使用
[resolve_gradient](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)
解析名称或传递您自己的渐变；使用
[Gradient.from_colors](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)
构建自定义渐变。

只有
[Gradient.colorize](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)
需要 NumPy，并且它在调用时导入 NumPy，因此此模块在没有 NumPy 的基本 `luxonis-ml` 安装上仍然可以导入。

## 类

### Gradient

色图：在 RGB 中插值的有序颜色停止点集。

`[0, 1]` 中的标量 `t` 通过周围停止点之间的分段线性插值映射到颜色。超出 `[0, 1]` 的值将被钳制。

> **示例**
> ```pycon
>>> g = Gradient.from_colors(["#000000", "#ff0000"])
>>> g.color_at(0.0)
Color(r=0, g=0, b=0, a=255)
>>> g.color_at(0.5)
Color(r=128, g=0, b=0, a=255)
>>> g.color_at(1.0)
Color(r=255, g=0, b=0, a=255)
```

#### 方法

##### color_at

```python
def color_at(t: float) -> Color:
```

返回 `[0, 1]` 中标量 `t` 处的颜色（已钳制）。

所有四个通道都进行插值，因此半透明停止点之间的渐变也会在 alpha 通道中淡入淡出。

参数

 * `t` (`float`): 沿渐变的位置。

返回

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

##### colorize

```python
def colorize(field: npt.ArrayLike) -> np.ndarray:
```

将标量场映射到 RGB，通过停止点插值每个通道。

只映射颜色通道：结果是不透明的 RGB，因此忽略停止点上的任何 alpha 值。当 alpha 值很重要时，使用 [color_at](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)。

参数

 * `field` (`npt.ArrayLike`): 标量数组，预期在 `[0, 1]` 范围内（值将被钳制）。接受任何形状，以及 `numpy.asarray` 转换为浮点数组的任何内容。

返回

 * `np.ndarray`: 形状为 `(*field.shape, 3)` 的 `uint8` 数组，按 RGB 顺序排列。

##### from_colors

```python
def from_colors(colors: list[ColorLike], *, positions: list[float] | None = None) -> Gradient:
```

从颜色构建渐变，除非给出位置，否则均匀分布。

参数

 * `colors` (`list[ColorLike]`): 两个或更多颜色（十六进制字符串、元组或 [Color](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)），从刻度的低端到高端。
 * `positions` (`list[float] | None`): 可选的停止点位置，在 `[0, 1]` 范围内，每个颜色一个；当为 `None` 时，颜色从 `0` 到 `1` 均匀分布。

返回

 * `Gradient`: [Gradient](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)。

引发

 * `ValueError`: 如果给定的颜色少于两种，或者 `positions` 的长度与 `colors` 不同，或者位置超出 `[0, 1]` 范围，或者位置重复。

#### 属性

##### stops

升序 `(position, color)` 对，位置在 `[0, 1]` 范围内；第一个应在 `0.0` 处，最后一个应在 `1.0` 处。

## 函数

### resolve_gradient

```python
def resolve_gradient(gradient: Gradient | str) -> Gradient:
```

将渐变或预设名称解析为 [Gradient](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)。

> **示例**
> ```pycon
>>> resolve_gradient("grayscale").color_at(1.0)
Color(r=255, g=255, b=255, a=255)
```

参数

 * `gradient` (`Gradient | str`): 一个
   [Gradient](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)，或
   [GRADIENTS](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)
   中预设的名称。

返回

 * `Gradient`:
   [Gradient](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)。

引发

 * `KeyError`: 如果给定的名称不是已注册的预设。

## 属性

### DEFAULT_DIVERGING_GRADIENT

当未给出时，用于有符号字段的渐变名称。

### DEFAULT_GRADIENT

当未给出时，用于无符号字段的渐变名称。

### DIVERGING_GRADIENTS

围绕中性中点构建的预设。

每个预设都有奇数个均匀分布的停止点，中间有一个接近白色的停止点，因此将热图居中时，该中性颜色恰好位于中心值。顺序预设没有这样的锚点：将它们居中仍然可以平衡范围，但没有特定的颜色标记中间。

### GRADIENTS

按名称键入的预设渐变。请参阅
[resolve_gradient](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)。
