# gradient

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

Color gradients (colormaps) for scalar fields such as heatmaps.

A
[Gradient](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)
maps a scalar in `[0, 1]` to a
[Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)
by linearly interpolating between ordered color stops. It is the color model for heatmaps, kept separate from the class
[Palette](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/palette.md)
because a heatmap colors a continuous magnitude, not a set of discrete classes.

A handful of ready-made gradients are registered by name in
[GRADIENTS](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)
(perceptually-uniform ones like `"viridis"`/`"turbo"` plus classics like `"jet"` and `"hot"`). Resolve a name or pass your own
with
[resolve_gradient](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md);
build a custom one with
[Gradient.from_colors](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md).

Only
[Gradient.colorize](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md)
needs NumPy, and it imports it when called, so this module stays importable on a base `luxonis-ml` install that has no NumPy.

## Classes

### Gradient

A colormap: an ordered set of color stops interpolated in RGB.

A scalar `t` in `[0, 1]` is mapped to a color by piecewise-linear interpolation between the surrounding stops. Values outside `[0,
1]` are clamped.

> **Examples**
> ```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)
```

#### Methods

##### color_at

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

Return the color at scalar `t` in `[0, 1]` (clamped).

All four channels are interpolated, so a gradient between translucent stops fades in alpha too.

Parameters

 * `t` (`float`): The position along the gradient.

Returns

 * `Color`: The interpolated [Color](https://docs.luxonis.com/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:
```

Map a scalar field to RGB, interpolating each channel through the stops.

Only the color channels are mapped: the result is opaque RGB, so any alpha on the stops is ignored. Use [color_at](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md) when alpha matters.

Parameters

 * `field` (`npt.ArrayLike`): An array of scalars, expected in `[0, 1]` (values are clamped). Any shape is accepted, as is anything `numpy.asarray` converts to a float array.

Returns

 * `np.ndarray`: A `uint8` array shaped `(*field.shape, 3)` in RGB order.

##### from_colors

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

Build a gradient from colors, evenly spaced unless positions are given.

Parameters

 * `colors` (`list[ColorLike]`): Two or more colors (hex strings, tuples, or [Color](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/base.md)), from the low end of the scale to the high end.
 * `positions` (`list[float] | None`): Optional stop positions in `[0, 1]`, one per color; when `None` the colors are spread evenly from `0` to `1`.

Returns

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

Raises

 * `ValueError`: If fewer than two colors are given, or `positions` is given with a different length than `colors`, a position outside `[0, 1]`, or a repeated position.

#### Attributes

##### stops

Ascending `(position, color)` pairs with positions in `[0, 1]`; the first should be at `0.0` and the last at `1.0`.

## Functions

### resolve_gradient

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

Resolve a gradient or a preset name to a [Gradient](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md).

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

Parameters

 * `gradient` (`Gradient | str`): A
   [Gradient](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md),
   or the name of a preset in
   [GRADIENTS](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md).

Returns

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

Raises

 * `KeyError`: If a name is given that is not a registered preset.

## Attributes

### DEFAULT_DIVERGING_GRADIENT

Name of the gradient used for a signed field when none is given.

### DEFAULT_GRADIENT

Name of the gradient used for an unsigned field when none is given.

### DIVERGING_GRADIENTS

Presets built around a neutral midpoint.

Each has an odd number of evenly spaced stops with a near-white one in the middle, so centering a heatmap puts that neutral color
exactly on the center value. The sequential presets have no such anchor: centering them still balances the range, but no
particular color marks the middle.

### GRADIENTS

The preset gradients, keyed by name. See
[resolve_gradient](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/color/gradient.md).