# @latkit/colormaps

Colormap catalog for Latkit.

## Install

```sh
npm install @latkit/colormaps
```

## Basic use

```ts
import { COLORMAP_LABEL, colormap, colormapGradientCss } from '@latkit/colormaps';

const viridis = colormap('viridis');
const [r, g, b] = viridis(0.5);

button.title = COLORMAP_LABEL.viridis;
button.style.background = colormapGradientCss('viridis', 'to right');
```

Colormap functions accept normalized values in `[0, 1]` and return RGB channels in `[0, 1]`.

## Type Aliases

### Colormap

> **Colormap** = (`t`) => readonly \[`number`, `number`, `number`\]

Maps a normalized scalar to an RGB color.

#### Parameters

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `t` | `number` | Normalized value. Values outside `[0, 1]` are clamped. |

#### Returns

readonly \[`number`, `number`, `number`\]

RGB channels in `[0, 1]`.

Input values are clamped to `[0, 1]`, and returned channels are also in
`[0, 1]`.

***

### ColormapGradientDirection

> **ColormapGradientDirection** = `"to top"` \| `"to right"`

Supported CSS gradient directions for [colormapGradientCss](#colormapgradientcss).

***

### ColormapKind

> **ColormapKind** = `"sequential"` \| `"diverging"`

High-level colormap family.

Sequential maps encode magnitude. Diverging maps encode signed deviation
around a midpoint.

***

### ColormapName

> **ColormapName** = *typeof* [`COLORMAP_NAMES`](#colormap_names)\[`number`\]

Name of a bundled colormap preset.

## Variables

### COLORMAP\_KIND

> `const` **COLORMAP\_KIND**: `Readonly`\<`Record`\<[`ColormapName`](#colormapname), [`ColormapKind`](#colormapkind)\>\>

Family metadata for each bundled colormap.

***

### COLORMAP\_LABEL

> `const` **COLORMAP\_LABEL**: `Readonly`\<`Record`\<[`ColormapName`](#colormapname), `string`\>\>

Human-readable label for each bundled colormap.

***

### COLORMAP\_NAMES

> `const` **COLORMAP\_NAMES**: readonly \[`"viridis"`, `"inferno"`, `"plasma"`, `"magma"`, `"cividis"`, `"turbo"`, `"grays"`, `"blues"`, `"reds"`, `"greens"`, `"amber"`, `"coolwarm"`, `"rdbu"`, `"spectral"`, `"piyg"`, `"icefire"`, `"berlin"`, `"rkb"`, `"mkg"`, `"purgreen"`, `"goldblue"`, `"tealpink"`, `"vermlime"`\]

Bundled colormap names in display order.

#### Remarks

The first group contains sequential maps for magnitude-like values. The
second group contains diverging maps for signed deviation around a midpoint.

## Functions

### colormap()

> **colormap**(`name`): [`Colormap`](#colormap)

Returns a pure colormap function for a bundled preset.

#### Parameters

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `name` | `"viridis"` \| `"inferno"` \| `"plasma"` \| `"magma"` \| `"cividis"` \| `"turbo"` \| `"grays"` \| `"blues"` \| `"reds"` \| `"greens"` \| `"amber"` \| `"coolwarm"` \| `"rdbu"` \| `"spectral"` \| `"piyg"` \| `"icefire"` \| `"berlin"` \| `"rkb"` \| `"mkg"` \| `"purgreen"` \| `"goldblue"` \| `"tealpink"` \| `"vermlime"` | Bundled colormap name. |

#### Returns

[`Colormap`](#colormap)

A transfer function from normalized scalar values to RGB channels.

#### Example

```ts
const viridis = colormap('viridis');
const [r, g, b] = viridis(0.5);
```

***

### colormapGradientCss()

> **colormapGradientCss**(`name`, `direction?`): `string`

Builds a CSS `linear-gradient()` from the same evaluator as `colormap`.

#### Parameters

| Parameter | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `name` | `"viridis"` \| `"inferno"` \| `"plasma"` \| `"magma"` \| `"cividis"` \| `"turbo"` \| `"grays"` \| `"blues"` \| `"reds"` \| `"greens"` \| `"amber"` \| `"coolwarm"` \| `"rdbu"` \| `"spectral"` \| `"piyg"` \| `"icefire"` \| `"berlin"` \| `"rkb"` \| `"mkg"` \| `"purgreen"` \| `"goldblue"` \| `"tealpink"` \| `"vermlime"` | `undefined` | Bundled colormap name. |
| `direction` | [`ColormapGradientDirection`](#colormapgradientdirection) | `'to top'` | CSS gradient direction. Default: `"to top"`. |

#### Returns

`string`

A CSS `linear-gradient()` string suitable for legends and swatches.

#### Example

```ts
legend.style.background = colormapGradientCss('magma', 'to right');
```

Use `to top` for vertical legends and `to right` for horizontal swatches.

***

### isDiverging()

> **isDiverging**(`name`): `boolean`

Checks whether a bundled colormap is diverging.

#### Parameters

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `name` | `"viridis"` \| `"inferno"` \| `"plasma"` \| `"magma"` \| `"cividis"` \| `"turbo"` \| `"grays"` \| `"blues"` \| `"reds"` \| `"greens"` \| `"amber"` \| `"coolwarm"` \| `"rdbu"` \| `"spectral"` \| `"piyg"` \| `"icefire"` \| `"berlin"` \| `"rkb"` \| `"mkg"` \| `"purgreen"` \| `"goldblue"` \| `"tealpink"` \| `"vermlime"` | Bundled colormap name. |

#### Returns

`boolean`

True if the colormap is diverging; false otherwise.